Implementation Overview

Initial Registration

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

• create an API endpoint on your app’s server thatcan receive anAlation Object Reference JSONobject
  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 (ideallythe same page used to configure Alation Data
  Explorer / the Embeddable CatalogChooser) with fields for
  the base URL of the customer’s Alation instance, and
  an Alation API Token

Clicking the Register button should POST an API request to /integration/v2/catalog_chooser/register_opener/ onthe Alation instance with the following information:
An HTTP headerTokenwith the customer’s Alation APIToken. A JSON object describing the integration with the following fields:

• endpoint- your app’s endpointURL to start a newworkflow with a selected object from
  Alation, including scheme (http or https), domain, port, and path. E.g.,
  https://app.customer.com/connection/from-alation/
• endpoint_type- Determines how we will try to reachthis endpoint when opening an
  object. See“Receiving Data”.
• name- your app’s name : a short string that will appearin the Open With menu, with proper
  capitalization, whitespace, punctuation, etc. E.g. “DataVisualizer”
• accept_object_types- A list of the enumeratedotypesyour app can accept out of
  • table
  • column
  • query

Accept_data_source_types

• customdb
• bigquery
• db
• greenplum
• hive
• impala
• mysql
• netezza
• oracle
• orient
• postgresql
• presto
• redshift
• sap
• sas
• snowflake
• sqlite
• sqlserver
• sybase
• teradata
• teradataaster
• Vertica

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 ofthe type specified inaccept_object_typeswithin sources ofthe 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] [otype]. Accepted types: [...]” (e.g. “DataVisualizeris not compatible withTeradataTables.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 anAlation Object Referenceobjectto the specified endpoint in form-encoded format. Your API
must respond with a JSON object with a single keytelling 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 withendpoint_type: "NAVIGATE",then Alation will directly open a browser tab to the your specifiedendpoint. To get information aboutthe 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 theAlationObject 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.