Overview
The Alation data source template connects Validatar to Alation in both directions from a single data source. That data source holds the credentials for both the Alation and the Validatar APIs, and everything in the Alation integration runs on its connection:
- Publishing to Alation. Two macros publish Validatar trust scores, quality scores by dimension and the test results you choose to Alation's Data Health feature.
- Cataloging the Alation instance. Ingesting the data source's metadata turns Alation's own objects (data sources, domains, glossary terms, policies, tags and more) into Validatar tables, which the Alation Instance Health Checks pack tests.
- Pulling from Alation. The Alation Metadata and Lineage Scripts run as Custom Metadata and Lineage Ingestion sources on connections built from this template, with the same Alation settings. What is specific to each warehouse sits at the top of each script. The metadata script fills the Alation Catalog Custom Fields.
Marketplace: Alation - Data Source Template
How It Works
- One template, several hosts. The template's pre-execution script holds the Alation and Validatar clients and the shared code of the metadata and lineage scripts. It runs before every script on a connection built from the template: the data source's own metadata ingestion, the two macros, tests on the data source, and the Custom Metadata and Lineage Ingestion sources that use the template.
- Alation objects become tables. Metadata ingestion catalogs the Alation instance itself. Each object type is a schema, each object a table named
<title> [<Alation id>], and each of the object's properties a column whose comment holds the current value. Only the Standard Fields every Validatar instance ships are written (friendly name, description, tags), so the catalog needs no custom field setup. - Nothing is written to Alation unless you ask. Ingestion and the health checks only read. Publishing writes Data Health rules under its own key prefix, and Dry Run is on by default.
- Demo mode. With Demo Mode on, every Alation call is answered from a built-in sample Alation instance: a fictional company whose catalog is healthy in most places and has a few deliberate problems. Use it to try the template and the health checks before Alation credentials exist. Nothing is sent to Alation while it is on.
Authentication
Alation supports two sign-in methods, chosen with Alation Auth Method:
| Method | Where the credential comes from | How it is used |
|---|---|---|
| OAuth Client Credentials (Alation Cloud Service) | An Alation Server Admin registers an OAuth client application and chooses its System User Role. The role is the only permission control. Copy the client ID and the client secret, which is shown once. | Exchanged for a bearer token on every run |
| Refresh Token (Alation Cloud Service or customer-managed) | A service user creates a refresh token under Account Settings > Authentication. Note the numeric user id. | Exchanged for a 24-hour API access token on every run. The refresh token itself expires after the admin-set lifespan, 90 days by default |
Alation role. Catalog Admin covers publishing to Data Health, domains, custom fields and, on Alation 2026.4.1 and later, lineage. Server Admin additionally covers users, connectors, Agents and BI servers, which some health checks and the User object type need. An object type the role cannot read is skipped and recorded rather than failing the run.
Validatar. An API token sent as the x-val-api-token header, with the Catalog, Authoring and DataSteward scopes. Publishing and the lineage script need it. The metadata script, cataloging Alation and the health checks do not.
Connection Parameters
| Parameter | Required | Default | Purpose |
|---|---|---|---|
| Alation Base URL | Yes | Your Alation URL, for example https://acme.alationcloud.com |
|
| Alation Auth Method | Yes | OAuth Client Credentials | OAuth Client Credentials or Refresh Token |
| Alation Client ID / Client Secret | OAuth | The OAuth client application's credentials | |
| Alation User ID / Refresh Token | Refresh token | The token owner's numeric id and the refresh token | |
| Demo Mode | Yes | false | Answer from the built-in sample Alation instance |
| Validatar Base URL / API Token | For publishing and lineage | Your Validatar URL and an API token | |
| Alation Connection Map | For publishing | Which Validatar data source is which Alation data source when publishing, as 12=7; 13=9. The metadata and lineage scripts carry their own data source ids |
|
| Publish Scope | Yes | Trust + Dimensions | Trust Score; Trust + Dimensions; Trust + Dimensions + Tests |
| Publish Tests | Yes | Opted-in tests | Opted-in tests or All tests |
| Publish Dimensions | No | all with tests | Limit dimension scores to a list, for example Completeness,Validity |
| Rule Key Prefix | Yes | validatar | Prefix of every Data Health rule key Validatar creates |
| Score Good At / Score Warning At | Yes | 90 / 75 | Status thresholds for scores |
| Use Impact Rating Targets | Yes | true | Use a table's impact rating target as its Good threshold |
| Set Warning Flags | Yes | false | Put an Alation Warning flag on tables with an Alert, and remove it on recovery |
| Alation Object Types | No | all except User | Object types to catalog at ingestion |
| Max Objects Per Type | No | 5000 | Cap per object type |
| Alation Glossary Hub ID | No | found automatically | The Document Hub id of the Glossary hub |
| Dry Run | Yes | true | Report what publishing would send without sending it |
Capabilities
Metadata Ingestion: the Alation Object Catalog
| Schema | What each table is | Alation role |
|---|---|---|
| Data Source | An Alation data source, with its connector, extraction status, schedule and the Validatar data source it is mapped to | Viewer |
| Connector | An installed OCF connector and its version | Server Admin |
| Agent | An Alation Agent, its connection state and certificate expiry (Alation Cloud Service) | Server Admin |
| BI Server | A BI server cataloged in Alation | Server Admin |
| Domain | A domain, its parent and how many objects it holds | Catalog Admin |
| Glossary | A glossary (folder) in the Glossary hub | Viewer |
| Glossary Term | A business term, with its stewards and whether it has a definition | Viewer |
| Document | A document in any other Document Hub | Viewer |
| Policy, Policy Group | Policy Center business policies and groups, with stewards | Catalog Admin |
| Tag | A tag and how many objects carry it | Viewer |
| Custom Field | An Alation custom field definition | Catalog Admin |
| Data Health Rule | A Data Health rule, whether published by Validatar or another tool | Viewer |
| Workflow | An Alation workflow and its state | Viewer |
| Data Product | A data product (Alation Cloud Service with Data Products) | Data product role |
| User | A user, their status and last login. Opt-in, because it holds names and emails | Server Admin |
| Ingestion Summary | One table per object type: loaded, skipped because the role cannot read it, or not available |
Macros
| Macro | Type | Use |
|---|---|---|
| Publish to Alation Data Health | Test data set | In a Python test placed last in a scheduled test job. Publishes scores and the selected tests for every mapped data source and returns one row per value published. Its optional parameter limits it to some data sources |
| Push Test Result to Alation | Standard test action | In a Run Macro step of a test action on a standard test. Publishes that test's result as it runs. Set its parameters to {{test_url}}, {{test_name}}, {{result}}, {{execution_url}} and {{failed_count}} |
The publish controls, statuses and the test-level custom fields that choose and name tests are described in the Alation Integration article.
Custom Fields
The object catalog needs none. Publishing reads two fields of the Alation Catalog Custom Fields set on each table: Alation Key, which the metadata script fills, and Publish Scores to Alation, a per-table opt-out. Tests opt in and get their Alation names through the Alation Publishing test fields, which the Alation Project Custom Fields item adds.
Installation
- Open Marketplace in Validatar, find Alation - Data Source Template and choose Get, then Import Directly. Validatar adds it under Settings > Data Source Templates.
- Create a data source from the template. To try it first, set Demo Mode to true and leave the credentials blank apart from the Alation Base URL, which can be any URL.
- Run Ingest Technical Metadata on the data source and open its catalog. Check the Ingestion Summary schema: every object type should say Loaded, or say which role it needs.
- For real use, turn Demo Mode off, fill in the Alation credentials and ingest again.
To install from a file instead, download the template from the marketplace listing and import it under Settings > Data Source Templates > Import.
Upgrading
Each Alation data source, and the connection of each Custom Metadata and Lineage Ingestion source that uses the template, keeps its own copy of the template's pre-execution script. Importing a newer template version does not update those copies, and saving a data source or connection again keeps the copy it already has. After an upgrade, open each of these connections and make sure its Pre-Execution Script matches the one in Settings > Data Source Templates > Alation, replacing it where it does not.
Version 1.2 corrects the batch publisher. Dimension scores are now published, trust scores are sent on the 0 to 100 scale used for quality and coverage, and tables that Validatar has not scored yet are skipped instead of showing zeros. After importing it, replace the pre-execution script on each connection as described above.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Ingestion stays at Running | The instance runs Python on a Data Agent and none is assigned or connected | Assign the data source to a Data Agent group whose agent is online |
| An object type shows "Skipped: not permitted" | The Alation role cannot read it | Grant Catalog Admin, or Server Admin for users, connectors, Agents and BI servers |
| An object type shows "Not available on this instance" | The feature is not on this Alation, for example Agents on customer-managed Alation or Data Products | Nothing to fix |
| Every call returns 401 | The refresh token expired, or the OAuth client was deleted or its secret regenerated | Update the credentials |
| Glossary terms appear under Document | The Glossary hub was not found automatically | Set Alation Glossary Hub ID |
| A tested table has no trust score rules in Alation | Validatar has not calculated the table's trust score since its tests ran. Trust scores are calculated on a schedule | Wait for the next calculation, or refresh the table's trust score in the Validatar catalog, then publish again |
| No dimension scores appear | The scope is Trust Score, the table's tests have no quality dimension, or the template is older than 1.2 | Choose Trust + Dimensions or wider, set a dimension on the tests, or upgrade the template |
| A test has no Actions section | The Standard Test Actions feature is off. It needs the license feature and the optional feature to be turned on | Ask a Validatar administrator to turn on Standard Test Actions |
| The test action reports "alation_object_key is empty" | The publish step has not run with Dry Run off since the test was opted in | Run the publish step once, or set Alation Object Key on the test |
Related Articles
- Alation Integration
- Alation Instance Health Checks
- Alation Metadata and Lineage Scripts
- Alation Catalog Custom Fields
- Alation Project Custom Fields
- What Is a Data Source Template?
- Python Script Data Source Template
Note: This template is built from Alation's published API specifications and has been validated in Validatar against its built-in sample Alation instance (demo mode). Both macros have run inside Validatar with Dry Run off: the publish step in a test job, and the test action on single tests, each through the template's own HTTP client. It has not yet been run against a live Alation environment, so parameters and behaviour may change after that validation.