> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Migration

> Connect to external databases, configure field mappings, and run guided migrations into the platform at /settings/data-migration.

The Data Migration page (`/settings/data-migration`) provides a guided, multi-step workflow for importing data from external database sources, including connection management, source exploration, field mapping, and migration run history.

## Overview

The page is gated by `system.organizations.admin` at the route level and wrapped in a `RouteErrorBoundary`. It uses a `MigrationStepper` component to guide the user through four sequential tabs: **Connections** (manage external DB connections via `useDataMigrationConnections`), **Explore** (browse the source database schema via `SourceExplorer`), **Mappings** (configure field-level mappings via `useDataMigrationMappings` and `MappingsTab`), and **Runs** (view past migration execution history via `useDataMigrationRuns` and `RunsTab`). The stepper tracks progress by whether connections, mappings, and runs exist.

## Who it's for

Requires permission `system.organizations.admin`.

## Before you start

* You must hold `system.organizations.admin`.
* External database credentials must be available before adding a connection.
* Review field mapping requirements with your data team before running a migration.

## Steps

<Steps>
  <Step title="Open Data Migration">
    Navigate to `/settings/data-migration`. The stepper shows the current progress across all four stages.
  </Step>

  <Step title="Add a connection">
    On the **Connections** tab, add one or more external database connections.
  </Step>

  <Step title="Explore the source">
    Switch to **Explore** to browse the source database tables and columns. This helps plan your mappings.
  </Step>

  <Step title="Configure mappings">
    On the **Mappings** tab, define how source fields map to target fields in the platform.
  </Step>

  <Step title="Run the migration">
    On the **Runs** tab, initiate a migration run. History of all runs and their outcomes appears here.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Stepper state">
    The `MigrationStepper` tracks whether `hasConnections`, `hasMappings`, and `hasRuns` are true and visually indicates progress through the workflow.
  </Accordion>

  <Accordion title="RouteErrorBoundary">
    This route is wrapped in a `RouteErrorBoundary` scoped to the `settings` module, so unhandled errors during migration operations display a contained error UI rather than crashing the full page.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Platform Foundation" icon="layer-group" href="/pf/overview">
    Platform Foundation overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/platform.tsx
  * src/platform/settings/pages/data-migration/DataMigrationPage.tsx
  * src/platform/settings/pages/data-migration/hooks/useDataMigrationConnections.ts
</Accordion>