Migration Checklist: Moving to Twenty CRM

Phase 0

Decide & Plan

Lock scope, hosting model, and the cutover window before any data moves.

• Choose deployment model: Twenty Cloud or self-hosted. Twenty Cloud is the managed SaaS at $9/user/month. Self-hosted uses Docker Compose with PostgreSQL and Redis on infrastructure you operate. The choice affects backup, upgrade cadence, and direct database access.

  Risk if skipped: Switching deployment models mid-project rebuilds the workspace from scratch and discards all configuration.

• Define migration scope by Twenty object. Confirm in writing which standard objects ship: Companies, People, Opportunities, Notes, Tasks. List any custom objects you will create. Mark each as in-scope or out-of-scope.

  Risk if skipped: Unlisted custom objects surface at import and force the schema build to restart inside the cutover window.

• Decide historical-activity scope and cutoff date. Pick a hard horizon for notes, tasks, and synced emails/calendar events (for example: last 24 months). Twenty syncs Gmail/Outlook forward from connection time; pre-connection history will not appear via the sync path.

  Risk if skipped: Assuming Gmail/Outlook sync backfills years of email history leaves a silent gap that only surfaces post-cutover.

• Confirm Twenty version and release cadence. Record the exact Twenty version (e.g., 1.3.0, 1.4.0, 2.0). Note that Merge Records, Junction Relations, and other features land in specific releases. Active development means breaking changes between versions.

  Risk if skipped: Building against an older version then upgrading mid-project can break custom-object metadata and require schema rework.

• Document gaps versus the source CRM in writing. Twenty does not ship native lead scoring, email sequences, formula/computed fields, a Rich Text field type, or attachments on Opportunities. List every source feature that has no Twenty equivalent and decide rebuild vs. drop.

  Risk if skipped: Discovering a missing native feature after cutover forces an emergency rebuild outside the platform.

• Identify GDPR data-residency requirements. If you operate self-hosted, the data sits wherever you run Postgres. Confirm region. If you use Twenty Cloud, verify the hosting region of the workspace meets contractual obligations.

  Risk if skipped: Provisioning in the wrong region forces a second migration after cutover.

• Capture AGPL-3.0 license implications with legal. Twenty's core is AGPL-3.0. If you plan to modify the codebase and expose it as a network service, AGPL obligations apply. Document any modifications planned.
• Assign a single accountable migration owner (DRI). One named person owns scope decisions, cutover go/no-go, and post-migration sign-off. Document their backup.
• Set cutover date, freeze window, and rollback decision point. Pick the source-system freeze date, the cutover window, and the hour by which a no-go call must be made if validation fails.

  Risk if skipped: Without a pre-agreed rollback gate, teams push through partial loads and create reconciliation work that takes weeks.

• Document explicit out-of-scope items. Write down what is NOT migrating (stale records over 2 years old, deprecated custom fields, test data, archived activities). Get sponsor sign-off.

  Risk if skipped: Unwritten out-of-scope items resurface as urgent during cutover.

Phase 1

Pre-Migration Prep

Clean the source, stand up the Twenty workspace, and brief the team before any export.

Phase 2

Source Export

Pull complete, timestamped exports of every in-scope object from the source.

• Export Companies as CSV with all standard and custom fields. Include name, domain, address, industry, employee count, owner email, created/updated timestamps, and every custom field. UTF-8 encoded.

  Risk if skipped: Missing custom fields at export time means a second export and second transform pass.

• Export People as CSV with all standard and custom fields. Include first name, last name, emails (primary + additional), phone, job title, LinkedIn URL, company linkage key, owner email, and all custom fields.
• Export Opportunities as CSV with all stage and amount details. Include name, amount, currency, stage, close date, probability, primary contact key, company linkage key, owner email, and any custom fields. Stage values matter — record exact labels.

  Risk if skipped: Importing amounts without currency context produces zero or mislabeled values in Twenty's Currency field.

• Export Notes with parent-record linkage. Capture body text, created date, author email, and the unique key of the parent (Company domain, Person email, or Opportunity name).
• Export Tasks with assignee, due date, and parent linkage. Capture title, body, status, due date, assignee email, and parent record key.
• Export custom-object records to their own CSVs. One file per custom object. Include the relation column(s) keyed to parent object identifiers.
• Export attachments with metadata and binaries. Pull the binary files plus a manifest CSV mapping each file to its parent record key. Note: Twenty does not yet support attachments on Opportunity (issue #3799) — plan to attach those to the related Company or Person instead.

  Risk if skipped: Opportunity attachments dropped at import without warning if the destination object does not support them.

• Export the user roster with email and role. This becomes the workspace member invitation list and the owner-mapping reference for Phase 3.
• Export pipeline stage definitions from the source. Capture the exact label and order of each stage. These become Twenty Opportunity Stage Select options.
• Capture screenshots and JSON exports of source automations and reports. Twenty workflows, views, dashboards, and permissions must be rebuilt manually. There is no migration path for these.

  Risk if skipped: Source automation logic lost forever once the source is decommissioned.

• Record the exact timestamp of every export. Stamp each file with the export time in ISO-8601 UTC. The delta between this timestamp and the cutover is what the Phase 5 final export must cover.

Phase 3

Transform & Map

Convert raw source exports into Twenty-shaped files, ready for import.

Phase 4

Sandbox Test Migration

Catch every problem in the sandbox before it costs you in production.

• Load a 1–5% representative sample of each object into the sandbox workspace. Use the Command Menu (⋮ icon top right of any table view) → Import records. Choose the CSV, map columns to fields, review errors highlighted in yellow, fix inline, then confirm.

  Risk if skipped: Skipping a sample run hides issues that only surface on full-volume load.

• Validate field-by-field on 10 random sandbox records per object. Open each record in the UI and compare every field against the source export. Look especially at Select values, dates, currency, phone country code, and relations.
• Test long strings, special characters, and accented values. Include sample rows with em-dashes, smart quotes, non-Latin characters, and 500+ character text blobs. Confirm UTF-8 survives end-to-end.
• Test NULL and empty-string handling per field type. Confirm whether each field interprets blank as null, empty string, or rejects the row. Document the per-field behavior.
• Test date/time imports including timezone edge cases. Include UTC, local, and ambiguous near-midnight values. Confirm the workspace timezone setting affects display, not stored value.
• Test parent/child relation resolution. Confirm `companyDomain` on a People CSV resolves to the correct Company. Confirm Opportunity-to-Company and Opportunity-to-primary-contact links resolve.

  Risk if skipped: Relation resolution failures look like 'silent drops' — the row imports but the link is blank.

• Test junction-object many-to-many import. Upload the junction CSV and confirm both sides appear in the linked-records view of each parent record.
• Test re-importing the same file to confirm upsert behavior. Run the same CSV twice. Confirm the second run updates records rather than duplicating. Note: re-importing with previously defined IDs has historical issues (#13195) — use the unique field, not the id.

  Risk if skipped: Non-idempotent re-runs duplicate every record and force a Postgres-level cleanup.

• Test attachment upload via the chosen path. Upload a sample binary and confirm it attaches to the right parent record and renders correctly.
• Time each sandbox load and extrapolate to production volume. Multiply by the production row count and confirm the result fits inside the cutover window with margin.

  Risk if skipped: Cutover windows planned without a measured throughput baseline routinely overrun by 2-5x.

• Have a domain expert spot-check 20 random sandbox records. A sales ops or RevOps reviewer who knows the source data confirms records look right end-to-end in the Twenty UI.
• Get written sign-off on the sandbox results before proceeding. DRI plus one domain reviewer sign off in writing that the sandbox is acceptable.

  Risk if skipped: Production cutover without sandbox sign-off has no rollback gate.

Phase 5

Production Cutover

Execute the load in dependency order. Stop and fix on any failure.

• Confirm source-system freeze is in effect. Verify no writes in the last hour. Lock the source to read-only if possible.

  Risk if skipped: Late writes create a delta that never gets reconciled.

• Take the final delta export from the source. Re-run the Phase 2 exports as of the freeze timestamp. Diff against the Phase 2 baseline to identify changed rows.
• Confirm workflows are disabled in Twenty. Re-verify Settings → Workflows before loading.

  Risk if skipped: A workflow left on fires on every imported record.

• Load workspace members and confirm owner-email coverage. Every owner/assignee email in the import data must already exist as an invited member.
• Load Companies first. Companies have no upstream dependency. Per Twenty's docs, always import Companies before People before Opportunities.

  Risk if skipped: Loading People before Companies leaves company links unresolved.

• Load People with `companyDomain` relation column. Use the unique Company domain (formatted as `https://acme.com`) to wire each person to their employer.
• Load Opportunities with company and primary-contact relation columns. Resolve via Company domain and Person email respectively.
• Load custom-object records. After standard objects exist. Use external-ID custom fields as the relation key.
• Load Notes and Tasks with parent linkage columns. Reference the parent by Company domain, Person email, or Opportunity unique key.
• Load attachments last. Upload binaries and link to the parent record. Re-anchor Opportunity attachments to Company or Person per Phase 3 decision.
• Capture import job results, row counts, and error logs at every step. Save the per-step row count and any error CSV. This is the audit trail for Phase 6 reconciliation.

  Risk if skipped: Without per-step counts, mid-load failures cannot be diagnosed.

• Re-enable workflows only after all loads complete. Re-enable in the reverse order they were disabled. Confirm no spurious fires by watching the audit log.

Phase 6

Validate

Prove the load was correct before users get in.

Phase 7

Post-Migration Cleanup

Rebuild the configuration that does not migrate, decommission the source, close the project.

• Communicate go-live to all end users with login URL and help contact. Include the Twenty workspace URL, login mechanism (Google/Microsoft SSO or password), and the first-responder contact for issues.
• Run role-segmented training sessions on Twenty basics. Sales reps, sales ops, RevOps, and admins each get a session tailored to their daily tasks.
• Rebuild Views, filters, and Kanban boards. Twenty's docs are explicit: Views must be recreated manually after migration. Catalog the source views and rebuild one per role.

  Risk if skipped: Without saved views, users default to flat tables and adoption drops.

• Rebuild Workflows in Settings → Workflows. Twenty's workflow engine is still maturing. Start with the most critical automations. Test each in a sandbox workspace before enabling in production.
• Rebuild Permissions and Roles. Configure object-, record-, and field-level permissions per role. Permissions do not transfer from the source.

  Risk if skipped: Default permissions may expose sensitive fields to all members.

• Connect Gmail/Outlook sync per user. Settings → Accounts → Add account. Each user authorizes their own mailbox. Configure auto-creation and message visibility per user.
• Reconfigure integrations to other systems. Slack, Notion, calendar sync, BI tools, etc. Each integration must be reconfigured against the Twenty workspace and tested.
• Set the source system to read-only. Announce the read-only date. Disable all user write paths. Keep read access for the retention window.
• Archive source-system exports to long-term storage. Keep the Phase 2 and Phase 5 export bundles encrypted in long-term storage for any future forensic need.

  Risk if skipped: Source data lost from local disk before the retention window expires is unrecoverable.

• Schedule a 30-day post-migration retrospective. Capture what went well, what didn't, and what to change for the next migration. Document the lessons in the project record.
• Decide and document the source-system decommission date. Typically 90 days after cutover, after the final retention window. Get sign-off from finance, legal, and IT.
• Plan and schedule a Twenty version upgrade cadence. Twenty is actively developed with frequent releases. Pin a quarterly upgrade review, test each version in a sandbox workspace, and check release notes for breaking changes.

  Risk if skipped: Skipping upgrades for a year compounds breaking changes and makes the next upgrade a multi-week project.

• Close out the migration project formally. Final status report, lessons learned, project closure with sponsor sign-off.