Fields Mapping.

This feature allows you to make the data export even the target data model is different than the source

Table of Contents

• Feature overview.
• Defining the field mapping in the export.json
• Defining the field mapping by the external CSV file.

Feature overview. ⇧

For example, you want to upload Account data into another object called TestObject__c.

Assume, that the TestObject__c has different field names than the Account:

• The field TestObject__c.ParentTestObject__c is a self-referenced lookup to the same object (TestObject__c) , similar like the ParentId is self-reference to the Account.
• The extrenal Id field for the Account object is ExternalID__c and for the TestObject__c is External_ID__c.
• Rest of the fields has the same names.

This is the mapping scheme between the Source and the Target:

Defining the field mapping in the export.json ⇧

The following configuration implements the required mappings.

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

The mappings are defined by the fieldMapping property.

The first item defines object mapping and will target all fields of the Account object to the TestObject__c. For example the field Account.TEST__c will be targeted to the TestObject__c.TEST__c. Other items define mappings for the individual fields. Object mappings and field mappings are independent items and can be used separately or simultaneously.

Defining the field mapping by the external CSV file. ⇧

However, sometimes you may have a large amount of objects and fields to map, so as your export.json could become extremely long. Alternatively in this case you can define the file mapping using special CSV file called FieldMapping.csv. Put this file in the same directory with your export.json.

Below is the content of FieldMapping.csv file for our example:

You should include all necessary mapping definitions for all objects in the current configuration in this single file.

In order to enable the Fields Mapping for the specific object you have to set to true the object's property useFieldMapping

Additional info:

• You should include all field listed in the sourceField property of the field mapping (or FieldName if you are using the csv) in the sobject's query string.

  In the example above you can see, that the ParentId is included in the query of the Account object. The field ExternalID__c may be not included explicitly, since it's defined as the External ID for the Account and so it will be included in the query automatically by the Plugin itself.

  Note, that the fields which are used in the field mapping but not included in the query will not be mapped.

• The fields and objects used in the field mapping schema are always CASE SENSITIVE.

  That's saying, if f.ex. the source field API name in the org metadata is 'ExternalID__c', you should correctly write 'ExternalID__c' in the sourceField and in the targetField properties, but you can't write 'externalid__c', which spelling will be not recognized and applied.

• If the specific field name has case differences between the Source and the Target (e.g. "Field__c" and "field__c"), you must include this field in the mapping scheme, otherwise the Plugin treats these fields as different.

• When querying the Target, the mapping scheme is applied to all fields used both in the SELECT and WHERE clauses. Note, that the mapping will work only for the fields directly belong to the sobject and will not work for the reference fields, as explained below.

  Lets say that you have mapped the Account lookup field AccountSource__c to AccountTarget__c, so:

  • The query string SELECT Id, Name, AccountSource__c WHERE AccountSource__c = 'TestAccount' will be correctly transformed into SELECT Id, Name, AccountTarget__c WHERE AccountTarget__c = 'TestAccount'

  • But the query string SELECT Id, Name, AccountSource__c WHERE AccountSource__r.Name = 'TestAccountName' WILL NOT be correctly transformed into SELECT Id, Name, AccountTarget__c WHERE AccountTarget__r.Name = 'TestAccount', since it contains a reference field AccountSource__r.Name.