## Migrate into Atlan without lifting-and-shifting

URL: https://docs.atlan.com/get-started/best-practices/migrate-into-atlan

> How to scope, sequence, and validate a migration from a legacy catalog so you rebuild your metadata foundation instead of copying old clutter.

# Migrate into Atlan without lifting-and-shifting

The single biggest decision in any migration is what *not* to migrate. Atlan connectors re-crawl your source systems to recreate tables, columns, and lineage directly—so the bulk of a legacy catalog doesn't need to move. Treat migration as **lift-and-curate, not lift-and-shift**: re-crawl technical assets and regenerate lineage from source, and migrate only the authored content that a human created and a connector can't reproduce. In practice this means roughly 70–80% of a legacy estate is regenerated, not migrated. Use the move as the moment to *correct* weak structures (domains, glossary, ownership) rather than reproduce them—think of it as designing your Atlan deployment from scratch, not porting your old tool.

## When to use what

Every legacy-catalog migration decomposes into exactly three components. Decide the treatment for each before touching a script.

| Component | What it covers | Treatment |
|---|---|---|
| **Technical assets & lineage** | Tables, columns, schemas, and the data-flow between them | **Don't migrate.** Connectors crawl the source to recreate assets; miners regenerate lineage. Migrating these wastes effort and conflicts with autogenerated lineage. |
| **Business glossary** | Terms, categories, and the vocabulary structure your business authored | **Migrate selectively.** Bring over genuine business terms and their descriptions; rebuild the structure clean rather than copying it. |
| **Asset enrichment** | Human descriptions, tags, custom fields, and ownership authored on assets | **Migrate on top of crawled assets.** Enrichment binds to assets that already exist, so it loads after the crawl. |

The technical-asset component is the scope reducer: because lineage is regenerated from source, only glossary and authored enrichment require active migration work.

**Legacy-catalog vs. Atlan-to-Atlan migration.** The three-component decomposition described earlier applies to migrating off a legacy catalog. Moving between Atlan environments (for example promoting from a lower environment to production, or consolidating tenants after an acquisition) is a different problem: technical assets and lineage are still best regenerated by pointing connectors at the source in the target environment, but the key gotcha is that qualified names are environment-specific. A raw export and re-import carries qualified names that don't resolve in the target and creates orphaned assets, so plan to remap qualified names to the target environment's identifiers before importing—see the migration-tooling documentation for how the cross-environment packages handle this.

### What migrates vs. what regenerates

| Migrate (selective, authored) | Regenerate or leave behind |
|---|---|
| Business terms and glossary structure | Technical asset inventory (connectors crawl it) |
| Human descriptions and enrichment | Automated lineage (miners regenerate it; static copies go stale) |
| Custom fields that users still rely on | Stale, duplicated, or unused datasets |
| Curated lineage that genuinely can't autoregenerate (for example, lineage between systems Atlan doesn't connect natively) | Low-value or dormant workflows and communities |
| Steward and owner assignments | Reporting counters and KPI tallies (re-derive them dynamically) |

## Design target model

Design the target model **before** you script anything. Writing ingestion logic against an undecided model guarantees rework.

1. **Frame the program and design the model (week 1).** Confirm the first wave's in-scope domains and your deployment pattern. Run a model-design sprint now: glossary standards, persona and role design, connection topology, and your custom-metadata schema. Start long-lead items immediately—SSO/identity setup, security review, and AI-governance approval take weeks to months and silently block go-live.
2. **Assess the legacy estate and challenge the scope.** Export an inventory including *usage telemetry*, then run a data-driven content analysis: what's actually used vs. dormant, high-value vs. noise. This is the step teams most often skip—and skipping it recreates the old clutter (your legacy catalog 2.0). Make your governance team decide what's still valuable; the default of "migrate everything" is what you're guarding against. Keep the decision rights explicit throughout: the hands-on migration work can be delegated, but *your* team decides scope, what "good" looks like, and when it's done. If the legacy metamodel is heavily customized (category-scoped metadata, complex ontologies), run a metamodel audit early—map complex constructs in simplified form, or agree explicitly that they stay in documents or downstream tools.
3. **Lock the future operating model and mapping.** Design the domain structure, glossary structure (global vs. local terms), and a *simplified* steward/approval model. Complete the mapping workbook and get formal sign-off on the field mapping before proceeding.
4. **Connect sources and crawl.** Stand up the tenant, connect priority sources, and crawl to populate technical assets. Miners regenerate lineage. Validate lineage on a sample of assets. The crawl track and the enrichment-prep track run **in parallel**, but the enrichment *load* is gated on assets existing first.
5. **Seed the glossary, then enrich assets.** Bring the curated business terms in, then apply authored descriptions, tags, owners, and custom fields on top of the crawled assets. **Never run a full import as your first test**: a full import is difficult to reverse, so test a small batch (5–10 assets) in a lower environment, then stage in batches and validate each batch. Migrate in waves—glossary, then curated assets, then remaining content—validating each wave.
6. **Validate iteratively.** Budget for multiple validate → remediate → re-validate loops, not a single pass. Check count and relationship parity against the source, run stratified spot-checks, and do a deep-dive on any regulatory or high-stakes lineage paths—visual spot-checks miss silent partial failures. Get per-domain sign-off.
7. **Run parallel and cut over per domain.** Take the legacy tool read-only per slice once parity, adoption, and sign-off are met for that domain. Plan for at least two import cycles: an initial bulk load plus a delta at cutover. Never ask data owners to maintain two systems at once—guarantee a single source of truth at every point.
8. **Resource adoption as its own workstream.** Change management, persona enablement, and embedding Atlan in the flow of work are what prevent another shelfware catalog. Assign a named owner for this track, plan it alongside the technical workstreams from week 1, and treat adoption milestones as first-class go/no-go criteria alongside parity and sign-off.

### Plan rollout

If a legacy contract expiry or exec review sets a fixed cutover date, split "done" into two definitions and run them as parallel tracks:

- **Technical continuity**: all connectors live, users provisioned with access, assets visible. This is the cutover-date objective.
- **Business rollout**: training complete, users productive, workflows active. This is a 4–6 week *trailing* milestone.

State the split explicitly so leadership doesn't read "users not fully trained on cutover day" as failure. Under time pressure, front-load the connector track and defer governance workflows entirely to post-cutover. Also run a **Plan A / Plan B** structure so go-live is never blocked on approval cycles: Plan A is the ideal native-connector path; Plan B stands up the same assets via a generic or custom connection with imported lineage that meets the minimum business-continuity bar. When you build an interim connection, **match the naming conventions the native connector produces** so the later switch is a clean swap rather than a rebuild.

## Common pitfalls

- **Lift-and-shift / one-to-one port** of legacy structure, terminology, and custom assets. Recreates the old mess and burns months. Redesign domains and glossary structure clean instead.
- **Migrating static lineage** instead of regenerating it from connectors. It goes stale the moment a pipeline changes. Flag static-lineage migration as a *risk item, not a deliverable*.
- **Scripting before the model is locked** (connection topology, custom-metadata schema, glossary standards). Guarantees rework.
- **Bulk-importing every legacy glossary entry as a term** without triage. Technical column descriptors pollute the glossary—route those to column descriptions or READMEs, and promote only genuine business terms. Run a glossary-standards workshop first to define what qualifies as a real business term.
- **Autoresolving ownership conflicts.** When multiple legacy connectors indexed the same physical table with different owners, they collapse and conflict in Atlan. Don't automerge or take first-wins: pause ownership migration, proceed with the fields that agree, produce a reviewable list of conflicts grouped by asset, and let *your* team name the authoritative source (often resolvable at schema level).
- **Blocking migration on perfect ownership.** For departed employees, substitute the current team lead or a named admin group; for unknown accounts, assign a visible, reversible placeholder that signals the asset needs triage. Don't wait.
- **Treating a runtime dependency as a training topic.** If a downstream service reads from the legacy system at runtime (for example, a masking or subject-access pipeline), that's a hard cutover dependency—surface it in discovery and block cutover on its adaptation, don't leave it for enablement.
- **Deprioritizing identity setup as "nice to have."** SSO/identity lead time is fixed; start the tickets the day migration begins and use interim login in the meantime.
- **Overwrite anxiety left unaddressed.** Raise proactively with governance-anxious teams that AI-assisted enrichment fills blanks rather than overwrites human-authored content—that explanation is usually the reassurance they need. Confirm the exact behavior in the Atlan enrichment/AI documentation before committing it to governance stakeholders.
- **Treating users' prior-catalog experience as a threat.** Teams arriving from a competing catalog bring real expertise—treat it as an asset. But don't skip the Atlan mental-model orientation on the assumption that "they know catalogs," and don't restart scoping from scratch either: orient them on where the models differ, then continue.

## See also

- Field mapping decisions, object-level mapping, and troubleshooting: [migration mapping reference](https://docs.atlan.com/llms/platform/get-started/migration-mapping-reference/llms.txt).
- Connector scoping, crawl filters, and why lineage is missing or partial: [connector & ingestion best practices](https://docs.atlan.com/llms/catalog/connector-capabilities/plan-connectors-and-ingestion/llms.txt).
- How lineage is generated per source, and impact analysis: [lineage best practices](https://docs.atlan.com/llms/catalog/lineage/capture-and-troubleshoot-lineage/llms.txt).
- Glossary and taxonomy structure, and metric definitions: [glossary & taxonomy best practices](https://docs.atlan.com/llms/governance/glossary/structure-glossary-and-metrics/llms.txt).
- Sequencing the overall implementation and running the parallel migration track: [implementation & rollout best practices](https://docs.atlan.com/llms/platform/get-started/plan-your-rollout/llms.txt).
- Migration utility mechanics, bulk-import formats, and cross-environment packages—Atlan product and migration-tooling documentation.

---