Install Commerce Data Exchange: Async Client

Applies To: Microsoft Dynamics AX 2012 R3

Commerce Data Exchange: Async Client is part of the asynchronous system that shares data between the Microsoft Dynamics AX database and channel databases. Async Client is installed at the channel and communicates with the channel database. In addition to Async Client, Commerce Data Exchange includes Commerce Data Exchange: Async Server. Async Server is installed at headquarters and communicates with the Microsoft Dynamics AX database.

When you install Async Client, the Retail Salt Utility is also installed. The Retail Salt Utility provides extra encryption for the passwords and credentials that are associated with the Microsoft Dynamics AX 2012 for Retail system.

The Async Client Configuration Tool is also installed together with Async Client. This tool lets you test connections and specify whether to use streaming. The streaming option is ideal for initial high-speed data synchronization. However, for ongoing synchronization, the non-streaming option is more reliable. For more information, see Configure settings for Async Client.

To deploy Async Client on multiple computers in an environment, you can use the Retail mass deployment toolkit to deploy Async Client from a central location. For more information, see Mass deploy Retail components by using System Center Configuration Manager.

Before you install Async Client

• Determine how many instances of Async Client you want to install, and on which computers.

  In a basic deployment of Retail, one instance of Async Client is installed for each channel database. If you want to install more than one instance of Async Client on a single computer, you must run the Windows PowerShell installation scripts manually for subsequent installations. For more information, see Install Async Client by using Windows PowerShell.

• Select a service account for Async Client. For information about the requirements for service accounts, see Create service accounts.

• Create the channel database that will be used with this instance of Async Client. When you install a channel database, the groups that have permissions on the database are created. During the Async Client installation, the service user is added to this group. For more information, see Install a Retail channel database.

• On the computer where you plan to install this component, run the prerequisite validation utility to verify that system requirements have been met. For information about how to run the prerequisite validation utility, see Check prerequisites.

  For more information about the hardware and software requirements for Microsoft Dynamics AX, see the system requirements.

• The SQLCMD utility is required to install Async Client. This utility is typically installed with Microsoft SQL Server. If a version of SQL Server is not installed on the computer where you install Async Client, you can download and install Microsoft Command Line Utilities 11 for SQL Server to meet this requirement.

Option 1: Install Async Client by using Setup

Use this procedure to install Async Client by using the Setup wizard. If you install other Microsoft Dynamics AX components at the same time, the installation pages vary, depending on the components that you are installing.

1. Start Microsoft Dynamics AX Setup. Under Install, select Microsoft Dynamics AX components.

2. Advance through the first wizard pages.

3. If the Setup Support files have not yet been installed on this computer, the Select a file location page is displayed. The Setup Support files are required for installation. Provide a file location or accept the default location, and then click Next. On the Ready to install page, click Install.

4. On the Select an installation option page, click Microsoft Dynamics AX.

5. On the Select installation type page, click Custom installation, and then click Next.

6. On the Select components page, select Async Client, and then click Next.

7. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click Next.

8. On the Configure Async Client page, select the check box to configure Async Client by using Setup. If you clear this check box, the application files are installed, but Async Client is not configured.

   If you’re configuring Async Client, enter the following information:

   • Async Server URL – The URL for the instance of Async Server. Typically, the URL is in the format https://<server name>:port/<web application name>.

     If Async Server is installed in a cluster that has a load balancer, enter the URL to the service on the load balancer.

   • Channel database ID – The identifier in Microsoft Dynamics AX for the channel database that is used by the selected instance of Async Client.

   • User name and Password (Async Server connection) – The credentials for the user that connects to Async Server. These credentials must match the credentials that are specified in the channel database profile. Credentials are case sensitive. The credentials are used to identify and authenticate Async Client.

   • User name and Password (Async Client) – The credentials for the user that runs the Windows service for Async Client. The user does not have to be a domain account. The user can be a member of a workgroup on the local computer. Credentials are case sensitive.

   Optionally, click Test connection to verify that Async Client is configured correctly. For information about how to troubleshoot errors that you might encounter, see Troubleshoot issues in Async Server or Async Client.

   Click Next.

9. On the Select or specify a database to use with Async Client page, enter server and database information for the message database and the channel database that will be used by Async Client. Then click Next.

   You can connect to an existing channel database only. Setup does not create a new channel database if you enter a channel database name that doesn’t exist. If you specify a message database name that doesn’t exist, Setup creates a new message database.

10. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click Next.

11. On the Ready to install page, click Install.

12. After the installation is completed, click Finish to close the wizard.

Option 2: Install Async Client by using Windows PowerShell

Use this procedure to install Async Client manually by using Windows PowerShell. To install multiple instances of Async Client on the same computer, you must use a manual installation. Manual installations are often performed by businesses and organizations that automate deployments by using scripts.

Extract installation files

Use Microsoft Dynamics AX Setup to extract the files that are required for manual installation.

1. Start Microsoft Dynamics AX Setup. Under Install, select Microsoft Dynamics AX components.

2. On the Select installation type page, click Custom installation, and then click Next.

3. On the Select components page, select Async Client, and then click Next.

4. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click Next.

5. On the Configure Async Client page, clear the Configure Async Client option.

6. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click Next.

7. On the Ready to install page, click Install.

8. After the installation is completed, click Finish to close the wizard.

Configure settings in the sc-settings.xml file

After you extract the installation files by using Setup, you must configure settings in the sc-settings.xml file.

1. Open the folder where the Windows PowerShell scripts are installed. By default, the files are located at C:\Program Files (x86)\Microsoft Dynamics AX\60\CDX\Async Client\Tools.

2. Create a copy of the sc-settings.xml file for each instance of Async Client that you plan to deploy. We recommend that you not change the original file.

3. Open your copy of the sc-settings.xml file in Microsoft Visual Studio or a text editor, such as Notepad.

4. Enter a value for the following parameters.

   Parameter	Enter this value	Default value
   ChannelMessageDatabaseServer	The name of the server that hosts the message database. The script is case sensitive. For example, enter value=“DatabaseServer” />.	None
   ChannelMessageDatabaseServerNamedInstanceName	The name of the Microsoft SQL Server instance that hosts the message database. The format for a SQL Server instance name is either the server name or the full instance name. For example, valid formats are localhost, localhost\instance2, server1, and server1\instance2.	None
   ChannelMessageDatabaseName	The name of the message database.	None
   ChannelDatabaseServer	The name of the server that hosts the channel database.	None
   ChannelDatabaseServerNamedInstanceName	The name of the SQL Server instance that hosts the channel database. The format for a SQL Server instance name is either the server name or the full instance name. For example, valid formats are localhost, localhost\instance2, server1, and server1\instance2.	None
   ChannelDatabaseName	The name of the channel database.	None
   ServiceName	The name that is displayed for the service in the Services control panel item.	CommerceDataExchangeAsyncClientService
   SynchServiceHeadOfficeURL	The URL for the instance of Async Server. Typically, the URL is in the format https://<server name>:port/<web application name>.	None
   ServiceUser	The account that will be used to run the Async Client service. Enter the account in the form value=“Domain or Computer Name\User”.	None
   ServiceBinarySourceFolder	The folder where the .dll files for Async Client are installed. By default, the folder is located at C:\Program Files (x86)\Microsoft Dynamics AX\60\CDX\Async Client\Package.	None
   ServiceInstallFolder	The folder where Async Client files will be installed.	%SystemDrive%\AsyncClientService
   DataStoreName	The channel database ID in Microsoft Dynamics AX for the channel database that is used by the selected instance of Async Client. To find or set the channel database name, use the Channel database form in Microsoft Dynamics AX. (Click Retail > Setup > Retail scheduler > Channel integration > Channel database.)	None
   DataStoreUserName	The user name that Async Client uses to connect to Async Server. To find or set the user name, use the Channel database form in Microsoft Dynamics AX. (Click Retail > Setup > Retail scheduler > Channel integration > Channel database.) Credentials are case sensitive.	None
   ChannelMessageDatabaseServerOverride	The name of the channel database server, if the name differs from what was specified.	[ChannelMessageDatabaseServer]

5. Save your changes.

Run Windows PowerShell scripts to configure Async Client

After you configure the parameters in the sc-settings.xml file, you can run the Windows PowerShell scripts that configure Async Client.

1. On the server where you want to run the script, open Windows PowerShell to the folder where the scripts are installed. By default, the files are located at C:\Program Files (x86)\Microsoft Dynamics AX\60\CDX\Async Client\Tools.

   • If you’re using Windows Server 2012 or a later operating system, use Windows Explorer to open the folder where the scripts are installed. Then click File > Open Windows PowerShell > Open Windows PowerShell as administrator.

   • If you’re using Windows Server 2008 R2 or an earlier operating system, start Windows PowerShell as the administrator. Then, change the directory by using the following command: CD "<Path to directory>".

2. In the Windows PowerShell console, run the following command to create a Windows PowerShell credential object on the local computer for the application pool identity.

   $Cred = @((New-Object System.Management.Automation.PSCredential('domain\username',(ConvertTo-SecureString 'password' -AsPlainText -Force))))
   

   For more information about how to create credential objects, see Create Windows PowerShell Scripts that Accept Credentials.

3. Run the following command to create a credential object for the account that is used to connect to Async Server.

   $Cred += @((New-Object System.Management.Automation.PSCredential('domain\username',(ConvertTo-SecureString 'password' -AsPlainText -Force))))
   

4. Run the following command to deploy Async Client.

   .\DeployAsyncClient.ps1 -SettingsXmlFilePath <path> -TopologyXmlFilePath <path> -Credentials $Cred –Verbose $true
   

   Example:

   .\DeployAsyncClient.ps1 -SettingsXmlFilePath “C:\Program Files (x86)\Microsoft Dynamics AX\60\CDX\Async Client\Tools\sc-settings.xml” -TopologyXmlFilePath “C:\Program Files (x86)\Microsoft Dynamics AX\60\CDX\Async Client\Tools\sc-topology.xml” -Credentials $Cred –Verbose $true

After you install Async Client

1. Use the Async Client Configuration Tool to test the connections to Async Server, the channel database, and the channel message database. You can also use the utility to set advanced options. For more information, see Configure settings for Async Client.

2. After you have determined that all connections are working, run the distribution schedule that sends data to each channel database. Click Retail > Setup > Retail scheduler > Channel integration > Channel database. Click Full data sync, and then select the Full sync distribution schedule.