A Salesforce data migration does not fail only when an upload returns errors. It can complete successfully and still leave duplicate customers, broken relationships, incorrect owners, silent automation side effects and reports that no longer reconcile with the source system.
The visible load is one step in a longer process. The difficult work is deciding what should move, how records relate, which values are trustworthy, what automation will run, and how the team will prove the destination is correct.
Whether you are moving from a legacy CRM, consolidating business units or transferring data between Salesforce orgs, use a staged migration with evidence and a rollback plan.
1. Define the migration outcome
Write down what “complete” means before mapping a single column.
Define:
- systems and business units in scope;
- objects, date ranges and record populations to migrate;
- data that will be archived rather than loaded;
- ownership and sharing expectations;
- acceptable downtime or change freeze;
- required historical dates and audit fields;
- reconciliation measures;
- final sign-off owners.
Avoid “move everything” as a default. Legacy data can be retained outside the live org when it has legal or analytical value but no operational purpose. Every unnecessary record adds storage, migration effort and future cleanup work.
2. Inventory the source and target models
Create an object-and-field inventory for both systems. For each source field, choose one target action:
- map directly;
- transform;
- combine or split;
- replace with a controlled value;
- archive only;
- exclude with an approved reason.
Record data type, length, required status, uniqueness, valid picklist values, lookup target, default and any target automation that reads or writes it.
Pay special attention to meanings that appear identical but are not. “Customer status” might describe the account lifecycle in one system and a contract status in another. A technically valid mapping can still be semantically wrong.
3. Draw the dependency order
Salesforce records must usually be loaded in relationship order. Users and reference data come before Accounts; Accounts come before Contacts and Opportunities; parent custom objects come before their children.
Build a dependency graph rather than keeping the order in somebody's memory. Mark:
- required parent lookups;
- optional relationships that will be added in a second pass;
- self-referencing objects;
- junction objects that need both parents;
- polymorphic relationships such as activities;
- circular dependencies that require staged updates.
Salesforce's current migration guidance recommends identifying mandatory relationships and loading objects in dependency order. It also recommends generating target templates and identifying required fields before populating the final files.
4. Create stable external IDs
Do not build a migration around temporary Salesforce record IDs alone. Preserve the source system's identifier in a dedicated target field and mark it as an External ID when appropriate.
External IDs help with three jobs:
- Idempotent upserts. A rerun can update the same destination record rather than insert another copy.
- Relationship resolution. Child rows can identify a parent by its legacy key.
- Reconciliation. Source and destination records retain a stable join key.
Make the identifier unique when the business rule supports uniqueness. Profile the source first: a “customer number” field that contains duplicates or blanks is not ready to become a reliable migration key.
5. Clean before transforming
Migration is the worst time to move known bad data unchanged and hope to fix it later.
Profile:
- duplicate people and organisations;
- invalid or shared email addresses;
- inconsistent country, state and phone formats;
- picklist values outside the target set;
- orphaned child records;
- inactive owners;
- impossible dates and placeholder values;
- text that exceeds target field lengths;
- inconsistent encodings and line endings.
Separate corrections that can be applied deterministically from those requiring a business decision. Do not let a spreadsheet formula silently choose which duplicate customer survives.
Keep an immutable copy of the original extract and version each transformed dataset. When a stakeholder challenges a result, you need to show how the value changed.
6. Decide what automation should run
A migration can trigger validation rules, Flows, Apex, duplicate rules, assignment rules, emails and external integrations. Disabling everything makes the load easier but can create records that the normal application would never permit. Leaving everything on can send thousands of emails or update downstream systems.
For each automation, decide explicitly:
- run normally;
- bypass through an approved migration control;
- pause temporarily with a recorded change;
- replace with a migration-specific process;
- run after the load as a controlled backfill.
Test the decision in a sandbox. Document who can activate the bypass, when it expires and how normal behaviour will be restored.
7. Prepare files for humans and machines
Use one dataset per object and keep column headers aligned with the approved mapping. Avoid formulas, hidden columns and colour as the only source of meaning in the final CSV.
Before loading:
- confirm encoding and delimiter;
- normalise dates and time zones;
- distinguish blank from “do not change” for updates;
- escape line breaks and quotes;
- remove accidental spreadsheet formatting;
- verify IDs have not been converted to scientific notation;
- count rows and unique external IDs;
- calculate control totals for important numeric fields.
Store the mapping, transformation rules and row counts beside the files. The person running the load should not be the only person who understands them.
8. Load one record, then a small representative batch
Salesforce recommends loading one record and verifying the result before loading the full dataset. After that first proof, use a small batch containing difficult examples:
- every record type;
- populated and blank optional relationships;
- maximum-length text;
- non-English characters;
- existing and new records for an upsert;
- users with different ownership and sharing outcomes;
- records expected to fail.
A test batch should prove mapping, automation, relationships, permissions and error handling—not merely return a green status.
9. Run in controlled batches
Smaller batches make failures easier to isolate and rollback. Group work by object, business unit, date or another boundary that can be reconciled independently.
For each run, preserve:
- operation and object;
- source filename and checksum or version;
- mapping version;
- start and finish time;
- row count submitted;
- successes and destination IDs;
- per-row errors;
- operator and target org;
- remediation and rerun files.
Do not rerun the original file after partial success unless the operation is safely idempotent. Build a new file containing only corrected failures, or use external-ID upsert where appropriate.
10. Validate at three levels
Technical reconciliation
Compare source, submitted, successful and failed row counts. Match external IDs and verify required relationships. Check control totals for currency, quantities and other meaningful measures.
Business reconciliation
Run reports that stakeholders understand: open pipeline by stage, customers by region, active cases by queue, or another measure that should agree with the source.
Behavioural validation
Open representative records as real users. Confirm layouts, access, automation, notifications, integrations and downstream reporting. A record that exists but is invisible to its owner has not migrated successfully.
11. Plan rollback before production
Rollback might mean deleting inserted records, restoring pre-migration values, reloading a backup, reversing ownership changes or stopping an integration. The plan depends on the operation.
Before the production run, know:
- which records the migration will create or change;
- how they can be identified reliably;
- what backup or export preserves the previous state;
- which actions are reversible and which are not;
- who can authorise rollback;
- the last safe decision point.
Test rollback on the rehearsal data. An untested rollback document is an aspiration.
Data Loader tips that prevent repeat failures
- Prefer upsert with a clean external ID when files may be rerun.
- Resolve parent lookups by external ID instead of manually translating Salesforce IDs in spreadsheets.
- Keep the first batch deliberately small.
- Preserve success files as well as error files.
- Add a migration-run identifier where appropriate so loaded records can be reported on.
- Never delete or mass-update production records from a file that has not been peer reviewed.
- Check API limits, automation volume and business-hour impact before starting a large load.
- Reconcile after each object rather than waiting until the entire migration ends.
How orgadmin.ai helps with controlled loads
The orgadmin.ai Data Loader runs in the browser and supports insert, update, upsert and delete. Rows can be pasted from a spreadsheet or uploaded as CSV or TSV, then mapped and reviewed before the operation begins.
It can relate lookups through external IDs, validates missing required fields and returns per-row results. Runs are limited to 10,000 records, which suits controlled migration batches and one-off admin work rather than pretending a browser workflow replaces an enterprise-scale migration platform.
Production DML is separately gated by the operator's deployment configuration. That guard matters because the review screen is useful, but it is not a substitute for a backup, rehearsal or approval process.
For sandbox data, use Data Seeding and its mandatory masking workflow rather than treating a production export as an ordinary migration file.
Make the migration repeatable
The best migration artefact is not the final CSV. It is a process another person can rerun and reconcile: source extract, transformations, mappings, external IDs, dependency order, run logs, validation reports and decisions.
Start a free orgadmin.ai trial to test a small, reviewed load against a sandbox and see whether the browser-based mapping and per-row feedback fit your migration workflow.