What you’re working toward.
A signed mapping register, a reconciled test import, and a cutover plan with a recovery path.
- Bring these people
- RevOps lead, source-system admin, and business owners
Have these inputs ready
- Read access to the source, an export sample, and a destination administrator.
- An agreed list of must-keep history, attachments, relationships, and reports.
- A named approver for sales, marketing, and customer-service data.
Inventory before mapping
List each source system, record type, integration, file attachment, and activity history. Count records and relationships separately. Identify who owns export access and which data cannot be exported cleanly.
- Export counts by object and status, then separately count associations and activities. Record the extraction time so later comparisons use the same population.
- Label each dataset migrate, archive, or exclude. For exclusions, record the reason, approver, and how users will retrieve the old information.
An inventory with object, source count, history coverage, export owner, and disposition.
Define the target model
Agree object types, associations, identifiers, owners, required fields, and lifecycle definitions. Keep a mapping register with source field, target field, transformation, and exception handling. Avoid using display names as durable identifiers.
- Map source ID, target identifier, property type, allowed values, transformation, and blank-value behavior. Preserve source IDs for traceability.
- Resolve owners and associations before loading. Write down what happens when a user is inactive, a parent is missing, or two source records identify the same customer.
A field-and-relationship mapping register with one owner per unresolved decision.
Test a representative sample
Include duplicates, missing owners, inactive records, unusual dates, and complex relationships. Check that reports and operational views behave as expected after the sample import. A correct total is not proof that associations are correct.
- Choose a deliberately varied test set: a normal customer, a duplicate, a multi-company contact, a record without an owner, and a deal with historical activity.
- Import in a controlled environment or clearly isolated test population. Open the resulting records and run the actual pipeline and handoff reports—not only the import summary.
A test log linking every source ID to its target record, expected result, actual result, and issue.
Reconcile before launch
Compare record counts and sampled field values by object type. Log exceptions, assign owners, and obtain business sign-off on what is deliberately excluded. Agree the freeze, delta transfer, rollback criteria, and first-day support plan.
- Reconcile accepted rows plus rejected rows to the input count. Separately compare unique entities, important field totals, and expected relationships; deduplication changes the meaning of a count.
- Define the write freeze, final delta window, import order, approval checkpoint, and restart procedure. A source export alone does not reverse target updates; preserve pre-change target values and record how to restore them.
A signed reconciliation report and cutover runbook with stop conditions and named decision-makers.
A migration mapping register
Illustrative field rules for a company-and-deal migration. Substitute your real identifiers and approved values.
Know when the work is ready.
Use these checks in the handover. Keep evidence of the result and assign an owner to anything that still fails.
- Every in-scope source record has a documented target or disposition.
- The test set preserves the intended company, contact, and deal relationships.
- Business owners approve the reports and accepted exclusions.
- The team has rehearsed stopping the cutover and restoring changed values.
Catch the problems early.
Matching totals can hide broken relationships
A portal can contain the right number of contacts and still attach them to the wrong companies. Reconcile associations as a separate acceptance check.
A rerun can create a second migration
Test the identifier and update rules before retrying. Capture the failed population instead of re-importing everything blindly.
Product references
HubSpot documents the identifiers and file structure needed for updates and associations. Use those requirements when preparing the mapping register.