How Record Mapping Works

Overview

Data Migrator uses record mapping to keep records accurate across multiple migration runs. When you enable record mapping for an object, Data Migrator maps individual records between the source and target organizations so that subsequent migrations add only new records and update existing ones. You control record mapping individually for each object in a template. Data Migrator provides two methods for mapping records between the source and target organizations: Automatic and Manual. The following sections describe how each method works and include example scenarios that illustrate successful and failed record mapping.

• Automatic Record Mapping

• Manual Record Mapping

• Record Mapping Scenarios

Enabling Record Mapping

By default, record mapping is disabled for all objects in a template. Without record mapping enabled, all source records are always inserted into the target organization during migration. This can result in duplicates if the same record exists in both locations.

Record mapping for an object is enabled from its Settings tab. The following article describes how to enable record mapping for an object.

• Setting Object Record Mapping

Automatic Record Mapping

Automatic record mapping is a stateful, mapping-based strategy that uses an internal mapping table to link source and target records. It relies on historical mappings from past deployments rather than real-time target data. Once a source-to-target mapping exists, the relationship is fixed, so there is no ambiguity for records already migrated using Automatic.

Automatic is designed for repeat migrations when:

• Data Migrator is the only migration tool in use
• The target org is empty during the first migration
• Long-term consistency across runs is required

Automatic guarantees that:

• The same source record always updates the same mapped target record
• Changes in business fields don't affect record matching
• Record updates are deterministic once a mapping exists

However, Automatic doesn't evaluate real-time target data.

How Automatic Works

Automatic follows a deterministic, mapping-driven process. The diagram below illustrates the full flow.

1

Read Source Record

Each source record is processed individually during the migration run.

2

Look Up Mapping in the Database

The system checks whether a mapping already exists for the source record's ID.

3

Evaluate the Mapping Result

Mapping Found	Action
No	INSERT a new record in the target org.
Yes	UPDATE the existing mapped target record.

4

Save the Mapping

When no mapping exists, the system inserts the record into the target org and creates a new mapping. On subsequent migrations, this record is updated rather than inserted again. This process repeats with each run, so newly added source records are tracked in the database.

Limitations

Important Limitations of Automatic Record Mapping

• Automatic cannot map records that already exist in the target organization.
• If another tool or manual process creates or modifies records in the target org, Automatic mappings can become outdated, leading to duplicate records.
• Automatic can only track records migrated through Data Migrator.

Outdated Mapping

Automatic is only as reliable as its database. Mappings become outdated when records are created in the target org, either manually or via another tool. The example below shows how this leads to duplicate records.

Example:

1. A user runs a migration for all Contact records to an empty org.

   1. All Contact records are copied from the source to the target org.
   2. Automatic mappings are created for each record.
2. The user manually creates Contact records for Charlie and Alice in both the source and target orgs.
3. The user runs another migration for all Contact records from the source org to the target org.

   1. Charlie and Alice have no Automatic mapping because they weren't migrated before.
   2. New records for Charlie and Alice are created in the target org.
   3. The target org now has duplicate records for Charlie and Alice: one from the manual creation and one from the migration.

Manual Record Mapping

Manual record mapping combines one or more record fields into a composite ID that links source and target records. Unlike standard Salesforce external IDs, any field can be used in the composite ID. When Manual searches the target org and finds exactly one matching record, it updates that record instead of inserting a new one.

It is designed for migrating records into target orgs that already contain records not previously mapped with Automatic record mapping, or for records in the target org created by other tools. Choose the Manual record mapping fields carefully: if the value of any selected field changes, the mapping will no longer match the previously migrated record.

How Manual Works

Before using Manual record mapping to migrate records, you must select one or more fields for the object to use for the record mapping. The selected fields are combined to create a key that is both unique and stable. This means the key does not change when commonly updated record fields change, and it is unique for every record in the org. You can choose one or more fields to use in the Manual key. The more fields you select, the more likely the key is to be unique. However, selecting more fields also increases the chance that the key will be unstable.

During Manual record mapping, the process searches the target org for matches against the generated key. The diagram and explanation below illustrate how it works.

1

Read Source Record

Each source record is processed individually during the migration run.

2

Generate Key

A KEY is generated from the record’s fields selected for the Manual mapping.

3

Query Target Org

Run a SOQL query in the target org for the KEY.

4

Evaluate the Query Result

Number of Records Matched	Action
0	INSERT a new record in the target org.
1	UPDATE the existing matched target record.
2 or more	ERROR - the record is skipped. More than one record matches the KEY, so the Manual key for this record is not unique, and the record can’t be migrated.

Limitations

Important Limitations of Manual Record Mapping

Selecting a combination of stable fields that create a unique ID for each record is critical.

• Stable: If a value in one of the fields selected for the key changes, the Manual mapping will no longer match the previously migrated record, and a new record will be inserted, resulting in a duplicate.
• Unique: If two or more records share the same key in the source org, the migration cannot correctly map them to target records because the key is not unique.

Bad Manual Fields

Manual record mapping is only reliable if the fields chosen for the Manual mapping create a key that is both stable and unique. Below are examples of poor field choices.

The following examples use the Contact object.

Fields Selected For Key	Why these fields are a bad choice
Name and City	Although Name rarely changes, pairing it with City makes the key unstable, because a contact's city can change.
Title and Department	This combination is not unique: multiple contacts can share the same title and department.
Name and Birthday	This combination appears unique and stable, but Birthday is often empty at first and filled in later, which makes the key unstable.

Record Mapping Scenarios

Template Design

Object: Contact

• Field: Name
• Field: Email
• Field: City

The tables below show the source and target records, with the differences in bold.

Source Org Contact Records

ID	Name	Email	City
001D000000kL4p1	Alice	[e-mail]	Berlin
001D000000kL4p2	Bob	[e-mail]	London
001D000000kL4p3	Charlie	[e-mail]	Paris
001D000000kL4p4	Dave	[e-mail]	Seattle

Target Org Contact Records

ID	Name	Email	City
002D000000kL5p1	Alice	[e-mail]	New York
002D000000kL5p2	Bob	[e-mail]	London
002D000000kL5p3	Charlie	[e-mail]	Paris

Data Migration with Automatic Record Mapping

Successful Scenario

In this scenario, a previous migration already created an Automatic mapping between the source and target orgs. The table below shows that mapping.

Source Name	Source ID	Target ID
Alice	001D000000kL4p1	002D000000kL5p1
Bob	001D000000kL4p2	002D000000kL5p2
Charlie	001D000000kL4p3	002D000000kL5p3

When the migration runs, Automatic record mapping looks up each source record's ID in the existing mapping. Records with a stored mapping are updated in the target org, and records without a mapping are inserted as new records. The diagram and table below illustrate this process and the resulting actions in the target org.

ID	Name	Email	City	Operation
002D000000kL5p1	Alice	[e-mail]	Berlin	UPDATE
002D000000kL5p2	Bob	[e-mail]	London	UPDATE
002D000000kL5p3	Charlie	[e-mail]	Paris	UPDATE
002D000000kL5p4	Dave	[e-mail]	Seattle	INSERT

A new Automatic mapping is then added for the newly inserted record:

Source Name	Source ID	Target ID
Dave	001D000000kL4p4	002D000000kL5p4

Failed Scenario

In this scenario, a previous migration had already created an Automatic mapping between the source and target orgs; however, only two records were mapped at that time. The table below shows that mapping.

Source Name	Source ID	Target ID
Alice	001D000000kL4p1	002D000000kL5p1
Bob	001D000000kL4p2	002D000000kL5p2

Before the next migration, an external tool adds a record for Charlie to both the source and target orgs. When the migration runs, Automatic looks up each source record's ID in the existing mapping, updating target records that already have a mapping and inserting new records for those that don't.

The diagram and table below illustrate this process and the resulting actions in the target org. Because no Automatic mapping exists for Charlie, the migration inserts a duplicate record, shown in the additional inserted row.

ID	Name	Email	City	Operation
002D000000kL5p1	Alice	[e-mail]	Berlin	UPDATE
002D000000kL5p2	Bob	[e-mail]	London	UPDATE
002D000000kL5p3	Charlie	[e-mail]	Paris
002D000000kL5p4	Charlie	[e-mail]	Paris	INSERT
002D000000kL5p5	Dave	[e-mail]	Seattle	INSERT

Two new Automatic mappings are added for the newly inserted records:

Source Name	Source ID	Target ID
Charlie	001D000000kL4p3	002D000000kL5p4
Dave	001D000000kL4p4	002D000000kL5p5

The migration failed because an external tool added Charlie to both the source and target orgs without creating an Automatic mapping between them. With no mapping for Charlie, Automatic inserted a new record in the target org instead of updating the existing one, resulting in a duplicate.

Data Migration with Manual Record Mapping

Successful Scenario

Manual Field Key: Name

In this scenario, Manual record mapping matches records using the configured key. With Name as the Manual key, the system generates a key for each source record and queries the target org for a match. Records that return exactly one match are updated, and records that return no match are inserted. The diagram and table below illustrate the Manual record-mapping process and the resulting actions in the target org.

ID	Name	Email	City	Operation
002D000000kL5p1	Alice	[e-mail]	Berlin	UPDATE
002D000000kL5p2	Bob	[e-mail]	London	UPDATE
002D000000kL5p3	Charlie	[e-mail]	Paris	UPDATE
002D000000kL5p4	Dave	[e-mail]	Seattle	INSERT

Failed Scenario

Manual Field Key: Name + Email

In this scenario, Manual record mapping uses Name + Email as the configured key. For each source record, the system generates this key and queries the target org for a match. Because Bob's source record has a new value in one of the key fields, it no longer matches his record in the target org.

Records that return exactly one match are updated, and records with no match are inserted. The diagram and explanation below show the Manual record mapping process and the resulting actions in the target org. Since Bob's source key no longer matches his existing target record, the migration inserts a duplicate, shown in the additional inserted row.

ID	Name	Email	City	Operation
002D000000kL5p1	Alice	[e-mail]	Berlin	UPDATE
002D000000kL5p2	Bob	[e-mail]	London
002D000000kL5p3	Charlie	[e-mail]	Paris	UPDATE
002D000000kL5p4	Bob	[e-mail]	London	INSERT
002D000000kL5p5	Dave	[e-mail]	Seattle	INSERT

The migration failed because Bob's Email value changed in the source org after the target record was created. Since Email is part of the Manual key, the new key generated from the source record (Bob + [e-mail]) no longer matched the existing target record's key (Bob + [e-mail]). With no match found, Manual inserted a new record in the target org instead of updating the existing one, resulting in a duplicate.