Skip to main content

Migrate into Atlan without lifting-and-shifting

Connect docs via MCP

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.

ComponentWhat it coversTreatment
Technical assets & lineageTables, columns, schemas, and the data-flow between themDon't migrate. Connectors crawl the source to recreate assets; miners regenerate lineage. Migrating these wastes effort and conflicts with autogenerated lineage.
Business glossaryTerms, categories, and the vocabulary structure your business authoredMigrate selectively. Bring over genuine business terms and their descriptions; rebuild the structure clean rather than copying it.
Asset enrichmentHuman descriptions, tags, custom fields, and ownership authored on assetsMigrate 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 structureTechnical asset inventory (connectors crawl it)
Human descriptions and enrichmentAutomated lineage (miners regenerate it; static copies go stale)
Custom fields that users still rely onStale, 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 assignmentsReporting 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​