CCH® SureAddress™ for D365 Commerce User Guide

Updated: June 18, 2024

Installing CCH SureAddress

Overview

CCH SureAddress Retail for Microsoft Dynamics 365 for Finance and Operations is a plug-in that integrates CCH SureAddress Retail solution with Microsoft Dynamics 365 for Finance and Operations Commerce SDK. With CCH SureAddress Retail for Microsoft Dynamics 365 for Finance and Operations, you can validate addresses in the following ways:

  • Explicit Address Validation. When On demand validation option is selected for retail store, you can explicitly request address validation for a given address record by clicking the Validate Address button.
  • Automatic Address Validation. When Automatic validation option is selected for retail store, addresses will be automatically validated whenever an address record is saved.

How It Works

When address validation is requested in Store Commerce/CPOS, the plug-in sends the address information from Commerce to SureAddress API Web Service. The SureAddress API Web Service validates the address using third party address validation software (such as Perfect Address). The validated address is sent back to the plug-in through the SureAddress API Web Service, and the plug-in presents the updated address in the Store Commerce/CPOS user interface.

There are four steps to installing and setting up CCH SureAddress for Dynamics 365 for Finance and Operations Commerce:

  1. Import the Model Files
  2. Importing Licenses
  3. Building Models and Synchronizing the Database
  4. Create a Deployment Package
  5. Deploy and Apply the Package
  6. Install CCH SureAddress Plugins for Commerce

Importing the Model File

To import the CCHSureAddress for Dynamics 365 for Finance and Operations model file, do the following:

  1. Get the CCH SureAddress andd CCH SureAddress Retail for Dynamics365 ZIP file from CCH.

  2. On the VM/machine, open the folder where the latest CCH SureAddress for Dynamics365 zip package exists.

  3. Unzip the model file on your machine.

  4. Open Command Prompt in Administrator mode and execute the following commands (in this order):

    Note: If you install a model on a development environment that contains

customization to that model (in a higher layer), you may need to resolve code or metadata conflicts using Visual Studio.

  • cd "[path of the metadata store where model should be imported]\Bin"
  • ModelUtil.exe -import -metadatastorepath="[path of the metadata store where model should be imported]" -file="[path where model files are unzipped]\CCH_SureAddress-CCH Inc..axmodel"
    • ModelUtil.exe -import -metadatastorepath="[path of the metadata store where model should be imported]" -file="[path where model files are unzipped]\CCH_SureAddress_Retail-CCH Inc..axmodel"

Importing Licenses

  1. Get the license file from CCH based on the serial number of AX installed in your development environment. Create a Licenses directory at a location where you want to copy the license files (for example, C:\License). Copy the licenses to the Licenses directory.
  2. Run the following command to turn on maintenance mode. You should turn on maintenance mode before you import the license files and turn it off after the import is complete.
    • Microsoft.Dynamics.AX.Deployment.Setup.exe --metadatadir " [path of the metadata store]" --bindir "[path of the metadata store]" --sqlserver . --sqldatabase [databasename] --sqluser [User with sysadmin privileges] --sqlpwd [userpwd] --setupmode maintenancemode --isinmaintenancemode true
  3. Restart the AOS.
  4. For Address Validation license execute the following on command prompt.
    • cd "[path of the metadata store]\bin"
    • Microsoft.Dynamics.AX.Deployment.Setup.exe --setupmode importlicensefile --metadatadir "[path of the metadata store]" --bindir "[path of the metadata store]" --sqlserver . --sqldatabase [databasename] --sqluser [User with sysadmin privileges] --sqlpwd [userpwd] --licensefilename "[location of License directory][Companyname]_ [wolterskluonmicrosoftcom_CCHSureAddress].xml"
      • Microsoft.Dynamics.AX.Deployment.Setup.exe --setupmode importlicensefile --metadatadir "[path of the metadata store]" --bindir "[path of the metadata store]" --sqlserver . --sqldatabase [databasename] --sqluser [User with sysadmin privileges] --sqlpwd [userpwd] --licensefilename "[location of License directory][Companyname]_ [wolterskluonmicrosoftcom_CCHSureAddressRetail].xml"
  5. After the license are imported, log in to Microsoft Dynamics and go to System administration > Setup > License configuration.
  6. Verify all CCH licenses are present and checked.
  7. Run the following command to turn off maintenance mode once the license files are imported.
    • Microsoft.Dynamics.AX.Deployment.Setup.exe --metadatadir " [path of the metadata store]" --bindir "[path of the metadata store]" --sqlserver . --sqldatabase [databasename] --sqluser [User with sysadmin privileges] --sqlpwd [userpwd] -- setupmode maintenancemode --isinmaintenancemode false
  8. Restart the AOS.

Building Models and Synchronizing the Database

  1. Open Visual Studio.
  2. Click Dynamics AX > Model Management > Refresh models.
  3. Click Dynamics AX > Build Models. The Full Build dialog displays.
  4. Select the first check box (Select all) on the packages tab.
  5. Select the Options tab and select following:
    • Build Pre-Compiled Form
    • Build Reports
    • Synchronize Database
    • Build cross reference data
  6. Click Build and synchronize the database. This can take more than an hour to complete.
  7. Once the build is complete, restart IIS and SQL server.

Creating the Deployment Package Using Visual Studio

  1. In Visual Studio, select Dynamics AX > Deploy > Create Deployment Package.
  2. Select the following packages:
    • CCHSureAddress
    • CCHSureAddress Retail
    • Directory
  3. Provide the package file location in the dialog box.
  4. Click Create to generate the package. Get the license file from CCH based on the serial number of AX installed in your production environment. Unzip the package. Add license files to unzipped package under the AOSService\Scripts\License folder.
  5. Zip the package again, now with the license files.

Deploying and Applying the Package to Lifecycle Services

  1. Log in to lcs.dynamics.com.
  2. Select the Shared Asset library and do the following:
    • Select the Software deployable package asset type.
    • Click the plus sign (+) to upload the package.
    • Enter the name and description of the package you are uploading.
    • Select the uploaded package.
    • Click Publish.
  3. Click the project in Life Cycle Service where the package needs to be installed.
  4. Click Asset Library. You may need to scroll to the right for this option to be visible.
  5. In the Asset library, click Import to import the package.
  6. Return to the project's home screen and select the virtual machine environment.
  7. Verify the virtual machine is running.
  8. Click Maintain, and then click Apply updates. A window displays, showing the eleven steps of deployment.

Install CCH SureAddress Plugins for Commerce

  1. Get the CCH SureAddress Commerce and CCH SureAddress StoreCommerce for Dynamics365 ZIP file from CCH.
  2. On the VM/machine, open the folder where the latest CCH SureAddress for Dynamics365 zip package exists.
  3. Unzip the model file on your machine.
  4. Execute the followiing command in Powershell from the path of the metadata store
    • CCH SureAddress Commerce.exe install
    • CCH SureAddress StoreCommerce.exe install

Note: Before installing the CCH SureAddress Commerce plugins , make sure Microsoft Commerce Scale Unit and Store Commerce are installed.

Configuring for D365 Finance & Operations

To configure your CCH SureAddress for Dynamics 365 for Finance and Operations settings, do the following:

  1. Do one of the following:

    • Go to Workspaces > CCH SureAddress Workspace, and then click CCH SureAddress Address Validation Setup.
    • Go to Modules > Common > CCH SureAddress tab > CCH SureAddress Address Validation Setup.

  2. Select General on the left side of the dialog.

  3. Enter the CCH SureAddress Validation URL, Client Number, and Validation Key.

  4. Select Address validation settings on the left side of the dialog.

  5. Set Enable automatic address validation to Yes if you want addresses to be validated any time an address record is saved.

  6. Set Choose Best option to Yes if you want best address to be submitted automatically when validating an individual address. You will not receive multiple options to choose from.

  7. The Multiple option display limit is no longer used for Address Validation. Leave the default setting as "1."

  8. Select the Select country/region to validate tab, and then specify the country or region for which CCH SureAddress should validate addresses.

    Note: Currently only USA and Canada is supported for address validation.

  9. Select the Address keywords to skip tab, and then specify keywords in street address lines that should be ignored during address validation.

    Example: Ordinarily, a line that starts with "ATTN:" or "C/O" will cause address validation to fail. If you enter these keywords in the Address keywords to skip tab, those lines will be ignored during validation.

  10. Click Save.

Configuring for D365 Commerce SDK

Retail Store Settings

There are various settings that are added to the retail store card by the plug-in. They affect the SureAddress validation in Store Commerce, and Cloud Point of Sale. All of the settings are store specific, so you can have different settings for each store if you want to. The settings are as follows:

Setting Purpose
SureAddress URL The URL used to validate address for the retail store.
SureAddress client number Client number for the SureAddress API
SureAddress validation key Validation key for the SureAddress API
Enable SureAddress If this is checked, SureAddress Store Commerce/CPOS plug-in will send request to SureAddress API and validated address will be recieved in the response.
Validation mode Determines when address is validated in Store Commerce/CPOS. If it is set to "Automatic", addresses will be automatically validated whenever an address record is saved. If it is set to "On Demand" addresses will be validated by clicking the Validate Address button in Store Commerce/CPOS.
Countries to Validate Add the country for which CCH SureAddress should validate addresses.

Note: Currently only USA and Canada is supported for address validation.

Setting up the Distribution Schedule

The plug-in data that is configured in D365 headquarters has to pushed down to the Retail Server and offline databases before the Store Commerce/CPOS plug-ins can be used.

To initialize the SureTax distribution schedule:

  1. Go to Retail and Commerce > Headquarters setup > Commerce scheduler > Initialize Commerce scheduler.
  2. Go to Retail and Commerce > Retail and Commerce IT > Distribution schedule.
  3. Go to the STA-0001 job and set a channel database group.

Access Levels

CCH SureAddress provides two levels of access: one for Basic Users and one for Power Users.

Power Users have full access to all address validation functionality and plug-in forms, including the following forms:

  • Address Validation Settings-
    • Individual Address Validation

Basic users have the following access:

  • View Only access to the Address Validation Settings form
  • Full access to the following address validation functionality and plug-in forms:
    • Individual Address Validation

Validating Addresses

Validating Individual Addresses

To validate an individual address in Dynamics 365 Commerce, do the following:

  1. Enter an address on the Store Commerce or CPOS customer form.
  2. Click Validate Address at the bottom of the window.
  3. Select the correct address and click OK.
  4. Click Save. The validated address is saved.