# Alation Integration

To integrate Alation with Telmai, you'll use a set of REST API endpoints to manage the connection, automatically or manually create data mappings, and perform other configuration tasks. These API calls enable Telmai to interact with your Alation data catalog for seamless data governance.

## Setup

These endpoints allow you to configure, retrieve, and remove the core Alation integration with Telmai. All requests require your `backend_service_host` and `tenant` identifier.

## Add or Update Integration

Use this endpoint to establish the connection between Telmai and Alation or to update an existing one. You'll need your Alation URL, a user ID, and a refresh API token.

<mark style="color:orange;">`PUT`</mark> `{backend_service_host}/{tenant}/configuration/integrations/alation`

#### Request Body

```json
{
  "url": "https://<your_host>.alationcloud.com/",
  "user_id": 81,
  "refresh_api_token": "xxxxxx..."
}
```

#### Response

```json
{
  "url": "https://<your_host>.alationcloud.com/",
  "user_id": 81
}
```

***

## Get Integration Properties

Retrieve the current configuration details for your Alation integration. This call doesn't require a request body.

<mark style="color:blue;">`GET`</mark> `{backend_service_host}/{tenant}/configuration/integrations/alation`

#### Response

```json
{
  "url": "https://<your_host>.alationcloud.com/",
  "user_id": 81
}
```

***

## Remove Integration

Permanently delete the Alation integration from your Telmai environment.

<mark style="color:red;">`DELETE`</mark> `{backend_service_host}/{tenant}/configuration/integrations/alation`

#### Response

```json
{
  "message": "Alation integration configuration deleted successfully"
}
```

***

## Mappings

These endpoints handle the creation and management of mappings, which link Telmai data assets to specific tables in your Alation data catalog.

## Start Automatic Mappings

This endpoint initiates a background job to automatically create mappings for your assets. You can optionally choose to overwrite existing mappings.

<mark style="color:green;">`POST`</mark> `{backend_service_host}/{tenant}/configuration/mappings/alation/auto`

Request Parameters:

* `should_overwrite`: `true` or `false` (default is `false`).

#### Response

```json
{
  "message": "Creating Alation mappings started",
  "job_id": "f583cea0-640d-4c50-9153-e187f92a982e"
}
```

The response provides a `job_id` that you can use to track the status of the mapping job.

***

## Get Mapping Job Result

Check the status and results of an ongoing or completed automatic mapping job using its `job_id`.

<mark style="color:blue;">`GET`</mark> `{backend_service_host}/{tenant}/configuration/mappings/alation/auto`

Request Parameters:

* `job_id`: The `job_id` from the automatic mapping request.

#### Response

```json
{
  "status": "COMPLETED", // Can also be IN_PROGRESS or FAILED
  "error_message": null,
  "result": [
    {
      "asset_id": "35xftecujtsjd",
      "data_source_id": 251,
      "data_source_name": "telmai_datasource",
      "schema_id": 46,
      "schema_name": "adventureworks.SalesLT",
      "table_id": 6121,
      "table_name": "CustomerAddress"
    },
    ...
  ]
}
```

***

## List All Mappings

Retrieve a list of all existing Alation mappings configured in Telmai.

<mark style="color:blue;">`GET`</mark> `{backend_service_host}/{tenant}/configuration/mappings/alation`

#### Response

```json
[
  {
    "asset_id": "35xftecujtsjd",
    "data_source_id": 251,
    "data_source_name": "telmai_datasource",
    "schema_id": 46,
    "schema_name": "adventureworks.SalesLT",
    "table_id": 6121,
    "table_name": "CustomerAddress"
  },
  ...
]
```

***

## Delete a Mapping

Remove a specific mapping by providing its Telmai asset ID.

<mark style="color:red;">`DELETE`</mark> `{backend_service_host}/{tenant}/configuration/mappings/alation`

Request Parameters:

* `asset_id`: The ID of the Telmai asset to unmap.

#### Response

```json
{
  "message": "Alation mapping deleted successfully"
}
```

***

## Create a New Mapping Manually

Manually create a new mapping between a Telmai asset and an Alation table. You must provide the Telmai asset ID and the Alation table ID.

<mark style="color:green;">`POST`</mark> `{backend_service_host}/{tenant}/configuration/mappings/alation`

#### Request Body

```json
{
  "asset_id": "35xftecujtsjd",
  "alation_table_id": 6121
}
```

#### Response

```json
{
  "asset_id": "35xftecujtsjd",
  "data_source_id": 251,
  "data_source_name": "telmai_datasource",
  "schema_id": 46,
  "schema_name": "adventureworks.SalesLT",
  "table_id": 6121,
  "table_name": "CustomerAddress"
}
```


---

# 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/api-reference/alation-integration-apis.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.