---
title: "Atlan Integration"
slug: "atlan-integration"
updated: 2026-11-10T03:59:46Z
published: 2026-11-10T03:59:46Z
canonical: "docs.validatar.com/atlan-integration"
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validatar.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Atlan Integration
## Overview
Atlan shows people what data exists, who owns it, and how it connects. Validatar tests whether that data can be trusted. The Atlan integration connects the two so that each platform shows what the other knows.
- **Validatar to Atlan.** Trust scores, quality scores by dimension, test counts and the names of failing tests appear on the tables and views they describe in Atlan, with green, yellow or red badges and a link back to Validatar.
- **Atlan to Validatar.** Atlan owners, tags, glossary terms, certificates, announcements, data domains and lineage appear in the Validatar catalog, next to the tests that cover the same data.
The integration runs inside Validatar. It calls Atlan through Atlan's official Python SDK (pyatlan) and uses Validatar's own scheduling, so there is no separate server, connector or scheduler to maintain.
## Get the integration
Five items on the Validatar marketplace make up the integration:
| Marketplace item | What it is | Reference |
| --- | --- | --- |
| [Atlan - Data Source Template](https://admin.cloud.validatar.com/marketplace/72) | The Atlan data source: credentials for both platforms, publishing to Atlan, and a catalog of the Atlan tenant itself. Includes a demo mode that answers from a built-in sample tenant | [Atlan Data Source Template](/docs/atlan-data-source-template) |
| [Atlan - Catalog Custom Fields](https://admin.cloud.validatar.com/marketplace/73) | An Atlan section in the Validatar catalog custom fields, at data source, schema, table and column level, for the values brought in from Atlan | [Atlan Catalog Custom Fields](/docs/atlan-catalog-custom-fields) |
| [Atlan - Project Custom Fields](https://admin.cloud.validatar.com/marketplace/76) | An **Atlan Publishing** section on every test, with the four fields that choose which tests are published and how Atlan names them | [Atlan Project Custom Fields](/docs/atlan-project-custom-fields) |
| [Atlan Metadata and Lineage Scripts](https://admin.cloud.validatar.com/marketplace/74) | A download with the two scripts that bring Atlan metadata and lineage into Validatar, the script that prepares Atlan for Validatar's results, and their setup guide | [Atlan Metadata and Lineage Scripts](/docs/atlan-metadata-and-lineage-scripts) |
| [Atlan Instance Health Checks](https://admin.cloud.validatar.com/marketplace/75) | 15 tests that check whether the Atlan tenant is working and well governed | [Atlan Instance Health Checks](/docs/atlan-instance-health-checks) |
## What appears in Atlan
Validatar publishes to a **custom metadata set** named **Validatar**. Custom metadata is Atlan's supported way for other tools to add their own properties to assets, and it is how other data quality tools show their scores in Atlan. An Atlan admin creates the set once, either with a setup script or by hand; [Atlan Custom Metadata for Validatar](/docs/atlan-custom-metadata-for-validatar) lists every property and both ways to create them.
| Published from Validatar | Where it appears in Atlan |
| --- | --- |
| Trust score, quality score and coverage score for each tested table or view | The Validatar custom metadata on the asset's profile, each score with a colour badge |
| A score for each [quality dimension](/docs/quality-dimensions) that has tests, such as Completeness, Validity or Timeliness | The same set, one property per dimension, each with a colour badge |
| The number of tests passing, failing and erroring, and the names of failing published tests | The same set. Tests Failing carries a red badge when it is above zero |
| The table's [impact rating](/docs/impact-ratings), when it last ran and when it was last published | The same set |
| A link to the table in the Validatar catalog | **View in Validatar**, which an admin can place in the asset's header |
| An optional announcement on tables whose critical tests fail | Atlan's announcement banner on the asset |
Atlan shows badges on the asset's overview and in the side pane on the Assets page, so a reader sees the colour of a score without opening the custom metadata tab.
> **Note:** Atlan keeps the current value of each property. Score history and trends remain in Validatar, one click away through View in Validatar.
### How values are set
- **Badge colours** are set once in Atlan, when the set is created: green at or above 90, yellow at or above 75, red below 75, unless the admin chooses other thresholds. Every asset uses the same bands.
- **Trust, quality and coverage scores** are Validatar's stored scores for the table, calculated over the look back period in Validatar's trust score settings. The trust score is published on a 0 to 100 scale (4.5 stars is 90).
- **Dimension scores** are the share of a table's tests in that dimension that passed their latest run: one vote per test, not weighted by severity, with errored tests left out. A dimension with no tests on a table is cleared rather than set to zero, so an untested dimension never looks like a failing one. [How the publish script calculates scores](/docs/atlan-integration#how-the-publish-script-calculates-scores) gives each calculation and why it can differ from what Validatar shows.
- **Test counts** cover every test on the table. **Failing Tests** names only the published tests that failed, under the names you choose for Atlan.
- **Announcements** are optional and off by default. When turned on, a table whose tests marked for announcement fail gets a Warning announcement titled "Validatar: ..." and loses it when they pass again. Validatar only ever changes announcements whose title starts with "Validatar:", so an announcement someone else posted is never replaced.
Scores are published after each scheduled test run. Results for tests you mark as critical can be published the moment the test runs, using a [test action](/docs/what-are-test-actions).
### External data quality (preview)
Atlan also has an external data quality structure on every asset. It holds an overall score, a score per dimension, and each test with its latest run, which is closer to a dedicated data quality tab than custom metadata is. Atlan uses it for its own connectors and partner tools, but does not document it for other tools, and it has not yet been confirmed that Atlan shows it for Validatar. The template can write it as a preview, alone or alongside the custom metadata set, through the **Publish Target** setting. Custom metadata is the default and the supported route.
## Choosing what to publish
Publishing is controlled in three places, from broad to narrow.
**1. Publish scope.** A single setting on the Atlan data source chooses how much Validatar publishes:
| Scope | Publishes |
| --- | --- |
| Trust Score | Trust, quality and coverage scores, test counts and the link for each table |
| Trust + Dimensions | The above, plus one score per quality dimension. You can limit this to a named set of dimensions |
| Trust + Dimensions + Tests | The above, plus the names of failing tests, and each test's results in the external data quality preview |
**2. Test-level fields.** When tests are in scope, test owners decide test by test using the fields in an **Atlan Publishing** section on the test, which the [Atlan Project Custom Fields](/docs/atlan-project-custom-fields) item adds:
- whether the test is published to Atlan
- the name Atlan users see for it, so a test can appear as "Order totals reconcile to the general ledger" rather than its internal name
- whether a failure posts an announcement on the table
- which Atlan asset the result belongs to, filled in by the integration and changeable to point a test at a column
By default only tests that are explicitly opted in are published. A second setting can publish every test on a matched table instead.
**3. Table-level opt-out.** Setting **Publish Scores to Atlan** to No on a table keeps it out of Atlan entirely. This is useful for staging tables that are tested but are not meant for catalog users.
New data sources start in **Dry Run**: the publish step reports what it would write and writes nothing. Turn Dry Run off once the report shows what you expect.
## How the publish script calculates scores
The two publishing macros in the [Atlan data source template](/docs/atlan-data-source-template) (version 1.1.1) take some values straight from Validatar's stored trust score and work out the others from each test's latest result. This section describes what that Python code does today, so you can tell why a number in Atlan does or does not match the one in Validatar. For how Validatar itself calculates scores, see [How Trust Scores Are Calculated](/docs/how-trust-scores-are-calculated).
The script has no time window of its own. It does not read or change the look back period.
| Atlan property | Source | Window | Weighting |
| --- | --- | --- | --- |
| **Trust Score** | Validatar's stored trust score, × 20 | The table's look back period in Validatar (14 days by default) | Severity, Quality Score Method and coverage |
| **Quality Score** | Validatar's stored quality score, as a percentage | Same look back period | Severity and Quality Score Method |
| **Coverage Score** | Validatar's stored coverage score, as a percentage | Same look back period | Coverage weighting |
| **Impact Rating** | The table's impact rating in Validatar | None | None |
| ** Score**, such as Completeness Score | Worked out by the script | Each test's latest run, however old | None: one vote per test, errors left out |
| **Tests Passing**, **Tests Failing**, **Tests Erroring** | Counted by the script | Each test's latest run | None |
| **Failing Tests** | The published tests whose latest run failed | Each test's latest run | None |
| **Last Run** | The latest run date among the table's tests | None | None |
### Trust, Quality and Coverage Score
The script reads the table's current trust score record from Validatar's REST API (`GET /api/v1/Catalog/data-sources/{id}/schemas/{id}/tables/{id}/trust-scores`) and publishes it unchanged except for scale. The trust score is Validatar's 0 to 5 stars × 20, so 4.5 stars is published as 90. Quality and coverage are the percentages the API returns. Each value is rounded to one decimal place.
These three values follow the look back period in Validatar's trust score settings, including any override on the table's schema or data source, because Validatar applied it when it calculated them.
Validatar recalculates the stored trust score once a day, just after midnight, and when someone refreshes it by hand. The publish test usually runs at the end of the daily test job, so the trust, quality and coverage scores it publishes come from the calculation before that job's results. Dimension scores and test counts are read at publish time, so they reflect the job that just ran.
When a table had no test runs in its look back period, Validatar stores a trust score of 0 with a run count of 0. The script treats that as "no score": it publishes no Trust, Quality or Coverage Score for the table, which clears any earlier values. Dimension scores and test counts are still published.
### Dimension scores
```
Score = tests whose latest run passed
÷ (tests whose latest run passed + tests whose latest run failed)
× 100
```
- **One vote per test.** Only each test's latest result counts. A test that ran 14 times in two weeks counts once.
- **No severity weighting.** A Critical test and an Informational test count the same.
- **No partial credit.** A failed run counts as failed, whatever the test's Quality Score Method.
- **No time window.** A test whose latest run was three months ago counts with that result.
- **Errors are left out** of both sides. A dimension in which every test errored gets no score.
- **Other results are skipped**, including tests that have never run.
- **Dimensions with no tests are not published**, so an untested dimension is cleared in Atlan rather than shown as 0. **Publish Dimensions** limits which dimensions are published.
The dimension comes from the test's current version. Tests with the None dimension are skipped.
### Which tests count
For dimension scores and test counts, the script asks Validatar for the tests linked to the table (`GET /api/v1/Catalog/.../tables/{id}/tests`). That list is wider than the set of tests behind the trust score:
- It includes a test linked to the table on either data set, even when the link does not impact the trust score. A comparison test counts toward both its source and its target table.
- It uses each test's current links, not the links it ran with.
- It includes only tests in projects that the Validatar API token's user can see.
**Tests Passing**, **Tests Failing** and **Tests Erroring** count these tests by their latest result, including tests with no dimension. **Failing Tests** names only the published tests whose latest run failed.
### Every run or the latest result
The biggest difference between Atlan's dimension scores and Validatar's quality score is what gets counted. Take a table with five tests, each in a different dimension, over 14 days:
| Test | Severity | Quality dimension | Runs in 14 days | Passed | Latest run |
| --- | --- | --- | --- | --- | --- |
| Order ID not null | Critical | Completeness | 14 | 14 | Passed |
| Order ID unique | High | Uniqueness | 14 | 12 | Passed |
| Order total above zero | Medium | Validity | 2 | 0 | Failed |
| Row count matches source | Low | Consistency | 14 | 14 | Passed |
| Loaded today | Informational | Timeliness | 14 | 10 | Failed |
- **Validatar's quality score** counts all 58 runs, each weighted by severity: 346 of a possible 372, or 93%. The two Uniqueness failures count. The Informational failures cost nothing.
- **Atlan's dimension scores** count each test once by its latest run: Completeness 100, Uniqueness 100, Validity 0, Consistency 100, Timeliness 0. The Uniqueness failures earlier in the fortnight do not show, and the Informational test's latest failure shows as a Timeliness score of 0.
Both are correct. The dimension scores answer "is each kind of check passing right now?" The quality score answers "how reliable has this table been over the look back period, weighted by what matters most?"
### Badge colours
The badges in Atlan use fixed thresholds set when the custom metadata set was created: green at 90 and above, yellow at 75 and above, red below 75 by default. They do not use Validatar's impact rating targets. A table rated **4 - High** that exactly meets its target of 4 stars is published as 80 and shows a yellow badge in Atlan, while Validatar shows it **Above Target**. The `band` column in the publish test's report can follow impact rating targets instead (**Use Impact Rating Targets**); that changes the report only.
### External data quality fields
With **Publish Target** set to External DQ or Both, the overall score is the Trust Score × 20, the score dimensions are the dimension scores above, and each test's run score is 100 if its latest run passed and 0 otherwise.
### Why Atlan and Validatar can show different numbers
| Value | In Validatar | In Atlan |
| --- | --- | --- |
| Trust, Quality, Coverage Score | Current stored record | The same record, as of the last publish; trust × 20 |
| Per-dimension result | Severity-weighted runs in the Test Execution Activity panel, or the run pass rate in the KPI bar | Share of tests whose latest result passed |
| Tests counted | Links that impact the trust score, captured at run time | Any current link, either data set, in projects the API token's user can see |
| Repeat runs | Every run in the window | Latest run only |
| Errors | Count against the quality score | Left out of dimension scores |
| Old results | Drop out after the look back period | Kept until the test runs again |
| Target colours | Impact rating target | Fixed 90 / 75 thresholds |
### Changing the calculation
The calculation lives in the template's publish script, `publish_atlan.py`, which runs as Python inside Validatar. It can be changed to match how you want scores to read in Atlan: for example, to count every run in the look back period rather than each test's latest result, to weight dimension scores by severity, or to give partial credit the way each test's Quality Score Method does. Talk to your Validatar team about the change you need.
## What appears in Validatar
From Atlan, the integration brings in:
- the Atlan qualified name and a link to the asset in Atlan
- the description
- owners, as names, and optionally as Validatar users
- tags, both those assigned directly and those propagated through lineage or hierarchy
- linked glossary terms
- the certificate (Verified, Draft or Deprecated) and its message
- the current announcement
- data domains and data products
- popularity, where Atlan mines usage, and when Atlan last crawled the table
- any Atlan custom metadata you name, such as a data steward or a criticality rating
- table-level lineage, and optionally column-level lineage
These land in an **Atlan** section of the Validatar catalog custom fields on the same data sources, schemas, tables and columns, and as Validatar lineage. They sit in their own fields, so Atlan values never overwrite descriptions or tags maintained in Validatar. You choose which fields come across, and for which schemas, at the top of the metadata script.
With this context in Validatar, teams can prioritise testing by domain or certificate, route failures to the right owner, and see which downstream objects a failed test affects.
## How it works
The integration is packaged as an Atlan [data source template](/docs/what-is-a-data-source-template-overview). It holds the credentials for both the Atlan and Validatar APIs and the code every job shares. Each job runs through a standard Validatar feature, on a connection built from the template with the same Atlan settings:
| Job | Runs in Validatar as | Typical schedule |
| --- | --- | --- |
| Bring in Atlan owners, tags, terms, certificates and domains | A Custom Metadata source on each warehouse data source, running the metadata script | Daily |
| Bring in Atlan lineage | A Lineage Ingestion source running the lineage script | Weekly |
| Publish scores and selected test results | A Python test, using the template's publish macro, placed last in the scheduled test job | After every test run |
| Publish a critical test's result immediately | A test action on that test, using the template's second macro | Each time the test runs |
| Catalog the Atlan tenant and check its health | Metadata ingestion on the Atlan data source, then the Atlan Instance Health Checks tests | Daily |
Because the publish step is itself a Validatar test, every publish has a pass or fail history and can alert like any other test.
### Checking the health of the Atlan tenant
The Atlan data source's own catalog is the Atlan tenant: each Atlan object type (connections, glossaries and terms, tags, custom metadata, data domains and products, personas, purposes, groups and recent workflow runs) is a schema, and each object is a table whose columns hold its properties. The [Atlan Instance Health Checks](/docs/atlan-instance-health-checks) pack tests that catalog and the Atlan API behind it. It covers API tokens about to expire, crawler runs that failed, connections that have not been crawled recently, tables without owners or descriptions, owners who are no longer active users, deprecated assets that other assets still read, duplicate glossary terms and tags, empty data domains, expired announcements, and whether Validatar's own publishing into Atlan is current.
### Trying it without Atlan
Turn on **Demo Mode** on the Atlan data source and every Atlan call is answered by a built-in sample tenant, a fictional company with four connections and a few deliberate problems. The object catalog, the health checks, the scripts and the publish step all run against it, nothing is sent to Atlan, and pyatlan does not need to be installed.
### Matching the two catalogs
Validatar and Atlan identify tables differently, so each job pairs a Validatar data source with an Atlan connection and matches schemas, tables and columns by name within the pair. An Atlan connection is named by its qualified name, such as `default/snowflake/1657025257`. The metadata and lineage scripts name their Atlan connection at the top of the script. Publishing reads the connection from each warehouse data source's **Atlan Connection Qualified Name** field, which the metadata script fills, or from a connection map on the Atlan data source when you set one. The Atlan data source's own catalog lists every connection with its qualified name, so the pairs are built from what Atlan reports. Once the metadata script has run, each table's Atlan qualified name is stored in Validatar and publishing uses it directly. When one Atlan connection crawls several databases, matching also takes the database into account, through the schema name (`SALES_DB.PUBLIC`) or the Validatar data source's own database. Objects found on one side and not the other are counted and reported, never silently dropped.
## Requirements
**Atlan**
- An integration identity: an **OAuth client** (Admin > API access > OAuth clients) or an **API token** (Admin > API access). OAuth clients are the default; API tokens are also supported.
- Personas on that identity covering the connections in scope. Without personas, a token can only see connections it created.
- Permission through those personas to read assets and lineage and to update custom metadata values. Updating assets is also needed for announcements and for the external data quality preview.
- An Atlan admin to create the Validatar custom metadata set once, and for the two health checks that list API tokens and users.
- Room in Atlan's API limit. Atlan allows 400 API calls a minute for the whole tenant and blocks programmatic calls for a minute when it is exceeded. The integration holds itself to 300 a minute by default, and the limit can be lowered on the data source.
**Validatar**
- Atlan's Python SDK, pyatlan 11.4, installed in the Python that runs Validatar scripts: under Settings > Configuration for the Validatar server or cloud runtime, or through the Data Agent's Python module install when scripts run on an agent. Demo Mode needs no install.
- A Validatar API token for the integration, used to publish and by the lineage script
- Govern Edition, to define the integration's custom fields
- The Data Lineage feature, to bring in Atlan lineage
- The Standard Test Actions feature, to publish critical test results the moment they run
Both platforms communicate over HTTPS. Atlan itself needs no Data Agent; the scripts run wherever the instance runs Python.
## Rollout
Most teams adopt the integration in stages. Each stage is useful by itself.
1. **Prepare.** Agree the decisions below, create credentials on both sides, map data sources, and create the Validatar custom metadata set in Atlan.
2. **Publish scores.** Add the publish step to the daily test job with Trust Score scope, run it in Dry Run, then turn Dry Run off. Tested tables in Atlan now show Validatar scores.
3. **Publish dimensions and tests.** Import the project custom fields, widen the scope, opt in the tests that matter to catalog users, and add test actions to critical tests.
4. **Bring in Atlan metadata.** Import the Atlan custom fields, then add the metadata script to each warehouse data source.
5. **Bring in lineage.** Start with table-level lineage, then add columns where needed.
### Decisions to make before setup
| Decision | Common starting point |
| --- | --- |
| Which data sources are in scope | The two or three warehouses Validatar tests most |
| How the integration signs in to Atlan | An OAuth client with a persona per set of connections |
| Publish scope | Trust Score for the first week, then Trust + Dimensions + Tests |
| Which tests are published | Only tests opted in by their owners |
| Badge thresholds | Green at 90, yellow at 75 |
| Which dimensions get a property in Atlan | All 13, or only the dimensions your tests use |
| Whether to post announcements in Atlan | Off until the data stewards agree |
| Whether to try the external data quality preview | Off; custom metadata only |
| Which Atlan custom metadata to bring into Validatar | Two to five properties that affect test priority, such as data owner and criticality |
| Lineage depth | Table level |
## What has been tested
The integration has run inside Validatar against the built-in sample tenant. That covered importing the template, cataloging the sample tenant, all 15 health checks (27 results with child tests, each as designed), the metadata script filling the Atlan fields on a Snowflake data source, the lineage script loading table lineage, importing all four items from the marketplace, and both publishing macros with **Dry Run** off: the publish test sent scores, dimension scores and failing tests for the tested tables, and a test action republished a table the moment its test ran. The Atlan calls, including the custom metadata write and the setup script, have been exercised through pyatlan against a simulated Atlan server. Since then the integration has run against a customer's live Atlan tenant.
## Related
- [Atlan Data Source Template](/docs/atlan-data-source-template)
- [Atlan Custom Metadata for Validatar](/docs/atlan-custom-metadata-for-validatar)
- [Atlan Instance Health Checks](/docs/atlan-instance-health-checks)
- [Atlan Metadata and Lineage Scripts](/docs/atlan-metadata-and-lineage-scripts)
- [Atlan Catalog Custom Fields](/docs/atlan-catalog-custom-fields)
- [Atlan Project Custom Fields](/docs/atlan-project-custom-fields)
- [What Is a Data Source Template?](/docs/what-is-a-data-source-template-overview)
- [What are Test Actions](/docs/what-are-test-actions)
- [How Trust Scores Are Calculated](/docs/how-trust-scores-are-calculated)
- [Quality Dimensions](/docs/quality-dimensions)
- [Impact Ratings](/docs/impact-ratings)
- [Configuring Custom Fields](/docs/config-custom-fields)