Salesforce Governed Data Migration
Overview
Move data as a controlled accounting exercise in which every source key, transformation, dependency, target result, exception, and rollback obligation is traceable.
Prerequisites
- Source and target systems, objects, owners, data classes, migration scope, cutover window, and success criteria
- Current source schema, Salesforce metadata, external IDs, relationships, validation, automation, sharing, and limits
- Mapping and transform rules, quality thresholds, quarantine, reconciliation, rollback or compensating action, and retention plan
Tool Discipline
Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.
Current Contract
Bulk API 2.0 supports asynchronous CSV ingest and query, including insert, update, upsert, and delete where documented and entitled. Data Loader and other tools have separate contracts; object behavior, automation, and limits remain org-specific.
Authentication
Separate source read, transformation, target write, verification, and support access. Keep tokens and private keys out of migration files; encrypt and expire approved extracts and restrict raw personal data.
Instructions
- Freeze scope, source snapshot or watermark, objects, fields, filters, counts, classifications, owners, and cutover criteria.
- Profile data quality and map source keys, target external IDs, required fields, lookups, parents, children, owners, picklists, and transforms.
- Discover target API versions, metadata, permissions, sharing, validation, automation, duplicate rules, storage, limits, and lock behavior.
- Order deterministic migration waves, create immutable manifests and hashes, and separate valid, rejected, and quarantined records.
- Run dry-run transformations, then small synthetic and representative non-production canaries with full dependency reconciliation.
- Execute approved production waves within limits; preserve job IDs and result files and never blindly replay uncertain batches.
- Re-query by stable keys, reconcile counts, values, relationships, ownership, duplicates, and downstream effects; cut over or roll back.
Approval Boundaries
Do not extract production data, disable automation, change external IDs, overwrite owners, delete records, start a load, or cut over without owners.
Output
Return scope and snapshot, mappings, quality report, dependency graph, manifests, job results, quarantine, reconciliation, cutover decision, rollback, and expiry.
Error Handling
| Condition | Response |
|---|---|
| External IDs are not unique | Stop upsert planning and resolve the source and target identity model. |
| Automation changes migrated values | Classify the intended behavior, revise transforms or approved automation, and rerun the canary. |
| Job outcome is incomplete or unavailable | Do not replay; retrieve result evidence and reconcile target keys first. |
Example
A redacted completion receipt might look like this:
migration=legacy-accounts; source=watermarked; rows=850000; waves=6; success=849920; quarantine=80; reconcile=exact
Resources
Next Steps
Run the workflow first in the lowest-risk authorized org and preserve its redacted receipt. Schedule a review against the next Salesforce seasonal release and the customer change calendar.