Atlan Custom Metadata for Validatar

Overview

The Atlan integration publishes Validatar's scores and test results into a custom metadata set in Atlan named Validatar. Atlan must have that set, with the exact property names on this page, before Validatar's first publish. This article is for the Atlan admin who creates it.

There are two ways to create the set:

Way	What it creates	Who runs it
Run the setup script (recommended)	The set, all its properties, and colour badges on every score	An Atlan admin, once, from any machine with Python
Create it by hand	The set and its properties. Score badges with green, yellow and red bands cannot be made in Atlan's badge editor	An Atlan admin, in Atlan

Atlan cannot import a custom metadata definition from a file. See Importing the set.

Either way, one step is always done by hand: the badge that puts View in Validatar in the asset header.

Where Validatar's values appear in Atlan

On every table, view and materialised view that Validatar tests and publishes:

the Validatar custom metadata on the asset's profile, with every property below
colour badges for the scores and for Tests Failing, on the asset's overview and in the side pane on the Assets page
a View in Validatar link, in the asset header once its badge is set up

Validatar replaces only its own set on each publish. Other custom metadata on the asset is never touched.

The Validatar custom metadata set

Set name: Validatar. Description: "Data quality published by Validatar."

Every property applies to tables, views and materialised views only. Only Failing Tests allows multiple values. The names must match exactly, including capitals and spaces, because Validatar writes each property by name.

Property	Type	Multiple values	Badge	What it holds
Trust Score	Decimal	No	Score bands	Validatar's trust score as a percentage of its five stars (4.5 stars is 90): quality weighted by coverage over the trust score window
Quality Score	Decimal	No	Score bands	Weighted pass rate of the Validatar tests on the asset
Coverage Score	Decimal	No	Score bands	How much of the asset's expected test coverage is in place
Completeness Score	Decimal	No	Score bands	Percent of the asset's Completeness tests that passed their latest run
Uniqueness Score	Decimal	No	Score bands	Percent of the asset's Uniqueness tests that passed their latest run
Validity Score	Decimal	No	Score bands	Percent of the asset's Validity tests that passed their latest run
Consistency Score	Decimal	No	Score bands	Percent of the asset's Consistency tests that passed their latest run
Accuracy Score	Decimal	No	Score bands	Percent of the asset's Accuracy tests that passed their latest run
Timeliness Score	Decimal	No	Score bands	Percent of the asset's Timeliness tests that passed their latest run
Standards Score	Decimal	No	Score bands	Percent of the asset's Standards tests that passed their latest run
Relationships Score	Decimal	No	Score bands	Percent of the asset's Relationships tests that passed their latest run
Security Score	Decimal	No	Score bands	Percent of the asset's Security tests that passed their latest run
Precision Score	Decimal	No	Score bands	Percent of the asset's Precision tests that passed their latest run
Performance Score	Decimal	No	Score bands	Percent of the asset's Performance tests that passed their latest run
Processing Score	Decimal	No	Score bands	Percent of the asset's Processing tests that passed their latest run
Compliance Score	Decimal	No	Score bands	Percent of the asset's Compliance tests that passed their latest run
Tests Passing	Integer	No	None	Validatar tests on the asset whose latest run passed
Tests Failing	Integer	No	Red above 0, green at 0	Validatar tests on the asset whose latest run failed
Tests Erroring	Integer	No	None	Validatar tests on the asset that could not complete, such as a connection error. Not a data quality verdict
Failing Tests	Text	Yes	None	Names of the published Validatar tests whose latest run failed
Impact Rating	Text	No	None	The asset's Validatar impact rating
Last Run	Date	No	None	When Validatar last tested the asset
Last Published	Date	No	None	When Validatar last published these values
View in Validatar	URL	No	Header link (by hand)	The asset in the Validatar catalog, with trust score history and test results

Score bands are green at 90 and above, yellow at 75 and above, and red below 75, unless you choose other thresholds. The 13 dimension properties are Validatar's quality dimensions. You can leave some out; see Choosing fewer dimensions.

To get this list as a spreadsheet, run python atlan_setup.py --csv validatar_custom_metadata.csv (described below). It writes one row per property with the type, multiple values, applicable assets, badge rule and description, and it makes no call to Atlan.

Option 1: Run the setup script

atlan_setup.py ships in the Atlan Metadata and Lineage Scripts download from the Validatar marketplace (get it here). It uses Atlan's official Python SDK, pyatlan.

Before you start

Python 3.10 or later on any machine that can reach your Atlan tenant over HTTPS.
An Atlan admin credential: an API token generated by an admin (Admin > API access), or an OAuth client with the Admin role (Admin > API access > OAuth clients). Creating custom metadata and badges needs admin rights. This credential is only for setup. The integration itself should use its own identity with fewer rights; see Permissions for the integration.

Steps

Unzip the download and open a terminal in its folder.
Install the packages the scripts need:
```
pip install -r requirements.txt
```
Tell the script where your tenant is and how to sign in. With an API token:
```
export ATLAN_BASE_URL=https://acme.atlan.com
export ATLAN_API_KEY=<admin API token>
```
With an OAuth client, set ATLAN_BASE_URL, ATLAN_OAUTH_CLIENT_ID and ATLAN_OAUTH_CLIENT_SECRET instead. On Windows, use set NAME=value in place of export NAME=value.

See what it will create. This makes no call to Atlan:

python atlan_setup.py

It prints one line per property, with its type, whether it allows multiple values, and its badge:

Trust Score            Decimal  multi=No  GREEN >= 90; YELLOW >= 75; RED < 75
Quality Score          Decimal  multi=No  GREEN >= 90; YELLOW >= 75; RED < 75
...
Tests Failing          Integer  multi=No  RED > 0; GREEN = 0
Failing Tests          Text     multi=Yes
...
View in Validatar      URL      multi=No  header link: add a badge in Settings > Badges, Display at the top

Create the set and the badges:
```
python atlan_setup.py --apply
```
The script creates the Validatar set with all 24 properties, limited to tables, views and materialised views. It then creates 17 badges: one on each of the 16 scores, and one on Tests Failing. Each badge is named after its property, such as "Validatar Trust Score". It prints each action as it goes.
Add the header link by hand, as described in Put View in Validatar in the asset header. The script does not create that badge.
In Atlan, open Settings > Custom Metadata and confirm that Validatar is listed with its properties.

Script options

Option	Default	What it does
(none)		Prints the plan. No call to Atlan
`--csv <file>`		Also writes the plan as a CSV file. No call to Atlan
`--apply`	off	Creates the set and badges in Atlan
`--dimensions <list>`	all 13	Comma-separated dimensions to create properties for, such as `Completeness,Validity,Timeliness`
`--good-at <n>`	90	A score at or above this is green
`--warning-at <n>`	75	A score at or above this, and below the green threshold, is yellow. Below it is red
`--set-name <name>`	Validatar	The name of the set. See Using another set name

Running it again

The script is safe to run again. When the set already exists, it adds only the properties that are missing and reports which ones it added. It never removes, renames or retypes a property. It saves the 17 badges again with the thresholds you pass, which is also how you change the bands later:

python atlan_setup.py --apply --good-at 95 --warning-at 80

Option 2: Create the set by hand in Atlan

Use this when you cannot run Python against Atlan. The result is the same set, without the green, yellow and red bands on the scores.

Create the set and its properties

In Atlan, open Settings > Custom Metadata. In the classic interface it is Admin > Custom Metadata.
Add a new custom metadata set (+ Get started when the tenant has none yet). Name it Validatar and add the description Data quality published by Validatar., then create it.
For each row of the property table, add a New property:
1. Enter the property name exactly as shown.
2. Choose the type shown: Decimal, Integer, Text, Date or URL.
3. Limit where it applies to tables, views and materialised views only.
4. Turn on Allow multiple values for Failing Tests only.
5. Save the property.
Check the finished list against the table: 24 properties, or fewer if you are leaving out dimensions.

Add badges

Atlan's badge editor compares a property with a value using Equals or Not Equals only. That is enough for Tests Failing, but not for score bands, which need "at or above". Run the setup script with --apply later if you want the score badges; it keeps the properties you created and adds the badges.

To badge Tests Failing by hand:

Open Settings > Badges and choose + Create new.
Pick the Validatar set and the Tests Failing property.
Add a condition Equals 0 in green, and a condition Not Equals 0 in red.
Save the badge.

Put View in Validatar in the asset header

Do this after either option.

Open Settings > Badges and create a badge on the View in Validatar property of the Validatar set.
Turn on Display at the top of the profile.
Save the badge.

Each tested asset now shows View in Validatar in its header, linking to the asset in the Validatar catalog.

Importing the set

Atlan has no import for custom metadata definitions. A set and its properties are created in Settings > Custom Metadata, through the API, or with the SDK, which is what atlan_setup.py uses.

Atlan's Asset Import app loads custom metadata values onto existing assets from a file. It does not create the set or its properties, and it is not turned on for every tenant. Validatar does not need it: the integration writes the values itself.

The CSV written by atlan_setup.py --csv is a checklist for review and for creating the set by hand. Atlan cannot import it.

Permissions for the integration

The credential on the Atlan data source in Validatar is not the admin credential used for setup. Give it a persona that covers the connections Validatar publishes to, with permission to:

read the assets on those connections
update custom metadata values, so it can write the Validatar set
update the assets themselves, only if you turn on announcements or the external data quality preview

An API token without personas can only see connections it created itself, so the publish step would find nothing to update. Give an OAuth client the same personas.

Changing the defaults

Using another set name

If the set must have another name, use the same name in three places:

When creating the set: python atlan_setup.py --apply --set-name "Data Quality (Validatar)", or the name you type by hand.
On the Atlan data source in Validatar: the Custom Metadata Set Name setting.
In the Atlan Instance Health Checks test Atlan - Validatar feed into Atlan is current: the SET_NAME value at the top of its script.

Property names stay the same under any set name.

Choosing fewer dimensions

You can create properties for only the dimensions your tests use, for example with --dimensions Completeness,Validity,Timeliness. Then set Publish Dimensions on the Atlan data source in Validatar to the same list.

Note: Keep the two lists in step. If Validatar has a score for a dimension that the set has no property for, that score is not sent, and the publish report names the missing property on each table it affects. The other values are still written. To add a dimension later, run the script again with the longer list; it adds the missing properties.

Changing the badge thresholds

Badge thresholds live in Atlan and apply to every asset. If you change them, also set Score Good At and Score Warning At on the Atlan data source in Validatar to the same numbers, so the publish step's report uses the same bands that Atlan shows. A table's impact rating target can change its band in that report, but never the badge in Atlan.

External data quality (preview)

The Atlan data source can also write Atlan's built-in external data quality structure, through its Publish Target setting (External DQ (preview) or Both). That structure exists on every asset, so it needs no setup in Atlan, and the script does not touch it. It is a preview: Atlan does not document it for third-party tools, and it has not yet been confirmed that Atlan shows it for Validatar. The custom metadata set on this page is the supported route.

Check the setup

In Validatar, run the Atlan data source's publish test with Dry Run on. Its result lists each table it would publish, with the target and the number of properties.
Turn Dry Run off and run it again.
In Atlan, open one of the listed tables. The Validatar custom metadata shows the scores with their badges, and View in Validatar appears in the header if you added that badge.

Troubleshooting

Symptom	Cause	Fix
`atlan_setup.py --apply` fails with 401	The token expired, or the OAuth client secret was regenerated	Create a new token or secret and set the environment variables again
`atlan_setup.py --apply` fails with 403	The credential is not an admin	Use an admin API token, or an OAuth client with the Admin role
"No module named pyatlan"	The packages are not installed in the Python you ran	Run `pip install -r requirements.txt` with the same Python
The publish report says "not in the Atlan set, so not sent: ... Score"	The set has no property for a dimension Validatar is publishing	Add the property (run the script again), or limit Publish Dimensions to the dimensions in the set
The publish step stops with "custom metadata set 'Validatar' was not found in Atlan"	The set does not exist, or its name differs from Custom Metadata Set Name on the Atlan data source	Create the set, or make the two names match
The publish step fails on a property name you did not expect	A property was created with a different name, capitals or spacing	Rename it in Atlan to match the table exactly
The publish step fails because the custom metadata set does not exist	The set has another name in Atlan than in Custom Metadata Set Name, or it was never created	Make the two names match, or create the set
Scores show, but without colours	The badges were not created	Run `python atlan_setup.py --apply`; it keeps the existing properties and adds the badges
No View in Validatar in the header	The header badge is a manual step	Follow Put View in Validatar in the asset header
The set appears on glossary terms or other asset types	The properties were created without limiting where they apply	Edit each property to apply to tables, views and materialised views only
The publish step cannot update an asset	The integration's persona lacks update permission for custom metadata on that connection	Add the permission, or add the connection to the persona

Note: This article describes the design of the Validatar and Atlan integration. The setup script has been tested through Atlan's official Python SDK against a simulated Atlan server, and the integration has been tested in Validatar against a built-in sample Atlan tenant. It has not yet been validated against a live Atlan tenant, so menu names and options in Atlan may differ from those shown here. To discuss using it, contact your Validatar account team.