Skip to main content

​
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 is the decision triage between a CSV import and a connector, run a platform migration end-to-end is the wizard narrative, migration jobs operations covers post-run cancel and rollback, and import and migration lifecycle 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 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: 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 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. 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

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

​
See also