A Salesforce migration can complete without a major import error and still leave users with data they can’t trust. Relationships can point to the wrong records, owners can disappear, picklist values can change meaning, and duplicates can survive the move. The records may be inside Salesforce while the CRM no longer reflects the business accurately.
Salesforce Data Migration needs to solve those problems before the final import. Salesforce Field Mapping defines what source values become, Salesforce Data Deduplication decides which records survive, and Salesforce Data Load Order sets the sequence needed to preserve relationships.
The loading tool comes after those decisions. Data Loader, Bulk API 2.0, ETL software, and custom scripts can move records, but they can’t decide whether 2 customer records represent the same company or whether an old status should map to an active Salesforce picklist value. HyphenX Solutions addresses this wider preparation work through its Salesforce Data Migration Services offering, where source review and mapping sit alongside migration testing and post-load checks. The same principle applies to any migration team: the quality of the final org depends heavily on decisions made before production loading begins.
This guide covers source profiling, field mapping, legacy identifiers, dedupe, dependency-based load order, automation, rehearsal, cutover, and post-load checks.
TL;DR
Salesforce Data Migration works best when the migration team treats the source-to-target design as a controlled specification. Salesforce’s current migration guidance recommends defining the objects and fields in scope, preparing target templates, retaining legacy identifiers where useful, loading objects according to their dependencies, and validating the result after migration.
Salesforce Field Mapping should document more than source and target field names. It needs transformation rules, data types, required values, default behavior, lookup dependencies, and decisions about blanks. Salesforce Data Deduplication should happen before the production load wherever possible, with clear rules for identifying duplicate candidates and selecting the record that survives.
Salesforce Data Load Order should come from the actual relationship structure in the target org. Parent records normally need to exist before children that reference them. External IDs help retain source identity and can support repeatable upserts. Salesforce Data Migration Best Practices also call for realistic test loads followed by reconciliation of record counts, key values, failed rows, and record relationships before users depend on the new org.
What Salesforce Data Migration Actually Includes
Salesforce Data Migration is the controlled movement of business records from another CRM, Salesforce org, spreadsheet, database, ERP system, or other application into Salesforce. Before loading starts, the team must define which records are in scope and confirm that the target model can receive them.
The target org needs the right objects and fields before data arrives. Record types, required fields, ownership, picklists, validation logic, and relationships can affect whether a source record fits the new model. Some legacy fields may have no direct target, while others may need to be combined.
Salesforce’s current data migration best-practices guidance advises teams to identify the objects and fields they intend to migrate before preparing target templates. It also recommends keeping source-system identifiers in custom fields because those identifiers can help preserve relationships and support later validation. That guidance makes migration scope a design decision instead of a file-transfer task.
The same distinction matters when moving between Salesforce orgs. Metadata, user setup, object relationships, and data dependencies need to be considered before records move. HyphenX Solutions’ Salesforce Migration Services cover broader Salesforce moves where configuration and data may both need attention, which is useful when the target org isn’t simply an empty copy of the source.
Salesforce Data Migration Best Practices therefore start with an agreed scope: which objects move, how much history is needed, what legacy data is retired, who approves transformations, and which source stays authoritative until cutover.
Profile Source Data Before Salesforce Field Mapping
Source profiling should happen before detailed Salesforce Field Mapping because a schema rarely tells the whole story. A legacy database may define a field as text, but that doesn’t tell the migration team whether the field contains 4 approved status values or 47 spelling variations collected over 10 years.
Start by measuring how much data actually exists. Record counts should be collected for every table or object in scope, with separate counts for active and inactive records where that difference matters. Profiling should then examine null rates, field lengths, unusual characters, date formats, email patterns, picklist values, invalid references, duplicate identifiers, and values that fall outside the expected business rules.
Relationship quality also needs attention. A source Contact table may contain Account IDs that no longer match an existing Account. A transaction table may point to products that were deleted years earlier. Migrating those rows without first deciding how orphaned relationships should be handled can create errors during loading or records that appear complete but have lost important context.
Source profiling should also identify records that shouldn’t migrate. Test accounts, obsolete leads, abandoned imports, outdated reference values, and duplicate customers can add volume without adding useful business history. Salesforce Data Migration Best Practices favor a defined migration scope because moving unnecessary data increases the number of records that must be mapped and checked later.
When source findings expose gaps in the Salesforce model, the implementation team should resolve them before migration scripts become fixed. HyphenX Solutions’ Salesforce Implementation Services include data-model design alongside migration and quality work, so this type of issue can be addressed while the target structure is still being built. A migration team working independently should follow the same principle by feeding source-data findings back into target design.
A useful profiling output doesn’t need to become a large report. It needs to identify which values can move unchanged, which require transformation, which records should be excluded, and which business questions need answers before Salesforce Field Mapping is approved.
Build Salesforce Field Mapping as a Working Specification
Salesforce Field Mapping is often presented as a spreadsheet with 2 columns: source field and target field. That format works for very small imports, but it leaves too much unexplained for a serious migration.
A migration-ready mapping workbook should record the source object, source field, target object, target field, source type, target type, transformation rule, required status, default behavior, lookup dependency, and the owner of any business decision. It should also state what happens when the source value is blank and whether a blank is allowed to overwrite an existing target value during an update.
| Mapping Item | Example | Purpose |
| Source object | Customer | Identifies the source entity |
| Source field | Customer_Status | Identifies the original value |
| Target object | Account | Defines where the record belongs |
| Target field | Customer_Status__c | Defines where the value lands |
| Source type | Text | Exposes conversion requirements |
| Target type | Restricted picklist | Defines target limits |
| Transformation rule | ACT becomes Active | Makes value conversion explicit |
| Required | Yes | Identifies load requirements |
| Default behavior | Unknown | Defines treatment of blank values |
| Lookup dependency | Parent Account | Connects mapping to load order |
Value mapping deserves its own review. A legacy field may contain Active, ACT, A, Current, and Customer even though each value describes the same state. The migration team should decide which Salesforce value represents that meaning, document the rule, and test it before loading a large dataset.
Data types create another source of failure. Text fields can exceed Salesforce field lengths. Decimal precision may differ between systems. Dates can use different formats, while date-time values can raise timezone questions. Restricted picklists reject values that don’t belong to their allowed set, and required fields can block records that were valid in the old system.
Salesforce’s Data Loader documentation confirms that Data Loader supports field mapping for standard and custom objects and produces separate success and error logs. The tool can process large files, but its mapping features still depend on the rules supplied by the migration team. A correct technical map can’t compensate for a business rule that was never defined.
Salesforce Field Mapping should also record fields that won’t migrate. A retired field should be marked as intentionally excluded instead of being left without a target and forcing someone to guess whether the omission was accidental. HyphenX Solutions’ Salesforce Consulting Services can be relevant when those decisions affect the future Salesforce process rather than the migration alone, since data-model choices can change reporting and user behavior after go-live.
A strong mapping workbook becomes the shared reference for migration development, test cases, defect review, and reconciliation. That is why Salesforce Data Migration Best Practices treat mapping as a specification that can be tested rather than a one-time setup screen inside an import tool.
Use External IDs to Preserve Source Identity
Salesforce creates its own record IDs, so a migration needs a way to connect old identifiers with new Salesforce records. Without that bridge, restoring parent-child relationships can turn into a series of name-based matches that are difficult to repeat safely.
An External ID field can hold an identifier from another system. Salesforce’s 2026 guidance distinguishes an External ID from a Unique field: the External ID can act as a reference to another system and can be used with Data Loader upsert operations, while the Unique setting prevents duplicate values from being saved in that field.
Imagine that a legacy CRM identifies an Account as CUST-18492. After the Account is inserted, Salesforce assigns a new native ID. Keeping CUST-18492 in an External ID field means a later Contact load can still identify the right source Account without matching on the company name.
Salesforce Field Mapping should identify which legacy key will be retained for each object. If several source systems contribute Accounts, the migration may need separate source-specific identifiers or a master identifier created before migration. The team should also decide whether each External ID needs a uniqueness constraint.
Salesforce’s current External ID guidance explains that External IDs can provide a reference bridge to external systems and can be used when working with Data Loader. This makes them useful for source-to-target traceability as well as repeated migration runs.
External IDs become even more useful when systems continue exchanging data after go-live. HyphenX Solutions’ Salesforce Integration Services cover environments where Salesforce exchanges information with other business platforms, and stable cross-system identifiers can make those connections easier to maintain. The migration team should therefore consider whether a legacy identifier will remain useful after the migration is complete.
Salesforce Data Migration can then use those identifiers during test loads and reconciliation. A migrated record can be traced back to its source row, and repeat runs can use upsert logic rather than creating another copy of the same business record.
Handle Salesforce Data Deduplication Before Production Loading
Salesforce Data Deduplication should begin before the production import. Moving known duplicates into the new org and planning to clean them later creates avoidable risk because users, automation, reports, and integrations can start working with several records for the same customer.
The first task is defining what a duplicate means for each object. An exact email match may be useful for Contacts, but shared family addresses or generic company inboxes can produce false matches. Account matching may need a source-system customer number or a normalized website domain. Lead matching may use different rules because a Lead represents a different stage of the customer relationship.
Candidate duplicates then need survivor logic. If 3 Account records describe the same company, the migration team must decide which record remains and how information from the other records is handled. A survivor rule might prefer the record tied to the master customer identifier or the one currently used by an ERP system.
| Field | Record A | Record B | Migration Decision |
| Account Name | North Star LLC | NorthStar, L.L.C. | Use approved legal name |
| Phone | Blank | 212-555-0184 | Retain populated value |
| Status | Active | Former | Use master-system status |
| Legacy ID | C-2381 | Blank | Retain source identifier |
| Owner | Former employee | Current rep | Apply approved ownership map |
Salesforce Data Deduplication also needs a rule for conflicting values. Choosing a survivor record without deciding what happens to the losing record’s valid fields can throw away useful information. The team should specify which system wins for each important attribute and which values require manual review.
Salesforce provides Matching Rules to define how duplicate candidates are identified and Duplicate Rules to define what happens when a duplicate is found. Its Duplicate Management guidance states that organizations can create custom matching logic and choose whether duplicate creation is blocked or allowed with warnings. Salesforce also supplies standard matching rules for business Accounts, Person Accounts, Contacts, and Leads, while custom rules can be created when those defaults don’t match the organization’s definition of a duplicate.
The target Duplicate Rules shouldn’t be treated as a substitute for source cleanup. Salesforce Data Deduplication during migration may need to compare data across several source systems and apply survivor logic that is more detailed than the ongoing controls users will encounter after go-live.
Salesforce Data Migration Best Practices therefore separate pre-migration cleanup from post-migration duplicate prevention. Remove or merge known duplicate source records first, then configure Salesforce controls to reduce the chance that users and integrations rebuild the same problem.
Build Salesforce Data Load Order From Object Dependencies
Salesforce Data Load Order is controlled by relationships. A parent record usually has to exist before a child record can reference it, which means a migration sequence should be built from the actual target schema.
Salesforce’s current recommended object load-order guidance states that parent records should be loaded before children that reference them. Salesforce uses Accounts before Contacts as a basic example because the Contact’s Account lookup depends on an Account that already exists.
That rule sounds simple until custom objects enter the migration. A custom child object may have a required lookup to an Account and another required lookup to a custom parent record. Both parent records need to exist before the child can load correctly. A junction object may depend on 2 separate parents, so loading either parent alone isn’t enough.
Reference data also affects Salesforce Data Load Order. Products may need to exist before Price Book Entries can be created. Price Book Entries must exist before dependent opportunity line items can be loaded. Users may need to exist before records can be assigned to their intended owners.
Self-referencing objects often require multiple passes. Account hierarchies are a common example. The migration can first create the Accounts without Parent Account values, then update those relationships after all required Salesforce IDs or External IDs are available. Custom object hierarchies can follow the same pattern.
A simplified sequence might look like this:
| Load Stage | Typical Records | Reason |
| Foundation | Users and required reference data | Later records depend on them |
| Parent objects | Accounts and top-level custom parents | Child relationships require them |
| Core child objects | Contacts, Opportunities, Cases | Parent records now exist |
| Product structure | Products, Price Books, Price Book Entries | Transaction records depend on them |
| Dependent records | Line items and junction records | Required references now exist |
| Relationship updates | Hierarchies and self-lookups | Target identifiers are available |
| Historical records | Activities and selected Files | Core business records already exist |
This table is an example rather than a universal Salesforce Data Load Order. Industry clouds, CPQ, Revenue Cloud, custom applications, or heavily modified Sales Cloud orgs can create very different dependency chains.
Salesforce Field Mapping and load planning should therefore be reviewed together. Every lookup field in the mapping workbook represents a dependency that may affect sequencing. HyphenX Solutions’ Salesforce Sales Cloud Services page describes migration work across sales objects such as Accounts and opportunities, which are common examples of records whose relationships need to survive a move into a new sales environment.
Salesforce Data Migration should use a dependency graph for complex orgs instead of a memorized object list. That gives the team a load order based on how the target org is actually built.
Review Validation, Automation, and Integrations Before Loading
A migration file can contain valid source data and still fail after it reaches Salesforce. Validation Rules, Flows, Apex triggers, duplicate controls, assignment logic, and integration behavior can all act on records as they are created or updated.
Create an automation inventory for the objects being migrated. The team should know which validations run on Accounts, which Flows react to new Opportunities, whether triggers create related records, and whether assignment logic can change an imported owner. Testing those behaviors early prevents the migration team from blaming the source file for changes caused inside the target org.
Historical data often exposes validation problems. A record created 8 years ago may contain a status or field combination that current business rules no longer allow. The migration team then needs an approved way to handle the mismatch. The source value can be transformed, the validation may be adjusted for a controlled migration condition, or the record may require another business decision.
Automation can also create unwanted volume. A Flow intended to create a follow-up activity for every new Opportunity could generate thousands of unnecessary tasks while historical Opportunities are being inserted. Triggers may update parent records and create locking pressure during large jobs. These behaviors have to be tested with realistic migration volumes.
Connected applications create another risk. A migration may update hundreds of thousands of Accounts, which can cause an integration to send the same changes to an ERP or marketing platform. HyphenX Solutions’ Salesforce API Integration Services describe integration planning that includes data movement and dependencies, and those same dependencies should be reviewed before a migration begins. Teams need a clear decision on whether connected systems remain active, pause, or process migration traffic differently during cutover.
Salesforce Data Migration Best Practices should document every temporary configuration change made for the load. The runbook needs to show when the change is made, who approves it, and how normal production behavior is restored and tested.
Choose the Loading Method Based on the Job
The migration method should follow the workload. Small controlled imports can use Salesforce’s user-facing tools, while larger or repeatable jobs often use Data Loader, ETL platforms, or scripts.
Data Loader supports insert, update, delete, and export operations. Salesforce documents support for standard and custom objects, field mapping, CSV success and error logs, and files with up to 5 million records when using Bulk API and up to 150 million records when using Bulk API 2.0. Those capabilities make Data Loader useful for many planned migrations where teams need a repeatable file-based process.
Current Data Loader can use Bulk API 2.0 directly, so teams don’t need a separate programmatic route to use it for large asynchronous loads. Salesforce’s Bulk API 2.0 ingest documentation states that ingest jobs support insert, update, upsert, and delete operations using CSV data. Salesforce manages the processing after the job is created and the data is uploaded.
Salesforce also says jobs involving more than 2,000 records are good candidates for Bulk API 2.0 when an asynchronous workflow fits the use case. Its Bulk API introduction explains that Bulk API 2.0 handles large datasets asynchronously and is intended to simplify bulk ingestion compared with the older Bulk API.
The operation matters as much as the tool. Insert creates new records. Update changes records that already exist. Upsert can update a matching record or create a new record depending on whether the selected key is found. External IDs make upsert particularly useful during repeated migration rehearsals because the same source identifiers can be used across test runs.
Save and version field mappings and loading settings when the team expects repeated rehearsals.
Large jobs still need performance testing because automation, record locking, and relationships can behave differently at production volume.
Rehearse the Full Migration Before Production
A sandbox rehearsal should test the process intended for production rather than a simplified version designed only to prove that records can be inserted. The test data should include realistic volumes and difficult cases that represent the source data users actually have.
An early technical test can confirm file format, Salesforce Field Mapping, External IDs, and basic object relationships. A later rehearsal should run the full Salesforce Data Load Order, use the approved transformations, apply the planned automation settings, and perform the same reconciliation that will follow the production load.
Every failed row should be categorized. Common causes include missing required values, invalid picklists, field-length violations, lookup failures, validation rules, duplicate controls, and ownership problems. Categorizing failures helps teams correct the root issue instead of repeatedly patching individual records.
Salesforce Data Deduplication also needs to be tested in the target environment. The migration team should confirm that approved source survivors load as expected and that Salesforce Duplicate Rules don’t reject valid records because the matching logic is too broad.
Timing should be measured during rehearsal. Record how long each object takes to load and how long error review or relationship updates require. That information helps the cutover team decide whether the planned production window is realistic.
A rehearsal should also test failure recovery. Salesforce bulk processing can return successful records alongside failed or unprocessed records, so the recovery plan needs to identify which rows require another job. Bulk API 2.0 provides separate result handling for failed and unprocessed records, which allows a migration process to distinguish records that need correction from records that weren’t processed.
Salesforce Data Migration should move into production only after the team can explain how the full process behaves. A successful rehearsal provides a tested runbook rather than a prediction.
Control Production Cutover and Delta Data
Production cutover introduces a problem that sandbox tests don’t fully reproduce: the source system may still be changing. Users can update Contacts or close Opportunities after the main extract has been taken, which means the migration needs a clear point when source changes stop or a method for capturing the changes made after extraction.
Some migrations use a full source freeze. Others take an initial extract and later run a delta migration containing records created or changed after that extract. The choice depends on downtime tolerance and whether the source can reliably identify changed records. Before the production load starts, take an approved point-in-time backup of the affected Salesforce data. Back up relevant metadata as well when the cutover includes configuration changes. Record where the backup is stored, who verified it, and how the team would restore affected data if a bulk update or import produces the wrong result.
The final runbook should list each Salesforce Data Load Order stage and its owner. For every job, record the source file version, submitted record count, successful record count, failed record count, start time, completion time, and any corrective rerun. Keeping those records makes later reconciliation easier because the team knows exactly which file produced each result.
Failures need controlled reruns. Reprocessing an entire file because a small percentage of records failed can create duplicates when insert operations are involved. Stable External IDs and upsert operations can reduce that risk, but the team should still isolate errors where the loading method allows it.
A critical parent-object failure should stop dependent loads when continuing would create more errors. For example, if an Account job fails at an unacceptable rate, pushing Contact records immediately afterward may turn one migration defect into thousands of failed lookup relationships.
Salesforce Data Deduplication controls should remain part of the cutover plan. Teams need to know whether Duplicate Rules behave differently during bulk operations and whether migration users have settings that differ from normal users. Those decisions should have been tested during rehearsal rather than changed during the live window.
Production access should open only after agreed checks pass. Users shouldn’t be asked to work in Salesforce while the migration team is still rebuilding key relationships or deciding whether an object needs to be reloaded.
Reconcile the Target Before Calling the Migration Complete
A migration job finishing successfully doesn’t prove that the data is correct. Salesforce Data Migration should end with reconciliation between the approved source scope and what now exists in the target org.
Start with record counts by object. Compare the number of records selected for migration with the number successfully created or updated. Every material difference should have an explanation, whether it comes from approved exclusions, dedupe merges, rejected records, or data that was intentionally archived rather than moved.
Field-level checks come next. Select important values that matter to real business processes, such as Account status, Opportunity amount, owner, close date, product reference, or customer identifier. Compare source and target values across a sample large enough to include the transformation rules that were applied.
Relationship checks deserve separate attention. Confirm that Contacts point to the intended Accounts and that junction records connect the right parents. Test self-referencing hierarchies and required lookups. Salesforce Data Load Order can appear successful at a record-count level even when relationships were reconstructed incorrectly.
Salesforce Data Deduplication should be checked again after the production load. Compare the expected number of survivor records with the target count, then use the approved matching logic to identify unexpected duplicates created by failed upserts or inconsistent keys.
Business reports provide another form of verification. A sales manager may know the expected number of open Opportunities in a region, while finance may know the value of active customer accounts. When those numbers differ sharply from the source, the migration team has a useful path for investigation.
Salesforce recommends record-count reports, spot checks, and review of Data Loader error information as migration validation methods. After acceptance, Salesforce Support Services may be relevant when teams need ongoing help with data quality or issues found during live use, but the migration itself should still close with a documented list of what was checked and any approved exceptions that remain.
Salesforce Data Migration Best Practices treat validation as part of the migration rather than cleanup after the project. Users can trust the new system only when the records and relationships match the business information they expect to find.
Conclusion
Salesforce Data Migration succeeds when scope, mapping, dedupe rules, source identifiers, and load dependencies are settled before production loading. A realistic rehearsal then tests those decisions against the target org’s automation and relationships.
The migration closes after reconciliation, not after the last import job. Compare the target with the approved source scope, investigate unexplained differences, and confirm that users can rely on the migrated records for reporting and daily work.
FAQs
What Is Salesforce Data Migration?
Salesforce Data Migration moves approved business records from another system into Salesforce. It includes source preparation, field mapping, dedupe, relationship preservation, load sequencing, import execution, and final validation.
What Is Salesforce Field Mapping?
Salesforce Field Mapping defines how source fields and values become Salesforce fields and values. It should record data types, transformations, required values, lookup dependencies, and rules for blanks or invalid values.
Why Does Field Mapping Need to Happen Before Loading?
Field mapping protects meaning before data moves. Mismatched picklists, field lengths, dates, required values, and lookups can cause failures or misleading records, so transformation rules should be tested before production.
What Is Salesforce Data Deduplication?
Salesforce Data Deduplication identifies records that may represent the same business entity. The team defines matching rules, chooses the survivor, and decides which useful values from duplicate records must be retained.
Should Duplicates Be Removed Before Salesforce Migration?
Known duplicates should usually be resolved before production. Salesforce Matching Rules and Duplicate Rules help control future duplicates, but they don’t replace source cleanup and approved survivor logic.
What Is Salesforce Data Load Order?
Salesforce Data Load Order is the sequence used to preserve relationships. Parent records normally load before dependent children, but required lookups and custom objects can change the correct order.
Should Accounts Always Be Loaded Before Contacts?
Accounts usually load before Contacts when the Contact needs an Account lookup. External IDs can help rebuild that relationship, but custom dependencies may require a different sequence.
What Is an External ID in Salesforce?
An External ID stores an identifier from another system. It helps trace migrated records to their source, supports upsert operations, and can help rebuild relationships after Salesforce assigns new native IDs.
What Is the Difference Between Insert and Upsert?
Insert creates a new record. Upsert checks a chosen key, often an External ID, and updates a match or creates a record when no match exists. That makes upsert useful for repeatable rehearsal loads.
How Do Salesforce Matching Rules and Duplicate Rules Differ?
Matching Rules identify possible duplicates. Duplicate Rules decide what Salesforce does with a match, such as warning or blocking. Test both with realistic source data so broad criteria don’t reject valid records.
Can Salesforce Automation Affect Data Migration?
Yes. Validation Rules can reject values, while Flows, Apex triggers, and assignment logic can change imported records or create related data. Review and test this behavior before production.
Should Salesforce Data Migration Use Data Loader or Bulk API 2.0?
Current Data Loader can use Bulk API 2.0, so the choice isn’t strictly Data Loader versus Bulk API 2.0. Use the mode and toolchain that fit volume, automation, and repeatability after mapping and dedupe rules are settled.
How Many Migration Rehearsals Are Needed?
There isn’t a fixed number. Most projects need an initial technical test and at least 1 realistic full rehearsal, with more cycles when failures, recovery, mapping, or load order remain uncertain.
How Is Salesforce Data Validated After Migration?
Compare source and target record counts, key field values, failed rows, External IDs, and relationships. Business reports can also expose unexpected differences that technical checks miss.
What Are the Most Important Salesforce Data Migration Best Practices?
Define scope, profile the source, document transformations, retain useful source IDs, resolve known duplicates, build load order from dependencies, rehearse with representative data, back up before cutover, and reconcile the target before closing the migration.
