Microsoft Dynamics AX

Implementation guide for

Commerce Data Exchange
White Paper

This document describes recommended patterns and practices

for setting up, configuring, customizing, monitoring, and
diagnosing Commerce Data Exchange: Synch Service and
Commerce Data Exchange: Real-time Service.

Bill Zhu and Josef Schauer

June 2013

http://www.microsoft.com/dynamics/ax
Table of Contents
Introduction ................................................................................................ 4

Commerce Data Exchange: Synch Service ................................................... 4

Introduction and overview ..................................................................................................... 4
Deployment topology ............................................................................................................ 5
Implementation planning ....................................................................................................... 5
Hardware and software requirements ...................................................................................... 5
Network configuration ........................................................................................................... 6
Configuring or bypassing IPsec ............................................................................................ 6
Configure IPsec (no VPN) .................................................................................................... 6
Bypass the IPsec requirement (with a VPN) ........................................................................... 7
Open the firewall ............................................................................................................... 7
Install Synch Service ............................................................................................................. 7
Troubleshoot the installation .............................................................................................. 12
Create an instance of Synch Service .......................................................................................13
Configure Synch Service settings ...........................................................................................15
Configure Synch Service logging ............................................................................................18
Advanced installation options for Synch Service .......................................................................19
Set up a forwarder instance of Synch Service ....................................................................... 19
Run multiple instances of Synch Service .............................................................................. 23
Synch Service Pack Viewer ....................................................................................................24
Save package files for viewing in Pack Viewer ...................................................................... 25
File formats...................................................................................................................... 26
Set up Retail Scheduler ........................................................................................................26
Scheduler jobs and subjobs................................................................................................ 27
Initialize default jobs ......................................................................................................... 28
Create scheduler subjobs ................................................................................................... 28
Transfer field list............................................................................................................... 30
From table filters .............................................................................................................. 31
Scheduled by information .................................................................................................. 31
Configure jobs .................................................................................................................. 32
Create a temporary staging database for P jobs.................................................................... 32
Copy scheduler job ........................................................................................................... 33
View the scheduler log ...................................................................................................... 33
Data distribution settings ......................................................................................................34
Distribution locations ......................................................................................................... 34
Create distribution locations ............................................................................................... 34
Distribution location list ..................................................................................................... 35
Distribution schedule ......................................................................................................... 36
Preactions and actions ....................................................................................................... 37
Filter on action creations.................................................................................................... 37
Table distribution .............................................................................................................. 37
Distribution types ............................................................................................................. 38
Parent/child relationships ................................................................................................... 38
Create a new distribution ................................................................................................... 38
Insert the default table distribution ..................................................................................... 40
How table links work ......................................................................................................... 40
Set up table links .............................................................................................................. 40

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

 Set up communication profiles ...............................................................................................42
Synch Service profiles ....................................................................................................... 42
Create Synch Service upload options ................................................................................... 43
AOS profiles ..................................................................................................................... 44
Database profiles .............................................................................................................. 45
Customize Synch Service ......................................................................................................46
Create the table in Microsoft Dynamics AX ........................................................................... 46
Create the table in the POS database .................................................................................. 46
Define the table schema in Microsoft Dynamics AX ................................................................ 47
Define a normal subjob in Microsoft Dynamics AX ................................................................. 47
Define transfer fields ......................................................................................................... 48
Define a scheduler job ....................................................................................................... 48
Define a schedule to run the job ......................................................................................... 49
Monitoring Synch Service ......................................................................................................50
Log files........................................................................................................................... 50
Synch Service message database ....................................................................................... 50
Synch Service messages form in Microsoft Dynamics AX ........................................................ 52
Troubleshooting with error codes ...........................................................................................52
Error codes ...................................................................................................................... 52
Troubleshoot common issues with data packages ................................................................. 55

Commerce Data Exchange: Real-time Service ........................................... 57

Introduction and overview ....................................................................................................57
Install and set up Real-time Service .......................................................................................57
Prerequisites for installing Real-time Service ........................................................................ 57
Server certificate installation .............................................................................................. 58
Install Real-time Service .................................................................................................... 61
Uninstall Real-time Service ................................................................................................ 62
Configure Real Time Service ..................................................................................................63
Configure a Real-time Service profile in Microsoft Dynamics AX .............................................. 63
Configure Real-time Service settings ................................................................................... 64
Configure Real-time Service for POS ................................................................................... 65
Real-time Service customization guide....................................................................................66
Add extension methods in Microsoft Dynamics AX ................................................................. 66
Example customization of Real-time Service......................................................................... 66
Calling extension methods from a POS client ........................................................................ 67
Debugging Real-time Service ............................................................................................. 67
Troubleshoot Real-time Service .............................................................................................72
N-1 setup and configuration ..................................................................................................73
Example .......................................................................................................................... 73
Goal ................................................................................................................................ 73
Set up and configure N-1 support ....................................................................................... 73

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Introduction
This white paper provides information and resources to help you successfully deploy and configure
Microsoft Dynamics AX 2012 R2 Commerce Data Exchange. It addresses deployment planning,
hardware configuration, software installation, configuration, customization, best practices, monitoring,
and troubleshooting.

Commerce Data Exchange: Synch Service

Introduction and overview
Microsoft Dynamics AX for Retail Commerce Data Exchange: Synch Service is the integrated service
that periodically replicates data between the head office database and store databases, and among
store databases.
Synch Service aggregates data into the fewest packages possible and multicasts them, updating
multiple recipients with information such as price changes while minimizing network load.
Synch Service runs as a Microsoft Windows service that listens for incoming requests or packages. If
the service receives a read instruction, it connects to the source database, reads data, and stores the
data in a data package file. All data transfer requests, such as requests to send data to a store or
upload point of sale (POS) sales transactions, are initiated by Microsoft Dynamics AX for Retail
Scheduler, whereas Synch Service supplies the data transfer mechanism.
A package can contain data from more than one database table. After the requested data has been
read, what happens next depends on how your organization’s Synch Service instances are configured.
In a basic configuration, as described in Deployment topologies for Retail, Synch Service at the head
office takes data from Microsoft Dynamics AX, creates the data package, and sends it to the store.
Synch Service at the store then inserts the data in the appropriate database.
In a forwarder configuration, as described later in this document, Synch Service forwards the package
to another instance of Synch Service. The forwarder configuration is used for load balancing, resulting
in better performance and scalability.
You can also distribute the communication load at the head office by running multiple head office
instances of Synch Service. For more information about this configuration option, see the Advanced
installation options for Synch Service section.
The following table lists the subcomponents of Synch Service.

Subcomponent Description
Synch Service Synch Service (DBServer.exe) is the data replication service. It handles
data transfer between Retail databases at the head office and in the
stores.

Synch Service Settings Synch Service Settings (DBServerUtil.exe) is the configuration utility for
Synch Service. It starts the Synch Service Settings Wizard, where you
can enter information to configure an instance of Synch Service.

Synch Service Pack Viewer Pack Viewer (DDPackView.exe) is a tool for inspecting the data included
in the packages that Synch Service sends and receives.

Transaction Automation Client The Transaction Automation Client (TransAutomClient.dll) is a .NET

feature that manages communication between Microsoft Dynamics AX
and Synch Service.
Note: TransAutomClient.dll is a prerequisite for Retail Headquarters. This
means that Synch Service must be installed on all instances of
Application Object Server (AOS) and on each client computer, even if you
do not intend to use those particular instances of Synch Service.

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Deployment topology
The following diagram illustrates the deployment topology.

Store Environment
Dynamics AX Headquarter Environment

Synch
Service

AX Database POS Terminal Store Database

Synch
Service
POS Terminal

Real-time
Service
Web Store Environment

Communications
Synch
AOS Service

CRT Database

Web Store/CRT

Implementation planning
For information about planning, see the Microsoft Dynamics AX 2012 Implementation Planning Guide,
which provides guidance to system architects, consultants, and IT professionals involved with planning
a Microsoft Dynamics AX 2012 implementation. Topics include the Microsoft Dynamics AX 2012
architecture, implementation methodology, and hardware and software requirements and planning.
This document includes information for Microsoft Dynamics AX 2012 R2.

Hardware and software requirements

For information about system requirements, see Microsoft Dynamics AX 2012 System Requirements,
which provides information about the hardware and software requirements for Microsoft Dynamics AX
2012. Before installing Microsoft Dynamics AX, make sure that the system you are working with meets
or exceeds the minimum hardware and software requirements.

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Network configuration
To help secure communications between Microsoft Dynamics AX (at the head office) and retail
channels, a virtual private network or Internet Protocol security (IPsec) is required to help protect the
data being transmitted over the Internet, if the computers for the retail channel are not on the same
secure network as the server where Microsoft Dynamics AX is installed.

Configuring or bypassing IPsec

Synch Service requires a specific IPsec encryption and authentication configuration. The next section
provides instructions for setting up this minimum configuration. If you use another method to secure
data transport, such as a virtual private network (VPN), you can bypass the IPsec requirement for
Synch Service, as described in the Bypass the IPsec requirement (with a VPN) section.

Configure IPsec (no VPN)

This procedure must be completed on every computer where Synch Service is installed, including the
AOS computer and all Microsoft Dynamics AX client computers.
Note: On computers that are on a domain, domain policies override the local policies described in this
section. Consult the domain administrator to determine whether you have to complete this procedure.
1. Click Start > Administrative Tools > Local Security Policy. You can also open Local Security
Policy by typing secpol.msc in the search or Run box.
2. Right-click IP Security Policies on Local Computer, and then click Create IP Security Policy.
3. In the IP Security Policy Wizard, provide the requested information. On the Requests for Secure
Communication page, clear the Activate the default response rule check box. On the final
page of the wizard, select the Edit properties check box, and then click Finish.
4. In the Properties dialog box for the policy, clear the Use Add Wizard check box, and then click
Add.
5. In the New Rule Properties dialog box, on the IP Filter List tab, click Add.
6. In the IP Filter List dialog box, type a name for the filter, clear the Use Add Wizard check box,
and then follow these steps:
a. Click Add.
b. On the Addresses tab, select Any IP Address in both fields.
c. On the Protocol tab, select TCP, select From for any port, select To for this port, and then
type the port number that you specified as the server port for Synch Service communications.
By default, the port number is 16750.
d. On the Description tab, type a name for this filter, and then click OK.
e. Click OK twice to close the IP Filter List dialog box.
7. On the IP Filter List tab, select the new filter list.
8. In the New Rule Properties dialog box, on the Filter Action tab, clear the Use Add Wizard
check box, and then click Add.
9. In the New Filter Action Properties dialog box, follow these steps:
a. On the General tab, type a name for the filter action.
b. On the Security Methods tab, select Negotiate security, click Add, select Integrity and
encryption, and then click OK.
c. Click OK.
10. On the Filter Action tab, select the new filter action.

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

11. In the New Rule Properties dialog box, on the Authentication Methods tab, click Add.
12. Select the authentication method to use, specify any required settings, and then click OK.
13. Select the new authentication method, click Move Up until the new method is at the top of the
list, and then click Close.
14. In the New IP Security Policy Property dialog box, click OK.
15. In the Local Security Policy console, right-click the new policy, and then click Assign.

Bypass the IPsec requirement (with a VPN)

If you use a method other than IPsec to help secure data transport, such as a VPN, you can bypass
the IPsec requirement in Synch Service.
1. In Microsoft Dynamics AX, click Retail > Setup > Retail scheduler > Channel integration >
Commerce Data Exchange: Synch Service profiles. Select the profile for which to bypass
IPsec, select Disable IPsec, and then click Close.
2. On the Synch Service computer, run Synch Service Settings (Start > All Programs > Microsoft
Dynamics AX 2012 > Commerce Data Exchange: Synch Service > Commerce Data
Exchange: Synch Service Settings) as an administrator, click Next until you reach the Synch
Service Properties page, select Disable IPsec, and then click Close.

Open the firewall

To establish communications between computers in the organization, you must open the firewall on
any computer where Synch Service is installed.
1. On the head office communications server, open the firewall to Synch Service.
2. On the store communications server, open the firewall to Synch Service.
For instructions, see the PCI Implementation Guide.

Install Synch Service

After you have downloaded a copy of Microsoft Dynamics AX 2012 R2 from the PartnerSource website
(logon required), follow these steps to install Synch Service. These steps must be repeated on all
computers on which the service needs to be installed.
1. Open the folder where you have downloaded Microsoft Dynamics AX 2012 R2.

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

2. Right-click the setup file, and then click Run as administrator.
The Microsoft Dynamics AX 2012 R2 installation form opens.

3. Under Install, click Microsoft Dynamics AX components to select the components to install.
The Microsoft Dynamics AX 2012 Setup wizard opens.

4. Click Next to continue the installation.

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

5. Click I accept the license terms to continue the installation.

6. The next page provides options for adding and modifying components, and for removing
components. Select Add or modify components, and then click Next.

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

7. Under Retail Components > Commerce Data Exchange, select Synch Service. When
installing at the head office, you should also select .NET Business Connector.

8. Prerequisite validation runs and checks that all the dependencies for installing the selected
components are met. If any errors are displayed, click the link to download and install the
prerequisites.

10

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

9. Click Next. The Synch Service configuration page opens.

If you select the Configure Synch Service check box, you are required to create a message
database for Synch Service and specify an account to run it. Otherwise, you can use the Synch
Service Settings tool to do this after installation.
10. Enter information in the following fields.

Field Description
Server name The computer that hosts the SQL Server instance on which the Synch Service
message database is created.

Database name The name of the message database for Synch Service.

User name The user account to use to run Synch Service.

If Synch Service is installed at the head office, the account must be a valid
Microsoft Dynamics AX user. To check whether a domain account is a valid
Microsoft Dynamics AX user, go to System administration > Common >
Users > Users.
If Synch Service is set up to run on the retail channel side, use a valid user
account on the computer that runs the Synch Service instance. The account
that you select must have read and write permissions to the channel database.

Password The password for the user account.

11

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

11. Click Next, and then follow the rest of the wizard pages to install Synch Service, create the
service, and create the message database.

Troubleshoot the installation

On the final page of the wizard, click the View log file link to see what happened during the
installation process.
The setup logs are located in a time-stamped folder that you can find under the Setup Logs folder
under the installation folder.

12

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Create an instance of Synch Service
If no service instances were created during installation, the Synch Service Settings tool can be used to
set up service instances and configure other properties of the service.
1. Start the Synch Service Settings tool by clicking Start > All Programs > Microsoft Dynamics
AX 2012 > Commerce Data Exchange > Synch Service > Service Settings.
Note: Administrator privileges are needed to run the Synch Service Settings tool.

When you start the tool, the following dialog box opens.

13

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

 The following table describes the controls that are available.

Control Description
Server Name The service instance that you are configuring.

Add Create a new instance by using the name entered in the Server Name field.

Remove Delete the instance entered in the Server Name field.

All Servers Display all existing service instances on the local computer. Select an instance to
configure it.

Start Start the selected service instance.

Stop Stop the selected service instance.

Packet Viewer Open Synch Service Pack Viewer.

View license agreement Display the applicable license information.

2. Click Add. The following dialog box opens.

3. In the Server name field, enter the name of the computer that hosts the SQL Server instance on
which the Synch Service message database is created. In the Database name field, enter the
name of the Synch Service message database. Then click OK to create the message database.
The following dialog box opens.

4. Configure the service account.

In this dialog box, you specify an account to run the Synch Service instance. If this instance of
Synch Service is installed at the head office, the user account must be a valid Microsoft Dynamics
AX user account.
5. Click OK to finish creating the service. The service is started by default.

14

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

6. The newly created service appears in the left pane on the home screen of the Synch Service
Settings tool. Select the service.

Configure Synch Service settings

After you register a new Synch Service instance, follow these steps to configure it.
1. Select a specific Synch Service instance, and then click Next. The following configuration page for
the service opens.

2. Configure the properties of the selected instance of Synch Service.

The following table describes the controls that are available.

Control Description
Server Name The name of the selected service instance. This is a read-only field.

Packet Owner The name of the service that creates the data packages. This setting is
available only if 2nd Stage Commerce Data Exchange Synch Service
is selected in the Server Mode field.

Server Mode The mode that this instance of Synch Service is running in. If this instance
is a primary instance, select Commerce Data Exchange: Synch
Service.
If this instance is a forwarder instance, select 2nd Stage Commerce
Data Exchange Synch Service. For more information about forwarder
mode, see the Set up a forwarder instance of Synch Service section.

Server Port The listening port for Synch Service. This setting is not available for a
forwarder instance, because in that case, the service only forwards
packages. If you plan to run more than one instance of the service on the
same computer, you must change the port values so that they do not
conflict with other services.

Off Turn the server listening port on or off. (We do not recommend that you
turn the port off.)

Telnet Port The port used by the Synch Service Telnet interface. This feature lets you
use Telnet to monitor the status of Synch Service. If you also run a Telnet
server on the computer, assign the Synch Service Telnet interface to
another port to avoid conflicts.

15

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

3. Click Next. The following configuration page opens.

4. Configure the Synch Service connection, and how incoming and outgoing messages are handled.
On this page, you need to specify the path of the working directory that keeps temporary files.
This directory keeps queue files by default, and it keeps data package files if you select the Keep
Package Files check box in the Server debugging properties window.
Note: In the Working Directory field, %s typically corresponds to the directory
C:\Users\<username>\AppData\Local.
The following table describes the fields that are available.

Field Description
Server Name The name of the service instance that you are configuring.

Working Directory The path of the folder where Synch Service keeps temporary files and, if it
is configured to do so, package files. To change this path, click Browse.

Days Messages Exist The number of days to keep processed incoming or outgoing messages. If
you type a value of 0 in this field, messages are not deleted.

Timer Interval The interval at which Synch Service checks for packages that must be
reprocessed because of communication errors.

Limit Job Process (cnt) The maximum number of job records that Synch Service processes per
connection. The number should be set lower when the average package
size is high and higher when the average package size is low. To disable
the feature (not recommended), enter a value of 0.
This feature guarantees that Synch Service continues processing, even if
it has a heavy load that would typically cause it to stop responding. Also,
when this feature is on, if the first job record in the batch has an error,
the rest of the packages are skipped for the run.

16

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

5. Click Next. The following configuration page opens.

6. Configure how connections are handled.

The following table describes the fields that are available.

Field Description
Server Name The name of the service instance that you are configuring.

Hold Connections The number of connections to the source database that Synch Service
should reserve.

Idle Conn. Time The number of idle minutes before the reserved connections time out and
are released.

Thread Timeout The number of seconds before threads used in connections to remote
locations time out.

Max. Forw. Threads The maximum number of threads that can be used concurrently to send
packages.

Max Hop Counter The maximum number of transfers, per package, between instances of
Synch Service. This setting prevents infinite loops that can result from a
misconfigured Synch Service instance.

Socket Timeout The number of seconds that Synch Service waits for the network to finish
a particular send or receive operation. To prevent Synch Service from
shutting down merely because it is waiting for the network, set this value
lower than the value in the Thread Timeout field.

Retry interval The interval before a failed connection is retried.

Maximum retries The number of attempts before Synch Service stops trying to perform an
operation on a package.

Forw. Attempts The maximum number of attempts that Synch Service makes to forward a
packet. This setting works only on a forwarder instance.

Use Processor The processor that the service should run on. If you want the operating
system to allocate processors based on need, select All Processors.

17

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

 Field Description
Disable IPsec Select this check box to bypass the IPsec requirements of Synch Service.
For more information, see the Bypass the IPsec requirement (with a VPN)
section.
Note: If the Disable IPsec check box is selected for a location in Retail
Scheduler, the Disable IPsec check box in Synch Service Settings should
be selected for all instances of Synch Service that are involved in
communication with that location.

Prefer IPV6 Use the IPv6 communication protocol, if it is enabled.

7. Click Next to go to the final page in the wizard.

Note: After creating and configuring an instance of Synch Service, you can verify its configuration
string in the registry, at
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Dynamics\6.0\Retail
Store Connect\Servers\<InstanceName>.

Configure Synch Service logging

The final page in the Synch Service Settings wizard is critical in helping debug potential issues with
the service and message processing.
Use this page of the wizard to configure what information is logged for each package, and how log
files are handled.

The following table describes the fields that are available.

Field Description
Server Name The name of the service instance that you are configuring.

Keep Package Files A selected check box indicates that Synch Service does not delete the
temporary package files in the working directory. Do not leave this feature
enabled for long, because it could cause you to run out of disk space and
prevent Synch Service from operating correctly.

Exception Dump A selected check box indicates that a memory dump file is created if Synch
Service stops working suddenly.

Log/Dump Dir The folder where log files are saved. Confirm that the folder that you specify
actually exists.

18

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Field Description
Log Mode A selected check box indicates that Synch Service operations are logged as
specified by the Log Level setting.

Write to Windows event log A selected check box indicates that Synch Service writes the logging data to
the Windows event log.

Max Lines / Logfile The maximum number of lines in each log file. Synch Service creates three
log files, rotating to the next log file when the maximum number of lines has
been reached. On startup, Synch Service makes a copy of the old log files by
appending .old to their names. This means that if the service has been set to
automatically restart on failure, the failure appears in the old log files.

Log Level The amount of error logging that takes place. Generally, the Error and Main
logging levels are sufficient, but greater detail might be helpful in some
cases. The following levels are available:
 Error – All errors reported from Synch Service are logged.
 Main – The main operations in Synch Service are logged.
 Actions – Detailed information about operations in Synch Service is
logged.
 Detail – Very detailed information about operations in Synch Service is
logged.
 Functions – Highly detailed and technical information about operations in
Synch Service is logged. (This option is intended for developer use only.)
Important: Logging as specified in the Log Level settings can take place
only if the Log Mode check box is selected.

Advanced installation options for Synch Service

The following sections describe several advanced deployment options. To distribute the load of Synch
Service, you can set up a forwarder instance of Synch Service.

Set up a forwarder instance of Synch Service

A second instance of Synch Service operating in forwarder mode can be used to reduce the processing
load on the primary Synch Service server. When your topology includes a forwarder, data packages
are cached in the database and working directory, where they are picked up by the forwarder and
transmitted to their destination. This might be desirable if the network route to a destination store is
slow, or if you want to multicast identical data packages to several stores, because it does not tie up
resources on the primary Synch Service instance. Forwarder is also known as Second Stage Synch
Service.
To use Synch Service in forwarder mode, you must run two instances of Synch Service at the head
office, one as the primary instance and the other as the secondary instance. Set up the forwarder
instance on a separate computer, and confirm that the message database where the incoming and
outgoing message tables are stored is accessible from there. Also confirm that the working folder is
accessible.

19

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

The following diagram illustrates a forwarder configuration.

The forwarder instance handles communication in only one direction, from the head office to the store
locations.
The name that you assign to the forwarder is the name that you use in the Database profiles form
to indicate which forwarder should handle a particular location. Use the following procedure to
configure a forwarder instance.
In Microsoft Dynamics AX, follow these steps:
1. Open the Synch Service Profiles form. (Click Retail > Setup > Retail scheduler > Channel
integration > Commerce Data Exchange: Synch Service profiles.)
2. Create a new profile, specifying the Service name value in the following format:
<Forwarder service name>;<receiver service name>
This causes the forwarder to send packages to the listed receiver location.
3. Open the Database profiles form. (Click Retail > Setup > Retail scheduler > Channel
integration > Database profiles.)
4. In the Database profiles form for any store, in the Commerce Data Exchange: Synch Service
list, select the newly created profile.
5. Confirm that the user that Synch Service is running as has read/write permissions to the working
directory and its contents.
The following screenshot shows a sample profile setup for a forwarder in Microsoft Dynamics AX.

Note: The format of the Service name value is <Forwarder service name>;<Receiver service
name>.

20

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

 The server name specifies the computer that hosts the receiver.
After you complete the setup in Microsoft Dynamics AX, you can create and configure the Synch
Service instance in forwarder mode by using the Synch Service Settings tool. When you add a
forwarder instance, the following dialog boxes open consecutively.
1. In the Message database dialog box, assign the message database for the primary Synch
Service instance to the forwarder, because the forwarder reads from that message database the
location where data packages are temporarily stored.

2. In the Service account dialog box, specify an account for running this Synch Service instance.

3. Select the forwarder instance, and then click Next.

21

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

4. On the next page, in the Server Mode field, select 2nd stage Commerce Data Exchange
Synch Service. Notice that the Server Port field is automatically disabled for editing, because in
forwarder mode, the Synch Service instance only forwards data packages to the destination.
In the Packet Owner field, provide the instance name of the primary Synch Service instance that
sends data packages to the forwarder.

5. On the next page, specify a working directory for the forwarder.

22

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

6. On the next page, use the default settings if you are not sure what parameter values to use.

7. Specify a log/dump directory, and select any other options that are needed.

Run multiple instances of Synch Service

Instead of using a forwarder instance, you can run additional primary instances of Synch Service as
needed at the head office. First, install and configure the new instance of Synch Service. When you
configure the new instance, use a different port number, so that there is no conflict between
instances.

23

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

The following diagram illustrates a configuration with multiple instances of Synch Service.

In Microsoft Dynamics AX, configure the following profiles for each instance of Synch Service:
 A Synch Service profile (Retail > Setup > Retail scheduler > Channel integration >
Commerce Data Exchange: Synch Service profiles)
 An AOS profile (Retail > Setup > Retail scheduler > Channel integration > AOS profiles).
For each AOS profile, select a different Synch Service instance. The AOS profiles can use the same
AOS instance.
Next, create new distribution schedules (Retail > Periodic > Data distribution > Distribution
schedule). For example, create a distribution schedule to send items and prices to stores on the west
coast. Select a new AOS profile and select the distribution location list that represents stores on the
west coast. Add the A-1040 (products) and A-1020 (discounts) jobs to the distribution schedule.
Repeat this step for other regions.

Synch Service Pack Viewer

Pack Viewer is a tool that helps you to examine the data in the packages that Synch Service sends
and receives. A package can contain any of the following:
 The database query being used
 The data to insert
 Both the query and the data

24

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

To start Pack Viewer, click Start > All Programs > Microsoft Dynamics AX 2012 > Commerce
Data Exchange > Synch Service > Pack Viewer.

Pack Viewer is a dialog box that looks as follows.

Pack Viewer converts the package file from binary format into XML files that you can open in Notepad
or another text editor. There is one XML file for the header and one for each table included in the
package. The files are stored in a folder with the same name as the package.
Package files are available for viewing only if you specify in Synch Service Settings that they should be
saved.
Although you can save all packages as a message archive, doing so can consume disk space quickly.
Typically, you save packages and use Pack Viewer only as a troubleshooting measure, such as when
you are experiencing a synchronization or replication issue.

Save package files for viewing in Pack Viewer

To save and access Synch Service packages, you need to run Synch Service Settings as an
administrator. Select the appropriate instance of Synch Service to configure, and click through the
wizard to apply the following settings:
1. On the Commerce Data Exchange: Synch Service specific properties page, in the Working
Directory field, type the path of, or browse to, the folder where you want to save the packages.
2. On the Server debugging properties page, select the Keep Package Files check box, and then
click Finish.
For more information, see the Create an instance of Synch Service section.

25

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

File formats
For the Synch Service instance that connects to Microsoft Dynamics AX, the following file formats are
used:
 For A and N jobs:
 Incoming message – Temporary files with the suffix I
This indicates a database read request sent from Microsoft Dynamics AX to Synch Service.
 Outgoing message – Temporary files with the suffix R
This indicates a data package sent to Synch Service at the retail channel.
 For Pull jobs (P jobs) that receive retail transaction data from the channel:
 Incoming message – Temporary files with the suffix I
This indicates a data package sent from the channel.
 Outgoing message – Temporary files with the suffix I
This indicates a data package sent to Microsoft Dynamics AX.
Note: The temporary files have the same suffix, I.
To see the content in a data package by using Pack Viewer, you need to change the suffix from I to R;
otherwise, you receive an error message.
For the Synch Service instance that connects to the retail channel database, the following file formats
are used:
 For A and N jobs:
 Incoming message – Temporary files with the suffix I
This indicates a data package sent from Synch Service at the head office.
 Outgoing message – Temporary files with the suffix I
This indicates data sent to be written into the channel database.
Note: To see the content in a data package by using Pack Viewer, you need to change the suffix
from I to R; otherwise, you receive an error message.
 For P jobs:
 Incoming message – Temporary files with the suffix I
This indicates a data upload request sent from Synch Service at the head office.
 Outgoing message – Temporary file with the suffix R
This indicates a data package sent to Synch Service at the head office.

Set up Retail Scheduler

Retail Scheduler coordinates communication between Microsoft Dynamics AX and stores. Use Retail
Scheduler to manage the distribution of data from the head office stores.
Jobs are used to distribute data to the locations. Jobs are made up of subjobs, which are specific
instructions for distributing data in selected tables and selected table fields. Each job has a location
filter, which is the set of distribution locations to which the data is distributed by the job. A distribution
location list is a group of distribution locations. For example, you can set up distribution location lists
per region or per time zone.
The distribution schedule is used to run the data transfer, either manually or by scheduling a batch job
in Microsoft Dynamics AX. A distribution schedule can be configured to contain one or more

26

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

distribution location lists and one or more scheduler jobs. In other words, a distribution schedule can
send data to one or more regions, and it can send data for one or more tables. For more information
about distribution locations and the distribution schedule, see the Data distribution settings section.

To run jobs, you must complete the following tasks:

 Initialize jobs and subjobs.
 Configure subjobs.
 Configure jobs.
 Set up distribution locations and distribution schedules.
 Convert pre-actions to actions.
 Run jobs or batches of jobs.

Scheduler jobs and subjobs

A scheduler subjob maps a source table to a destination table, including individual fields. For example,
a subjob specifies the Microsoft Dynamics AX table InventTable and the corresponding table
InventTable in the Retail POS database. The transfer field list specifies which fields from InventTable
are included.
A scheduler job is a grouping of related subjobs. For example, the A-1040 scheduler job contains all
subjobs that are related to times.
In Microsoft Dynamics AX for Retail, there are three types of jobs:
 Action (A) jobs – A jobs send only changed data from Microsoft Dynamics AX to stores.
 Normal (N) jobs – N jobs also send data from Microsoft Dynamics AX to stores. N jobs delete all
existing data in the destination tables and then insert the whole set of data.
 Pull (P) jobs – Use P jobs to update the data in the Microsoft Dynamics AX database by pulling
data, such as sales and inventory transactions, from the stores.

27

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Initialize default jobs
Microsoft Dynamics AX for Retail comes with predefined scheduler jobs and subjobs that meet the
replication needs of most organizations. To populate these jobs and subjobs, you must initialize
Microsoft Dynamics AX for Retail.
New jobs can be added or existing jobs can be customized based on business requirements.
The following task is performed during deployment of Microsoft Dynamics AX for Retail and creates the
base configuration data, including the scheduler jobs and subjobs.
1. Click Retail > Setup > Parameters > Retail Parameters.
2. In the Retail parameters form, on the General tab, click Initialize.

Create scheduler subjobs

To create and configure a subjob, complete the following procedure.
Note: A subjob can be assigned to more than one job.
1. Click Retail > Setup > Retail scheduler > Scheduler subjob.
2. Click New to create a new subjob, or select the subjob to modify in the list on the left. You can
also click Copy scheduler subjob to use an existing subjob as a starting point.

3. Enter the subjob number, which is a unique ID that identifies the subjob.
4. Enter a description of the subjob.

28

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

5. Select the replication method in the list. The following options are available:
 Normal – Select this method if the subjob is for an N job that sends all data to the retail
store.
 By actions – Select this method if the subjob is for an A job that sends only changed data to
the retail store.
6. On the Setup FastTab, in the From design area, select the location number from which to extract
the information into Microsoft Dynamics AX.
7. In the From table list, select the table from which to retrieve information at the retail channel.
8. In the To design area, select the location number to which to push information from Microsoft
Dynamics AX.
9. In the To table list, select the table into which to populate information at the retail channel.
10. Select the Replicate DataAreaId check box to replicate the legal entity ID at the retail channel
or the head office.
Caution: Use the Replicate DataAreaId field with caution, because it can cause invalid data to
be populated in the wrong fields.
11. Select the field for DataAreaId in the list.
12. In the Replication area, select the replication method in the list.
13. Select the field transfer type in the list. The following options are available:
 All distribution locations – The data flows to all the retail stores.
 Include list – The data flows to the retail stores specified in the include list.
 Exclude list – The exclude list is the fields that are not selected in the transfer field list.
14. Select the Delete check box if replication is performed when a record is deleted.
15. Select the Insert check box if replication is performed when a record is created.
16. Select the Enabled check box to activate the subjob.
17. Select the Pull data check box to indicate that the job needs to pull data from retail stores to the
head office. If you select this option, you must select a replication method of Normal.
The Transfer field list exists check box is automatically selected if transfer fields are specified
for the table that is replicated to the retail store.
The From/To filters exist check box is automatically selected if filters are specified for the tables
selected in the subjob.
18. On the Replication FastTab, in the Actions area, enter the action counter interval. A value can
only be entered if By actions is the replication method.
19. In the Replication counters area, enter the replication counter value.
20. Select the replication counter interval.

29

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Transfer field list
1. Open the scheduler subjob by clicking Retail > Setup > Retail scheduler > Scheduler subjob.
2. Select the subjob in the list on the left, and then click Transfer field list to select the fields that
are distributed to the retail stores. The Field list form opens.

3. Select the from field in the list. The field type is automatically selected based on the field
selection.
4. Select the to field in the list. The field type is automatically selected based on the field selection.
5. Select the conversion type in the list. The following options are available:
 None – Select this option to apply no conversion rules.
 Equals (=) – Select this option to specify the filter value in the Value field.
 Substring – Enter the substring value in the Value field.
 Today() – Select this option if the filter is based on the current date timestamp.
 TimeNow() – Select this option to populate the current time.
 Skip text conversion – Select this option to skip the conversion process.
 Time to integer – Select this option to convert a time value to an integer.
 Integer to time – Select this option to convert an integer to a time value.

30

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

From table filters
1. Open the scheduler subjob by clicking Retail > Setup > Retail scheduler > Scheduler subjob.
2. Select the subjob in the list on the left, and then click From table filters to set filters on the
selected from table. The From table filters form opens.

3. Click New to create a new filter.

4. Select the field name in the list. A new window opens with a list of fields to select.
5. Select a filter in the list.
6. In the Value1 field, enter the filter value.
7. In the Value2 field, enter the filter value.

Scheduled by information
1. Open the scheduler subjob by clicking Retail > Setup > Retail scheduler > Scheduler subjob.
2. Select the subjob in the list on the left, and then click Scheduled by to view the scheduler job
that runs the subjob.
The Scheduled by form opens.

31

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Configure jobs
Jobs should contain subjobs that are related. For example, the Currency job contains subjobs that
update currencies and exchange rates. Jobs should also contain subjobs that use replication methods
that are consistent with the type of job. As a general rule, N jobs and P jobs should contain subjobs
with Normal replication, and A jobs should contain subjobs with By actions replication.
1. Click Retail > Setup > Retail scheduler > Scheduler job.

2. Click New to create a new job, or select the job to modify.

3. Enter a unique job number for the new scheduler job.
4. Enter a description of the job.
5. In the Retail channel schema field, select the appropriate schema version. The retail schema
version is also specified on the subjob. Only subjobs with the same schema should be added to
this scheduler job.
6. On the Subjobs FastTab, click Add to assign subjobs to the scheduler job.
Note: A scheduler job is processed as a SQL transaction. If one subjob fails, all other subjobs in
the job will also be rolled back.
7. Select the subjob number in the list. The Description field displays the name of the selected
subjob.
8. By default, the values on the Object setup FastTab are not used.

Create a temporary staging database for P jobs

This action applies only to P jobs. It will create the temporary tables that are used during data import.
1. Open the scheduler job by clicking Retail > Setup > Retail scheduler > Scheduler job.

32

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

2. Select the P job in the list on the left, and then click Create TempDB staging table to create a
staging database for P job tables.

Copy scheduler job

To use an existing scheduler job as a starting point, copy the job and modify the copy.
1. Open the scheduler job by clicking Retail > Setup > Retail scheduler > Scheduler job.
2. Select the job in the list on the left, and then click Copy scheduler job to copy an existing job to
create a new scheduler job.

View the scheduler log

Each time a scheduler job is run as part of a distribution schedule, a new GUID is generated and the
status is logged. When launched from the scheduler job form, the log information from all distribution
schedules this scheduler job belongs to is displayed.
1. Open the scheduler job by clicking Retail > Setup > Retail scheduler > Scheduler job.
2. Select the job in the list on the left, and then click Scheduler log to view historical information
about the job execution.
The scheduler log form opens.

33

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Data distribution settings
Create data distribution settings to specify whether and how data in the Microsoft Dynamics AX
database is sent to store databases. You can specify that certain records are sent only to the locations
where those records are applicable. You can also specify whether and how changes to certain tables
and table fields are distributed.
Data distribution starts and ends with a record that is changed.
The distribution process consists of the following steps:
1. Set up data distribution locations for stores.
2. Set up action filters to specify which tables and fields, if any, are monitored for changes.
3. Set up table distributions. When a record in one of the selected tables is modified, the distribution
settings for the table determine whether that modified record is distributed, and whether records
in parent or child tables should be distributed with it.
4. When a record is modified, the appropriate data is sent to the appropriate locations by means of
jobs. The settings of the jobs further refine the specifics of the distribution.

Distribution locations
A distribution location is a record that represents the destination for distributed data. Whenever you
create a store, a corresponding distribution location is automatically created. In general, you must
have a distribution location for each store location that has its own database.

Create distribution locations

The distribution locations that are created automatically when you create stores are probably
sufficient, but you can also create new distribution locations.
Note: If you create a distribution location manually, ensure that the distribution location ID matches
the ID for the store that the distribution location represents.
1. Click Retail > Setup > Retail scheduler > Distribution locations.
2. In the Distribution locations form, click New.

34

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

3. Complete the following information for each distribution location:
Fields
 Location number – Enter a unique ID for the distribution location.
 Description – Enter a description of the distribution location.
 Channel – Select the channel the distribution location is associated with.
 Database profile – Select the database connection profile for this location. For a store
location, select a database profile.
 Channel profile – Available only for online channels. Links to channel-specific properties.
 Retail channel schema – The schema that is used by the linked database.
 Send data – Available only for online channels. Select this option if data is sent to this
location.
 Receive data – Available only for online channels. Select this option if data is retrieved from
this location.
 Continuous data transfer schedule – Available only for online channels. Select the
distribution schedule that must be processed even if Send data is not selected. For example,
no new changes are applicable to this channel database, and Send data is not selected, but
the on-hand quantity must be sent to the channel.
Functions – Open a menu where you can select from the following options:
 Test connection – Test the connection to the instance of Synch Service that is selected in
the connection profile for this location.
 Read schema – Read the database schema for the selected location.
 Send configuration – Send the Synch Service upload options to the instance of Synch
Service that is referenced in the database profile.
 Deploy initial dataset – Available only for online channels. This function sends all
required data to the channel during initial deployment. When prompted, select the A-
0001_OC distribution schedule.

Distribution location list

You can create a distribution schedule that associates one or many locations (distribution location
lists) with one or many scheduler jobs.
1. Click Retail > Setup > Retail scheduler > Distribution location list.

35

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

2. In the Distribution location list form, click New.

3. Click Add to add a new retail channel to the distribution location list.
4. Select the location number in the list.

Distribution schedule
The distribution schedule links distribution locations lists (where to send the data) with scheduler jobs
(which data to send). You can run a distribution schedule manually or you can configure a Microsoft
Dynamics AX batch job to run periodically.
1. Click Retail > Periodic > Data distribution > Distribution schedule.

36

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

2. Enter the following information:
Name – Enter a unique identifier for the distribution schedule.
Description – Enter a description of the distribution schedule.
AOS connection profile – Specify the AOS profile to use to run the distribution schedule. To
balance the load, you can define multiple AOS profiles with different Synch Service instances
assigned. This will distribute the processing of distribution schedules among all Synch Service
instances.

Preactions and actions

Action jobs (A-jobs) send only the changes since the last run. Microsoft Dynamics AX uses preactions
to track those changes. The insert, update, and delete methods for all relevant tables have been
modified to create preactions. Preactions are converted to actions in a separate step that uses the
table distribution configuration to determine where changes must be sent.

Filter on action creations

When you set up an action filter, you can watch for transactions that affect specific fields in tables. If
an employee creates, modifies, or deletes a record in a selected table, the action filter automatically
collects the changed information in a preaction.
If you want to watch for modifications only to specific fields in a table, you can select those fields in
the action filter. Do not select specific fields if you want to monitor all changes to a table.
You can create action filters for specific stores.
1. Click Retail > Setup > Retail scheduler > Filter on action creations.

2. In the Filter on action creations form, click New to create a new action filter.
3. Select a table in the list on the left.
4. On the Field FastTab, add fields to the list. Preactions are created only for fields in this list. If
another field in the table is updated, no preaction is created.

Table distribution
The table distribution specifies how changes that are made to data are distributed from Microsoft
Dynamics AX to channel locations. To use action jobs correctly, you must configure the table
distribution.

37

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Distribution types
The distribution type for a table determines how that table is distributed. The following distribution
types are available:
 All distribution locations – Distribute modifications to the records in a table to all locations. This
is the default distribution type.
 Same as parent distribution – Distribute modifications based on the distribution type of the
parent table. Select this distribution type for records that must always be accompanied by other
records. For example, items and the bar codes for those items must have the same data
distribution.
Note: If you select this distribution type, you must set up table links that describe the relationship
between the child table and its parent table.
 By distribution groups – Distribute modifications based on the distribution list for the record
that was changed in the table. For example, changes made to an item are sent only to the stores
that sell that item.
Note: Typically, you select this distribution type only for tables at the top of the table distribution
hierarchy.
 No distribution – Do not distribute modifications. If a table of this distribution type is the parent
of another table, and the distribution type of the child table is set to Same as parent
distribution, changes to the child table are not distributed.

Parent/child relationships
If you use a table distribution to establish a parent/child relationship between two tables, you must
complete both of the following tasks:
 For the child table, set up table links to describe the relationship between the child table and its
parent table. For more information, see the Set up table links section.
 For the parent table, specify the types of actions (insert, update, or delete) that cause any child
tables to be distributed together with the parent table. These linked settings also include any
linked child tables of the child tables.

Create a new distribution

1. Click Retail > Setup > Retail scheduler > Table distribution. The Table distribution form
opens.

38

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

2. In the Table distribution form, click New.
3. Select the parent distribution in the list.

The Record ID field is automatically populated based on the assigned number sequence.
4. Select the table ID in the window that opens. The Table name field displays the name of the
selected table.
5. Select the distribution type in the list. The following options are available:
 All distribution locations
 Same as parent distribution
 By distribution group
 No distribution
The Parent to another table check box is automatically selected if the table that is selected as
parent table is also the parent of other tables.
The Table links check box indicates whether a parent/child link has been generated between the
two tables. The table link must be created if the distribution type that is selected is the same as
the parent distribution.
The No actions check box is selected to indicate that no action is required for changes that occur
to the selected table. If you want to use no actions, the parent table must be empty or set to 0
(zero).
6. Select the Linked actions on insert check box to indicate that the distribution occurs when new
records are created in the selected table.
7. Select the Linked actions on update check box to indicate that the distribution occurs when
existing records are updated in the selected table.
8. Select the Linked actions on delete check box to indicate that the distribution occurs when a
record is deleted.

39

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

9. On the General tab, you can review the information entered on the Overview tab.

Insert the default table distribution

The default setup for table distribution is appropriate for most organizations. Even if you want to
customize the table distribution, inserting the default setup can save you a lot of time.
Note: If you inserted the default setup when you set up the Retail module, you can skip this
procedure.
1. Click Retail > Setup > Retail scheduler > Table distribution.
2. In the Table distribution form, click Insert default setup.

How table links work

When a record in a child table is modified, and the resulting pre-action is converted to an action,
Retail Scheduler checks whether the modified record is in a table for which distribution is controlled by
the settings of a parent table. If the modified table is linked to a parent table for data distribution,
Retail Scheduler checks whether the modified record meets the criteria for distribution that are
specified in the parent table’s settings.
If a table link includes multiple criteria, all the criteria must be met for distribution to occur based on
that link. If a modified record does not meet the criteria of any of the links to the parent table,
distribution does not occur.

Set up table links

Table links define the conditions that must be met for the records in a child table to be distributed in
accordance with the distribution type of a parent table. The effect of setting up a table link is
comparable to the effect of setting up a link between a primary key and a foreign key in SQL Server.
However, a table link applies only to data distribution. Table links are required only for tables for
which you select a distribution type of Same as parent distribution.
There must be a logical relation between the tables that you link. For example, you cannot link the
Item table to the Customer table, because there is no logical relation between those two tables.
For parent fields, you must select fields that are part of the primary key for the parent table.
For child fields, we recommend that you select fields that are either part of the primary key or part of
a properly indexed foreign key for the child table.
1. In the Table distribution form, select the table to link to its parent table.
Note: The parent table must already be listed in the table distribution.
2. Click Table links. The Table links form opens.

40

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

3. In the Table links form, click New.
On the General FastTab, the child table information is populated in the Table ID and Parent
table ID fields, and the associated Description fields.
4. In the Parent distribution field, select a parent table ID.
Note: If there are multiple entries in the list, meeting the criteria of any one table link creates the
link (SQL OR operation).
5. In the Field ID field, select the field to link to a field in the parent table. The field name is
displayed automatically.
Note: If there are multiple entries in the list, all the criteria must be met for the link to be
created.
6. In the Parent field, select the field in the parent table to which to link the child field. The parent
field name is displayed automatically.
7. Select the type in the list. The value that you select determines the type of check that is required.
The following options are available:
 Field – The field specifies that the distribution occurs if the logical relation between the fields
specified in the parent and child table matches.
 Filter – The Filter option is not supported in the current version of Microsoft Dynamics AX for
Retail.
 Equals (=) – Specify the value in the Value field to check against the field value during
distribution.
8. If the parent field must contain a specific value, type that value in the Value field.
9. Repeat steps 3 through 8 for any additional criteria for this table link.

41

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Set up communication profiles

Synch Service profiles

A Synch Service profile in the head office Microsoft Dynamics AX system provides the connection
string that enables Microsoft Dynamics AX to communicate with an instance of Synch Service.
1. Click Retail > Setup > Retail scheduler > Channel integration > Commerce Data
Exchange: Synch Service profiles.

2. Click New to create a new Synch Service profile.

3. Enter the following information:
 Service name – The name of the service as it was specified in Synch Service Settings (Start
> All Programs > Microsoft Dynamics AX 2012 > Commerce Data Exchange: Synch
Service > Commerce Data Exchange: Synch Service Settings).
 Server name – The name of the server where Synch Service is installed.
 Port – The port used by this instance of Synch Service.
 Disable IPsec – Select the check box to disable IPsec, a framework of open standards to help
protect communications over Internet Protocol (IP) networks through the use of cryptographic
security services.
Important: IPsec should only be disabled if there are other means in place to help provide
secure communication channels for Synch Service.

42

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

  Prefer IPv6 – Select this check box to prefer IPv6 connections, if both IPv4 and IPv6 are
available on the network.
 Timeout (seconds) – Specify the connection timeout.
 Real-time Service profile – The name of a Real-time Service profile.
Synch Service uses this profile to connect to Real-time Service to monitor the status of jobs. If
you do not want this instance of Synch Service to monitor status, leave this field blank.
 Commerce Data Exchange: Synch Service upload options – The name of the upload
option used by Synch Service. If you select an upload option, you must click Send
configuration and restart the service for the settings to take effect.
4. Click Test connection to confirm that the connection string for the selected Synch Service profile
is correct.

Create Synch Service upload options

Synch Service uploads status messages from its local message database to Microsoft Dynamics AX by
using Real-time Service.
1. Click Retail > Setup > Retail scheduler > Channel integration > Commerce Data
Exchange: Synch Service upload options.

2. Enter the following information:

Name – A unique identifier for the set of upload options.
Upload enabled – Select this option to upload status messages to Microsoft Dynamics AX.
Error messages only – Select this option to upload only error messages to Microsoft Dynamics
AX. If you do not select this option, all status messages are uploaded
Interval – Enter the frequency, in minutes, that status messages are uploaded.

43

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

AOS profiles
An AOS profile provides the connection string that enables Microsoft Dynamics AX to communicate
with the head office database.
1. Open the AOS profiles form by clicking Setup > Retail Scheduler > Channel integration >
AOS profiles.

2. Click New to create a new AOS profile.

3. Enter the following information:
 Name – Type a unique name for the profile.
 Server name – Type the name of the AOS server.
 Instance name – Type the name of the AOS instance.
 TCP/IP port – Type the TCP/IP port for the AOS instance.
 Commerce Data Exchange: Synch Service – Select the profile for the correct instance of
Synch Service.
4. Click Test connection to confirm that the connection string for the selected AOS profile is correct.

44

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Database profiles
A database profile provides the connection string that enables Microsoft Dynamics AX to communicate
with a store database.
1. Open the Database profiles form by clicking Setup > Retail Scheduler > Channel
integration > Database profiles.

2. Click New to create a new database profile. Optionally, you can click Duplicate to create a new
profile based on a currently selected profile.
3. Enter the following information:
 Name – Type a name for the profile.
 Server name – Type the name of the database server.
 Database name – Type the name of the database.
 Encrypt database connection – Select this check box to encrypt the database connection.
 Commerce Data Exchange: Synch Service – Select the profile for the correct instance of
Synch Service.
4. Click Test connection to confirm that the connection string for the selected database profile is
correct.

45

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Customize Synch Service
This section contains an example that shows the steps for adding a custom table in Microsoft
Dynamics AX and synchronizing the data in that table with a channel database.

Create the table in Microsoft Dynamics AX

This example uses two fields in a table that is called TestTable01: field C1 of integer type and field
C2 of string type.

If you want to use this new table with action scheduler jobs, add the following code snippet to the
insert, update, and delete methods, and add it to the filter on action list.

boolean replicate = false;

replicate = RetailConnActionManagement::shouldReplicate(this, this.orig(), false);

super();

if (replicate)
{
RetailConnActionManagement::createActions(this, RetailConnActionUpdate::Insert);
}

Create the table in the POS database

Go to the POS database in SQL Server, and create the new table.
Note: In this example, we are implicitly using RecID as the primary key, so RecID must also be
included in the POS database table. Because this table is not global, it contains the DataAreaID field
from Microsoft Dynamics AX. Whether DataAreaID is required in the POS database depends on actual
business requirements.
CREATE TABLE TESTTABLE01
(
C1 INT,
C2 NVARCHAR(10),
DATAAREAID NVARCHAR(4),
RECID BIGINT PRIMARY KEY
)

46

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Define the table schema in Microsoft Dynamics AX
1. Click Retail > Setup > Retail scheduler > Retail channel schema.
2. Because this table is for POS, select AX 2012 R2 POS, and then click Location tables.

3. Create a new table called TESTTABLE01.

4. Click Location fields, and then add the fields that you defined in the POS database.
Note: The Type and Length fields have been deprecated and can be ignored. Only the field
names matter.

Define a normal subjob in Microsoft Dynamics AX

Normal subjobs are used in N jobs, which synchronize all data in a table.
1. Click Retail > Setup > Retail scheduler > Scheduler subjobs.

47

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

2. Create a new subjob like the one shown in the following screenshot.

3. In the Retail channel schema field, select AX 2012 R2 POS.

4. The Channel table name field lists all tables that have been defined for the AX 2012 R2 POS
schema. Select TESTTABLE01.
5. Because the DataAreaID field was included in the new table, you must select the Replicate
DataAreaID check box. Then, in the Field for DataAreaID field, select DATAAREAID.

Define transfer fields

1. Click Transfer field list, and then add all field mappings except DataAreaID.

2. Save and close.

Define a scheduler job

You can add your new subjob to an existing job, or you can create a new job, depending on business
requirements.
1. Open the Scheduler job form by clicking Retail > Setup > Retail scheduler > Scheduler job.

48

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

2. Create a new job like the one shown in the following screenshot.

3. Add the newly created subjob to the job.

4. In the Retail channel schema field, make sure that AX 2012 R2 POS is selected. Because this
is a normal subjob, select RetailConnReplicationNJob in the Job execution class field.

Define a schedule to run the job

You can add this job to one of the existing Retail schedules, or you can create a new schedule for it,
depending on business requirements.
1. Open the Distribution schedule form by clicking Retail > Periodic > Data distribution >
Distribution schedule.
2. Create a new schedule, and include the new job.

You have now completed the setup and configuration to send TestTable01 data to the POS database.
You can then enter data into the TestTable01 table and run the scheduler job to verify that data can
be sent successfully to the POS database.

49

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Monitoring Synch Service
Microsoft Dynamics AX for Retail provides several resources for monitoring Synch Service.

Log files
The Synch Service creates two types of log files. By default, log files are stored in the following folder:
C:\Users\<service user account>\AppData\Local\Microsoft Dynamics AX\60\Commerce Data
Exchange\Synch Service\<service name>\logs
The first log file contains information about regular processing tasks of the Synch Service and is
named <InstanceName>-SC-[X].log, where X is an integer between 1 and 3. When you restart an
instance of Synch Service, the log file is renamed <SnstanceName>-SC-[X].old.log.
Logging and the output location (file or Windows Event log) are configured in Synch Service settings.
The second log file contains error messages for the Synch Service message upload and is named
<InstanceName>-SCMonitoring.log.
The following screenshot is an example of how these files look. Files with the .dmp extension are
memory dump files.

Synch Service message database

Each instance of Synch Service uses a message database to track the status of data transfers. The
following tables are included in the message database:
 SCMonitoringConfig
This table stores upload configuration information sent from Microsoft Dynamics AX. You can
check this table to make sure that the upload configuration was sent for this instance of Synch
Service. This table is designed to have only one row.
 IncomingMessages

Field Description
PackageNo A sequential package number.

ServiceName The name of this instance of Synch Service.

MessageID The description of the scheduler job.

SourceServiceName The source of the incoming messages.

ReceivedFile The location for incoming data package files.

ProcessedFile The location for outgoing data package files.

50

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

 Field Description
CancelledByUser If a scheduler job encounters an error during processing, set this flag to 1
to skip the remaining retries.

ConnectionString Connection string for the source.

Status To find out the meaning of a status, open the AOT in Microsoft Dynamics
AX, and locate the RetailConnSCMonIncomingMessages or
RetailConnSCMonOutgoingMessages table. Right-click the Status field,
and then click Add-Ins > Open new window > Open used enum.
 Received = 0
 Processed = 1
 Error = 2
 Waiting = 4
 No data = 5
 Pending forward = 7
 To forward = 8
 Forwarded = 9

 OutgoingMessages

Field Description
PackageNo A sequential package number.

ServiceName The name of this instance of Synch Service.

DestServiceName The name of the destination instance of Synch Service.

DestServerName The name of the server where the destination instance of Synch Service is
running.

ConnectionString The connection string for the destination.

Forwarder The name of the instance of Synch Service that will forward the data
package. By default, the forwarder name is the same as the service
name.

Status To find out the meaning of a status, open the AOT in Microsoft Dynamics
AX, and locate the RetailConnSCMonIncomingMessages or
RetailConnSCMonOutgoingMessages table. Right-click the Status field,
and then click Add-Ins > Open new window > Open used enum.
 Received = 0
 Processed = 1
 Error = 2
 Waiting = 4
 No data = 5
 Pending forward = 7
 To forward = 8
 Forwarded = 9

TryCount The number of times the system has attempted to process the message.

RemotePkg The package number assigned by the destination instance of Synch

Service.

ErrorNo The error number, if an error occurred.

CancelledByUser If a scheduler job encounters an error during processing, set this flag to 1
to skip the remaining retries.

51

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Synch Service messages form in Microsoft Dynamics AX
Synch Service status and error messages can be viewed in the Commerce Data Exchange: Synch
Service messages form. (Click Retail > Inquiries > Commerce Data Exchange: Synch Service
messages.)
Note: You must configure an upload profile before the messages are available in Microsoft Dynamics
AX.

Troubleshooting with error codes

This section provides troubleshooting help for potential Synch Service communication issues.
Additional troubleshooting instructions can be found in the following documents:
 For information about troubleshooting location connections, see Troubleshoot a connection.
 For information about troubleshooting jobs in Retail Scheduler, see Configure and schedule retail
data distribution.

Error codes
When a communication issue occurs, an error is returned by Synch Service. You can view Synch
Service errors in the following three places in Microsoft Dynamics AX:
 When you are testing the connection for a distribution location, in the Infolog
 In the Scheduler job form (Click Retail > Setup > Retail scheduler > Scheduler job.)
 In the message database for each instance of Synch Service

52

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

The following table lists the errors that are returned by Synch Service, together with the likely cause
of the error and suggestions for resolving it.

Error code Description Suggested resolution

0 Error on sending request Modify the location by specifying the
The distribution server for the location has distribution server for the location (Retail
not been specified in Retail Scheduler. scheduler > Common forms >
Locations).

4096 Error inserting in system tables Grant db_datareader and db_datawriter

Synch Service cannot write to the permissions for the message database to
incoming or outgoing message tables. The the SQL logon for the user that the Synch
tables might be missing, the user that the Service service runs as.
service is running as might not have
read/write permissions to the message
database, or required fields in the tables
might be wrong or missing.

4097 Remote connection dropped Restore the network connection. If the

The TCP/IP connection was terminated network connection is slow or overloaded,
while Synch Service was forwarding a consider increasing the TCP/IP time-out for
package, or the receiving Synch Service both Synch Service instances. This is done
instance was shut down during the in Synch Service Settings.
transfer.

4098 Canceled because of send and receive size Resend the package by running the Retail
The registered size of the package does Scheduler job again.
not match the actual size of the package.
This is most likely caused by a
transmission failure.

4099 Cannot find new packet number Confirm that the message database is
Synch Service could not assign a new configured correctly, and that the Synch
package number to an incoming package. Service user has the required privileges.
This is usually caused by an incorrect
message database configuration in Synch
Service Settings for the receiving instance
of Synch Service.

4100 Cannot instance a socket Confirm that the TCP/IP protocol is installed
The operating system could not create a and enabled on the computer. For more
Windows TCP/IP socket. TCP/IP might not information about enabling TCP/IP, see
be installed or enabled on the computer. “Enable remote connections in SQL Server
and start the server” in “Deploy Microsoft
SQL Server” in the Deployment and
Installation Guide.

4102 HopCount has exceeded its maximum Verify the DNS registration of the server
value name or its entry in the Hosts files on all
A package cannot be transferred, because computers involved.
the hop counter for the package has Confirm that the distribution server name
reached the maximum that was set in for the location (Retail scheduler > Setup
Synch Service Settings. > Channel integration > Commerce
This error can occur when a service name Data Exchange: Synch Service profiles)
is incorrectly assigned to an IP address. It matches the one in Synch Service Settings.
can also be caused by an inconsistency
between the distribution server name for a
location and the actual server name for
the instance of Synch Service.

53

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Error code Description Suggested resolution
8192 Error in processing request Check the event log for more information.
An unhandled exception occurred while Because this error happened at the
Synch Service was reading from or writing database level, it is likely that the database
to a database. This error is typically not has reported the cause of the error in the
related to the database connection. event log.
Check for an invalid or incorrect field
transfer setup in a subjob.

12288 An error occurred connecting to Synch Start the Synch Service service.
Service Confirm that the Synch Service service
The Data Client component of Microsoft name has an IP address associated with it.
Dynamics AX cannot connect to Synch This can be checked from a command
Service. This error occurs when the Synch prompt by typing ping <Synch Service
Service service is not running, when the computer name>. If the service name
Data Client is trying to connect to a does not respond to a ping command, you
service that does not exist or does not must reconfigure your DNS server or Hosts
have a correct IP address associated with file so that the service name is associated
it, or when the Data Client is trying to with the correct IP address.
connect to Synch Service on an invalid Verify that the port numbers match in
TCP/IP port. Synch Service Settings and in the Synch
Service profile.
Verify that IPsec (if enabled) or the firewall
is configured correctly. One way to verify
this is to connect to the Synch Service port
by using Telnet.

12289 The connection string was empty In Retail Scheduler, verify that the
The connection string for the location has database profile is configured correctly.
not been provided.

12290 Could not log in Grant access to the Microsoft Dynamics AX

Synch Service does not have the user that is used by Synch Service at the
necessary permissions to log on to the head office.
specified company. Grant db_reader and db_writer permissions
for the POS database to the user that is
used by Synch Service at the store.

12291 Connection temporarily unavailable Wait until Synch Service has released one
All sessions (servers) that Synch Service of the sessions that it is using, or assign
is allowed to use are unavailable. more sessions to Synch Service in Synch
Service Settings.

12293 Cannot load plugin dll Uninstall and reinstall the plug-in to correct
In most cases when this error occurs, the the registry setting.
plug-in has been registered, and the Remove the Synch Service server, and then
configuration is correct, but the path to add it again.
the plug-in .dll file is invalid, or the .dll file
is missing.

12294 Plugin version not supported Upgrade Synch Service to the same version
This version of the plug-in cannot be used as the plug-in.
with this version of Synch Service. In Install the version of the plug-in that
most cases, the plug-in requires a newer matches the version of Synch Service.
version of Synch Service.

12295 Waiting for a previous package Take corrective action so that the package
A previous package belonging to the same is processed successfully.
JobID has not been processed Cancel the job.
successfully. Check the job status to
determine whether the job is waiting, or
whether there is an issue with the job.

54

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Error code Description Suggested resolution
12296 Error connecting to a database If the error occurs when Synch Service is
Synch Service cannot connect to the trying to generate a package, the
database. connection string for the source database is
probably incorrect. Correct the database or
AOS profile configuration, and then test the
connection. If possible, test the connection
on the same computer that is running
Synch Service to confirm that all hosts and
services are configured correctly.

12305 Error while sending package information Retry the operation.

Check all connections.

12306 Error while transferring package Retry the operation.

A connection has failed, or the network is Check all connections.
unstable.

16384 Error writing file Free some space on the disk.

Confirm that the process has the necessary
permissions to write to the disk.

16385 Error creating file Free some space on the disk.

Synch Service cannot write to the hard Confirm that the process has the necessary
disk. The disk might be full, Synch Service permissions to write to the disk.
might not have permissions to write to the Confirm that the path to the working
working directory, or the path to the directory is correct.
working directory (as specified in Synch
Service Settings) might be incorrect.

16386 Error reading file Re-create the file by running the job again.
Synch Service was trying to read a file
that does not exist.

Troubleshoot common issues with data packages

A failed package blocks other packages from being processed.
When a package is not processed successfully, its blocked status can keep other packages from being
sent, even after you have resolved the cause of the error. To resume normal communications, remove
the messages related to the blocked package from the message database. On the originating
computer, in SQL Server Management Studio, expand the Databases folder, click the message
database, and then click New Query. In the query pane, type delete from dbo.IncomingMessages
where PackageNo='nnnn' (where nnnn is the ID number of the failed package), and then click
Execute. Any associated messages in the OutgoingMessages table are also deleted.
If Synch Service was configured to upload status messages to Microsoft Dynamics AX, the error
messages can be viewed in the Commerce Data Exchange: Synch Service messages form, which
is located at Retail > Inquiries > Commerce Data Exchange: Synch Service messages.
Note: You can cancel messages with errors to unblock other data packages.
Synch Service at the head office is unable to read results for a query packet.
If a job does not succeed, and no records are affected in the Retail store or POS database, follow
these steps to determine the reason for the failure.
1. Confirm that the request from Retail Scheduler reached the head office instance of Synch Service.
2. Confirm that the request packet, also referred to as an I file (<Synch Service service name>-
<sequential number>-I.tmp), was created by Synch Service. If the Keep Package Files check
box was selected in Synch Service Settings, this file is in the working directory.

55

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

3. Verify that the entry in the incoming message table for this packet has no errors. If Synch Service
is unable to process a request, it does not generate a result packet, also referred to as an R file
(<Synch Service service name>-<sequential number>-R.tmp), which causes an error. The reason
for this could be that .NET Business Connector is not configured correctly. Run Setup for Microsoft
Dynamics AX 2012, and install only .NET Business Connector. When this installation is completed,
you are prompted for details about the AOS instance. Enter the required information, and then
restart the Synch Service computer.
.NET Business Connector is required on the head office communications server and on each
Microsoft Dynamics AX client computer.
Synch Service crashes while processing a large number of transactions.
The default thread time-out for Synch Service is 1,200 milliseconds, but this might not be sufficient
when a large number of transactions is being processed. If you are processing more than 200,000
transactions, and Synch Service crashes without synchronizing the data, try increasing the thread
time-out to, for example, 3,600 milliseconds.
When you run a distribution schedule, an error is displayed: “Connection profile or Synch
Service profile are not configured properly: N-1060.”
Select an AOS connection profile in the AOS connection profile list before you run a scheduler job.
Synch Service cannot connect to the database.
Make sure that you give enough database access privileges to the user account that is configured to
run Synch Service.
1. Click Start > Microsoft SQL Server 2008 R2 > SQL Server Management Studio.
2. Under Security > Logins, make sure that the account you use to run Synch Service is listed.

56

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Commerce Data Exchange: Real-time Service
Introduction and overview
Real-time Service provides Retail POS and Commerce Runtime with real-time access to Microsoft
Dynamics AX data for scenarios such as:
 Customer orders
 Sales orders and invoices
 Customer validation and creation
 Inventory lookup
 Cashier validation
 Credit vouchers
 Gift cards
 Loyalty programs

Retail POS and Commerce Runtime can perform most operations without connectivity to Microsoft
Dynamics AX. However, for certain scenarios, both need to retrieve or update data directly in
Microsoft Dynamics AX.

Install and set up Real-time Service

Note: The installer only copies necessary files to the computer. You need to follow the instructions to
install and configure the service correctly.

Prerequisites for installing Real-time Service

 A Microsoft Windows Server operating system, or a Windows client operating system with Internet
Information Services (IIS), IIS Windows PowerShell snap-in, and Windows Process Activation
Service, is installed
 You have obtained an SSL certificate with data encryption capability. You can get the certificate
from a commercial certification authority (strongly recommended).
 The Real-time Service files are installed.
You should see the binaries installed at %ProgramFiles%\Microsoft Dynamics AX\6.2\Commerce
Data Exchange\Real-time Services\6.2.
 .NET Business connector is installed.
 A Microsoft Dynamics AX user account to run as is set up. The user must have the necessary
privileges in Microsoft Dynamics AX to perform all the retail tasks.

57

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Server certificate installation
To create and install the SSL certificate, follow the instructions of the certificate authority that
provides the certificate. In most cases, you will first create a certificate request in Internet Information
Services Manager. The request is sent to the certificate authority, which in turn issues the certificate.

Depending on the certificate authority, you will install the certificate through either using the
certificate request in Internet Information Services Manager or import the certificate from a pfx file
using the Microsoft Management Console.
1. Open the Microsoft Management Console with administrator privileges. (Click Start > mmc.exe,
right-click, and then click Run as Administrator.)
2. Click File > Add/Remove Snap-in, select Certificates, and then select Local Computer.

58

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

 You should see the certificate manager console.

3. In the certificate manager console, right-click Personal, and then click All Tasks > Import. The
Certificate Import Wizard opens.

4. Follow the Certificate Import Wizard to finish importing the certificate. Make sure that you import
the private key, which is needed for channel encryption.
5. Under Personal > Certificates, browse and locate the server certificate. Right-click the
certificate, and then click All Tasks > Manage private keys. The certificate security dialog box
opens.

59

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

6. In the certificate security dialog box, add the Real-time Service user account to the list, and give
read access to the user.

7. Under Personal > Certificates, browse and locate the server certificate. Double-click the
certificate to open the certificate properties dialog box.
8. On the Details tab, select Thumbprint.

The thumbprint is the 20-byte array that is displayed. Copy the value, removing all the spaces.
For example, the thumbprint for the certificate in the preceding screenshot is
6b3b49dfad6100a47ef623c8e471c567bf052530.
You need the thumbprint for the service installation.

60

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Install Real-time Service
1. Open a Windows PowerShell window with administrator privileges, and set the execution policy to
remote-signed (or unrestricted if you are using an unsigned script).

2. Change the directory to the sample deployment scripts folder.

This is the Sample Deployment Scripts folder under the Real-time Service binary folder, where you
can see a few Windows PowerShell scripts. For the default MSI install, the folder is
%ProgramFiles%\Microsoft Dynamics AX\6.2\Commerce Data Exchange\Real-time
Services\6.2\Sample Deployment Scripts.
3. Run Windows PowerShell scripts to install Real-time Service.
>./InstallCommerceDataExchangeRealtimeService.ps1.
4. When you are prompted by the installation scripts, supply the following mandatory parameters.

Property Description
User account The domain\user for the domain account for Real-time Service.
Note: This account needs to be a Microsoft Dynamics AX account that has
sufficient privileges to perform all the necessary retail tasks.

Password The password for the domain account.

Service binary source folder The service binary folder, where the web.config and service files are
path located. For the default MSI install, this folder should be something like
%ProgramFiles%\Microsoft Dynamics AX\6.2\Commerce Data
Exchange\Real-time Services\6.2.

Server certificate thumbprint The thumbprint for the server certificate.

The installation scripts then install Real-time Service with all the required dependency
components. If the installation is completed successfully, you see output like the following.

61

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

5. In a browser, test the service installation by opening the link to the service:
http://localhost:9080/CommerceDataExchangeRealtimeService/service.svc. The Windows
Communication Foundation (WCF) metadata exchange Help page opens if the service has been
configured correctly.

Uninstall Real-time Service

In the event that you need to uninstall Real-time Service, follow these steps.
1. Open a Windows PowerShell window with administrator privileges, and set the execution policy to
remote-signed (or unrestricted if you are using an unsigned script).
2. Change the directory to the sample deployment scripts folder.
This is the Sample Deployment Scripts folder under the Real-time Service binary folder, where you
can see a few Windows PowerShell scripts. For the default MSI install, the folder is
%ProgramFiles%\Microsoft Dynamics AX\6.2\Commerce Data Exchange\Real-time
Services\6.2\Sample Deployment Scripts.
3. Run Windows PowerShell scripts to uninstall Real-time Service.
>./UninstallCommerceDataExchangeRealtimeService.ps1.

62

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

 When the script prompts you for the service install folder, provide the path of the folder where the
web.config file is located. The default location is
%SystemDrive%\inetpub\DynamicsAxRetail\CommerceDataExchangeRealtimeService.

Configure Real Time Service

Configure a Real-time Service profile in Microsoft Dynamics AX

The Real-time Service profile contains all the information that the clients need to connect to the
server. The service profile can be configured in Microsoft Dynamics AX.
The user interface to configure the Real-time Service is located at Retail > Setup > Retail
scheduler > Channel integration > Real-time Service profiles.

The following table describes the fields that are available.

Field Description
Server The server host name

Port The port to use for communication. For net.tcp, the default port is 808.
For http, the default port is 9081.

Protocol The communication protocol. By default, it is net.tcp, but we also support

https.
Note: To use https, you need to change the server configuration. For
details, see the Configure Real-Time Service settings section.

63

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Field Description
Web application name The web application name for Real-time Service. If you are using the
default install script to install the service, the web application name
should be CommerceDataExchangeRealTimeService.

Common name The server certificate common name. You can find this at Start >
mmc.exe > Personal > Certificates, in the Issued To column.

Passphrase The passphrase that is used for Microsoft Dynamics AX to verify that a
POS terminal is a valid terminal.

Language The language used to return error message from Real-time Service.

Real-time Service version The Real-time Service version to use. Use the default (Microsoft Dynamics
AX 2012 R2) unless you are working with N-1 support.

Configure Real-time Service settings

The Real-time Service server settings can be modified by changing the web.config file. This is a
standard WCF configuration file. You can find the file at
%SYSTEMDRIVE%\inetpub\DynamicsAxRetail\CommerceDataExchangeRealtimeService\Web.config.
Change the logging level
The logging level is controlled by using the <system.diagnostics> element. The default logging level is
set to Warning for the trace log and Error for the event log. However, you can change these to
Information if you need more extensive logging. By default, the trace log is located at
C:\Windows\Temp\RetailLogs\w3wp.exe.xml.
<system.diagnostics>
<sources>
<!-- this registers the listener with traces from a specific source -->
<source name="RetailNetTracer" switchValue="Warning">
<listeners>
<add name="RollingXmlWriterTraceListener" />
</listeners>
</source>
<source name="RetailNetTracerEventLog" switchValue="Error">
<listeners>
<add name="EventLogTraceListener" />
</listeners>
</source>
</sources>
...
</system.diagnostics>
There are two listeners in the preceding configuration: the Windows event log and the log file. To read
the contents of the log file, you need to use Service Trace Viewer. To start Service Trace Viewer, click
Start, and then search for Service Trace Viewer. Alternatively, you can start it from C:\Program Files
(x86)\Microsoft SDKs\Windows\v7.0A\Bin\NETFX 4.0 Tools\SvcTraceViewer.exe.
The log file for Real-time Service is located at C:\Windows\Temp\RetailLogs, and the file name is
typically w3wp.exe_00.xml.
Change the binding configuration
The default binding for Real-time Service is netTcpBinding. WSHttp is also supported for https
connections. You can change the binding.
<services>
<service behaviorConfiguration="ReleaseBehavior"
name="Microsoft.Dynamics.Retail.TransactionServices.TransactionService">

64

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

 <endpoint address="Common" binding="netTcpBinding"
bindingConfiguration="StreamedTCPBinding" name="Common"
contract="Microsoft.Dynamics.Retail.TransactionServices.Contracts.ITransactionService" />
...
</service>
</services>
Note: If you need to change the binding configuration from Net.Tcp to WSHttp, use the binding
configuration provided in the config file, and update the Real-time Service profile in Microsoft
Dynamics AX. This ensures that the client and server can work together.

Configure Real-time Service for POS

After you have created a Real-time Service profile, go to the POS register, and configure the Real-time
Service profile to be used for that register.

After you have selected a Real-time Service profile, run the Synch Service job A-1090 Registers.

65

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Real-time Service customization guide
In addition to the default functionality that is delivered with the product, Real-time Service also lets
customers and partners extend its functionality by adding extension methods. These methods can be
invoked from the client side to perform any custom business logic.
Note: For the extension methods to work, Real-time Service must be installed and configured
correctly. For more information, see the Install and set up Real-time Service section.
This section describes how to add extension methods in Microsoft Dynamics AX, and how to consume
the extension methods from a Commerce Runtime client.

Add extension methods in Microsoft Dynamics AX

Prerequisites
 An installation of Microsoft Dynamics AX 2012 R2
 A Developer license for Microsoft Dynamics AX 2012 R2
Adding extension methods in Microsoft Dynamics AX is straightforward. You just need to add a new
method in the RetailTransactionServiceEx class in the AOT. There are a few requirements for this
method so that it can be invoked through Real-time Service:
 The method must be a public static method.
 The return type must be a container of length 2 or longer. The first two elements are reserved for
a Boolean that indicates success or failure of the method call, and a string that can be used for
comment or error message. The other items in the returned container can be of any type,
including nested containers.
 The parameters for the method must be of primitive types in Microsoft Dynamics AX. Only the
following types are supported because of limitations in.NET Business Connector.

X++ type CLR type

boolean System.Boolean

date System.DateTime

int System.Int32

int64 System.Int64

str System.String

guid System.Guid

Real System.Single or System.Double

Example customization of Real-time Service

For this example, we want to add a method that accepts a customer account number and then returns
a greeting message that uses the customer’s name. For example, for customer Sandy, whose account
number is 1001, the method would return “Hello Sandy!”
The implementation in Microsoft Dynamics AX involves adding the following method in the
RetailTransactionServiceEx class:
public static container Hello(AccountNum accountNumber)
{
CustTable custTable;
DirPartyTable dirPartyTable;
container result = [false, ''];

66

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

 if (accountNumber)
{
select firstOnly Name from dirPartyTable
exists join custTable
where custTable.accountNum == accountNumber
&& dirPartyTable.RecId == CustTable.Party;

if (dirPartyTable)
{
result = [true, 'Success!', strFmt("Hello %1 !", dirPartyTable.Name)];
}
else
{
result = [false, 'Customer not found'];
}
}
else
{
result = [false, 'accountNumber is null.'];
}

return result;
}

Calling extension methods from a POS client

Consuming the Real-time Service extension methods from a POS or Commerce Runtime client is also
straightforward. It is similar to consuming the ordinary Real-time Service methods. The only
difference is that, instead of calling InvokeMethod, we need to call InvokeExtensionMethod.
The following example calls the Hello methods that we used as an example in the previous section:
public void HelloCustomer(string accountNumber)
{
try
{
var response =
this.CommerceRuntime.TransactionService.InvokeExtensionMethod("Hello", "2014");
if (response.Count == 1)
{
Console.WriteLine(response[0] as string);
}
}
catch (CommunicationException ex)
{
Console.WriteLine("Request failed: {0}", ex.Message);
}
}
Note: The response successful and comments have been abstracted away. If the request fails (false
on the first container results), the service client throws a communication exception. Only the
additional response data is returned.

Debugging Real-time Service

If you use Microsoft Visual Studio to develop your own functionality that calls into Microsoft Dynamics
AX through Retail-time Service, you can set up end-to-end debugging by following these steps to
67

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

ensure that you can break into your X++ code. Because Real-time Service is built on top of WCF,
Microsoft Dynamics AX requires special handling for triggering the X++ debugger when calls come in
through WCF.
1. Start the Microsoft Dynamics AX 2012 Configuration utility.

2. Select Local client, and then click Manage > Create configuration.

3. Name the client configuration.

68

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

4. Select the Enable user breakpoints to debug code in the Business Connector check box.
You can leave the license code fields blank.

5. Select Business Connector (non-interactive use only).

6. Click Manage > Create configuration.

69

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

7. Name the Business Connector configuration. You will need to find this name in the registry later.

8. Select the Enable user breakpoints to debug code in the Business Connector check box.
Again, you can leave the license code fields blank.

9. Open Registry Editor by running the command regedit.exe.

70

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

10. Locate the
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Dynamics\6.0\Configuration\ConfigNa
me key, where ConfigName is the name that you gave the Business Connector configuration.

11. Create a new string value with the name debug_across_os_session and a value of 1.

12. Reset IIS by typing the command c:>\iisreset.

13. If the X++ method is marked as a server method, you also need to configure AOS server
debugging. Set breakpoints in the Microsoft Dynamics AX X++ code, typically in the
RetailTransactionService class. You should now be able to break into the X++ debugger.

71

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

Troubleshoot Real-time Service
Issue
You receive a failure message when you try to use a POS terminal to issue gift cards or query
customer orders. You drag the POS log (in %temp%\RetailLogs) into Service Trace Viewer (click
Start, and then search for Service Trace Viewer) to see what happened. The error message says
“Communication object cannot be found.”
Solution
Make sure that you import the certificate into the Personal folder, not the Trusted Root Certification
Authorities folder, on the POS computer, as shown in the following screenshot.

72

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

N-1 setup and configuration
The N-1 feature is a set of Microsoft Dynamics AX 2012 R2 functionalities that supports previous
versions of POS clients. Database schemas differ between versions of the POS store database.
Microsoft Dynamics AX 2012 R2 provides framework support and data transformation, so that
Microsoft Dynamics AX 2009 R2 works with the POS database from Microsoft Dynamics AX 2012
Feature Pack.
N-1 also enables customizations and extensions by partners and customers to work with their own set
of tables.
To use the N-1 support feature, you need to have the following items:
 A Retail system that has been upgraded to Microsoft Dynamics AX 2012 R2.
 Stores and registers that use POS clients from the previous version (N-1) of Retail.
 The version of Microsoft Dynamics for Retail Store Connect that is used by the previous version of
POS.
 Real-time Service 5.1. This is a modified version of Microsoft Dynamics for Retail Transaction
Service that enables Microsoft Dynamics AX 2012 R2 to continue to accept calls from stores that
use previous versions.
 Microsoft Dynamics AX 2012 R2 Synch Service
The following items are not required:
 The previous version of Retail Transaction Service
 The previous version of Retail Store Connect
 The previous version of Microsoft Dynamics AX

Example
The example in this section is based on the following assumptions:
 You have a Retail system on Microsoft Dynamics AX 2009 that has one store (S0001) with one
terminal (T001).
 The distribution location of the terminal is T001.
 Database profile TestDB5Profile is pointing to the database that is being used by this terminal.
 The Retail Store Connect profile name that is used by this store is TestStoreConnect5Profile, and it
is assigned to TestDB5Profile.
 The Retail Transaction Service profile assigned to this terminal is TestTS5Profile.
 The AOS profile name used in the scenario is TestAOSProfile.

Goal
After the Microsoft Dynamics AX upgrade is completed, you can still use the older version of the
software in the store without change, and you can also work with the upgraded Microsoft Dynamics AX
2012 R2 Retail system.

Set up and configure N-1 support

The following steps are required to set up and configure N-1 support, so that Microsoft Dynamics AX
2012 R2 Retail can work with older version stores.
1. After the upgrade is completed, generate the seed data that is required for N-1 operations. This
process creates the scheduler jobs and the logic required to support N-1 operations.
a. Open the AOT.

73

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

 b. Select the RetailConnSeedDataGeneratorAX5 class (if the system is upgraded from
Microsoft Dynamics AX 2009) or the RetailConnSeedDataGeneratorAX61 class (if the
system is upgraded from Microsoft Dynamics AX 2012 Feature Pack).
c. Right-click the class, and then click Open.
Scheduler jobs that are created by the RetailConnSeedDataGeneratorAX5 class are
suffixed with _AX5. Scheduler jobs that are created by the
RetailConnSeedDataGeneratorAX61 class are suffixed with _AX61.
2. Set the schema type for the distribution location of this terminal to AX 2009 POS. This lets the
system determine that we are dealing with an N-1 version system.
3. If there is no existing distribution location list, create a new distribution location list, and add
distribution location T001 to it. For this example, the new distribution location list is named
DefaultIncludeList.
4. Open the Distribution schedule form, and configure the new scheduler jobs that were created
when you ran the class.
a. Select each N-1 scheduler job. In this example, these are the jobs suffixed with _AX5.
b. Set the AOS profile to the current AOS profile that you are using.
c. Set the distribution location list to DefaultIncludeList.
5. Create a new Synch Service profile. For this example, the name of the new profile is
StoreConnectv62Profile.
6. Open the AOS profiles that you are currently using, and set the Synch Service profile to the one
that you created in the previous step.
Note: The database profile TestDB5Profile that is pointing to the N-1 (older) version store
database should still be using the N-1 (older) version Retail Store Connect service. Make sure that
the Synch Service profile on the TestDB5Profile database profile is set to
TestStoreConnect5Profile.
7. In Microsoft Dynamics AX 2012 R2, the Real-time Service profile has a field called Retail schema
type. By default, after upgrade, the schema type of all Real-time Service profiles is set to the
schema type AX 2012 R2 POS. For N-1 support, the Real-time Service profile that is used by N-1
(older) version stores and terminals should have the Retail schema type set to AX 2009 POS.
Therefore, in this example, make sure that the schema type of the Real-time Service profile
TestTS5Profile is set to AX 2009 POS. Set the server name to the name of the server on which
Real-time Service 5.1 is installed.
8. Go to the server on which you installed Real-time Service 5.1, and start the service. By default, it
is disabled after setup is completed.
After the preceding steps are completed, you can send and receive data from the N-1 (older) version
store by running the scheduler jobs that were created for N-1.
Note: In our scenario, the scheduler job is assigned to a distribution list that only contains distribution
locations that point to an older version store (locations with schema type AX 2009 POS). If the
distribution location list that is assigned to the scheduler job contains a mix of distribution locations
that have different schema types, the scheduler job only acts on locations with a schema type that
matches the schema type of the scheduler job.
Provided that the N-1 feature is being used, the upgrade model and the SysDeleteObjects
configuration key should not be disabled. Disabling these keys removes all code and data that are
used by the N-1 feature.

74

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE

 Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you and your
people to make business decisions with greater confidence. Microsoft Dynamics works like and with familiar
Microsoft software, automating and streamlining financial, customer relationship and supply chain processes in a
way that helps you drive business success.

U.S. and Canada Toll Free 1-888-477-7989

Worldwide +1-701-281-6500
www.microsoft.com/dynamics

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the
date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a
commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of
publication.

This white paper is for informational purposes only. Microsoft makes no warranties, express or implied, in this document.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of
this document may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means
(electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of
Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject
matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this
document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2013 Microsoft Corporation. All rights reserved.

The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted
herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person,
place, or event is intended or should be inferred.

Microsoft, Microsoft Dynamics, the Microsoft Dynamics logo, MSDN, SharePoint, SQL Server, Visual Studio, Windows, Windows
PowerShell, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States
and/or other countries.

75

IMPLEMENTATION GUIDE FOR COMMERCE DATA EXCHANGE