All Collections
Gearset for data sandbox seeding
Configuring external ID and related objects for a data deployment
Configuring external ID and related objects for a data deployment

Configuration options for deploying dependencies and upserting records

Oli Lane avatar
Written by Oli Lane
Updated over a week ago

Once you've selected the top-level objects for your data deployment, Gearset will analyze your data model and present you with further configuration options to customize your data deployment. You can either tweak these options, or leave them as the default to accept Gearset's recommendations.

After clicking NEXT on the first configuration step of the data deployment, you'll be presented with a page like this:

Step 1: How do you want to match existing records?

On the left-hand side are the objects that you selected in the previous step. For each object, you can pick one of its fields to act as the external ID. If Upsert records is selected, when deploying records, Gearset will try to match records in the source and target using this ID, and if the record exists in both the source and the target, the target will be updated to match the version in the source; if the record exists only in the source, it will be inserted as new into the target.

The ID field must be specified as an "external ID" or "lookup ID" field within Salesforce.

  • An External ID is a custom field property, and this is the view in Salesforce:

  • The ID Lookup property is visible only via the API in Workbench:

(Note: While it is possible to mark an auto number field as an external ID in Salesforce, you will not be able to use an auto number field for upserting, as it is neither create-able nor update-able).

If no such fields exist on the object, no matching of existing records will occur - all records will be inserted into the target as new.

Step 2: Which related objects do you want to include?

On the right-hand side, objects related to the objects you selected in the previous step are displayed. By default, all of these will also be included in your deployment, but you can override this by deselecting the checkbox next to a particular related object.

As on the left-hand side, you can also select which field to use as the external ID for each object. 

Reference existing records

Some standard objects have specific requirements that make them hard to deploy (in particular, upsert doesn't work by default). These include User, UserRole, RecordType and Group. In these cases, Gearset will apply special handling to make sure that the deployment works correctly. You won't be able to change the deployment method for these objects.

These records will be downloaded from both the source and target, and cross-referenced internally by Gearset (rather than by using Salesforce's external ID mechanism). 

New User records will never be deployed by Gearset. If an OwnerId field on a record references a user that doesn't exist in the target, it will be set to the user carrying out the data deployment.

Did this answer your question?