Print this page

How do I use an External ID to import related records?

Knowledge Article Number 000002783
Description An External ID may be used in place of a related record's Salesforce Id to associate a chosen object's record to another object's records in Salesforce upon Upsert via the Data Loader.

For example, you have two custom objects:
- Object A
- Object B

Objects A and B are related to each other via a lookup relationship from Object B to Object A.

How do I import object B records and related them to Object A records via the lookup field using an External ID field on Object A?

 An External ID field can be used to match or relate Object A records when importing Object B records without having Object A's Salesforce Ids. External Ids are commonly used to store unique record identifiers from external systems and allow for routinely loading data into Salesforce without having to prepare your file with existing or related Salesforce record Ids each time.

1. Identify an existing External ID field on Object A that you'd like to use for matching or create an External Id via a new custom field  (Data Type 'Text') on 'Object A' and select the External ID and Unique field attributes. See Create Custom Fields​Custom Field Attributes​ and What is an external ID? for more details.

2. Populate the newly created External ID field for Object A records in Salesforce so that you may use it as the matching criteria upon importing object B records by creating a .csv file containing all Object A records:
- If Object A records already exist in Salesforce you may Build a Report and Export a Report or alternatively use the Data Loader to Export Data. Be sure to include the Object A record's Salesforce Ids in your report or export file in order to perform an update to the record's new External ID field.

- If importing new records identify a column that contains data that would serve as a unique identifier for Object A records. Typically, this would be from a system outside of Salesforce and ideally these unique values for Object A records would already be contained in your Object B import file or commonly contained in files from an external system.

3. Perform an Insert for new records or an Update for existing records to Object A, mapping required fields (be sure to include and map Salesforce Id for an update or upsert operation) and the External ID column to the Object A record's External ID field from step 1. The goal is to populate a unique External ID value in Salesforce for all of Object A's records. See Insert, Update, or Delete Data Using Data Loader​ for more details.

4. Prepare your Object B file with the related Object A record's corresponding External ID values you'd like to use for matching in order to populate the lookup field from Object B to Object A:
- ​​In the .csv file for Object B, choose an existing column containing the unique data that matches the External ID values you set for Object A's records in steps 1-3 or create a new column named External ID and manually populate it or use Excel's vlookup function to bring over the External ID values set on Object A records.

5. Click on Upsert in the Data Loader, choose the appropriate object (Object B in our example), Browse... and select your import file for Object B and click Next >.

6. In Step 2b: Choose your related objects select the External Id field for the Object A dropdown to use the External ID field for matching related Object A records upon importing Object B records.

7. In Step 3: Mapping there should be a Salesforce field with the following name syntax: [ObjectName]:[ExternalIDField__c] where in our example, [ObjectName] is "Object A" and [ExternalIDField__c] is the API name of object A's External Id field from step 1. Drag and drop this field to map it to your Object B file's column containing the External Id values for Object A's records. 

By doing this you can easily relate the Object B records to the Object A records using the External ID that you created. This eliminates the process of importing Object A records, Exporting the new IDs, matching them up in Excel and then importing the child records.

Always back up your data before performing any Data Loader operation. You can do this by Exporting Backup Data via the export service or by selecting to Export Data for the appropriate objects via the Data Loader. Run a test with one or a small subset of records to ensure the operation was successful by verifying the corresponding records in Salesforce are correct. Once you have confirmed the result is correct perform the appropriate Insert, Update, and/or Upsert operation for all records. 

promote demote