> ## 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 migration from Settings → Migrations: the full operator walkthrough

> The operating guide for migration jobs on the Settings → Migrations console: who sees it, the pre-flight checks the job runs before it writes, the queued → running → partial-success/failed lifecycle with re-submission, pause/resume semantics, rollback by contact-delete, and a per-symptom troubleshooting table.

# Run a migration from Settings → Migrations

**Settings → Migrations** in the dashboard is the entry point for migration work in Orbit, and it is more than a job-history table: it is the console that walks you from connector selection through commit and the live lifecycle. This page is the operating guide for that console — the other pages it links to cover one layer each. [Import or migrate contacts](/guides/import-and-migrate-contacts) is the decision triage between a CSV import and a connector, [run a platform migration end-to-end](/guides/platform-migration-jobs) is the wizard narrative, [migration jobs operations](/guides/migration-jobs-operations) covers post-run cancel and rollback, and [import and migration lifecycle](/concepts/imports-migration-model) is the data-plane model underneath all of it.

## 1. What the console surfaces, and who sees it

Open it from the dashboard sidebar: **Settings → Migrations**. The page exposes the migration wizard — the same five-step flow you met in onboarding — for all five supported sources, alongside the running-history list, so starting a job and re-entering one in flight share one surface.

* **Visibility.** Owner and admin roles see the wizard and every job row; rollback is restricted to owner/admin (see section 5). Members with read access see the history list.
* **Why it exists alongside the API.** The wizard is an operator surface over the `GET /imports` route group — connect, preview, run, progress, cancel, rollback — so humans run the lifecycle without scripting. Nothing the wizard does is privileged: every step round-trips through the same public endpoints the [Imports API reference](/api-reference/imports) documents, and a script can replay any of them.

## 2. Pre-flight checks before a commit

The wizard's preview step runs the job's checks against the upstream account *before* anything is written. Each check below is named because the *skip/overwrite/merge* policy you set here decides what commit does to it — a check is not a formality:

* **Field-type compatibility.** Each entity kind in the scope is mapped onto the target model, and fields that do not map cleanly (an untyped text value against a strictly-typed custom field) are flagged in the preview rather than rejected mid-run.
* **Duplicate handling policy.** Collisions the checker already sees — a phone number already claimed in your pool, a contact that matches one in your tenant — are listed upfront, and you set the policy per entity kind: **skip** (leave your record), **overwrite** (replace it), or **merge** (combine fields).
* **Per-field preview.** The dry-run response carries per-entity counts, the full conflict list, and a deliberately pessimistic ETA, so the commit screen is a read decision, not a blind one.

Run preview as many times as you need; it never writes, and it is timestamped so a stale upstream can be re-projected.

## 3. The job lifecycle

A confirmed run moves through one persisted job with a single status:

| Status            | Meaning                                                                   |
| ----------------- | ------------------------------------------------------------------------- |
| `pending`         | Queued; the worker has not picked it up.                                  |
| `running`         | Actively pulling entities and writing to your tenant.                     |
| `succeeded`       | Terminal — all selected entity kinds finished.                            |
| `partial success` | Terminal — some rows skipped or failed; see the re-submission note below. |
| `failed`          | Terminal — the worker stopped with a failure reason recorded.             |
| `cancelled`       | Terminal — an operator stopped it at a checkpoint.                        |

**Re-submitting partial success.** A partially-successful job's skipped and failed rows are not lost — the conflict/error list on the finished job carries the per-row reason, so you fix the class (bad columns, suppression conflict, an untyped field) and re-run those rows. The conflict policy you chose at pre-flight applies again on the retry. For CSV contact imports, the skipped rows land as a downloadable report; the platform migration path returns them in the job's conflict list. See [import and reconcile contacts](/guides/import-contacts) for CSV specifics.

Statuses beyond `pending` and `running` are terminal; cancel is rejected on a terminal job as a conflict, and a rollback on an in-flight job is refused until it settles.

## 4. Pause and cancel semantics

Orbit has no "pause" — the verb is **cancel**, and understanding what cancel does and does not guarantee is the point of this section. A job's `pending` or `running` state accepts a cancel; the worker flips it to `cancelled` at the next safe checkpoint between batches, never mid-batch. Concretely:

* Cancel **stops future work** — it does not undo past work. Your workspace may be partially migrated.
* Cancel does **not block the rollback path** — the now-terminal `cancelled` job still qualifies for rollback (see section 5).
* A cancelled job is **not resumable** — restart it by re-running the wizard (and get a fresh pre-flight this time).

If a cancel refuses with "still final," the job reached terminal between your page render and your click; refresh and read the actual state.

## 5. Rollback

A completed import is reversible within its rollback window — **24 hours from when the job finished** — by a rollback that deletes precisely the contacts the job created. Every imported contact is stamped with the job id that created it, so rollback deletes **by import id**, not by sweeping the tenant. The data-plane contract this rests on — the state machine, the per-source entity kinds, the idempotent-conflict model — is [import and migration lifecycle](/concepts/imports-migration-model).

Rollback is restricted to **owner/admin** roles, and it is scope-bounded rather than tenant-rewinding:

* **Created contacts are deleted**, and pre-existing contacts the job merely *updated* are untouched — a rollback never destroys data that predated the migration.
* **Non-contact configuration** (routing objects, channel settings pulled from the source) is out of rollback's scope and stays.
* **A job rolls back once.** A second attempt is rejected as already done; the rolled-back row carries the marker and the count.

Outside the 24-hour window, the data is ordinary contact data: remove leftovers with a targeted bulk delete rather than a job-level rollback.

## 6. Troubleshooting

| Symptom                                 | Cause                                                                                     | Fix                                                                                            |
| --------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Job stuck in `pending` for minutes      | Queue saturation or worker unavailability                                                 | Poll; re-run cancel when the state allows; escalate if it persists                             |
| Partial success on a CSV import         | Row-level failures with per-row reasons                                                   | Download the skipped-rows report, fix the cause class, re-submit only the failed rows          |
| Suppressed-row surprise after import    | Duplicate-suppression policy conflict (skip/overwrite/merge did not do what you expected) | Re-check the policy you chose at pre-flight; the conflict list names each collision            |
| Field-type mismatch rejected in preview | Untyped text mapping onto a typed custom field                                            | Define or re-type the field in [custom fields](/guides/custom-fields), re-run the preview      |
| Large CSV times out / queue unavailable | The synchronous path caps at 10,000 rows; the async queue refused the enqueue             | For contact CSVs, fall back to `POST /contacts/bulk` under 10k rows or retry the async enqueue |
| Cancel or rollback returns `409`        | The job moved between render and click, or the window expired                             | Read `error.details.current_status`; refresh and act against the actual state                  |

The per-error-code fixes (cancel / rollback / queue / GDPR lifecycle errors) live in [troubleshooting: contact imports](/troubleshooting/import-jobs), and the broader failure-index page is [troubleshooting](/reference/troubleshooting).

## See also

* [Import or migrate contacts](/guides/import-and-migrate-contacts) — pick the right surface before you start: connector, CSV, or CDP profile ingest
* [Run a platform migration end-to-end](/guides/platform-migration-jobs) — the wizard narrative alongside this operator page
* [Migration jobs operations](/guides/migration-jobs-operations) — the cancel/rollback half of the lifecycle in depth
* [Import and migration lifecycle](/concepts/imports-migration-model) — the state machine and the rollback-by-import-id contract
* [Data model](/concepts/data-model) — where imported contacts, segments, and configuration objects land
* [Import and reconcile contacts](/guides/import-contacts) — the CSV-specific walkthrough for sources without a connector
* [Troubleshooting](/reference/troubleshooting) — the cross-surface failure index