CCH® SureAddress™ for SalesForce Commerce Cloud User Guide

Updated: August 13, 2024

Summary

The CCH® SureAddress™ cartridge for Salesforce Commerce Cloud provides a quick integration for real-time address verification for USA and CAN addresses.

This guide is for SGJC (SiteGenesis) and Storefront Reference Architecture (SFRA). If installing for SFRA, skip the ‘Custom Code for SiteGenesis’ section in this document and follow directions in the ‘CCH SureAddress SFRA Integration Guide.docx’ documentation

Component Overview

Functional Overview

CCH SureAddress is the advanced address correction solution optimized for billing, taxation, direct marketing, and more. CCH SureAddress enables companies of all sizes to improve operations by correctly identifying situs down to complete ZIP+4.

CCH SureAddress takes incomplete, misspelled, or otherwise incorrect addresses and scrubs them down using a robust algorithm to determine the correct address with complete ZIP+4. CCH SureAddress is delivered as a real-time, software-as-a-service (SaaS), cloud computing methodology.

Integration of real-time address validation uses CCH SureAddress API (REST web service).

Use Cases

The CCH SureAddress cartridge can be used for address validation on the Salesforce Commerce

Cloud storefront using the CCH SureAddress API. It includes support for the following use cases:

SiteGenesis:

  • Address validation for customer address data within Create/Edit Account and Address Book touchpoints.
  • Address validation for Shipping Address during Checkout.
  • Address validation for Billing Address during Checkout.

SFRA:

  • Address validation for customer address data within Create/Edit Account and Address Book touchpoints.
  • Address validation during Checkout for the following stages:
    • Shipping
    • Payment

Important:

  • For the above address validation integrations for SiteGenesis and SFRA, the following flows are integrated with by the CCH SureAddress cartridges:
    • Disabled Flow. Proceeds with native behavior for the following cases: CCH SureAddress is disabled (set in custom preferences), country is not supported, and the addresses are identical.
    • Error Flow. When CCH SureAddress returns an error, the error message is displayed. If the user clicks OK, then the address will be saved. If the user clicks the X button in the top right, the user can return to the screen and edit the address as needed.
    • Success Flow. When CCH SureAddress returns a successful response, the window will display options to Use Orig or Use Verified address. If the user clicks Use Orig, then the original address data entered by the user will be saved. If the user clicks Use Verified, then the verified address returned by CCH SureAddress API will be saved.
  • An active CCH SureAddress account is required to use this cartridge.
  • This cartridge is limited to the following CCH SureAddress API Usage:
    • PostRequest : Used for address validation
  • CCH SureAddress only supports address validation for USA/CAN addresses.
  • Address validation is based on address data:
    • Address line 1 (number and street name)
    • City
    • State
    • Zip5
    • Only USA/CAN Addresses are supported

Compatibility

This cartridge has been tested and is compatible with:

  • Salesforce Commerce Cloud Release 20.9.
  • SFCC SFRA 5.0.1
  • Locale EN

Privacy

Address specific data are the only customer data sent to CCH SureAddress for address validation.

Setup and Implementation

Setup

  1. Import the "int_sureaddress" cartridge into the Salesforce Commerce Cloud UX Studio Workspace (Eclipse):
    1. Open UX Studio (Eclipse).
    2. If not already connected, create a Digital Connection to your Sandbox (or the environment you want to upload code to).
    3. Click File > Import > General > Existing Projects Into Workspace.
    4. Browse to the directory where you saved the "int_sureaddress" cartridge.
    5. Click Finish.
    6. Click OK when prompted to link the cartridge to the sandbox and upload.
    7. (Skip for SFRA) Repeat the above process for the SiteGenesis project (you can import from its root directory), which will be customized later in the custom code section. This will add three cartridges to your UX Studio Workspace: app_storefront_controllers, app_storefront_ core, and app_storefront_pipelines.
  2. Import CCH SureAddress metadata and service using Site Import (SureAddressSiteImport.zip):
    1. Log in to the Salesforce Commerce Cloud Business Manager.
    2. Navigate to Administration > Site Development > Site Import & Export.
    3. In the Import section, set Upload Archive = ‘Local’.
    4. Click Choose File and select the zip file metadata/SureAddressSiteImport.zip.
    5. Click Upload and confirm that the file was uploaded.
    6. Select uploaded file and click Import.
    7. Notes for files in Site Import zip: services.xml - imports the services (can omit if services are already setup on your instance). system-objecttype-extensions.xml - imports meta data including custom preferences and attribute.

Configuration

  1. Add "int_sureaddress" to the effective cartridge path:
    1. Log in to the Salesforce Commerce Cloud Business Manager.
    2. Select Administration > Sites > Manage Sites.
    3. Select the desired site.
    4. Select the Settings tab.
    5. Add int_sureaddress: to the start of the Cartridges field. (can be on right as well if only installing SFRA, please note to separate cartridges with ':')
    6. Click Apply.
  2. Update SureAddress.http.PostRequest service with correct credentials:
    1. Log in to the Salesforce Commerce Cloud Business Manager.
    2. Select to Administration > Operations > Services.
    3. Click CCH SureAddress API PostRequest.
    4. Remove the dummy values and update the Credentials.
    5. The URL should point to either the development or production tax API Endpoint provided by CCH SureAddress (the URL is in the following format: https:///SureAddress.asmx/PostRequest).
    6. The user name is the Client Number provided by CCH SureAddress.
    7. The password is the Validation Key provided by CCH SureAddress.
    8. Click Apply when finished.
  3. Configure CCH SureAddress Configurations using the Salesforce Commerce Cloud Business Manager:
    1. Log in to the Salesforce Commerce Cloud Business Manager.
    2. Select the desired site from the tabs across the top of the page.
    3. Select Site Merchant Tools > Preferences > Custom Preferences.
    4. Click CCH SureAddress Configurations.
    5. Update configurations for CCH SureAddress here. You can view the tooltips for descriptions for each setting.

Custom Code for SiteGenesis

Skip Custom Code section if only installing for SFRA.

Note: It is the expectation that these custom code snippets will modify the references of actual storefront cartridges. CCH SureAddress (int_sureaddress) was developed assuming storefront cartridge naming conventions are as followed:

  • app_storefront_core, app_storefront_controllers (Note: If your SiteGenesis controllers cartridge is not named app_storefront_controllers, you must edit SureAddress.js file located at int_sureaddress/cartridge/controllers and replace ‘app_storefront_controllers’ at lines 14 and 15 with the name of your controllers cartridge)
  1. Copy int_sureaddress/cartridge/js/sureaddress.js to {{siteRoot}}/app_storefront_core/cartridge/js.
  2. Locate the file app.js located in {{siteRoot}}/app_storefront_core/cartridge/js/app.js.
  3. Update {{siteRoot}}/app_storefront_core/cartridge/js/app.js by inserting two lines in separate parts of the file in the below code snippets (inserted lines are in bold):

*Insert “*sureaddress = require('./sureaddress'),” below “validator = require(…)” line as shown below near top of app.js (see bolded code below):

**Start Code**

'use strict';

var countries = require('./countries'),

dialog = require('./dialog'),

minicart = require('./minicart'),

page = require('./page'),

rating = require('./rating'),

searchplaceholder = require('./searchplaceholder'),

searchsuggest = require('./searchsuggest'),

tooltip = require('./tooltip'),

util = require('./util'),

validator = require('./validator'),

sureaddress = require('./sureaddress'),

tls = require('./tls'); };

**End Code**

  • Insert “sureaddress.init();” in init() function in app.js (see bolded code below):

**Start Code**

var app = {

init: function () { if (document.cookie.length === 0) {

$('

').addClass('browser-compatibility-alert').append

($('

').addClass('browser-error').html(Resources.COOKIES_DISABLED)).appendTo ('#browser-check');

}

initializeDom();

initializeEvents();

// init specific global components

countries.init();

tooltip.init();

minicart.init();

validator.init();

sureaddress.init();

rating.init();

searchplaceholder.init();

// execute page specific initializations

$.extend(page, window.pageContext); var ns = page.ns;

if (ns && pages[ns] && pages[ns].init) {

pages[ns].init();

}

// Check TLS status if indicated by site preference

if (SitePreferences.CHECK_TLS === true) {

tls.getUserAgent();

}

} };

**End Code**

  1. Next, locate the file account.js located in {{siteRoot}}/app_storefront_core/cartridge/js/pages/account.js.
  2. Update account.js by inserting two separate lines of code and commenting out the apply button's on-click hook as shown in the below code snippets (inserted/updated lines in bold):

*Insert “*sureaddress = require('../sureaddress');” line and put a comma ( , ) after the line starting with "validator" near top of account.js (see bolded code below):

**Start Code**

var giftcert = require('../giftcert'),

tooltip = require('../tooltip'),

util = require('../util'),

dialog = require('../dialog'),

page = require('../page'),

login = require('../login'),

validator = require('../validator'),

sureaddress = require('../sureaddress');

**End Code** *

Insert “sureaddress.init();” under validator.init() in account.js (see bolded code below):

**Start Code**

}

});

validator.init();

sureaddress.init();

}

**End Code**

Comment out code starting with line with '// SUREADDRESS, comment out' up to line with 'end edit for SUREADDRESS' apply button’s on-click hook in initializeAddressForm() function in account.js:

**Start Code**

function initializeAddressForm() { 

    var $form = $('#edit-address-form');

    $form.find('input[name="format"]').remove();

    tooltip.init();

    //$("<input/>").attr({type:"hidden", name:"format", value:"ajax"}).appendTo (form);

    $form.on('click', '.apply-button', function (e) {

   // SUREADDRESS, comment out 

   /*

        e.preventDefault();

        if (!$form.valid()) {

            return false;

        }

        var url = util.appendParamToURL($form.attr('action'), 'format', 'ajax');

        var applyName = $form.find('.apply-button').attr('name');

        var options = {

            url: url,

            data: $form.serialize() + '&' + applyName + '=x',

            type: 'POST'

        };

        $.ajax(options).done(function (data) {

            if (typeof(data) !== 'string') {

                if (data.success) {

                    dialog.close();

                    page.refresh();

                } else if (data.error) {

                    page.redirect(Urls.csrffailed);

                } else {

                    window.alert(data.message);

                    return false;

                }

            } else {

                $('#dialog-container').html(data);

                account.init();

                tooltip.init();

            }

        });

        end edit for SUREADDRESS */ 

    })

.on('click', '.cancel-button, .close-button', function (e) {

**End Code**

  1. Next, locate the file Resource.ds located in {{siteRoot}}/app_storefront_core/cartridge/scripts/util/Resource.ds
  2. Update Resource.ds by inserting two lines of code below the line with ‘resetPaymentForms’ (inserted lines in bold):

Insert two lines of code (starting with sureaddressVerifyAddress and sureaddressUpdateAddress) to urls variable declaration below resetPaymentForms line in Resource.ds (see bolded code below):

**Start Code**

ResourceHelper.getUrls = function(pageContext) {

var URLUtils = require('dw/web/URLUtils');

var Resource = require('dw/web/Resource');

// application urls var urls = {

…

…

resetPaymentForms : URLUtils.url(…

sureaddressVerifyAddress : URLUtils.https('SureAddress-VerifyAddress').toString(),

sureaddressUpdateAddress : URLUtils.https('SureAddress-UpdateAddress').toString(),

compareShow : URLUtils.url('Compare-Show').toString(),

**End Code**

  1. Once all the custom code updates are complete, you will build SiteGenesis with gulp or grunt. This will build the client code in app_storefront_core that will need to be uploaded to your SandBox via the below step.

  1. Once the above build is complete, upload to your SandBox via UX Studio’s ‘Upload Cartridges’ command for your Digital Connection.

External Interfaces

All requests are completed through CCH SureAddress API (Web Service) via REST. For the full reference guide contact your CCH SureAddress representative.

Operations and Maintenance

Data Storage

Other than custom preferences, no CCH SureAddress specific data is stored in Salesforce Commerce Cloud.

Availability

The functionality of this cartridge depends on the availability of CCH SureAddress service.

User Guide

Business Manager

CCH SureAddress Site Preferences

The following is an outline of all of the configuration options available in Merchant Tools > Preferences > Custom Preferences > CCH SureAddress Configurations.

  • SureAddress Integration Enabled? Activate the extension for the entire site by selecting Yes.
  • Global Business Unit. The business unit that will be sent to CCH SureAddress for all API requests. The maximum length of business unit is 20 characters.
  • Client Tracking. Value for Client Tracking field to be sent with all CCH SureAddress API requests. The maximum length is 16 characters.

Known Issues and Limitations

  • Address fields do not accept ‘\’ character
  • int_sureaddress_sfra
    • Multi-Address checkout is not supported

There are no other known existing issues. Please report any issues to CCH support at salestax.com.

Release History

Version Date Changes
17.1.0 08/01/2017 Initial release
18.1.0 10/17/2018 Recertification
19.1.0 06/28/2019 Recertification SGJC (SiteGenesis), add SFRA support, removed Minimum Score
20.1.0 8/31/2020 Recertification SGJC (SiteGenesis) and SFRA support. Added unit tests, integration, test, removed used of imports() from modules, and fixed issue, so you will no longer get an address validation prompt if resolved and original addresses are the same.