Full export.json file format.

Table of Contents

• Script object.
• ScriptObjectSet object.
• ScriptOrg object
• ScriptObject object.
• MappingItem object.
• MockField object.

As documented here the SFDMU uses a single export.json file to customize data migration process.

Here you can find the full list of the JSON objects and properties available for configuration.

Script object. ⇧

• The export.json file exposed the root Script object allowing you to define the most common migration parameters, e.g.:

// The Script object definition (the content of the export.json file)
{
    "bulkApiVersion": "1.0",	// This is a global Script object property

    // ... Other global Script object properties

}

• All Script object properties are defined in the global parent scope and will override the same (or having a similar functionality) properties, defined in the child objects in the configuration hierarchy.
  

  Below is the list of of the available Script object properties:

ScriptObjectSet object. ⇧

• Sometimes you may have to split the entire "parent" migration job into multiple "child" jobs. Such "child" job is declared using the ScriptObjectSet object type. Each ScriptObjectSet can have its own subset of ScriptObjects, which are being executed all together as a separated sub-job.

• Defining of multiple ScriptObjectSets might be really helpful, when you need to perform multiple operations with the same sObject (e.g. Account), for instance: you can perform hierarchical Deletion of old Accounts in the first ScriptObjectSet, then you are Inserting new Accounts in the second ScriptObjectSet, etc.

• The Plugin runs each ScriptObjectSet sequentially by keeping the order as it appears in the export.json.

• Use the objectSets property of the Script object to declare the array of the ScriptObjectSets:

  {
    "objectSets": [
      {
  
        // ScriptObjectSet configuration to Delete old Accounts and related Opportunities
        "objects": [
          {
            "query": "SELECT Id FROM Account WHERE Name LIKE '%Account To Delete%'",
            "operation": "DeleteHierarchy"
          },
          {
            "query": "SELECT Id, AccountId FROM Opportunity",
            "operation": "DeleteHierarchy",
            "master": false
          }
        ]
      },
      {
  
        // ScriptObjectSet configuration to Insert new Accounts and related Opportunities
        "objects": [
          {
            "query": "SELECT Id, Name, Phone FROM Account WHERE Name LIKE '%Account To Insert%'",
            "operation": "Insert"
          },
          {
            "query": "SELECT Id, Type, StageName, AccountId FROM Opportunity",
            "operation": "Insert",
            "master": false
          }
        ]
      }
    ]
  }
  

Below is the list of the available ScriptObjectSet properties:

ScriptOrg object ⇧

• The ScriptOrg object is utilized when you need to provide connection information, such as the username, instance URL and access token, via the export.json file. This is particularly useful when your orgs are not connected using Salesforce CLI on the local machine where you are executing a data migration job.
• Below the example of export.json with orgs section.

{
    "orgs": [
       {
           name: "source@example.com",
           instanceUrl: "my.source.instance@salesforce.com",
           accessToken: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
       },
       {
           name: "target@example.com",
           instanceUrl: "my.target.instance@salesforce.com",
           accessToken: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
       }
    ],
    "objects": [
         // Object definitions go here...
    ]
}

During the execution of the migration job, the SFDMU retrieves the necessary connection information, including the username, directly from this section. This eliminates the need to use the sfdx force:org:display command.

For example, when executing the command sfdx sfdmu:run --sourceusername source@example.com --targetusername target@example.com, the SFDMU fetches the connection information from the first and second items of the orgs array, respectively.

The table above presents the fields in the orgs section, along with their corresponding data types, whether they are optional or have a default value, and a brief description of each field.

Notes:

• Please ensure that you keep the export.json file, which contains the orgs section, in a secure location, as it contains sensitive information.

ScriptObject object. ⇧

• The ScriptObject object is used to customize migration parameters for specific sObject. Properties are declared in the ScriptObject's scope will override respective properties of all nested objects in the configuration hierarchy.

• Use the objects property of the Script object to declare the array of the ScriptObjects which should be processed:

{
    // Array of ScriptObjects
    "objects": [

        // ScriptObject to upsert Accounts
        {
            "query": "SELECT Id FROM Account",
            "operation": "Upsert",
            "externalId": "Name",

            // ... The rest of this ScriptObject properties

        },

        // ScriptObject to upsert Contacts
        {
            "query": "SELECT Id, AccountId FROM Contact",
            "operation": "Upsert",
            "externalId": "LastName",
        }
    ]
}

Below is the list of the available ScriptObject properties:

MappingItem object. ⇧

• The MappingItem object is used to setup the optional Fields Mapping for the current ScriptObject.

• If you need to map between fields, use fieldMapping property of the ScriptObject to declare the array of MappingItem objects.

• Make sure you've set useFieldMapping to true to activate the Fields Mapping feature.

    objects: [
        {
            "query": "SELECT Id, Name, ParentId, TEST__c FROM Account",
            "operation": "Upsert",
            "externalId": "ExternalID__c",
  
            // This should be set to true in the ScriptObject's scope to enable the Fields Mapping feature for this object
            "useFieldMapping": true,
  
            "fieldMapping": [
                {
                    "targetObject": "TestObject__c"
                },
                {
                    "sourceField": "ParentId",
                    "targetField": "ParentTestObject__c"
                },
                {
                    "sourceField": "ExternalID__c",
                    "targetField": "External_ID__c"
                }
            ]
        }
    ]
  

Below is the list of the available MappingItem properties:

MockField object. ⇧

• The MockField object is used to setup the optional Data Anonymization for the current ScriptObject.

• If you have to anonymize fields of the current sObjects, add the mockFields property in the ScriptObject definition, which will contain the array of the MockField objects:

• Make sure you've set updateWithMockData=true to activate the Data Anonymization feature.

    objects: [
        {
  
            "query": "SELECT Id, Name FROM Account",
            "operation": "Insert",
            "externalId": "Name",
  
            // This is the data anonymization declaration
            "mockFields": [
                  {
                      "name": "Name",
                      "pattern": "name",
                      "excludedRegex": "^DummyAccount$",
                      "includedRegex": "Account\\sTo\\sMask"
                  }
            ],
  
             // This should be set to true in the ScriptObject's scope to enable the Data Anonymization feature for this object
            "updateWithMockData": true
  
        }
    ]
  

  Below is the list of the available MockField properties:

Notes:

• Either objects or objectSets properties should be set in the export.json.

  However, it's possible to set them together. In this case the global objects array is considered as a initial ScriptObjectSet in the configuration and executed at the beginning of the migration process, after that the Plugin will execute the rest of the ScriptObjectSets in the script.
  
  

• External ID fields are always case-sensitive.

  The API name(s) of field(s) set as an External ID (single and composite) - are always case-sensitive and must exactly match the fields metadata.

  For instance, you CANNOT SET External ID like below:

  • externalId: "name"

  • externalId: "Name;Account__r.name"

    ... because the field "name" (starting from lowercase letter) does not present in the metadata.
    
    

• The "I know what I do" option.

  When a production SF org is set as a Target, during the job running, the Plugin will ask the user to type the instance name of the target production org (e.g. prod-instance.my.salesforce.com) to make sure that the user does really want to make a modification, preventing critical production data from destroying by accident.

  This prompt can also be skipped by adding the flag --canmodify INSTANCE-NAME to the CLI command, which is also indicating user's agreement to the changes are being made by the Plugin.

  Be aware, that you can't ignore this prompt by simply adding the --noprompt flag, since in that case --noprompt will abort the job instead of asking the user.
  
  

• Setting up HardDelete operation as well as putting ScriptObject.hardDelete to true will permanently delete records (only supported by the Bulk Api). Be aware, that when deleteOldData is set to true and old records are deleted using the Buil Api, the target records are also hardly deleted.

  See also the Salesforce documentation about the HardDelete:
  Hard delete records from Salesforce,
  Activation of Bulk API Hard Delete on System Administrator Profile