Data Migration, Cutover & Release Engineering

A Salesforce data migration is a product release—not a file upload

JSBC Labs31 October 20268 min read

The upload is the least important part

A migration can report 100% successful rows and still fail the business. Accounts arrive without the right owners, related records point to the wrong parents, duplicate rules reject the most valuable customers, and automation sends emails before anyone has approved cutover. The loader did its job. The migration did not. Treating data movement as a file-upload task optimises the easiest part while leaving identity, behaviour and operational risk unmanaged.

The JSBC Labs position is that a consequential Salesforce migration is a product release. It changes the production data model users experience, activates platform behaviour and transfers authority from one system to another. It therefore needs a defined scope, acceptance criteria, rehearsals, a go/no-go decision, reconciliation and a recovery plan. CSV files, Data Loader and Bulk API are execution mechanisms inside that release—not the release itself.

Define a migration contract before a mapping workbook

Start with a contract that says which business populations move, which system is authoritative for each attribute, what history is retained, which records are excluded and what good looks like after cutover. A mapping spreadsheet can say Legacy_Status becomes Status__c; it cannot decide whether conflicting legacy values should be normalised, quarantined or preserved. Those decisions require accountable data owners, not an ETL developer guessing during a weekend run.

Make acceptance measurable. Specify expected record ranges by object and business segment, required relationship coverage, permitted exception thresholds, ownership rules, financial or operational control totals, and the reports users must be able to run. Include files, activities, consent, sharing and audit fields where they matter. This contract prevents a common late-stage argument in which the migration team proves rows were inserted while the business proves the resulting organisation cannot operate.

Profile before you transform

Inspect the source before finalising the target design. Measure nulls, duplicate candidates, value distributions, invalid dates, field lengths, orphaned relationships and records owned by inactive people. Salesforce's data-loader guidance recommends identifying the data to migrate, cleaning it, preparing a template for each object and testing a single record before the main load. Profiling turns those sensible steps into an evidence-based plan rather than optimistic preparation.

Do not silently clean away ambiguity. Publish transformation rules and an exception taxonomy: automatically correct values that are unambiguous, route business decisions to named owners, and quarantine records that would undermine integrity. Track how many records follow each path. The aim is not to make every source row fit Salesforce at any cost; it is to produce a target dataset whose compromises are explicit, reviewable and reversible where necessary.

Stable identity is the migration backbone

Preserve the legacy identifier in a governed External ID field and define whether it is unique. Salesforce supports upsert by external ID, allowing a repeat run to update an existing target instead of blindly inserting another record. External IDs can also resolve relationships without hard-coding environment-specific Salesforce record IDs. That makes rehearsals repeatable and gives reconciliation a durable link between source and target.

Identity design must cover more than the primary object. Decide how accounts, people, assets, products, transactions and junction records correlate across systems. Record crosswalks for every generated Salesforce ID and protect them like deployment evidence. If duplicate rules or matching logic can reject or redirect a record, test that behaviour deliberately; do not bypass it merely to improve the success percentage. A migration without stable identity becomes a sequence of one-off scripts that cannot be safely rerun or investigated.

Sequence dependencies and automation deliberately

Order loads by dependency: users and reference data before owners and transactions, parents before children, and base records before junctions. Official Salesforce guidance illustrates the same principle with users, accounts and opportunities. For large volumes, Salesforce also recommends grouping child records by parent to reduce locking risk. The correct sequence belongs in an executable runbook with checkpoints, not in the memory of the person operating the loader.

Decide explicitly how flows, Apex triggers, validation rules, duplicate rules, rollups, sharing and outbound integrations behave during each stage. Running all automation may preserve normal business rules but create side effects, contention or impossible runtimes. Bypassing everything may create data normal users could never save. Use narrow, time-bound and auditable controls where bypass is justified, document derived work that must be replayed, and verify the post-load state before restoring ordinary processing.

Rehearse at production scale

A successful sample proves the mapping can work; it does not prove the cutover will finish. Rehearse the complete run against representative volume, configuration and data shape. Measure extraction, transformation, network transfer, API processing, sharing calculation, automation and reconciliation separately. Salesforce's Well-Architected guidance identifies Full Copy sandboxes as suitable for production-like staging and data-migration validation, subject to appropriate controls for sensitive data.

Use the rehearsal to find skewed parents, lock contention, unexpectedly selective validation, oversized files and slow post-processing. Bulk API 2.0 divides ingest jobs into internal batches and exposes successful, failed and unprocessed results; plan to retrieve and reconcile all three. Salesforce recommends Bulk API 2.0 for loads above 2,000 records, but choosing the API is only the start. Concurrency, batch shape, dependency order and the target org's automation determine the real throughput.

Reconcile outcomes, not just row counts

Compare source, staged, submitted, succeeded, failed, unprocessed and target populations. Then test business integrity: relationship coverage, ownership, aggregate balances, duplicate incidence, required-field completeness, attachment availability and the visibility users receive through sharing. Salesforce's migration guidance calls for record counts, spot checks and exception reports. Strengthen that baseline with control totals and queries tied directly to the migration contract.

Every exception needs an owner and disposition: retry, correct and reload, accept with approval, or exclude with a recorded reason. Store job IDs, input hashes, transformation versions, crosswalks and result files together so an investigator can reconstruct what happened. A green loader summary is operational telemetry, not acceptance evidence. The migration is complete only when accountable business and technical owners can explain the differences and sign off the target state.

Operate cutover and recovery as one plan

The cutover plan should name the source freeze, final delta extraction, validation gates, decision owners, communications, integration switch, user access window and post-release monitoring. Define the latest safe start time for every critical stage and the evidence required to continue. A go/no-go meeting without current reconciliation data is ceremony; an operator continuing because the schedule says so is gambling with production authority.

Back up the affected Salesforce data before destructive or corrective work, and prove how recovery would operate. Salesforce's export service can produce CSV backups, while richer recovery needs may require a dedicated backup product and rehearsed restore procedures. Rollback is rarely just deleting inserted rows: updates, relationships, automation side effects and external messages may require restoration or compensation. Design that path before cutover. The professional standard is not promising that migration cannot fail; it is making failure visible, bounded and recoverable.