#Salesforce Org-to-Org Data Migration

This guide covers how to use iSyncSF for one-time or phased data migration between Salesforce orgs — including org consolidation, platform changes, and legacy system retirement. While iSyncSF is also used for recurring sync, migration scenarios have distinct planning, configuration, and validation requirements covered here.

#When You Need Org-to-Org Migration

• Mergers and acquisitions: Consolidating two Salesforce orgs into one after a corporate merger or acquisition. Customer records, opportunities, and historical data from the acquired company need to move into the primary org.
• Platform changes: Moving from one Salesforce edition to another (e.g., Professional to Enterprise), or from a legacy org to a newly provisioned org with a redesigned data model.
• Splitting orgs: Dividing a single Salesforce org into business-unit-specific orgs. Each unit takes its own subset of records.
• Legacy system retirement: Migrating data from an older Salesforce org to a new implementation built from scratch, where the old org will be decommissioned after migration.

#Migration vs Sync — Key Differences

Both migration and sync use the same iSyncSF engine, templates, and object settings. The difference is in how you configure and plan the operation.

#Planning Your Migration

Inventory Source Data

Before configuring iSyncSF, inventory all objects and record counts in the source org. Identify which objects contain business-critical data that must be migrated and which can be excluded (e.g., temporary staging objects, obsolete custom objects).

Map Source Schema to Target Schema

If the source and target orgs have different schemas (different field names, different picklist values, missing fields), you need to map them before migration:

• Identify field name differences between source and target — these will require Field Mappings.
• Identify missing fields in the target — decide whether to create them or map values to alternative fields.
• Identify picklist value gaps — configure Picklist Value Mappings to translate source values to valid target values.

Run Org Compare

Use Org Compare to automatically detect schema mismatches between the source and target orgs. Org Compare identifies fields that exist in one org but not the other, data type differences, and picklist value gaps. Resolve these differences before starting the migration.

Define the Object Dependency Graph

Determine which objects reference which others via lookup and master-detail relationships. Parent objects must be migrated before their children. iSyncSF computes this automatically during the scan phase, but you should assign Sequence numbers on your template lines that reflect the natural dependency order (independent objects first, dependent objects later).

Estimate Migration Time

Migration time depends on record volume, the number of objects, batch sizes, and callout limits. As a rough guide:

• Simple objects with few fields: approximately 5,000–10,000 records per minute.
• Complex objects with many lookups: approximately 1,000–3,000 records per minute.
• Objects with large text or rich text fields: reduce batch size to stay under the 12 MB callout limit.

#Configuring iSyncSF for One-Time Migration

Template Settings

• Create a Sync Template with Continue on Error enabled. Migration jobs should process all records and log errors rather than halting at the first failure.
• Do not enable Delta Sync for a first-time migration — you want all records to be included.

Template Lines

• Add Template Lines in dependency order. Independent objects (those with no lookup dependencies on other custom objects) should have the lowest Sequence numbers.
• Use SOQL filters only if you need to exclude specific records (e.g., test records, records marked for deletion).

Object Settings

• Configure field mappings for any fields where the API name differs between source and target.
• Set CustomExternalID for each object to enable upsert. This prevents duplicates if you need to re-run the migration after fixing errors.
• Use Expression formulas for field transformations — for example, concatenating two source fields into one target field, or providing conditional default values.

#Handling Relationships and ID Remapping

One of the most complex aspects of org-to-org migration is maintaining record relationships. Salesforce record IDs are org-specific — an Account ID in the source org does not exist in the target org. iSyncSF handles this automatically.

Automatic ID Remapping

When parent records are inserted into the target org, they receive new Salesforce IDs. iSyncSF maps each source parent ID to its new target ID. When child records are processed, lookup fields are automatically populated with the correct target org IDs. No manual ID mapping is required.

Processing Order

Parent objects are always processed before children. During the pre-scan phase, iSyncSF analyzes the relationship hierarchy and calculates the correct insertion order. You should align your template line Sequence numbers with this natural order to avoid unnecessary reprocessing.

Self-Referencing Objects

Self-referential objects (e.g., Account hierarchy via ParentId, Contact manager lookups) require special handling. iSyncSF uses a two-pass approach:

1. First pass: Insert all records without the self-referencing lookup value.
2. Second pass: Update records with the correct self-referencing lookup, now that all records exist in the target and their new IDs are known.

Lookup Fields to Non-Migrated Objects

If a lookup field references an object that you are not migrating (e.g., User, RecordType), use Exclude Parent Fields in Object Settings to skip ID remapping for that field. The assumption is that the referenced records already exist in the target org with the same IDs (which is true for User records in same-company orgs and for RecordTypes with matching DeveloperNames).

#Post-Migration Validation

Thorough validation is essential before decommissioning the source org or declaring the migration complete.

Record Count Comparison

Compare record counts between source and target using the Preview/Scan results. The scan output shows how many records were queried from the source. Compare this with a record count in the target org to verify completeness.

Relationship Spot-Checks

Select a sample of child records in the target org and verify that their lookup fields point to the correct parent records. For example, verify that Contacts are linked to the correct Accounts, and Opportunities are linked to the correct Accounts and Contacts.

Error Review

Review the Sync History tab for error summaries. Export the error details as CSV for detailed analysis. Common migration errors include:

• FIELD_CUSTOM_VALIDATION_EXCEPTION — validation rules rejecting data.
• REQUIRED_FIELD_MISSING — a required field in the target was not populated.
• INVALID_FIELD — a field exists in the source but not the target (schema mismatch).
• DUPLICATES_DETECTED — duplicate rules in the target are blocking inserts.

Business Data Integrity

Run reports in the target org to validate business data integrity. Compare key metrics (total revenue, record counts by status, record counts by owner) between source and target to ensure no data was lost or corrupted during migration.

Audit Log Review

Check the DataSyncAuditLog records for any entries with error status. These identify records that failed to migrate and may need manual intervention or a targeted re-run.

#Rollback Strategy

For large migrations, having a rollback plan is essential. iSyncSF provides rollback capability, but it requires planning.

Keep Audit Logs Until Validation is Complete

Rollback depends on audit log records to identify which records were inserted. Do not run cleanup on audit logs until the migration has been fully validated and accepted. This may mean temporarily increasing your retention period or disabling scheduled cleanup for the duration of the validation window.

What Rollback Does

• Inserted records: Rollback deletes records that were inserted into the target org during the sync job.
• Updated records: If DataVersion versioning was enabled during the sync, rollback restores updated records to their pre-migration values.
• Scope: Rollback is scoped to a specific sync job — it does not affect records created by other processes or previous sync runs.

Phased Rollback for Large Migrations

For very large migrations that span multiple sync jobs, consider rolling back in phases — by sync job, not by object. This gives you finer control and avoids the overhead of rolling back millions of records in a single operation.

Post-Validation Cleanup

After the migration has been validated and the rollback window has passed, clean up audit logs to free storage. Use the scheduled cleanup jobs or manual cleanup as described in the Cleanup & Maintenance guide.