How Record Mapping Works

Overview

Data Migrator supports record mapping during data migration to ensure records are correctly updated across multiple migration runs. Currently, Virtual External ID (VEID) is the only record-mapping strategy available, but another option is in development.

No Record Mapping

When the None option is selected for a migration, all source records are inserted into the target organization. Records are not matched between source and target, which can create duplicates if records already exist in both locations.

VEID

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

It's designed for repeat migrations when:

• Data Migrator is the only migration tool being used

• The target org is empty during the first migration

• Long-term consistency across runs is required

VEID guarantees:

• 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, VEID doesn't evaluate real-time target data.

How VEID Works

VEID 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 VEID 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 will be updated rather than inserted again. This process repeats with each migration run, allowing newly added source records to be tracked in the VEID mapping table.

Limitations

Important Limitation of VEID

• It cannot map records that already exist in the target organization.

• If another tool or manual process creates or modifies records in the target org, VEID mappings may become outdated, potentially resulting in duplicate records.

• It can only track records migrated using Data Migrator.

Outdated Mapping

VEID is only as reliable as its mapping table. Mappings become outdated when records are created in the target org, either manually or by 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. VEID mappings are created for each record.

2. A user manually creates Contact records for Charlie and Alice in both the target and source 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 VEID 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.