Skip to main content

​
Operate migration jobs from Settings → Migrations

Settings → Migrations in the dashboard is the durable console for every platform-migration job your organization has run — the place you return to after the onboarding wizard closes. This guide is the operator loop for that console: how to read a job’s real status, the recovery sequences (retry versus roll back — Orbit itself has no pause), and what to capture when you escalate. The end-to-end wizard narrative and per-job detail are covered elsewhere: run a platform migration end-to-end walks connect → preview → run, and run a migration from Settings → Migrations is the full console walkthrough from connector selection through lifecycle. Start here when the question is “a job is on the board and I need to act on it.”

​
1. Where the page lives

Open it from the dashboard sidebar: Settings → Migrations. Every role with settings access can open the page and read the job list. The destructive half of the console is role-gated: owner and admin roles see the Roll back action, and other roles never get the button. Cancel is not role-gated — anyone who can see the list can stop a job that is still in flight, and the server enforces the same split, so a member never sees a button the API would reject. Two neighbouring guides frame what happens before this console matters: migration jobs operations covers the post-run cancel/rollback lifecycle in depth, and platform migration jobs covers the wizard sequence that puts a job on the board. This guide is the middle of the loop: the job exists, it may not be going well, and the console is where you deal with it.

​
2. Read the board

Each row is one persisted migration job, with a source label (Twilio, Telnyx, Klaviyo, MessageBird, or Front), a status badge, the start time in your timezone, and — after a rollback — a rolled-back marker. The list is not a live feed: it loads on page open and refreshes when you click Refresh. If you take an action on another device or a teammate changed a job, the board is stale until you refresh. The status is the decision input, and the only mistake the console cannot protect you from is acting against a stale one:
  • Queued — the worker has not picked the job up yet. Allow a few minutes before you treat this as stuck.
  • Running — actively pulling entities and writing to your tenant.
  • Completed — terminal; everything the scope selected landed.
  • Failed — terminal; the worker stopped with the failure recorded. Treat a failed job as partially migrated — anything imported before the stop stays.
  • Cancelled — terminal; an operator stopped the job at a checkpoint. Also partially migrated, by choice.
Statuses beyond Queued and Running are terminal — the job never moves again. Cancel on a terminal row comes back as a conflict (“already finished,” not a system failure), and roll back on an in-flight row is refused until the job settles. Matching the action to the actual state is the whole discipline.

​
3. The recovery loop

Recover a failed or stuck migration with one of three sequences. Decide which before you click anything:

​
A. Retry — the normal recovery

Cancel what is in flight if anything is, re-run the wizard over the same connector, and let the new job’s duplicate policy (skip / overwrite / merge, set at preview) reconcile against what the failed job already wrote. Prefer this when the job stopped because the upstream account was stale, a credential expired, or the chosen scope was wrong — you want the data, delivered correctly. There is no in-place re-run or per-step “retry failed rows” on the console itself: retry is a fresh job over the same connection. For CSV contact imports, failed rows do come back as a downloadable skipped-rows report you fix and re-submit — that recovery path is documented in import and reconcile contacts. To retry from the console:
  1. Click Refresh and confirm the failed job is terminal (Failed or Cancelled). If anything from the same source is still running, cancel it first (see sequence B) and wait for it to settle — two overlapping jobs over one connection double the conflict surface.
  2. Restart the wizard from the row’s Start a migration entry point (the empty state and the provider-migration hub on Settings → Integrations link there), reconnect, and run a new preview — a fresh job always re-runs the pre-flight, so a fixed upstream shows up in the preview counts before anything writes again.
  3. Set the duplicate policy for the re-run deliberately: the failed job’s partial data is what the new job collides with, and the policy decides who wins each collision.

​
B. Cancel — stop the bleeding first

Cancel is the first move whenever something is going wrong mid-run: wrong scope, stale upstream, a migration you meant to stop. The console gates it behind a confirm dialog, and the semantics matter:
  • The worker stops at the next safe checkpoint between batches — clean, never torn mid-batch.
  • Already-imported data stays. Cancel decides nothing about past work; it stops future work.
  • The job ends in Cancelled and is not resumable — sequence A is the only way forward.
A cancel that comes back as a conflict means the job finished in the meantime; refresh and read the state it actually reached.

​
C. Roll back — reverse a landed migration (owner/admin)

Rolling back deletes precisely the contacts that job created — reversibility is by job id, not a tenant rewind. Reach for it when a migration landed wrong and you want the imported data gone before re-running, or when the migration was exploratory and should not stand. It is permanent, the confirm dialog says exactly what it destroys, and the scope is narrow: contacts the job created are removed, pre-existing contacts the job merely updated are untouched, and non-contact configuration (routing, channel settings) is out of scope. A job rolls back once — a second attempt is rejected, and the rolled-back marker plus the removed count confirm the first one landed. The safe recovery scripts, composed:
  • Failed before it wrote much → sequence A. Cancel if needed, re-run, done.
  • Landed wrong and you want it out → cancel to terminal (if needed), roll back, then sequence A from a clean slate.
  • Stuck queued for minutes → cancel, refresh, sequence A. A queued job that never starts running is a worker-pickup problem, and the ticket evidence below is what support needs if retry also hangs.

​
4. Export escalation evidence

When a job stays stuck across a cancel-and-retry, support replay is one lookup if you bring the identifiers instead of a narrative. Capture, from the console itself:
  1. The job’s imp_… id. Take it from the network request the console makes (browser developer tools → the GET /imports response lists every row’s id) or from GET /imports over the API — it is the only key a job is found by.
  2. The exact status observed — the badge text and when you saw it.
  3. The meta.request_id from any failing API call — the standard response envelope carries it, and support replays the request’s exact state from that id.
  4. The sequence already attempted — “cancelled, waited for terminal, re-ran wizard, new job is also stuck queued” tells support the retry loop is exhausted.
Sequence A/B/C before the ticket means most jobs never become tickets — this section is for the ones that do.

​
See also