Introduction

Sometimes customers make mistakes when entering their addresses. This may happen in the "My Account" section, in the checkout process or during registration. Such mistakes may later increase delivery costs and create various other problems. The address check framework provides a convenient way to connect to an external address validation service (like AddressDoctor ) which sends back hints about address errors. The hints may look like this in the UI:

The API of the framework defines a standard interface used to integrate custom validation mechanisms into IS7.

A reference implementation based on the Concept - Managed Service Framework is shipped with IS7. This implementation is just dummy but may be used as a starting point to implement a real integration. The recommended way to implement a custom address check is to wrap it as a managed service. This is not necessarily a must though.

References

• Cookbook - Address Check Framework
• Concept - Managed Service Framework
• Cookbook - Managed Service Framework
• Cookbook - Address Check Framework 7.3

IS7 Integration

General Notes

In the standard product, the address validation is shipped within several different artifacts:

• Standard empty API that should be implemented by custom address check implementations. This API is located in bc_addresscheck.
• Standard pipeline with utility methods that may be used to implement custom validations more easily. This pipeline is located in bc_addresscheck.
• A sample reference implementation. It cannot be used in real projects since it does not provide any practical value. It can be used for a quick reference for implementing the real address validation. The mock implementation is located in ac_addresscheck_demo and wraps the standard API in a managed service.
• Usages of the standard API in the storefront reference application and a corresponding UI. These artifacts are located in the checkout process, the my account section and the registration pages.
• An interface in the back office that enables or disables the address check for checkout, My Account or the registration. The settings are application-specific.

An implementer of a custom address validation needs to:

• become familiar with this document;
• become familiar with the managed services framework;
• follow the practical cookbook.

The reference app uses the results from the ValidateAddressBO pipelet to show address suggestions. If a new validation service is plugged, no other changes that require implementation efforts will be necessary. The next sections introduce the configuration interface in the back office as well as the sample UI in the reference application.

Configuration

Customer and order managers may configure several application-specific options in the back office. These options are located in the General tab of the application and define in which areas of the application the address check is activated. Please have a look at the next screenshot.

The options are hard coded; adding new ones requires additional programming efforts.

If the address validation is wrapped as a managed service, it should appear in the UI dedicated to the managed services as shown on the next image.

The name of the reference address check service is "Address Check Show Case".

Integration Into the Registration Page

If the address validation is enabled on the registration page, the customers may see a hint about address errors when they fill in all details. The customer may then correct the address, choose a suggestion, or continue on the registration page without changing what was previously entered. The second step of the registration is shown in the screenshot below.

Integration Into the My Account Section

In the My Account section, the user get hints while adding new addresses or editing existing addresses. The UI is shown below.

Integration Into the Checkout Process

In the checkout process, the user gets hints while adding new addresses, e.g., in the anonymous checkout. The UI is shown below.

Getting Suggestions From the Demo Service

The demo service is a useless dummy and is used only in demo scenarios. A simple way to trigger it and get back suggestions is to enter "street1" as the street in an address form.

Implementation

This section briefly outlines the artifacts that are involved in the implementation of the address validation.

bc_addresscheck

The address check framework is defined in the cartridge bc_addresscheck. The cartridge contains the basic interface that describes an address validator:

public interface AddressValidator
{
    public AddressValidationResponse validateAddress(AddressValidationRequest addressValidationRequest);
}

Roughly speaking, the implementation receives a request that contains an AddressBO. The expected response contains the result of the validation and perhaps a list with address suggestions in case the validation fails.

The ValidateAddressBO is the only pipelet that should be used ( ValidateAddress is deprecated now). It invokes the AddressValidator registered in the system and returns the result in the pipeline layer. The ValidateAddressBO is essentially a wrapper of AddressValidator in the pipeline layer.

bc_addresscheck includes few artifacts that may be reused in custom projects. This is utility processing logic that is meant to encapsulate the operations that are most likely to be needed in custom implementations. An example is the ProcessAddressValidation-ValidateAddressBO pipeline. It may ease the check of the response of the ValidateAddressBO pipelet. E.g., the developer may easily navigate to the suggestions page just by using the corresponding output connector instead of performing numerous redundant checks at many places in the pipeline layer. The pipeline is shown in the next image.

An important utility is the temporary address storage interface:

public interface CustomerBOTempAddressStorageExtension extends BusinessObjectExtension<CustomerBO>, AddressBORepository
{
    public static final String EXTENSION_ID = "CustomerBOTempAddressStorageExtension";
}

This is an extension of CustomerBO and it is an address repository. As an address repository, it is capable to perform any operations that are required for address repositories. The default implementation keeps the addresses in the user session. The idea is to transfer the address suggestions across multiple steps in the UI. E.g. in step 1, the users may be required to enter their addresses. In step 2, the address suggestions are shown but they should be kept in memory in case the user would like to apply one of the suggestions. Since the extension is just an address repository, all artifacts in bc_address that manipulate addresses may be used to perform all CRUD operations with the repository.

The ValidateAddressBO pipelet only takes an AddressBO as input. ServiceBORepository or ApplicationBO are no longer required. In previous versions, the developers were obliged to wrap their implementations in managed services. Now, bc_addresscheck defines an extension of AddressBO which is used as a simple lookup for registered address validators.

public interface AddressBOAddressValidatorExtension extends BusinessObjectExtension<AddressBO>, AddressValidator
{
    public static final String EXTENSION_ID = "AddressBOAddressValidatorExtension";
}

The default implementation in sld_b2c_ch_base searches for a managed service that adapts the AddressValidator. Developers are not obliged to use it. They may simply provide their own extension that does not depend on the managed services.

ac_addresscheck_demo

The cartridge ac_addresscheck_demo(previously known as ac_addresscheck_std) is a sample implementation of a dummy address validation service. Developers may refer to it when providing their own implementation. It is referred to in the Cookbook - Address Check Framework , too. The sample implementation is wrapped as a managed service.