> ## 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.

# Operate migration jobs from Settings → Migrations: retry, cancel, roll back

> The operator loop for the Settings → Migrations console: read a job's real status, recover a failed or stuck migration with cancel → retry or cancel → roll back, and capture the job id and request id as escalation evidence.

# 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](/guides/platform-migration-jobs) walks connect → preview → run, and [run a migration from Settings → Migrations](/guides/audience-migrations-console) 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](/guides/migration-jobs-operations) covers the post-run cancel/rollback lifecycle in depth, and [platform migration jobs](/guides/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](/guides/import-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

* [Run a platform migration end-to-end](/guides/platform-migration-jobs) — the wizard sequence: connect, dry-run preview, live progress, and the API equivalents
* [Migration jobs operations](/guides/migration-jobs-operations) — the post-run cancel/rollback lifecycle in depth, with the REST and SDK walkthrough
* [Run a migration from Settings → Migrations](/guides/audience-migrations-console) — the full operator walkthrough of the console, from connector selection through the lifecycle
* [Assisted import wizard](/guides/assisted-import-wizard) — the onboarding wizard walkthrough for Twilio, Telnyx, Klaviyo, and MessageBird
* [Migrate from Twilio](/guides/migration-from-twilio) — the concept mapping (numbers, messaging services, TwiML, webhooks) for the most common source
* [Migrate from enterprise CCaaS](/guides/migrate-from-enterprise-ccaas) — the phased runbook for contact-center suites (Genesys, Talkdesk, Five9, NICE CXone)
* [Troubleshooting: contact imports](/troubleshooting/import-jobs) — per-error-code fixes for cancel, rollback, and queue failures