Use Atlan platform well

||Connect docs via MCP

This guide is the approach layer for using Atlan—how to think about the platform, match the right mechanism to the job, and avoid the handful of missteps that generate most support tickets. It isn't the button-by-button UI reference; for where a specific setting lives or exactly what a feature supports today, use the Atlan product documentation.

Two facts shape almost every decision here:

• Atlan stores metadata, not data—there is no dev→prod code-promotion model. Most configuration (personas, glossary, tags, UI tuning) is done directly in production. A non-production environment has narrow valid uses (testing a connector against a source's dev tier; low-risk training), but running a full duplicate of your governance configuration across environments doubles the work and delays rollout. Don't treat Atlan like an application in a software-delivery lifecycle.
• What a user sees is shaped by their home and persona, not just what they can access. "Why can this user still see everything?" is usually a scoping question, not a bug.

When to use what

Naming the wrong mechanism is the most common failure. Match the job to the mechanism first, then execute.

You want to…	Reach for…	Notes
Bulk-edit metadata on assets that already exist (descriptions, certifications, tags, owners)	The Export/Import Assets flow	Edits existing assets only—it can't create new ones.
Create new glossary terms or categories at scale	The Bulk Upload flow	Creates new entries (and updates existing ones by name).
Turn on a gated feature	A request to your Atlan account team	Not a customer self-serve toggle—see the sequence below.
Remove an asset	A programmatic delete or a Support request	Deletes today are handled via Support or programmatically rather than a UI action—confirm current delete methods in the product documentation.

For the exact column formats, editable-field lists, and file rules of the Export/Import Assets and Bulk Upload flows—and the exact delete methods—see the Atlan product documentation; those specifics change and aren't restated here.

Choose soft vs. hard delete

• Soft delete (archive) hides the asset from the UI and search but keeps it recoverable—it's reversible.
• Hard delete (purge) removes it permanently—it's irreversible.
• Default to soft delete via Support unless you have an explicit need for permanent removal. Support is the safest path because it handles the asset and its underlying storage together.
• The common request—"purge a whole crawled schema from the UI"—is handled via Support or programmatically rather than a UI action today; confirm current delete methods in the product documentation. Often the better fix isn't a delete at all: exclude those objects at the crawler so they're never ingested in the first place.

AI / natural-language search

Treat conversational AI, chat, and natural-language search as one evolving discovery surface, not several separate products. It's the surface for finding and browsing assets in plain language. Capabilities roll out in phases, so confirm what's supported today in the product documentation before you promise a specific behavior—and don't quote a roadmap date as committed.

One split recurs and is worth getting right: conversational/natural-language search and token-consuming context/enrichment features typically follow different cost and approval tracks. Conversational search is usually the lower-risk, faster-to-approve surface—it can often run under an existing AI-platform approval if the model vendor is already cleared—whereas context agents and enrichment generally carry their own cost profile and need separate justification. Confirm the current consumption/cost model in the product documentation, or with your Atlan account team, before you scope approvals or build a cost case. Keeping the two tracks distinct avoids inflating the apparent cost of the simpler surface.

Enable gated feature

Gated capabilities aren't a self-serve switch. Approach them like this:

1. Confirm the business approval. Your Atlan account team confirms enablement is approved before anything is flipped. For an AI feature, confirm any customer-side security or AI-governance approval is cleared too—that approval often has a long lead time, so start it early.
2. Confirm the tenant is ready. A gated feature generally requires that your tenant has had at least one successful workflow run.
3. Enable, then verify. Once enabled, verify the change is actually live before you rely on it or announce it to users. Some capabilities require a support ticket rather than a self-serve enablement.
4. Agree a change-notification norm. Teams dislike features appearing "without notice," especially in production. Set the expectation up front that enablement is deliberate and announced—and don't turn on things no one asked for.

You can often provision but not enable an AI feature so your approval process runs in parallel without blocking readiness—with an explicit agreement that it won't be switched on until formal approval lands. Where possible, scope a new feature to admins or a single persona before a broad rollout.

Any bulk edit or destructive change

Smoke-test before you commit. Run the change on a small, real batch (a handful of assets or terms), verify the result, then scale. There is no automated undo on an Export/Import Assets or Bulk Upload run, so a full production import must never be your first test.

Common pitfalls

• Naming the wrong bulk mechanism: using the Export/Import Assets flow to try to create assets or terms, or the Bulk Upload flow to mass-edit assets. This generates the single most common class of "sync failed" tickets. Decide "am I editing what exists, or creating something new?" first.
• Editing during a sync, or changing the file's structure (reordering or deleting columns, touching the header rows, sorting to find a row). These corrupt the file and fail the sync. Use filters, not sorting, and make only supported edits—then let the sync finish.
• Enabling a feature without confirming approval, or announcing "it's on" without verifying on the tenant. Breaks the governance expectation and risks telling users something untrue.
• Presenting a preview capability as generally available, or a roadmap date as committed. Erodes trust when reality diverges—describe maturity honestly.
• Treating conversational search and token-consuming context agents as the same cost/approval track. Confirm the current consumption model in the product documentation; scoping them together can inflate the apparent cost and stall approval of the simpler, valuable surface.
• Treating Atlan like a software-delivery app: duplicating governance and UI configuration across dev and prod. Configure metadata directly in production; reserve non-prod for its few valid uses.
• Improvising commercial terms when a license count is exceeded or a module wasn't purchased. Acknowledge it openly, route it to your Atlan account team, and get the path forward confirmed in writing before adding users or modules.
• Guessing at availability, timelines, or backend behavior. A clean "I'll confirm and send it by [date]" preserves trust; a confident wrong answer destroys it.
• Putting long documentation into an asset's description field. The description field is meant for short summary text, not long-form documentation—use a README or an attached resource for documentation content.
• Sharing SQL as plain text in chat tools. Share the Atlan query link instead—it keeps the query governed and permission-checked.

Troubleshooting

Diagnose live as far as you can, then escalate with a complete written follow-up—a named owner and a date. When live diagnosis is exhausted (no logs, backend behavior), a support ticket is the right move, not continued guessing.

A complete escalation packet is the difference between same-day resolution and a multi-round ticket. Include: tenant name; the affected surface, asset type, and count; reproduction steps; the UI and log error messages; screenshots or a recording; a workflow ID or timestamp; and whether it reproduces consistently.

Symptom	Likely cause	Next move
An Export/Import Assets or Bulk Upload sync fails or errors	Edited during sync, changed the file structure, or used an invalid value	Check the sync log, compare against the original, verify the structure is intact, wait a few seconds, and retry. If the structure is compromised, re-export and start clean.
A spreadsheet sync-back stops working for all admins	Almost always an expired authorization, not a backend bug	Reconnect / re-authorize the integration first. Only if it persists after a clean reconnect escalate with the full packet.
Atlan feels slow and users are drifting back to the old tool	Often a known performance issue being worked on	Confirm whether it's a known issue rather than over-promising a fix date; escalate internally with diagnostics; give users the steps to capture diagnostics when slowness recurs. Treat user attrition as a serious risk, not a cosmetic one.
A recurring reliability issue you've reported before (timeouts, login errors, scheduled-query failures)	The same underlying issue resurfacing	Acknowledge the recurrence—don't re-litigate from scratch. Re-escalate with the prior reference plus fresh diagnostics; you shouldn't have to re-report it cold.
A production-down blocker	Filed at the wrong severity	File production blockers at the highest severity, not the default. If a critical issue has been stuck for days, take ownership and re-escalate the existing ticket rather than asking to re-raise it.
AI chat / search returns slow, inaccurate, or irrelevant results	One of four distinct causes—separate them before fixing	1) Enrichment gap: sparse or missing descriptions starve the model—the fix is metadata enrichment, not a search setting. 2) Prompting: vague queries—coach on phrasing. 3) Performance: latency or timeouts—treat as a reliability issue and escalate with diagnostics. 4) Known limitation: the query needs an attribute or relationship not yet supported—set expectations rather than treating it as a bug.
A user sees the wrong things (too much or too little)	Persona scoping, not a defect	This is an access-control design question—route it to governance & access best practices.
A documented marketplace app or package isn't visible on the tenant	It's a gated package that hasn't been enabled	Request enablement through the gated-feature process rather than filing a bug.
Usage / popularity data is missing for some asset types	The usage source (query history) hasn't run, or the asset type isn't covered	Confirm the usage-mining workflow ran for that source; if the type isn't covered, set expectations as a known gap rather than a defect.
A brand-new tenant has no admin who can log in to configure SSO	A bootstrap chicken-and-egg: SSO isn't up, and no local admin exists	Route to Atlan support for initial admin access—don't try to solve it inside the product.
Security asks for a custom domain / vanity URL	A deployment-level request, not a tenant setting	Confirm the current support state in writing with your Atlan team before committing to it.

Many "it's broken" tickets are really deep design questions in disguise. Diagnose only far enough to classify, then route: missing or partial lineage → lineage best practices; a crawler or miner failing → connector & ingestion best practices; a user seeing the wrong assets → governance & access best practices; poor enrichment output → metadata enrichment best practices.

See also

• Personas, purposes, policies, and "who can see or edit what": governance, access & personas best practices.
• AI-generated descriptions, enrichment coverage, and feeding context to AI: metadata enrichment best practices.
• Glossary and taxonomy structure and metric definitions: glossary & taxonomy best practices.
• Why lineage is missing or partial: lineage best practices.
• Connector choice, crawl scoping, and crawler/miner failures: connector & ingestion best practices.
• Sequencing your overall implementation: implementation & rollout best practices.
• Exact UI locations, bulk-file formats, delete methods, and current search capabilities—Atlan product documentation.