1. To-Increase Dynamics 365 for Finance & Operations
  2. Connectivity studio
  3. Design
  4. Set up messages

Set up field mapping

The message is the carrier for all the information that is needed for the integration. On the field mapping you define which target document record fields are mapped to which source document record fields. The resulting field mapping is used to get the right data from the source and get it in the right format to the right place in the target.

 


Application Consultant Application Consultant Start Start Add mapping fields Add mapping fields Set up the field mapping for each record mapping of the message. On the field mapping, you define which target document record fields are mapped to which source document record fields. The resulting field mapping is used to get the right data from the source and get it in the right format to the right place in the target. To set up the field mapping, you can: Add fields manually. Select fields from a list. You can only use the fields, as defined for the related record in the target document. Procedure 1. Click Connectivity studio Integration Design. 2. On the Message tab, in the list, find and select the desired message. 3. Click Edit. 4. In the Mapping section, in the Target record pane, in the list, find and select the desired target record. 5. Sub-task: Add mapping field manually. 6. On the Mapping tab, on the Field mapping tab, click New. 7. In the Target field field, enter or select a value. Note: You can only enter a field as defined for the target record on the target document. 8. Sub-task: Select mapping fields. 9. You can select fields from a list of fields as defined for the applicable target record in the target document. Click Select mapping fields. Note: Only the target record fields are shown that are not yet used for a field mapping. 10. Select the Selected check box. 11. Click Select mapped fields. 12. Click Select all. 13. Click OK. 14. Sub-task: Set field mapping details. 15. Select the Key field check box. 16. Usually, you select a source field from a source record. However, you can also select a source field from a target record. This target record serves as source for the field mapping. You can, for example, use a previous record mapping to only find a record and use this as input for the field mapping. To use a target record as source record, in the Source field lookup, change the direction to Target and select a target record. In the Source record field, enter or select a value. Note: If you use a target record as source record, make sure that the selected target record mapping is done before the current record mapping. 17. In the Source field field, enter or select a value. 18. You can set a constant value. On executing the field mapping, the 'Get a value' process, gets the constant value and uses it as input for the 'Modify a value' process. You can use a constant value if the required value does not exist in the source. To apply a constant value, select the Constant check box. Note: If this check box is selected, also fill in the Constant value field. 19. If the Constant check box is selected, define the constant value for the target field. In the Constant value field, enter or select a value. Note: If the target document is an: - Internal document, you can select a value from the table that is related to the target record. - External document, you can only type a value. 20. To make sure a target field is always filled, you can define a default value for the target field. If no source value is available for the field, the target field gets this default value. In the Default value field, enter or select a value. Note: If the target document is an: - Internal document, you can select a value from the table that is related to the target record. - External document, you can only type a value. 21. You can indicate in which cases the field mapping must be executed: - Always: The field mapping is always executed. - On insert: The field mapping is only executed if a record is inserted (new record). - On update: The field mapping is only executed if a record is updated (existing record). - Skip: the field mapping is skipped when the message is run. This option is usually used temporarily. For example, when you design or test a message. In the Execute field, select an option. Note: - If you export data (if the target document is an external document), this field must have the value Always. - On import of data (if the target document is an internal document), you can use On insert or On update. To determine if a record is new and must be inserted or already exists and must be updated, the key fields of the target record are used. So, make sure to set key fields on the target record if you use On insert or On update. 22. Define if the current value in D365 FO must be updated or not. You can set up these scenarios: - Always update: Execute = 'Always', Retain local value = 'Never'. - Only update if source value exists: Use a mapping condition to only map the field value if a source value exists. - Keep D365 FO value if it exists: Retain local value = 'Not empty'. - Never update: Execute = 'On insert'. - Always keep D365 FO value: Retain local value = 'Always'. In the Retain local value field, select an option. Note: This field is shown only if the target document: - Is a D365 FO document. - Has the BisDocumentAxDatabase handler class selected, or an extension of this handler class. Example: In Master data management, you can use this option to not override a value in the child company if the value is updated in the master data company. 23. Clear or select the Skip validation check box. Notes To make sure, your field mapping is complete, you can view the document fields that are not mapped. To view the non-mapped fields of the:Source document, on the Message page, on the ActionPane, on the Design tab, in the Source group, click Non-mapped fields.Target document, on the Message page, on the ActionPane, on the Design tab, in the Target group, click Non-mapped fields.You can define which fields are not mapped on-purpose. To do so, on the Non-mapped fields page, on the Skipped tab, enter these fields and the reason to not map these fields. Import or intercompany? Import or intercompany? Define field mapping sequence Define field mapping sequence On import, the business logic in D365 FO calls the ModifiedField method. This method can set or change other values. If the field mapping sequence is not right, it can reset values which are just imported.You can modify the sequence of the fields in the mapping. The sequence is important if you: Import data. Exchange data between D365 FO environments. Tip: Set field mappings in the sequence in which you fill in the fields in the related form. Procedure 1. Click Connectivity studio Integration Design. 2. On the Message tab, in the list, find and select the desired message. 3. Click Edit. 4. In the Mapping section, in the Target record pane, in the list, find and select the desired target record. 5. On the Mapping tab, on the Field mapping tab, in the list, find and select the desired field mapping. 6. Click Move up. 7. On the Mapping tab, on the Field mapping tab, in the list, find and select the desired field mapping. 8. Click Move down. 9. Close the page. Notes You can use the tracer to investigate if the field sequence is right. To use the tracer, run the message manually, and on the Run the message dialog, select the Use tracer check box. When the message run is finished, open the tracer: On the Message form, on the ActionPane, on the Operation tab, in the test group, click Tracer. Is advanced field mapping  setup required? Is advanced field mapping  setup required? Set up field mapping - Advanced

Set up field mapping - Advanced

For each field mapping, you can define several advanced settings. You can set up:
  • Conditions
  • Type conversions
  • Transformations
  • Options
  • Company-specific field mapping
Note: A field mapping without any advanced settings gives a better performance. So, the more advanced settings, the more time it takes to execute the field mapping.

 End End Use mapping  variables? Use mapping  variables? Create mapping variables Create mapping variables During a message run, you can use mapping variables to store values. You can write (calculated) values to a mapping variable, and later during the message run, read the value from the mapping variable. You can use mapping variables across records. The mapping variable values are only stored during the message run. When the message run is finished, the mapping variable values are deleted. During a message run, to: Write a mapping variable, on a field mapping, define the mapping variable as target variable, instead of using a target field. To set the mapping variable value, you can use several field mapping options, for example, a constant value, a custom expression, or a source field value. You can also use mapping variables on custom methods. Read a mapping variable, on a field mapping, define the target field to be filled with the mapping variable value. Instead of a source field, use the Variable field options to define the mapping variable which value must be used to set the target field value. Read a mapping variable for use in a custom expression, for the custom expression, create a variable with the Mapping variable field filled. Procedure 1. Click Connectivity studio Integration Design. 2. On the Message tab, in the list, find and select the desired message. 3. Click Edit. 4. On the Action Pane, click Design. 5. Click Mapping variable. 6. Click New. 7. In the Name field, type a value. 8. In the Data type field, select an option. 9. Close the page. 10. To show the mapping variable fields, refresh the page. Notes You can use mapping variables instead of calculations. Yes No Yes No Yes No

Activities

Name Responsible Description

Add mapping fields

Application Consultant

Set up the field mapping for each record mapping of the message. On the field mapping, you define which target document record fields are mapped to which source document record fields. The resulting field mapping is used to get the right data from the source and get it in the right format to the right place in the target.

To set up the field mapping, you can:

  • Add fields manually.
  • Select fields from a list.

You can only use the fields, as defined for the related record in the target document.

Define field mapping sequence

Application Consultant

On import, the business logic in D365 FO calls the ModifiedField method. This method can set or change other values. If the field mapping sequence is not right, it can reset values which are just imported.
You can modify the sequence of the fields in the mapping. The sequence is important if you:

  • Import data.
  • Exchange data between D365 FO environments.
Tip: Set field mappings in the sequence in which you fill in the fields in the related form.

Set up field mapping - Advanced

Application Consultant
For each field mapping, you can define several advanced settings. You can set up:
  • Conditions
  • Type conversions
  • Transformations
  • Options
  • Company-specific field mapping
Note: A field mapping without any advanced settings gives a better performance. So, the more advanced settings, the more time it takes to execute the field mapping.

Create mapping variables

Application Consultant

During a message run, you can use mapping variables to store values. You can write (calculated) values to a mapping variable, and later during the message run, read the value from the mapping variable. You can use mapping variables across records.

The mapping variable values are only stored during the message run. When the message run is finished, the mapping variable values are deleted.

During a message run, to:

  • Write a mapping variable, on a field mapping, define the mapping variable as target variable, instead of using a target field. To set the mapping variable value, you can use several field mapping options, for example, a constant value, a custom expression, or a source field value. You can also use mapping variables on custom methods.
  • Read a mapping variable, on a field mapping, define the target field to be filled with the mapping variable value. Instead of a source field, use the Variable field options to define the mapping variable which value must be used to set the target field value.
  • Read a mapping variable for use in a custom expression, for the custom expression, create a variable with the Mapping variable field filled.

Set up field mapping - Advanced

See also

Provide feedback