Fields Mapping.

Table of Contents

• Overview
• Example Scenario
  • Use case
  • Defining the Field Mapping in the Export Configuration
• Using an External CSV File for Field Mapping
• Mapping External Id Field
• Additional Notes

Overview ⇧

Purpose: This feature simplifies data exports to different target data models by allowing the use of field mappings that accommodate differences in field names and structures between the source and target objects.

Example Scenario ⇧

Use case ⇧

Suppose you want to export Account data into another object called TestObject__c in a target system where field names and structures differ from the source. The Fields Mapping feature enables such cross-object data migration by defining a mapping scheme that translates source fields to their respective target fields.

Consider the following differences between the source object Account and the target object TestObject__c:

• TestObject__c.ParentTestObject__c is a self-referenced lookup to TestObject__c, similar to how Account.ParentId references Account.
• The external ID field for Account is ExternalID__c, while for TestObject__c, it is External_ID__c.
• Most other fields share the same names across both objects.

Here is the field mapping scheme for this scenario:

Defining the Field Mapping in the Export Configuration ⇧

You can implement these mappings using the fieldMapping property in the export.json file as shown below:

{
    "objects": [
        {
            "query": "SELECT Id, Name, ParentId, ExternalID__c, TEST__c FROM Account",
            "operation": "Upsert",
            "externalId": "Name",
            "useFieldMapping": true,
            "fieldMapping": [
                {
                    "targetObject": "TestObject__c"
                },
                {
                    "sourceField": "ParentId",
                    "targetField": "ParentTestObject__c"
                },
                {
                    "sourceField": "ExternalID__c",
                    "targetField": "External_ID__c"
                }
            ]
        }
    ]
}

Using an External CSV File for Field Mapping ⇧

For extensive field mappings across multiple objects and fields, consider using a dedicated CSV file named FieldMapping.csv. This file should be placed in the same directory as your export.json:

Here is an example of the FieldMapping.csv content for the scenario described:

To activate field mapping for an object, set the object's useFieldMapping property to true.

Here's a corrected and improved version of your article:

Mapping External Id Field ⇧

You can map a field used as an External Id field to another field on the target side. However, it is important to understand that the comparison of external id values to match records between the source and target occurs before the field mapping is applied. Consequently, the plugin will compare the original field names on both sides. This approach generally works fine for the Insert operation.

For instance, in the export.json file described above, if you set externalId to ExternalID__c instead of Name, it will not function properly for Upsert operations. This is because the plugin will attempt to use the source field ExternalID__c to compare records rather than the mapped field External_ID__c. This can lead to issues, especially if the ExternalID__c field does not exist in the target organization.

Additional Notes ⇧

• Ensure to include all fields specified in the sourceField in the object's query string. Fields mentioned in the mapping but omitted from the query will not be mapped. Fields included using the "multiselect" keyword will be ignored in the mapping schema.
• Field and object names in the mapping schema are CASE SENSITIVE.
• The mapping applies only to fields that directly belong to the sobject and does not extend to queries on reference fields.
• You cannot map the same field to multiple fields within the same object using Field Mapping.