Back to all articlesCRM migration

Preserve Record Relationships When CRM Identifiers Change

Alactic Editorial9 min read

Prepared with AI assistance by Alactic Editorial. Examples identified as hypothetical are illustrative, not customer results.

A contact can import successfully while losing its account. An activity can appear in the destination CRM while pointing to the wrong opportunity. Successful record creation is not proof that the relationships survived.

To preserve relationships when CRM identifiers change, retain each source identifier, capture its corresponding destination identifier, and translate every relationship through that crosswalk. Import prerequisite records first, hold unresolved relationships in an exception queue, and compare the resulting links against the source—not just against the destination's import totals.

The working artifact below combines a filled identifier worksheet, an import dependency sequence, and an orphan-record queue. It addresses established relationships only. Deciding whether two records represent the same person is a separate task.

1. Specify which relationships must survive

Start with a relationship inventory, not a file-upload order. For each object, identify the fields that refer to other records and define what a blank value means. A deliberately empty account field is different from a populated account field whose target is missing.

A practical inventory records:

  • Child object and relationship field: for example, a contact's account reference.
  • Referenced object: the account that must exist before that link can be assigned.
  • Source representation: a stable identifier, not merely a displayed account name.
  • Destination representation: the accepted reference format, verified for the chosen import method.
  • Requiredness: whether the relationship is mandatory in the source, required by the destination, or required by your migration acceptance rules.
  • Failure treatment: hold the whole record, defer the link, or exclude it with an approved reason.

Include relationships that are easy to overlook: parent accounts, opportunity contact roles, activity participants, owners, and references to records outside the migration scope. Some relationships may live in separate association records rather than ordinary fields.

Do not silently turn an unsupported relationship into a text note and count it as preserved. A note may retain context, but it does not recreate a navigable relationship. Record that difference as a migration limitation requiring a decision.

2. Build a crosswalk that survives retries

The crosswalk is a controlled mapping from a source record key to the destination record created or selected for it. It should remain available throughout reconciliation and recovery, rather than existing only in a temporary spreadsheet formula.

Use a key that includes the source system and object type. An account and a contact may share the same identifier text without being the same record. Preserve identifiers as text so that leading zeros, punctuation, or long values are not altered by spreadsheet formatting.

Recommended crosswalk fields
source_system | source_object | source_id
destination_object | destination_id
migration_batch | load_status | verification_status

For a straightforward one-to-one migration, each source key should resolve to exactly one destination record. Stop if the same source key has conflicting destination IDs. Also investigate multiple source keys mapped to one destination unless that consolidation was explicitly approved elsewhere.

Capture destination identifiers from confirmed import results or another verified destination lookup. Do not assume the destination retained the source ID, and do not match records by row position. Rejected rows, sorting, and partial imports can all change the correspondence between files.

If a destination lookup uses a retained source-key field, first verify that the field is complete and unambiguous for the migration batch. Names, email addresses, and phone numbers are not substitutes for this mapping. Using them would introduce identity-resolution decisions into a relationship-preservation task.

3. Order imports by dependency, not convenience

The dependency sequence follows the relationship inventory. In the fictional example below, contacts and opportunities depend on accounts, while activities depend on both contacts and opportunities.

  1. Prepare prerequisites. Confirm any required owner or reference-data mappings and validate the source extract.
  2. Load accounts. Capture and verify account destination IDs.
  3. Load contacts. Translate account references through the account crosswalk; hold unresolved rows.
  4. Load opportunities. Translate account references and capture opportunity destination IDs.
  5. Load activities. Translate both contact and opportunity references using their completed crosswalks.
  6. Load separate associations. Where applicable, create relationship records only after both endpoints exist.
  7. Reconcile destination relationships. Inspect actual stored references, resolve exceptions, and repeat checks after repairs.

This sequence is a recommended design, not a claim about a particular CRM's import controls. Verify supported objects, reference formats, update behavior, and feature availability in the destination workspace and current plan before preparing production files.

Some dependency graphs contain cycles—for example, two records referring to each other. If the destination permits it, load the records without those optional references, capture their IDs, and then apply the links in a second pass. If required fields prevent that approach, stop and agree on a supported loading method. Do not invent placeholder relationships merely to pass validation.

4. Use this filled hypothetical relationship worksheet

Fictional worked example: all identifiers, companies, batches, and counts in this worksheet are hypothetical. The source snapshot contains two accounts, three contacts, two opportunities, and three activities. The migration rule is to hold a row whenever an expected relationship cannot be resolved.

The following crosswalk shows the accepted records after loading. These are source keys paired with destination IDs—not an assumption that the destination accepts arbitrary external IDs as references.

Batch: DEMO-B1 | Source system: LegacyCRM
Object       Source ID   Destination ID   State
Account      A10         DA501            Verified
Account      A20         DA502            Verified
Contact      C10         DC601            Verified
Contact      C20         DC602            Verified
Contact      C30         —                Held
Opportunity  O10         DO701            Verified
Opportunity  O20         DO702            Verified
Activity     T10         DT801            Verified
Activity     T20         DT802            Verified after repair
Activity     T30         —                Held

The companion relationship worksheet states which references must be translated. Each line is one expected relationship, so an activity with two references occupies two lines.

Child / destination   Field        Source target   Destination target   Result
C10 / DC601           account      Account:A10     DA501                Pass
C20 / DC602           account      Account:A20     DA502                Pass
C30 / —               account      Account:A30     —                    Hold
O10 / DO701           account      Account:A10     DA501                Pass
O20 / DO702           account      Account:A20     DA502                Pass
T10 / DT801           contact      Contact:C10     DC601                Pass
T10 / DT801           opportunity  Opportunity:O10 DO701                Pass
T20 / DT802           contact      Contact:C20     DC602                Pass after repair
T20 / DT802           opportunity  Opportunity:O20 DO702                Pass
T30 / —               contact      Contact:C99     —                    Hold
T30 / —               opportunity  Opportunity:O10 DO701                Ready; row held

This snapshot contains ten source records and eleven expected relationship edges. Eight records are accepted and two are held. Eight relationship edges are verified in the destination; three remain unapplied because their child rows are held. One of those three references is already resolvable, but the whole-row hold rule prevents a partially linked activity from being loaded.

Keeping record counts and relationship counts separate makes that distinction visible. Otherwise, a report could misleadingly classify every relationship on a held record as missing a parent.

5. Turn unresolved links into an owned exception queue

An orphan-record queue should say more than “lookup failed.” Record the child, missing target, reason, owner, next action, and evidence needed to close the issue. Include incorrect links too: an existing but wrong parent can be more difficult to spot than a blank reference.

The fictional queue for the worksheet is:

ID   Child       Issue and state
E01  Contact:C30 Account:A30 absent from source account extract.
                 Open; contact not loaded.
     Owner       Source data owner
     Next action Confirm whether A30 was omitted or is outside scope.
     Close when  Approved parent is loaded and mapped, or an explicit
                 exclusion decision is recorded.

E02  Activity:T30 Contact:C99 absent from source contact extract.
                  Open; entire activity held despite valid O10 reference.
     Owner        Activity migration lead
     Next action Retrieve the referenced contact or obtain an approved
                 correction from the source owner.
     Close when   Both expected references resolve and are verified.

E03  Activity:T20 Destination contact was DC601; expected DC602.
                  Closed after authorised correction and recheck.
     Owner        Migration operator
     Next action  None; inspect other rows generated by the same transform.
     Evidence     Destination read-back shows DC602 and DO702.

Do not substitute a convenient account or contact to clear the queue. If the source relationship itself is wrong, obtain an approved correction and preserve the original value alongside the decision. That makes a deliberate change distinguishable from migration damage.

A parent excluded by scope needs an explicit disposition: expand the scope, omit the dependent record, or accept a documented loss of relationship. “Imported successfully” is not an acceptable disposition for an unexplained missing link.

6. Check relationship correctness, not just existence

Validation should answer three different questions: can the reference resolve, did the expected reference get written, and does the resulting record context make sense?

Before import

  • Check source-key uniqueness within each object and source system.
  • Find nonblank relationship values whose referenced records are absent from the extract.
  • Ensure every loadable child reference has exactly one crosswalk result.
  • Separate intentional blanks, unresolved references, and deliberately deferred links.

After import

Read back destination identifiers and stored relationship values using an available export or verified inspection method. For each expected edge, compare the actual destination parent ID with the translated expected parent ID.

In the hypothetical example, T20 initially passed an existence check: DC601 was a real contact. It failed the stronger comparison because its source relationship required C20, which mapped to DC602. Record counts alone would not have detected that error.

Use record-level spot checks to supplement the full comparison. Open an account and follow its contacts and opportunities; open an activity and confirm its related records. Include repaired records, unusual relationship types, and records with several links—not only straightforward examples.

Define acceptance measures before the final load: expected edges, correctly linked edges, wrong-parent edges, unresolved references, intentional blanks, and approved exclusions. Set a release rule for unresolved critical relationships rather than accepting an unexplained percentage of failures.

7. Repair failures without creating duplicate children

After a partial failure, distinguish records that were rejected from records that were created with incomplete or incorrect links. The recovery action is different for each.

  • Rejected child: resolve its prerequisite, then retry creation after confirming it does not already exist.
  • Created child with a bad link: use its captured destination ID to perform a supported relationship update, rather than creating the child again.
  • Uncertain outcome: reconcile the destination against the source key before retrying.
  • Systematic translation defect: pause dependent loads, identify all affected rows, correct the transformation, and revalidate the affected set.

Keep the generated load file, result file, crosswalk version, and exception decisions together for each batch. A later repair should not silently overwrite the evidence of what was originally submitted.

Whole-row holds are easier to reason about but delay otherwise usable records. Deferred linking can make records available sooner, but it creates a second completion obligation and temporarily incomplete context. Choose deliberately, and do not label a deferred-link record complete until its relationships pass verification.

8. Prove one dependency chain before expanding

For the next migration rehearsal, choose one account with related contacts, opportunities, and activities, plus an intentionally unresolved reference. Build the crosswalk, execute the dependency sequence, and read back every expected relationship.

Your measurable output is a reconciled worksheet: every source record is classified as accepted, held, or explicitly excluded; every expected relationship is verified, deferred, or assigned an exception owner. There should be no unclassified differences.

Expand the batch only after the team can explain both the successful links and the held records. That is the practical test of relationship preservation: not whether the files uploaded, but whether each accepted record still points to the record it was meant to reference.

CRM migrationData migrationRecord relationshipsData validation

Put the next conversation to work.

Explore Alactic Communications for WhatsApp conversations, campaigns and AI-assisted workflows. Choose the product and plan that fit your team.

Explore Communications