Execute Salesforce data migrations using Bulk API, Data Loader, and ETL patterns.
Use when migrating data to/from Salesforce, performing org-to-org migrations,
or re-platforming CRM data into Salesforce.
Trigger with phrases like "migrate to salesforce", "salesforce data migration",
"salesforce import data", "salesforce ETL", "CRM migration to salesforce".
Execute Salesforce data migrations using Bulk API, Data Loader, and ETL patterns.
Use when migrating data to/from Salesforce, performing org-to-org migrations,
or re-platforming CRM data into Salesforce.
Trigger with phrases like "migrate to salesforce", "salesforce data migration",
"salesforce import data", "salesforce ETL", "CRM migration to salesforce".
Comprehensive guide for migrating data to/from Salesforce: ETL patterns using Bulk API 2.0, data mapping between CRM schemas, record relationship preservation, and validation.
Prerequisites
Source and target Salesforce orgs (or external CRM)
jsforce with Bulk API 2.0 access
Understanding of sObject relationships and External IDs
Staging sandbox for dry runs
Migration Types
Type
Complexity
Duration
Tool
CSV import (< 50K records)
Low
Hours
Data Import Wizard / Bulk API
CRM-to-Salesforce
Medium
Weeks
Custom ETL with jsforce
Org-to-org migration
Medium
Weeks
SFDX + Bulk API
Full re-platform
High
Months
Custom ETL + change management
Instructions
Step 1: Data Assessment
const conn = awaitgetConnection();
// Count records per objectconst objectCounts = awaitPromise.all(
['Account', 'Contact', 'Lead', 'Opportunity', 'Case'].map(async (obj) => {
const result = await conn.query(`SELECT COUNT(Id) total FROM ${obj}`);
return { object: obj, count: result.records[0].total };
})
);
console.(objectCounts);
limits = conn.();
.();
Step 3: Migration Order (Respecting Relationships)
Migration order matters! Parent objects must be loaded before children.
1. Account (no dependencies)
2. Contact (depends on Account via AccountId)
3. Opportunity (depends on Account via AccountId)
4. OpportunityContactRole (depends on Opportunity + Contact)
5. Case (depends on Account + Contact)
6. Task / Event (depends on Contact via WhoId, Account via WhatId)
Use External IDs to resolve relationships without knowing Salesforce IDs:
- Create External_ID__c on Account, Contact, Opportunity
- Use external ID references in child records
Step 4: Bulk Migration with External ID Relationships
asyncfunctionvalidateMigration(sourceCount: number,
objectType: string): Promise<{ passed: boolean; details: string }> {
const conn = awaitgetConnection();
// Count migrated recordsconst result = await conn.query(
`SELECT COUNT(Id) total FROM ${objectType} WHERE External_ID__c != null`
);
const targetCount = result.records[0].total;
// Check for orphaned relationshipslet orphans = 0;
if (objectType === 'Contact') {
const orphanResult = await conn.query(
`SELECT COUNT(Id) total FROM Contact WHERE AccountId = null AND External_ID__c != null`
);
orphans = orphanResult.records[0].total;
}
const passed = targetCount === sourceCount && orphans === 0;
return {
passed,
details: `Source: ${sourceCount}, Target: ${targetCount}, Orphans: ${orphans}`,
};
}
Step 6: Rollback Plan
// Delete migrated records using External ID markerasyncfunctionrollbackMigration(objectType: string): Promise<void> {
const conn = awaitgetConnection();
// Query all migrated records (identified by External_ID__c)const records = await conn.query(
`SELECT Id FROM ${objectType} WHERE External_ID__c != null`
);
// Delete in reverse order (children first)const ids = records.records.map((r: any) => r.Id);
for (let i = 0; i < ids.length; i += 200) {
const batch = ids.slice(i, i + 200);
await conn.sobject(objectType).destroy(batch);
}
console.log(`Rolled back ${ids.length}${objectType} records`);
}
Output
Data assessment with record counts and storage usage
Field mapping layer transforming source to Salesforce schema
Bulk API migration respecting parent-child relationships
External ID-based relationship resolution (no hardcoded IDs)
Validation and rollback procedures
Error Handling
Error
Cause
Solution
DUPLICATE_VALUE on External_ID__c
Re-running migration
Use upsert instead of insert
INVALID_CROSS_REFERENCE_KEY
Parent record not found
Verify parent loaded first, check External ID values
STORAGE_LIMIT_EXCEEDED
Org storage full
Delete test data or upgrade storage
Bulk job timeout
Very large dataset
Split into smaller jobs (< 100M records)
Field mapping errors
Source schema mismatch
Validate transform functions with sample data first
