The CRM migration runbook

A CRM migration fails in one of three ways: the data arrives wrong, the team keeps using the old system, or something nobody documented turns out to have been load-bearing. All three are avoidable and none of them are avoided by enthusiasm.

This runbook is written as steps rather than principles because that is what you need at the time. Print it, work down it, and cross off what does not apply to you.

Phase 1: decide and freeze (8 steps)

1. Write down the specific reason you are moving. If it is a feature, name it. If it is a price, name the number.
2. List every system that reads from or writes to the current CRM. Forms, calendars, billing, reporting, that spreadsheet somebody maintains.
3. Find the undocumented dependency. There is always one. Ask the person who has been there longest.
4. Decide the cut-over date and make it a date when nothing else important is happening.
5. Announce a freeze on configuration changes in the old system from two weeks before.
6. Decide what you are not bringing: records older than a threshold, closed-lost deals past a date, contacts with no activity ever.
7. Get one person named as the owner. A migration with a committee has no owner.
8. Confirm you can actually export everything you need before you sign anything.

Phase 2: export (7 steps)

9. Export contacts, companies, deals, activities, notes and files, each as its own file.
10. Export custom fields and their values, including the ones you think nobody uses.
11. Export the picklist values behind every dropdown, because those become mapping decisions later.
12. Export users and their permissions as they stand, which is your reference for setting up access on the other side.
13. Export attachments separately, and check the total size before you assume it will be easy.
14. Take a second export a day later and compare row counts, so you know the export is complete rather than truncated.
15. Store the exports somewhere you will still have access to in six months, not on the laptop of whoever ran them.

Phase 3: map (9 steps)

16. Map objects first: what the old system calls an account, an organisation or a company.
17. Map the fields, one row per field, in a document that survives the migration.
18. Decide the unique key for each object. Email for contacts, domain for companies, something stable for deals.
19. Map pipeline stages, and take the opportunity to reduce them if you have more than seven.
20. Assign a probability to each new stage, because the weighted forecast depends on it.
21. Map owners to the new user list, including the people who have left.
22. Decide what happens to records owned by departed staff before you load them, not after.
23. Normalise the messy fields: phone formats, country names, industry values.
24. Write down every field you decided not to migrate and why, so nobody has to reconstruct the reasoning later.

Phase 4: load and verify (10 steps)

25. Load a sample of a hundred records first and stop.
26. Check the sample by hand against the old system. Every field, ten records, properly.
27. Load companies before contacts and contacts before deals, so relationships have something to attach to.
28. Load the suppression list before anything else touches an outbound tool.
29. Load the full set and record the row counts in and out.
30. Reconcile the counts. A gap of a few percent is a problem, not rounding.
31. Spot-check the relationships: deals that should have a company, contacts that should have a deal.
32. Check the weighted forecast against the old system's number. If they differ, find out why before anyone sees both.
33. Verify a sample of attachments actually opens.
34. Set up users, roles and access scopes, then have two people log in and confirm they see what they should.

Phase 5: cut over (7 steps)

35. Repoint the integrations: forms, calendar bookings, webhooks. Test each with a real submission, not a sample payload.
36. Move mailbox connections and confirm threads attach to the right records.
37. Set the old system to read-only rather than cancelling it.
38. Keep it readable for at least one full sales cycle. This is the rollback nobody plans and everybody wants.
39. Train in the new system on real records, not a demo dataset.
40. Watch the first week for the thing nobody thought of, and fix it in the new system rather than reverting.
41. After a cycle, export the old system one final time and archive it before you cancel.

Contacts, companies and deals import through the data bank, which is deliberately a staging area rather than the live tables. A bad load is a table you throw away instead of a mess you unpick.

Two limits worth knowing before phase three. Custom fields are on the roadmap, so a field-heavy old CRM will not map one to one today. Duplicate detection and merge are also on the roadmap, which makes step eighteen, choosing a stable unique key, more important than it would otherwise be.

On the other side, exporting out is a full Postgres dump plus CSV everywhere, because the instance is your own project rather than a partition of ours. Whatever you migrate in, you can migrate out.