📘

Not Tested with OCF

Alation's Open-With functionality has not been tested with our OCF connectors.

Implementation Overview

Initial Registration

To get your app to appear in Alation Catalog’s OpenWith menu (on appropriate object pages) and to wire things up
so that it works, you must:

• Create an API endpoint on your app’s server that can receive an Alation Object Reference JSON object
  and send the user to a screen in your app for a new workflow built around that object and
• Create a page on your server’s admin settings (ideally the same page used to configure Alation Data
  Explorer / the Embeddable CatalogChooser) with fields for:
  • The base URL of the customer’s Alation instance
  • An Alation API Token

Clicking the Register button should POST an API request to /integration/v2/catalog_chooser/register_opener/ on the Alation instance with the following information:

• An HTTP header Token with the customer’s Alation APIToken.
• A JSON object describing the integration with the following fields:

Alation will return a success message or one of the following error codes:

• 400 - You entered an invalid parameter
• 401 - You’re not authenticated
• 403 - You’re authenticated with a token that is not permitted to register new openers
• 500 - Unknown server error

On success, that Alation instance will include your app’s name in the Open With menu on each page of the type specified in accept_object_types within sources of the types specified in accept_data_source_types. If the
object does not fit within your accepted-type constraints, then your name will be listed but disabled (“grayed out”) with the tooltip “[Your app’s name] is not compatible with [DS type] [object type]. Accepted types: [...]” (e.g. “DataVisualizer is not compatible with Teradata Tables. Accepted Types: Tables and Columns on Hive, SQL Server,
and Postgres.”)

Receiving Data

If the user selects your app, Alation will send data about the chosen object to your endpoint. There are two
endpoint types:

• POST (default) - Alation makes a POST request to your endpoint, then opens a browser tab to the location
  returned from your endpoint.
• NAVIGATE - Alation opens a browser tab directly to your endpoint. In this case your endpoint should be
  configured with template variables to receive details of the Alation object in the URL.

POST Endpoint Type

Alation will POST an Alation Object Reference object to the specified endpoint in form-encoded format. Your API
must respond with a JSON object with a single key telling us where to direct the user:

{ "location": "https://my-app-server/dashboard/100" }

NOTE: A popup blocker may prevent your page from opening successfully.

Alation will open a new browser tab (which will open your Desktop app in the case of a deep link) and load the specified location, so the user can begin their journey with your tool.

NAVIGATE Endpoint Type

If you register your opener with endpoint_type: "NAVIGATE", then Alation will directly open a browser tab to the your specified endpoint. To get information about the selected object, you should add template variables to your endpoint with the following syntax:

{
  "endpoint_type": "NAVIGATE",
  "endpoint":
  "https://my-app-server/create-dashboard?uri=${dataSource.jdbcUri}&table=${qualifiedName}"
}

The variables should reference fields in the Alation Object Reference JSON. It’s possible that users may not be logged in to your application (or even registered yet) so the endpoint URL should hold on to the data so you can retry the creation after the user logs in.

Updating a registration

To change your Open With configuration, you can send DELETE, PUT, and PATCH requests to
/integration/v2/catalog_chooser/register_opener//

Below are a couple examples. For both cases, the first step is to

**POST** to https://alation.company.com/integration/v2/catalog_chooser/register_opener/
{
  "endpoint":"https://coolapp.company.com/connection/from-alation/",
  "name": **"Cool App"** ,
  "accept_object_types":["table"],
  "accept_data_source_types": **["mysql"]** 
  }

Broadening Support

We can use PATCH to extend the existing integration to also accept tables in Oracle. The name, endpoint, etc. are
unchanged:

PATCH

{"accept_data_source_types": ["mysql", "oracle"] }
to
https://alation.company.com/integration/v2/catalog_chooser/register_opener/ Cool%20App
/

Changing Name

In this case, we must DELETE and re-POST because the name is changing:

DELETE

https://alation.company.com/integration/v2/catalog_chooser/register_opener/Cool%20App/

POST

**POST** to https://alation.company.com/integration/v2/catalog_chooser/register_opener/
{
"endpoint":"https://coolapp.company.com/connection/from-alation/",
"name": "Cooler App 2" ,
"accept_object_types":["table"],
"accept_data_source_types": ["mysql"] 
}

With Open With, Alation can help the user find a trusted data asset, and be a referral to your app where they can put it to use.

Alation Object Reference

Parameters Available from DataOS - Open With

Data OS allows you to bake in Alation variables into the API call to the other application. The example outputs shown come from the below Alation page.