# Alation Integration

Telmai integrates with [Alation](https://www.alation.com/) to push data quality results directly into your Alation data catalog. The integration is one-directional: Telmai sends results to Alation, not the other way around.

## Overview

Setup involves steps in both platforms:

| Platform    | What you do                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------- |
| **Alation** | Create a custom Rich Text field named **Telmai Observability** and generate a Refresh API Token |
| **Telmai**  | Connect to Alation using the token, then map Telmai assets to Alation tables                    |

***

## Step 1: Prepare Alation

### Create the Custom Field

Telmai writes results into a [Rich Text custom field](https://docs.alation.com/en/latest/steward/TemplatesAndCustomFields/AboutTemplatesAndFields.html#rich-text) in Alation. The field must be named exactly:

```
Telmai Observability
```

Create this field in Alation under **Settings > Customize Catalog > Custom Fields** and attach it to the Table object type.

### Generate a Refresh API Token

Telmai authenticates to Alation using a Refresh API Token tied to a specific user account.

To generate one in Alation:

1. Sign in as the Alation user account Telmai will use
2. Go to **Settings > Account** (or your profile menu)
3. Navigate to the **API Tokens** section
4. Click **Generate Token** and copy the token value

{% hint style="warning" %}
Store this token securely. Telmai uses it to write data to your catalog on an ongoing basis.
{% endhint %}

***

## Step 2: Connect Telmai to Alation

You can configure the connection from the **Administration** page in Telmai (under **Settings > Alation**) or via API.

<figure><img src="/files/ptDNXBIcFBNQ7gxXhZHV" alt="Alation settings panel in Telmai Administration showing fields for Alation Cloud URL, User ID, and Refresh API Token"><figcaption><p>The Alation connection form under Administration — enter your Alation URL, User ID, and Refresh API Token, then click <strong>Connect</strong>.</p></figcaption></figure>

You will need:

* **Alation URL** — the base URL of your Alation instance (e.g., `https://your-org.alation.com`)
* **User ID** — the numeric Alation user ID for the account associated with the token
* **Refresh API Token** — the token generated in Step 1

Once connected, Telmai confirms the setup by returning your Alation URL and user ID.

#### Modifying or Removing the Integration

You can update the integration at any time by providing new credentials. To remove it entirely, delete the connection in Telmai — Telmai will confirm that the integration has been successfully removed.

***

## Step 3: Map Assets

Data mappings link Telmai data assets to their corresponding tables in Alation. Without a mapping, Telmai cannot write quality results to the correct catalog entry.

### Automatic Mapping (Recommended)

Telmai can scan both platforms and create mappings automatically.

* Trigger the auto-mapping job from the Telmai UI or API
* Optionally choose to overwrite existing mappings
* Telmai returns a job ID so you can track progress

### Manual Mapping

If you prefer to control mappings individually, you can create them one at a time by providing a Telmai asset ID and the corresponding Alation table ID.

### Managing Mappings

You can list all existing mappings or delete a specific mapping by its Telmai asset ID at any time.

### Checking Mapping Job Status

Use the job ID returned when you triggered auto-mapping to check progress. On completion, the result lists each new mapping with:

* Telmai Asset ID
* Alation Data Source ID and Name
* Alation Schema ID and Name
* Alation Table ID and Name

***

## API Reference

All Alation integration operations are also available via API. See [Alation Integration APIs](/telmai/api-reference/alation-integration-apis.md) for the full reference.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.telm.ai/telmai/integrations/alation-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.