How to synchronize new tables between AX and CRT using N, A and P schedules

Contents
Overview ....................................................................................................................................................... 2 Important concepts....................................................................................................................................... 2 Basic general concepts .............................................................................................................................. 2 A-job specific concepts ............................................................................................................................. 2 Data-area specific data transfer from AX to channel ............................................................................... 2 Channel specific data transfer from AX to channel .................................................................................. 2 Table distribution configuration overview ............................................................................................... 3 Incremental data transfer ......................................................................................................................... 4 Bi-directional data transfer ....................................................................................................................... 4 Synchronizing updates .............................................................................................................................. 4 Assumptions in this document ..................................................................................................................... 4 Synchronize using N jobs .............................................................................................................................. 5 Add to schema .......................................................................................................................................... 5 Define sub-job ........................................................................................................................................... 5 Add sub-job to job..................................................................................................................................... 5 Synchronize using A jobs............................................................................................................................... 5 Creating pre-actions.................................................................................................................................. 5 Add to filter by action creations ............................................................................................................... 6 Add to table-distribution configuration .................................................................................................... 7 Add to schema .......................................................................................................................................... 8 Define sub-job ........................................................................................................................................... 8 Add sub-job to job..................................................................................................................................... 8 Synchronize using P jobs ............................................................................................................................... 8 Prepare table for uploads ......................................................................................................................... 8 Incorporate ReplicationCounter, an auto-increment column in the table in channel ......................... 8 Implement maxReplicationCounterFromOrigin ................................................................................... 8 Add to schema .......................................................................................................................................... 8 Define sub-job ........................................................................................................................................... 8

Add sub-job to job..................................................................................................................................... 9

Overview
Commerce Data Exchange provides three different modes of synchronizing data between AX and the Commerce Runtime database (CRT). It is important to understand the difference between them. 1. N-jobs N stands for Normal. These schedules are designed for performing fast bulk copying of data from AX to the channel database. For each synchronization of an included table, the corresponding table in the destination database is completely wiped before writing data received from AX. 2. A-jobs A stands for Action. These schedules are designed for performing incremental synchronization of data from AX to the channel database. More importantly, they also perform channel specific data transfer (discussed in more detail below). 3. P-jobs P stands for Pull. These schedules are designed for pulling data from the channel database into AX. Typically, these jobs are used for bringing transactions and orders into AX.

Important concepts
Basic general concepts
Sub-job Captures information about a single table to be synchronized Job Captures information about a set of Sub-jobs to be synchronized Distribution location Captures information about a data distribution target Location list Captures information about a set of distribution locations Schedule Captures information about synchronization of a set of location lists to a set of jobs

A-job specific concepts

Pre-action Captures information a single change performed by the user, e.g. update the name of an item. Action Captures information about one or more changes to be replicated to one or more distribution locations.

Data-area specific data transfer from AX to channel

Supported by: Both N and A schedules. Details: For a legal entity specific table, e.g. InventTable, only the rows mapping to the legal entity of the destination store are sent to that location.

Channel specific data transfer from AX to channel

Supported by: A schedules only. Details: This feature allows for only the set of rows that are directly or in-directly mapped to a channel, to be synchronized to it. This works based on the table-distribution configuration described below.

Table distribution configuration overview

To properly utilize A jobs, it is important to understand table-distribution. This feature provides a way to express two main things: Relationships between different tables from the perspective of data replication. Mechanism for resolving a change to a distribution location.

This can be best understood with an example. Notice the selected node, InventTable the table that contains the basic item information. Its configuration expresses that whenever theres a row inserted, updated or deleted in InventTable, perform the same action on the related rows in InventTableModule the table that contains the price information for items. InventTable by itself doesnt have a direct way to express which channel should an item be sent to. That relation is modelled in the design as a link between InventTable RetailAssortmentExploded

RetailPubRetailChannelTable RetailPubRetailOnlineChannelTable RetailConnDistributionLocation. The last one, RetailConnDistributionLocation represents a destination database. Therefore, the same relationship is expressed in table-distribution configuration. Now whenever theres a change in InventTable: 1. We traverse down starting at InventTable in the table-distribution tree trying to figure out which other data needs to be sent. 2. We traverse up till we reach RetailConnDistributionLocation to figure out which databases need all these changes to be sent to. That said, A jobs can be used without table-distribution. Table-distribution configuration can be deleted from the user-interface. The result is that A jobs would perform incremental synchronization of data, but not location specific data transfer, nor related data transfer. The reason for this should be obvious from the above paragraph. Without table-distribution, CDX doesnt know how to resolve a change to a location, nor what rows from other tables need to be replicated with the original change.

Incremental data transfer

Supported by: A and P schedules. Details: N jobs do not support incremental data transfer. Upon each execution of N sub-job, all the data in the destination table is deleted before data received from AX is applied. That is not the case with A and P jobs. o A-jobs: Since pre-actions are captured only for the changes, the system has a way to identify only the rows that have to be replicated and thus replicate only the changed rows to the channel database from AX. o P-jobs: Before requesting any data from a channel distribution location for a table, CDX determines the largest counter among the records received so far from that location. Next, it requests the CDX on the channel side to only send records having counters greater than the value known in AX. This allows the system to perform incremental uploads of data from channels to AX.

Bi-directional data transfer

Supported by: NOT SUPPORTED Details: It is not possible to configure CDX to synchronize the same table from AX to a channel database and back. This restriction prevents any conflicts from ever arising since the same data cannot be updated by multiple databases.

Synchronizing updates
Supported by: N and A jobs. Not by P jobs. Details: P jobs do not support synchronizing updates from the channel distribution location to AX. P jobs are designed to perform fast bulk inserts only.

Assumptions in this document

Tables to be replicated exist in both AX and the channel database Store Connect, AOS profiles and Database profiles have been set up as required

Synchronize using N jobs

Add to schema
Go to the distribution location of the channel (Setup Retail scheduler Distribution locations) and select Functions Read schema. This would bring the information about all the tables and their fields present in the channel into AX.

Define sub-job
1. Click Retail > Setup > Retail scheduler > Scheduler subjob. 2. Click New to create a new subjob, or select the subjob that you want to modify. a. Make sure Replication method is Normal. 3. Complete the information in the Scheduler subjob form. You can also copy the settings of an existing subjob to a new subjob. For help completing the form, open the form, and then press F1. Note You can assign a subjob to more than one job.

Add sub-job to job

1. Click Retail > Setup > Retail scheduler > Scheduler job 2. Select an existing N job 3. In Subjobs pane, click New and select the sub-job created in the previous section.

Synchronize using A jobs

Creating pre-actions
Pre-actions are used to record that a change was made on a table. Insert of a new row, update of an existing row, or delete of an existing row are all considered changes. The insert(), update() and delete() methods on the table to be synchronized using A jobs, need to be overridden to capture pre-actions. RetailConnActionManagement::createActions can be called to capture the pre-action from the overridden methods. Additionally, not all changes need to be captured e.g. we may be interested in changes to a subset of all the fields present on the table. To account for this, the overridden method must call RetailConnActionManagement::shouldReplicate to check whether a pre-action needs to be created or not, and only call RetailConnActionManagement::createActions if shouldReplicate returns true. Since the super() call in the overridden methods modifies the field values in the record, care has to be taken to about the sequence of the calls so as to be as in the examples below. 1. Insert method example:
public void insert() { Boolean replicate = false; if (isConfigurationkeyEnabled(configurationKeyNum(Retail)))

{ replicate = RetailConnActionManagement::shouldReplicate(this, this.orig(), false); } ttsbegin; super(); if (replicate) { RetailConnActionManagement::createActions(this, RetailConnActionUpdate::Insert); } ttscommit; }

2. Update method example:

public void update() { Boolean replicate = false; if (isConfigurationkeyEnabled(configurationKeyNum(Retail))) { replicate = RetailConnActionManagement::shouldReplicate(this, this.orig(), false); } ttsbegin; super(); if (replicate) { RetailConnActionManagement::createActions(this, RetailConnActionUpdate::Update); } ttscommit; }

3. Delete method example:

public void delete() { ttsbegin; if (isConfigurationkeyEnabled(configurationKeyNum(Retail)) && RetailConnActionManagement::shouldReplicate(this, this.orig(), true)) { RetailConnActionManagement::createActions(this, RetailConnActionUpdate::delete); } super(); ttscommit; }

Add to filter by action creations

1. Open Retail > Setup > Retail scheduler > Filter on action creations 2. Click New and add the name of the table for which pre-actions should be captured.

3. Enter the names of all the fields whose updates should cause a pre-action to be captured in the Fields pane.

Add to table-distribution configuration

1. Open Retail > Setup > Retail scheduler > Table distribution 2. Determine the parent table node: This should be based on how a change in the table to be synchronized should resolve to a distribution-location. 3. Select the parent node, and click New to add the new child node. a. For Table ID, select the ID of the table to be synchronized. b. For determining Distribution type, use the following: i. All distribution locations Distribute modifications to the records in a table to all locations. This is the default distribution type. ii. 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. Important If you select this distribution type, you must set up table links that describe the relationship between the child table and its parent table. For more information, see "Set up table links," later in this section. iii. 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. Important Typically, you select this distribution type only for tables at the top of the table distribution hierarchy. iv. 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. c. Linked actions on insert, update, delete these settings do not affect the replication of this table, but those of its child tables. 4. Check the linked actions settings on the parent. a. Linked actions on insert: Check this if an insert in parent should cause the linked row from this table to be replicated too. b. Linked actions on update: Check this if an update in the parent should cause the linked row from this table to be replicated too. c. Linked actions on update: Check this if a delete in the parent should cause a delete for the linked row from this table to be replicated too. Important Special care should be taken if selecting this option. If the same row in the child table could be linked to multiple parent rows, checking this option will lead to the child being deleted, if any of the parents is deleted. In such a situation it is advisable to leave this unchecked and handle this situation in the channel by only consuming those childs for which parents can be found.

Add to schema
Same as N job.

Define sub-job
Same as N job, except by actions as replication-method.

Add sub-job to job

Same as N job.

Synchronize using P jobs

Prepare table for uploads
Incorporate ReplicationCounter, an auto-increment column in the table in channel
This is very important and provides a way to identify records created after a certain previously known value of ReplicationCounter.

Implement maxReplicationCounterFromOrigin
AX uses the maxReplicationCounterFromOrigin method to determine the largest value received from the channel for records in a specific table from a specific location. The field mappings for the sub-job should be set up such that values in ReplicationCounter column in the table in the channel database end up in ReplicationCounterFromOrigin column in the corresponding table in AX database. Example implementation:
public RetailReplicationCounter maxReplicationCounterFromOrigin(RetailConnDistributionLocationId _locationId) { RetailTransactionTaxTrans taxTransTable; RetailTerminalTable terminalTable; if (_locationId) { select maxOf(ReplicationCounterFromOrigin) from taxTransTable where taxTransTable.Origin == _locationId; return taxTransTable.replicationCounterFromOrigin; } return taxTransTable.ReplicationCounterFromOrigin; }

Add to schema
Same as N job.

Define sub-job
Same as N job. Check Pull data.

Add sub-job to job

Same as N job.