Skip to main content

​
Run a platform migration end-to-end

This guide walks the full lifecycle of a platform-to-platform migration job: starting it in the import wizard, watching it run, managing it afterward from Settings → Migrations, rolling back a bad run, and verifying the result. It covers the operational side — the concept mapping for each source platform lives in migrate from Twilio and migrate from an enterprise CCaaS. A platform migration ports configuration from your old provider into Orbit — contacts, and the platform-specific objects the source exposes (for example, Twilio messaging services, Telnyx routing configuration, Klaviyo profiles, MessageBird or Front channel connections). The supported sources are Twilio, Telnyx, Klaviyo, MessageBird, and Front. The old platform keeps serving traffic as usual; cutover happens when you redirect your own integration, not as part of the job.

​
Platform migration vs CSV import

Two import paths exist, and they overlap only in how they land contacts:
  • Platform migration (this guide) — Orbit connects to the source platform with a credential you provide and pulls both contacts and platform configuration over an authenticated connection. Use it when you are leaving a supported provider.
  • CSV import — you shaped the export yourself and upload rows. Use it when the source is a generic file (a CRM export, a spreadsheet, a provider Orbit does not have a connector for). See import contacts.
When the source is one of the five supported platforms, prefer the migration path: the wizard validates the credential and shows a dry-run preview before anything is written.

​
1. Start the migration in the import wizard

From the onboarding flow — or later from the import entry points in the dashboard — open the wizard for your source (/import/twilio, /import/telnyx, /import/klaviyo, /import/messagebird). The five steps are the same shape for every source:
  1. Connect — paste a read-only credential (for example, a Twilio Account SID and Auth Token). OAuth-based sources redirect you back into the wizard automatically.
  2. Choose the import scope — which entities to pull (contacts, configuration objects, conversation history where the source supports it).
  3. Dry-run preview — the wizard calls the preview endpoint and shows counts per entity, an ETA, and known conflicts, before anything is written. Read this screen; it is the last free checkpoint.
  4. Review and commit — confirm the selections and start the job.
  5. Live run — the final step streams progress from the server-sent events feed keyed by the job id, with a polling fallback if the stream drops. Per-entity progress updates in place until the job reaches succeeded, failed, or cancelled.
On the run step you can leave the page — the job continues in the background, and the wizard state is URL-encoded, so a refresh or a reopened link picks the same job back up.

​
2. Manage jobs from Settings → Migrations

The wizard’s run view is ephemeral. Once onboarding is over, the durable surface for migration jobs is Settings → Migrations in the dashboard. It lists every migration job your organization has run, with:
  • the source platform (Twilio, Telnyx, Klaviyo, MessageBird, Front),
  • the current status — pending, running, succeeded, failed, or cancelled,
  • when the job started and finished, and its failure reason when it ended as failed,
  • rollback state — whether it was rolled back, when, and how many contacts the rollback removed.
From the list you can act on a job:
  • Cancel a job that is still pending or running. The worker checks the cancellation flag between pages, so it stops cleanly rather than mid-batch. Rows already imported stay imported.
  • Roll back a finished job (finished means succeeded, failed, or cancelled). This requires the owner or admin role.
The same page and the same actions are available over the API — GET /imports to list jobs, POST /imports/:jobId/cancel, POST /imports/:jobId/rollback — so an operator without dashboard access can hand the job id to someone who scripts instead.

​
3. What rollback means

Rollback deletes the contacts that this job created, in a single transaction, and records the removal count on the job (visible as the rollback count in the Migrations list). That is deliberately narrower than the job’s whole output:
  • Contacts a migration job creates are removed.
  • Contacts that already existed in Orbit and were only updated by the run keep their records — rollback never destroys pre-existing data.
  • Imported platform configuration that is not contact-shaped (for example, imported routing or channel settings) is not removed — rollback covers contacts only.
A job that is still running cannot be rolled back — cancel it first, let it settle, then roll back. The API returns a conflict when the job is still in-flight or was already rolled back.

​
4. Verify, then re-run if needed

After a job succeeds, verify before you cut traffic over:
  1. Spot-check in the dashboard — open the audience or the relevant settings surface and confirm the imported entities look right (contact fields, imported configuration).
  2. Check the failure detail — a failed job carries a failureReason on the Migrations list; a job that ended succeeded may still have skipped per-entity items if the source refused them.
  3. Re-run safely — re-running the wizard for the same source creates a new job over the same data. Where the conflict policy is offered (skip, overwrite, or merge per entity), pick it deliberately: skip leaves already-imported rows alone, overwrite replaces them, merge combines. For contacts specifically, an existing record wins under skip and is updated under merge/overwrite.
If a run went wrong, the safe sequence is: cancel (if still running) → roll back → fix the source or the selection → re-run.

​
5. Troubleshooting

  • Job stuck in pending. The worker may be saturated with other jobs; give it a few minutes, then cancel and re-run if it never picks up.
  • Job stuck in running with no progress. Open the Migrations page from a fresh session — the list polls independently of any stale wizard tab. If it truly never advances, cancel it and re-run; a cancelled run is cleaned by rollback.
  • Partial rows after a failed or cancelled run. What landed, landed. Roll back the job to remove created contacts, then re-run once the cause is fixed.
  • Cancel or rollback returns a conflict. The job moved between your last read and the action — check its current status first. Rollback on a still-running job, and cancel on an already-terminal job, are both rejected.
  • Rollback is not offered on the dashboard button. Rollback is restricted to the owner or admin role; a member sees the jobs but cannot roll them back.
  • The wizard’s progress stream disconnects. The run step falls back to polling the job endpoint, and Settings → Migrations shows the same status independently — the job itself is unaffected.

​
See also