Getting data into Salesforce correctly is harder than it looks. Source systems accumulate years of inconsistent data that is assigned by different people in their own systems, and it sits in the form of silos that cannot be connected to each other. All of it needs to arrive in Salesforce with its relational structure intact at the time of Salesforce integration. If the business and integration partner miss out on important details, the errors are invisible at go-live and painful for months afterward.
This guide covers the setup process for a Salesforce data migration that keeps historical data intact. The same principles apply whether you are planning a first-time implementation, moving from a legacy CRM, preparing for an NPSP to Nonprofit Cloud migration, or managing a Revenue Cloud move. The underlying methodology is the same across all of them.
Why Historical Data Gets Lost During Migration
Up to 40% of CRM migrations encounter significant problems with data integrity, according to analysis across hundreds of projects. The failures are rarely catastrophic. They can show up as broken parent-child links, orphaned activity records, picklist values that failed to translate, and timestamps that lost their timezone context weeks after go-live.
The most common cause is treating migration as an export-and-import operation. Exporting a flat CSV from a source system and importing it directly into Salesforce flattens the relational structure. As a result, every connection between records gets severed in that flat file.
A second common cause is leaving automations active during the load. Salesforce workflows, validation rules, assignment rules, and escalation triggers are built for live records. Running a migration without disabling these first can trigger major problems like mass email sends to customers.
Understanding these failure modes is what shapes a migration plan that works.
Phase 1: Audit Your Source Data Before Touching Anything
The most reliable migrations spend more than half of their total timeline in preparation. That sounds disproportionate until you consider what happens when teams rush into execution with unexamined data.
Start with a data inventory across every object you plan to migrate. For each object, document the following:
- Record count: total and by status or record type
- Field coverage: which fields are actually populated vs. empty
- Data quality issues: duplicates, inconsistent formats, missing required values
- Date ranges: how far back the data goes, and what is genuinely needed in Salesforce vs. what can be archived
On that last point: Gartner puts the average annual cost of poor data quality at $12.9 million per organization. A significant portion of that cost traces back to migrating dirty data that was already a problem in the source system. Migration does not clean date while moving it. Messy data going in produces messy data coming out, just in a new place.
For most organizations, drawing a data cut-off line somewhere between three and five years handles the bulk of active business needs. Records older than that should either be archived in the legacy system or stored in a dedicated archival solution.
Phase 2: Map Fields and Establish External IDs
Field mapping is where migrations succeed or fail silently. The goal is a documented record of which field in the source system corresponds to which Salesforce field, and what transformation logic applies when the format is different.
Map by API field name, which you find in Setup under each object. API names stay stable even when labels change, which means the mapping document stays accurate if someone renames a field six months after go-live. Mapping by label is a common shortcut that creates silent errors when labels get updated.
What External IDs Are and Why They Matter
An External ID is a custom field on a Salesforce object, marked as External ID and Unique, populated during migration with the source system’s unique record identifier. This tells Salesforce exactly which legacy record each Salesforce record corresponds to.
Without External IDs set up, two problems become unavoidable. Child records cannot be reliably linked to their parent records during the load. And if a delta migration is needed to catch updates made in the legacy system after the initial extract, there is no reliable way to match incoming records to the correct Salesforce records without re-importing everything.
With External IDs in place, an upsert operation in Salesforce Data Loader matches incoming records to existing ones by their External ID. This prevents duplicates and allows child records to link correctly to parents even when parent records load first.
Object Load Order
Parent records must exist in Salesforce before child records can reference them. The standard load sequence for most migrations:
- Accounts: top-level parent in most orgs
- Contacts: linked to accounts via AccountId
- Opportunities: linked to accounts, sometimes to contacts
- Cases: linked to accounts and contacts
- Activities (Tasks and Events): linked via WhoId/WhatId; load last
- Custom objects: load after whichever standard objects they reference
Activities are consistently the hardest object to migrate. Salesforce stores tasks and events as polymorphic objects that can link to almost any other object in the system. Loading activities before the records they reference exist creates orphaned records.
Phase 3: Clean Before You Migrate
Four categories of data issues cause the most failures during migration loads. Each one breaks the process in a different way:
- Picklist mismatches. If the source system stores “United States” and Salesforce expects “US,” every affected record triggers a validation error on import. Build a translation table and normalize picklist values before loading.
- Inconsistent date and number formats. Date strings like “12/5/2025” vs. “05-12-25” fail at the API level. The same applies to phone numbers with inconsistent country code formatting. Standardize formats in the staging environment.
- Duplicate records. Duplicates migrated into Salesforce create long-term trust problems with the data. Clean them in the source system or in the staging environment.
- Records updated after the initial extract. If the migration runs over multiple days and the source system stays live, records will change between the initial extract and the cutover load. Lock the legacy system at cutover, or run a delta migration to catch updates.
The cleaning happens in a staging environment. Extract the data, clean it in staging, and load the clean version into Salesforce. It keeps the source data intact as a reference and gives a tested, validated dataset to work from.
Phase 4: Run Your Migration in Sandbox First
Every migration cycle runs in a sandbox before touching production. The rule applies to small datasets as much as large ones.
The sandbox should be a full copy of the production configuration which should include same validation rules, workflows, field settings, and permission sets. A migration that passes in a developer sandbox but fails in production usually fails because the production org has a rule that was not replicated in the test environment. That mismatch surfaces as a batch job failure on go-live day, which is the worst time to discover it.
What to Test in Sandbox
- Run a pilot load with 5–10% of total records, selected to represent the full range of data types and relationships
- Validate record counts: records in should equal records out, minus any intentional exclusions
- Spot-check relationships: pull a sample of accounts and confirm their contacts, opportunities, and activities are correctly linked
- Test reports and dashboards the team relies on. Missing or mislinked historical data shows up immediately in reporting
- Run real user workflows on the migrated data
Technical testing catches schema errors. User testing catches the quieter problems that only surface when someone tries to do their actual job in the migrated environment.
For most mid-market migrations, Salesforce Data Loader handles the bulk of the work. It is free, handles up to 150 million records via Bulk API 2.0, and supports all standard and custom Salesforce objects. For multi-org consolidations or migrations that feed into ongoing integration pipelines, MuleSoft adds transformation and orchestration capabilities that Data Loader does not have.
Planning a Salesforce migration and want a second opinion on your approach? Talk to Sarla’s implementation team.
Phase 5: Disable Automations During the Load
This step is the one most commonly skipped on first-time migrations, and it is the one that causes the strangest post-migration problems.
Before any records load into production, turn off or bypass:
- Workflow rules and Process Builder flows triggered by record creation or update
- Assignment rules that route leads or cases to queues or users
- Escalation rules and SLA timers on cases. These are built for live tickets
- Email alerts that fire on record changes
- Validation rules that reference fields with no historical equivalent in the source system
Document every automation disabled and have a clear re-enablement plan ready for after validation completes. Automations left off in production after go-live create a different class of problems.
Phase 6: Validate, Then Lock the Legacy System
Post-load validation is a structured audit that compares what was intended to migrate against what Salesforce actually contains.
Validation checkpoints to run before declaring the migration complete:
- Record count reconciliation. Compare total record counts by object between the source extract and Salesforce. Discrepancies here point to failed loads or records excluded by validation errors.
- Relationship integrity checks. Pull a random sample of accounts and trace their full record hierarchy: contacts, opportunities, cases, activities. Broken links surface here.
- Field value spot checks. Verify that financial amounts, dates, and status fields migrated correctly on a cross-section of records. Numeric and date fields are where format conversion errors most often appear.
- Report comparison. Run the same report in both the legacy system and Salesforce and compare outputs. Totals or record counts that differ point to a data problem that needs tracing before go-live.
Once validation passes, lock the legacy system. Users should have no ability to add or update records in the old system from this point forward. Data entered in the legacy system after the final extract but before lockdown requires manual reconciliation.
The Data Drift Problem
There is a problem that sets in after a successful migration that almost nobody plans for: data drift. The org that passed validation on day one gradually drifts back toward the same data-quality problem that drove the original migration.
The fix is a governance model, put in place before go-live.
- Validation rules that enforce required field completion on key objects
- Duplicate rules that catch duplicates at point of entry
- Regular data quality reports that give admins early visibility into where the org is degrading
- A managed services arrangement that provides ongoing Salesforce administration and data stewardship
The Data & AI practice at Sarla works with organizations on the post-migration data layer.We help in setting up Data Cloud integrations, unified customer profiles, and the governance structure that keeps a clean migration clean over time.
Do You Need a Salesforce Partner for Data Migration?
A straightforward migration from a small source system with well-documented data and a simple Salesforce configuration is something a capable in-house admin can handle with the right preparation and tooling.
Most migrations are more complex than that. In 2025, in-house teams ran 48% of migrations, down from 65% the year prior, while external service providers handled 46%. The reason is that modern Salesforce environments have deepened considerably. The coordination overhead is where in-house teams most often run into difficulty.
When the data being migrated includes multi-year activity history or records that will feed Agentforce agents and predictive tools, the cost of getting it wrong exceeds the cost of bringing in specialists with a tested methodology.
Sarla’s Salesforce implementation team has executed CRM migrations across the US, including organizations in regulated industries where broken record relationships or missing compliance data have direct legal consequences. The methodology in this article is the one we apply on every engagement, regardless of size.