Skip to main content

​
Monitor, cancel, and roll back platform migrations

The import wizard carries you from connect to run, but the wizard’s progress view is the only screen that exists while onboarding is open. Once you close it, the durable operations surface for migration jobs is Settings → Migrations in the dashboard. This page lists every platform-migration job your organization has run and is where you cancel a migration that is going wrong or roll back one that already landed. The full wizard walkthrough lives in run a platform migration end-to-end; this guide is the operations half of the lifecycle. Open it from the dashboard sidebar: Settings → Migrations.

​
1. What the page lists

Each row is one persisted migration job for your organization, showing:
  • Source — the platform the job pulled from: Twilio, Telnyx, Klaviyo, MessageBird, or Front.
  • Status — the job’s current state in the lifecycle (pending, running, succeeded, failed, cancelled).
  • Started — when the job began, in your timezone. After a rollback, the row also shows a “rolled back” marker so you can tell a reverted migration apart from one that still stands.
The list refreshes on demand via the Refresh button, and each row exposes up to two actions — Cancel and Roll back — gated by the job’s state and your role.

​
2. Status and what each state allows

Migration jobs follow the same state machine the troubleshooting table documents: Terminal means the job never moves again. Three consequences fall out of that:
  • Cancel is only offered on pending and running rows. Asking to cancel a terminal job comes back as a conflict — read it as “already finished,” not as a failure.
  • Rolling back a job that is still in flight is refused — cancel it, wait for it to settle into a terminal state, then roll back.
  • Run rollback promptly. The rollback window for import jobs is 24 hours after the job finished; past that, remove leftover rows with a targeted bulk delete instead of a job-level rollback. A job that was already rolled back is rejected as already done — second attempts are safe but change nothing, and the row’s rolled-back marker tells you the first one landed.

​
3. Cancel a running migration

Useful when the job is importing the wrong scope, or the upstream account turned out to be stale.
  1. On the job’s row, click Cancel.
  2. Read the confirm dialog — it states the outcome — and confirm with Cancel migration. Use Keep running to back out.
Cancel is best-effort: the worker flips the job to cancelled the next time it reaches a safe checkpoint between batches, so the stop is clean rather than mid-batch. What the semantics mean in practice:
  • Already-imported data stays. Cancel stops future work; it does not undo past work. Your workspace may be partially migrated.
  • The job ends in cancelled, a terminal state — you cannot resume it. Re-run the wizard to restart.
  • Rollback remains available after the cancel lands, so the full reversal is cancel → wait for the terminal state → roll back.
If cancel refuses because the job finished in the meantime, the confirm error tells you the job’s actual status — refresh and the row shows its final state.

​
4. Roll back a finished migration

Rollback is restricted to the owner or admin role; other roles see the job list but never get the button.
  1. On a terminal job’s row, click Roll back.
  2. Read the confirm dialog — rollback permanently deletes every contact this job created — and confirm.
Scope worth knowing before you confirm:
  • Contacts the job created are deleted. The success toast reports how many rows were removed.
  • Pre-existing contacts the job merely updated are untouched — rollback never destroys data that existed before the migration.
  • Imported non-contact configuration (imported routing, channel settings) is out of rollback’s scope and stays.
  • A job rolls back once. After a successful rollback the row carries the rolled-back marker and the count, and a second attempt is rejected — there is nothing left to remove.
If rollback refuses with “still running,” the job has not finished settling — wait for the status to go terminal. If it refuses with “already rolled back,” someone on your team got there first.

​
5. Platform migrations vs contact CSV imports

Both show up under “import jobs,” but they are different lifecycles:
  • Platform migration (this page) — Orbit pulls contacts and platform configuration over an authenticated connection to Twilio, Telnyx, Klaviyo, MessageBird, or Front. Jobs appear on Settings → Migrations. Run one from the provider-migration hub on Settings → Integrations, or from onboarding.
  • Contact CSV import — you upload a shaped file of rows over the API or from Audience → Imports. Jobs appear on the contacts import history, not here. See import and reconcile contacts.
The two paths share the underlying state machine and the same cancel/rollback vocabulary — one model, two entry points — which is documented on the import and migration lifecycle concept page. The per-error decisions (IMPORT_NOT_CANCELLABLE, IMPORT_STILL_RUNNING, ALREADY_ROLLED_BACK, queue unavailability) live in troubleshooting: contact imports.

​
6. When to escalate

Most Migrations-page problems resolve locally — refresh the list, read the job’s live status, match your action to the state table above. Escalate when:
  • a job sits in pending for more than a few minutes (the worker should pick it up almost immediately),
  • a running job stops advancing and cancel does not move it to cancelled,
  • cancel or rollback keeps returning conflicts after a refresh, or
  • a rollback completed but you suspect imported contacts remain.
When you open a ticket, include:
  1. Your organization / tenant id — visible in the dashboard URL and on Settings → Organization.
  2. The job id — the imp_… identifier for the migration (shown on the API response for the job list; quote it when you contact support).
  3. The response’s meta.request_id for any failing API call — support can replay the exact state of the request from that id.
With those three, support replay is one lookup instead of a reconstruction.

​
See also