Data Migration & Cutover

A Salesforce data migration is a product release—not a loading exercise

JSBC Labs26 September 20268 min read

Row counts do not define success

Salesforce migrations are often managed as extraction, transformation and loading jobs. The plan counts objects, fields, files and throughput, then declares success when the target contains the expected number of rows. That proves transport. It does not prove that the new system can operate the business those records represent.

A migration changes customer identity, record ownership, relationships, automation inputs, reporting history and the meaning of active work. Treat it as a product release with users, acceptance criteria, operational risk and a recovery plan. The loading technology matters, but it is downstream of decisions about what the target system is supposed to mean on day one.

Design the target truth before mapping columns

Source fields rarely map cleanly to target business concepts. A legacy status may combine lifecycle, approval and billing state. One account record may represent a legal entity, trading location and household at once. Copying those values into similarly named Salesforce fields preserves ambiguity while making it look modern.

Define the target-state rules first: record grain, ownership, lifecycle, required relationships, authoritative source and retention. Then classify every source value as direct, transformed, derived, defaulted, archived or excluded. Record who approved each rule. A mapping workbook is valuable only when it captures semantic decisions rather than becoming a long list of API names.

Create identity that survives more than one load

A migration that depends on newly generated Salesforce IDs becomes difficult to restart, reconcile or extend. Preserve a stable source identifier for every migrated entity and make the relationship between source and target explicit. Salesforce external ID fields support matching for imports and upserts; they can also be used to associate related records without first substituting every Salesforce record ID into the source file.

Choose the key deliberately. It must be stable, unique in the intended scope and meaningful to the systems that will perform deltas or reconciliation. Do not build identity from mutable values such as email address or account name. Where several legacy systems can produce the same numeric key, include a source namespace. The objective is repeatability: the same source entity should resolve to the same target record every time.

Load order is part of referential integrity

Relationships make the migration a dependency graph, not a folder of independent CSV files. Parent records generally need to exist before children can reference them. Junctions depend on both sides. Owners, queues, record types, products, price books and other reference data may need to precede the business records that use them. Salesforce's own guidance recommends deliberate object load order to prevent relationship errors and integrity problems.

Document the graph and the key used at each edge. Separate records that cannot yet resolve their parent instead of silently leaving relationships blank. Self-references and circular dependencies may require staged updates after initial insert. A successful child load with missing context is not partial success; it is a data defect that must be visible in reconciliation.

Automation turns data load into business execution

Every inserted or updated record can encounter validation rules, duplicate rules, record-triggered flows, Apex triggers, sharing calculations and downstream integration. The migration may therefore send emails, create tasks, publish events or change related records. Disabling everything is risky; leaving everything active can execute years of historical business logic against data that already completed its lifecycle elsewhere.

Create an automation matrix for each object. Identify controls that protect target integrity, side effects that must be suppressed, calculations that should run and post-load processes that must be invoked deliberately. Use governed migration permissions or configuration where exceptions are justified—never hard-coded user exemptions that remain after cutover. Re-enable and verify controls in a sequenced release step, not as an informal cleanup task.

Rehearsal must use production-shaped data

A clean load of ten thousand uniform records does not predict a production migration containing skewed ownership, deep hierarchies, large files, duplicate identities and historical edge cases. Salesforce's large-data-volume guidance highlights data distribution, locking, sharing and query selectivity because these characteristics affect throughput and platform behaviour.

Rehearse with representative volume and shape. Time extraction, transformation, transfer, processing, sharing recalculation and validation—not only API submission. Keep accepted and rejected row counts by object and rule. Repeat the rehearsal from a clean baseline using the same scripts and configuration intended for production. Manual fixes made only in the rehearsal environment are evidence that the process is not ready.

Throughput is a system constraint, not a tool setting

Bulk API 2.0 is designed for large data operations, and Salesforce CLI supports bulk upsert using an external ID. That does not mean maximum parallelism is always the fastest safe option. Parallel loads can increase record locking when rows share parents or owners, while serial processing may be more predictable for skewed datasets and relationship-heavy automation.

Partition work around contention boundaries rather than arbitrary file sizes. Measure job duration, failures, retries and lock rates under realistic conditions. Coordinate large operations with the wider production workload, including integrations, scheduled automation and user activity. The correct batch and concurrency strategy is empirical; it should come from rehearsal evidence, not a default copied from another org.

Cutover is a controlled change of authority

The hardest migration window is usually not the bulk load. It is the period between the final source extract and the moment users and integrations trust Salesforce. Define when the legacy system becomes read-only, how late changes are captured, which deltas are replayed, and who authorises the switch. Avoid an undefined interval where both systems can accept authoritative updates.

Use a cutover runbook with entry criteria, checkpoints, owners, timestamps and stop conditions. Freeze only what is necessary and communicate its business effect. Verify identities, permissions, integration credentials and scheduled jobs before opening access. A technical load completion message is not the go-live decision; the accountable business and technical owners need evidence that the operating state is coherent.

Reconcile meaning, not just totals

Object-level row counts are necessary and insufficient. Two datasets can contain the same number of opportunities while disagreeing on value, owner, stage, customer relationship or currency. Reconciliation must include financial and operational control totals, relationship completeness, duplicate rates, status distributions, attachment counts and samples across high-risk segments.

Automate comparison where possible and retain the evidence. Classify every exception as accepted, corrected or unresolved with an owner. Reconcile downstream effects too: sharing access, reports, search, integrations and critical automation. The most important question is not ‘Did all rows load?’ but ‘Can the target support the business decisions that depend on them?’

Rollback is about authority and data, not metadata

Reverting a deployment does not remove migrated records or undo messages already sent to external systems. Once users begin working, the target contains new transactions that do not exist in the source. A credible recovery plan defines what can be deleted, what must be restored, how new activity will be preserved and when rollback becomes more dangerous than a forward fix.

The JSBC Labs view is that migration readiness requires five proofs: stable identity, deterministic transformation, repeatable loading, semantic reconciliation and executable recovery. Put those proofs beside the user, integration and cutover plan. A migration is complete when operational authority has moved safely and the organisation can explain every material exception—not when the last CSV reaches 100 percent.