Migration Runbook Template
A section-by-section runbook for data and platform migrations, with an example cutover timeline, load order, validation checks and clear rollback criteria.
A migration plan says what you intend to do. A runbook says exactly what happens, in what order, who does it, and what happens if it goes wrong. On cutover night nobody should be making decisions from memory. This template works for Salesforce data migrations, org consolidations and moves into Marketing Cloud from another email platform; adapt the load order and checks to your own scope.
1. Overview and scope
One short paragraph: what is moving, from where to where, and why. List the objects or data sets in scope with approximate record counts, and state what is explicitly not moving (for example, email history older than a set date, or closed cases before a cut-off).
2. Roles and contacts
Name one person for each role and a backup. At minimum: migration lead (owns the runbook and the clock), data loader operator, source system owner, target platform admin, business validator for each area, and the person with authority to call go or no-go. Record how to reach each of them during the cutover window.
3. Pre-migration checks
- 01
Rehearsals completed
At least one full rehearsal in a sandbox with production-like volumes, with timings recorded for every step. Use the rehearsal timings, not estimates, in the cutover plan.
- 02
Mapping signed off
Field mappings, value translations and owner mappings are approved by the business owners and versioned.
- 03
External IDs in place
Every target object that receives related records has an external ID field, so loads can upsert and relate records without lookups by name.
- 04
Automation bypass ready
Flows, triggers, validation rules and assignment rules that should not fire during the load are bypassed, typically through a custom permission assigned only to the migration user.
- 05
Permissions confirmed
The migration user has the access it needs, including Set Audit Fields upon Record Creation if you must preserve original created dates and created-by values, and Update Records with Inactive Owners if records belong to inactive users. Both must be enabled in Setup first; check current requirements in Salesforce Help.
- 06
Backups taken
Source extracts and a target backup are stored securely and access is restricted.
- 07
Freeze announced
Users know when the source becomes read only and when the target opens.
4. Example load order
| Seq | Data set | Depends on | Check after load |
|---|---|---|---|
| 1 | Users and roles | None | Active user count, role assignments |
| 2 | Accounts | Users for ownership | Record count, parent account links |
| 3 | Contacts | Accounts | Count, orphan contacts with no account |
| 4 | Leads | Users, campaigns if used | Count, owner distribution |
| 5 | Opportunities and line items | Accounts, products, price books | Count, amount totals by stage |
| 6 | Cases | Accounts, contacts | Count, open case total |
| 7 | Activities and notes | All parent records | Sample check on related records |
| 8 | Files and attachments | All parent records | Count and spot-open sample files |
| 9 | Consent and preferences | Contacts, leads | Opt-out totals match source |
5. Cutover timeline
Write the timeline relative to go-live (T), with a named owner and a planned duration from rehearsal for every line. For example:
- T-5 days: final mapping freeze; change requests deferred to after go-live.
- T-1 day, 18:00: source set to read only; final delta extract starts.
- T-1 day, 20:00: automation bypass switched on in target; loads begin in sequence.
- T-1 day, 23:30: technical validation complete; business validators start checks.
- T, 07:00: go or no-go call.
- T, 08:00: automation bypass switched off; integrations re-enabled; users given access.
6. Validation
Validation has two layers. Technical checks compare record counts, totals and orphan counts between source and target for every data set, and review error files from each load. Business checks are performed by named validators who open real records they know and confirm they look right: a key account, an open opportunity, a recent case, an opted-out contact.
7. Rollback and go or no-go criteria
| Situation | Decision | Action |
|---|---|---|
| Counts within agreed tolerance, no critical defects | Go | Proceed with switch-on steps |
| Non-critical defects with workaround | Go with known issues | Log issues, communicate workarounds, fix in hypercare |
| Critical data missing or wrong in a core object | No-go or partial rollback | Fix and reload affected data set if within window |
| Timeline overrun beyond agreed buffer | No-go | Reopen source system, reschedule cutover |
| Integration failures after switch-on | Decision by migration lead | Disable integration, keep users on target if data is sound |
8. Communication and hypercare
List who is told what at each milestone (start, go or no-go, live) and through which channel. Then define hypercare: how long it lasts, who triages issues, how users report them, and when the source system is finally decommissioned or archived.
Related reading
Planning a cutover?
We can write and rehearse your migration runbook with you, then support the cutover window and hypercare.
