> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a platform migration end-to-end: wizard, Migrations page, cancel, rollback

> Move from Twilio, Telnyx, Klaviyo, MessageBird, or Front using the import wizard, then monitor, cancel, and roll back jobs from Settings → Migrations.

# 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](/guides/migration-from-twilio) and [migrate from an enterprise CCaaS](/guides/migrate-from-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](/guides/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

* [Migrate from Twilio](/guides/migration-from-twilio) — concept mapping (numbers, messaging services, TwiML, webhooks) plus the CLI-driven import option
* [Migrate from an enterprise CCaaS](/guides/migrate-from-enterprise-ccaas) — the same mapping exercise for Genesys, Five9, NICE, and Talkdesk
* [Import and reconcile contacts](/guides/import-contacts) — the CSV path for sources without a connector
* [Opt-out lists](/guides/opt-out-lists) — consent enforcement that applies to migrated contacts exactly as it does to any other audience