Capture addresses

Edit online

Customer's addresses are required to create, modify, and fulfill an order. Therefore, the user must be able to capture valid addresses for multiple purposes.

Solution

The following section describes APIs, user exits, services, and other components.

The user can either add or edit customer's address during order creation or order modification. When the user chooses to add an address to the order, the address capture window is displayed.

If the customer's country and postal code are not captured, the default country and postal code of the enterprise are considered while capturing the customer's address. However, when the customer wants to provide an address with a different country, the user can select a country from the Country/Region list. To populate the list of countries, the getCommonCodeList API is called with the CodeType as COUNTRY. The getRegionList API returns a list of regions that satisfy input criteria.

The getCommonCodeList API is called to populate the Titles list in the Contact Information panel with the titles defined for the enterprise.

When the user selects the country, the appropriate address capture fields are displayed and the corresponding list of states is retrieved. The address capture window is commonly implemented across different screens in the application.

When the user opens the address capture window to edit an existing address on an order, the address attributes are pre-populated from the PersonInfo element. Based on the Country attribute in the PersonInfo element, the relevant fields are displayed on the address capture window.

To capture an address, the minimum inputs that are required are the enterprise code and the country.

The enterprise code is retrieved from the order or customer entity for which the address is being captured. If the customer's country is not already available, then the country is retrieved based on the logged-in user's locale.
After the country information is retrieved, the country and enterprise code are passed to the getStateRegionList API, which determines the region schema from the "Region Schema To Use For State Selection" rule and returns a list of the regions to be used by the State attribute in the PersonInfo element of the entity.
If the region schema uses a different region level, this can be provided in the mashup input as defined by the API. The results of this API call are used to populate the lists for State, Province, and so on. If no regions are retrieved, the list is replaced by a text field.

The CSR can enter multiple addresses, such as Ship To and Bill To. When the CSR enters only a customer's Bill To address, then the Ship To address panel displays a "Same as Bill To," which indicates that the CSR does not need to enter a shipping address unless it is different from the billing address. When the CSR saves the address, if only the billing address is entered, then it is passed as the shipping address to the manageCustomer API with the IsDefaultBillTo, IsBillTo, and IsShipTo attributes as "Y".

In the order creation or modification flow, the address capture window can behave in the following ways:

If the customer associated with the order has multiple addresses, the outputs of the getCompleteOrderDetails, getCompleteOrderLineList, and getCustomerDetails APIs are collectively used to display the list of available addresses for the customer. The user can either choose to select one of the listed addresses or modify the current address.
If the customer associated with the order does not have additional addresses, the user can only use or edit the available address.

Address verification

Customer's addresses are verified before saving to the order. The verifyAddress API is called to verify the address. The API in turn calls the YCDVerifyAddressWithAVSUE user exit that validates the input that is provided by the user. If all attributes are valid and the address is properly verified, the IsAddressVerified flag is updated appropriately. The user exit allows the application to interact with the Address Verification System (AVS) and return appropriate values to the verifyAddress API. The following values as returned as a result of address verification:

VERIFIED: The screen is closed and the address is marked as verified.
FAILED: The error reasons that are returned by the verifyAddress API are displayed at the top of the screen for the user to fix. If the user has permissions to override address verification errors, the option to approve the address is allowed. If the user selects "Apply", the address is assumed valid and returned as verified.
AVS_DOWN: The screen is closed and the address is marked as not verified, but considered to be valid.

If multiple addresses are returned or the ProceedWithSingleAVSResult attribute is returned with the value as N, the screen switches to a multiple address selection mode, where the user is presented with the addresses returned. If the user has the permission to override the address verification errors, the originally entered address is returned in the list of results from which the user can select an address.

Implementation

The following section describes the rules that you must configure.

You must configure the "Configure Country/Region and State Display Rules" appropriately. For more information, see the Sterling Business Center System Configuration.
Modifying addresses and overriding the address verification are permission controlled tasks. For more information about administering user group permissions, see Organization and participant modeling concepts.

For more information about the APIs and user exits, see the Javadoc.

End-user impact

The user can capture and validate addresses in the default and global formats.