Mapping the Tables and Fields to Synchronize

The basis of synchronizing data in Business Central with data in Common Data Service is mapping the tables and fields that contain the data to each other. Mapping happens through integration tables.

Mapping Integration Tables

An integration table is a table in the Business Central database that represents an entity, such as an account, in Common Data Service. Integration tables include fields that correspond to the fields in the table for the Common Data Service entity. For example, the Account integration table connects to the Accounts entity in Common Data Service. There must be a integration table mapping for each entity in CDS that you want to synchronize with data in Business Central.

When you create the connection between the apps, Business Central sets up some default table and field mappings. You can change the table mappings if you want. For more information, see Standard Entity Mapping for Synchronization. If you have changed the default mappings and want to revert your changes, on the Common Data Service Connection Setup page, choose Use Default Synchronization Setup.

Note

If you are using an on-premises version of Business Central, the integration table mappings are stored in table 5335 Integration Table Mappings, and can be viewed and modified from page 5335 Integration Table Mappings. Complex mappings and synchronization rules are defined in codeunit 5341.

Synchronization Rules

An integration table mapping also includes rules that control how integration synchronization jobs synchronize records in a Business Central table and an entity in Common Data Service.

Mapping Integration Fields

Mapping tables is only the first step. You must also map the fields on the tables. Integration field mappings link fields in Business Central tables with corresponding fields in Common Data Service, and determine whether to synchronize data in each table. The standard table mapping that Business Central provides includes field mappings, but you can change those if you want. For more information, see Viewing Entity Mappings.

Note

If you are using an on-premises version of Business Central, Integration field mappings are defined in table 5336 Integration Field Mapping.

Handling Differences in Field Values

Sometimes the values in the fields that you want to map are different. For example, in Dynamics 365 Sales the language code for the United States is "U.S.," but in Business Central it's "US." That means you must transform the value when you synchronize data. This happens through transformation rules that you define for the fields. You define transformation rules on the Integration Table Mappings page by choosing Mapping, and then Fields. Predefined rules are provided, but you can also create your own. For more information, see Transformation Rules.

Handling Missing Option Values in Mapping

Common Data Service contains option set fields that provide values that you can map to Business Central fields of the type Option for automatic synchronization. During synchronization, non-mapped options are ignored and the missing options are appended to the related Business Central table and added to the CDS Option Mapping system table to be handled manually later. For example, by adding the missing options in either product and then updating the mapping. For more information, see Handling Missing Option Values.

Coupling Records

Coupling links records in Common Data Service to records in Business Central. For example, accounts in Common Data Service are typically coupled with customers in Business Central. Coupling records offers the following benefits:

  • It makes synchronization possible.
  • Users can open records in one business app from the other. This requires that the apps are already integrated.

Couplings can be set up automatically by using the synchronization jobs, or manually by editing the record in Business Central. For more information, see Synchronizing Data in Business Central and Common Data Service and Couple and Synchronize Records Manually.

Filtering Records

If you do not want to synchronize all records for a specific entity in Common Data Service or table in Business Central, you can set up filters to limit the records that are synchronized. You set up filters on the Integration Table Mappings page.

To filter records for synchronization

  1. Choose the Lightbulb that opens the Tell Me feature icon, enter Integration Table Mappings, and then choose the related link.

  2. To filter the Business Central records, set the Table Filter field.

  3. To filter the Common Data Service records, set the Integration Table Filter field.

Creating New Records

By default, only records in Business Central and Common Data Service that are coupled will be synchronized by the integration synchronization jobs. You can set up table mappings so that new records will be created in the destination (for example, Business Central) for each record in the source (for example, Common Data Service) that is not already coupled.

For example, the SALESPEOPLE - Dynamics 365 Sales synchronization job uses the table mapping SALESPEOPLE. The synchronization job copies data from user records in Common Data Service to salesperson records in Business Central. If you set up the table mapping to create new records, for every user in Common Data Service that is not already coupled to a salesperson in Business Central, a new salesperson record is created in Business Central.

To create new records during synchronization

  1. Choose the Lightbulb that opens the Tell Me feature icon, enter Integration Table Mappings, and then choose the related link.

  2. In the table mapping entry in the list, clear the Synch. Only Coupled Records field.

Using Configuration Templates on Table Mappings

You can assign configuration templates to table mappings to use for new records that are created in Business Central or Common Data Service. For each table mapping, you can specify a configuration template to use for new Business Central records and another template to use new Common Data Service records.

If you install the default synchronization setup, most of the time, two configuration templates will be automatically created and used on the table mapping for Business Central customers and Dynamics 365 Sales accounts: CDSCUST and CDSACCOUNT.

  • CDSCUST is used to create and synchronize new customers in Business Central based on an account in Dynamics 365 Sales.

    This template is created by copying an existing configuration template for customers in the application. The CDSCUST is created only if there is an existing configuration template and the Currency Code field in the template is blank. If a field in the configuration template contains a value, the value will be used instead of the value in the mapped field for the Common Data Service account. For example, if the Country/Region field in an account in Common Data Service contains U.S. and the Country/Region field in the configuration template is GB, then GB is used as the Country/Region for the customer in Business Central.

  • CDSACCOUNT creates and synchronizes new accounts in Common Data Service based on an account in Business Central.

To specify configuration templates on a table mapping

  1. Choose the Lightbulb that opens the Tell Me feature icon, enter Integration Table Mappings, and then choose the related link.

  2. In the table mapping entry in the list, in the Table Config Template Code field, choose to the configuration template to use for new records in Business Central.

  3. Set the Int. Tbl. Config Template Code field to the configuration template to use for new records in Common Data Service.

See Also

About Integrating Dynamics 365 Business Central with Common Data Service
Synchronizing Business Central and Common Data Service
Schedule a Synchronization