HomeGuidesRecipesAPI ReferencePython SDK
Alation Help Center
API Reference

Open-With Registration

📘

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:
Field NameDescriptionAccepted Values
endpointYour app’s endpointURL to start a new workflow with a selected object from
Alation, including scheme (http or https), domain, port, and path. For example:
<https://app.customer.com/connection/from-alation/>.
endpoint_typeDetermines how we will try to reach this endpoint when opening an
object. See "Receiving Data."
nameYour app’s name : a short string that will appear in the Open With menu, with proper
capitalization, whitespace, punctuation, etc. For example: DataVisualizer.
accept_object_typesA list of the enumerated object types your app can accept. Use attribute for column objects.attribute, directory, file, query, table
accept_file_system_typesA list of file system types your app can accept. This field is required when accept_object_types is file or directory. Values are not case sensitive. ab_storage, hdfs, map_r, ocf, s3, unix
accept_data_source_typesA list of data source types your app can accept. This field is required when accept_object_types is attribute, query, or table. Values are not case sensitive.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 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.

Available in objectParameterExample OutputDetails
All objects${apiUrl}/api/table/7827/A JSON page that returns information about this table
All objects${catalogUrl}/table/7827/The Alation URL without the domain
All objects${oid}7827The Alation object ID (see the URL)
All objects${otype}table
All objects${semanticMetadata.description}

This is an example description

If the description has been added this will show
All objects${semanticMetadata.title}Page ViewsIf the ML/Allie guess has been confirmed or manually populated
All objects${userName}John Doe
All objects${userEmail}[email protected]
Queries${currentSqlText}
Queries${sqlTextApiUrl}
Tables and columns${catalogUrl}/table/7827/
Tables and columns${dataSource.apiUrl}/api/datasource/68/
Tables and columns${dataSource.catalogUrl}/data/68/
Tables and columns${dataSource.host}"bootstrapservers=""https://psrc-yorrp.us-east-2.aws.confluent.cloud"
Tables and columns${dataSource.jdbcUri}"Really:Long;JDBC-URI_HERE;"
Tables and columns${dataSource.oid}undefined
Tables and columns${dataSource.port}9093
Tables and columns${dataSource.semanticMetadata.description}Table Description
Tables and columns${dataSource.semanticMetadata.title}Table Name
Tables and columns${dataSource.type}customdb
Tables and columns${dataSource.database}This will return the database name if given in jdbcUri. Supported only for Greenplum, PostgreSQL, Redshift, SybaseEase, and Snowflake.
Tables and columns${location.column}Columns not supported
Tables and columns${location.schema}ApacheKafka
Tables and columns${location.table}pageviews
Tables and columns${qualifiedName}ApacheKafka.pageviews
Tables and columns${stewards}[email protected],[email protected]