Lesson 4 of 5
Writing the migration runbook
9 min
A migration runbook is the step-by-step script for executing the migration: every action, in order, with its owner, timing, predecessor and evidence. It is written during the mocks, improved after each one, and on go-live weekend it is the only plan anyone follows. If a step is not in the runbook, it does not happen; if it happens anyway, it should be added.
What every step contains
| Field | Purpose | Example |
|---|---|---|
| Step ID | Unique reference for status and issues | MIG-210 |
| Action | One clear action, starting with a verb | Load business partner delta (customers) via Migrate Your Data |
| Predecessors | Steps that must be complete first | MIG-200 delta extract validated |
| Owner and backup | Named person on shift, plus a named backup | Migration specialist A; backup B |
| System and client | Where the step runs | Production system CMP, production client (never test client 100 in CMQ) |
| Planned start and duration | From the last timed rehearsal | Sat 02:00, 1.5 h |
| Actual start and end | Filled during execution | Recorded live |
| Evidence | What proves completion | Message log export; record count matches extract |
| Checkpoint | Whether a go/no-go decision follows | Checkpoint 2 after MIG-260 |
| Contingency | What to do if it fails | Rerun after fix within 1 h; else escalate to Luis |
The fields of a runbook step. Contoso kept its Wave 2 runbook as a shared, versioned workbook.
Writing good steps
- One action per step, so status is unambiguous.
- Durations from measured rehearsals, not estimates.
- Every step that changes data has a validation step after it, owned by someone else where possible.
- Decision points are steps too: "Checkpoint 2: Dan confirms AR reconciliation; Luis decides go or stop."
- Handovers between shifts are explicit steps with a briefing and a status snapshot.
- Contingency is written next to the step, not in a separate document nobody opens at 3 a.m.
The runbook improves with every mock
- Draft before Mock 1Steps from the load sequence and work instructions
- Execute and recordActual times, deviations and unplanned steps captured live
- Review after the mockMissing steps added, durations updated, owners and contingency fixed
- Version and approveNew version issued with a change log; Luis approves
- Freeze before dress rehearsalOnly the go-live version runs in the dress rehearsal and on the day
A useful measure of runbook maturity is the number of unplanned steps per rehearsal: things people had to do that were not written down. Contoso counted 41 in Mock 1, 12 in Mock 2, 3 in Mock 3 and none in the dress rehearsal. That trend gave Grace more confidence than any status color.
What would you do?
During Mock 3, a migration specialist realizes that the pricing condition load needs a manual step (releasing a condition table) that is not in the runbook. He does it and carries on. What should happen next?
- The migration runbook is the step-by-step script of the migration, a chapter of the cutover plan.
- Each step: ID, action, predecessors, owner and backup, system and client, timing, evidence, checkpoint, contingency.
- Durations come from rehearsals; decision points and handovers are steps too.
- Update and version the runbook after every mock; track unplanned steps toward zero.
Check your understanding · not graded
Lesson check
1. What is a migration runbook?
2. Where should planned durations come from?
3. What does a falling count of unplanned steps show?
4. Why must every step name the system and client?