External Id

1. How/When to use external ids

Even though you can go about your org to org migration without external ids, but there are couple of cases where you have to have external id.

• Hierarchical relationships
• You want to avoid duplicates and have no other approach to avoid duplicates

Hierarchical relationships

Hierarchical relationships are handled using an insert and update, for that reason, its a requirement to have external id for hierarchical objects. e.g. in the below relationship, Approval_Process__c has a self relationship. The JSON to successfully migrate the Approval_Process__c and self lookup will look something like below.

Note the externalIdField and refresh attributes in JSON. Set externalIdField to your external Id field and set refresh to true. Also, note that, when you specify "externalIdField" in JSON mapping, then external Id field is required and must be populated in both source and target orgs.

[
  {
    "parent": "Approval_Process__c",
    "externalIdField": "ExternalKey__c",
    "refresh": true,
    "lookups": [
      {
        "lookupMappedField": "Entry_Criteria__c",
        "lookupObject": "Approval_Process__c",
        "keys": [
          "ExternalKey__c"
        ]
      }
    ]
  }
]

You want to avoid duplicates and have no other approach to avoid duplicates

Since you can easily integrate this migration tool in your CI/CD. You may run the migration multiple times in a target org, which is fine, but if you don't have external id, you may see duplicates in target. If for some reason, you can't have external id and would like to avoid duplicates in the target org, then you can take couple of approaches.

• Before migration, delete the records from target org. Tool provides you a way to delete the records from target org based on your JSON mapping.
• Or, you can run the migration selectively so you just migrate only the records that you know won't cause duplication in the target. For that, you can use "where" attribute in JSON.

[
  {
    "parent": "Pricebook2",
    "where": "IsStandard != true"
  }
]