Overview

Alation’s partners would like to add Alation’s data discovery features to their offering by providing access to Alation’s Catalog UI in their product at the moment of selecting a data object to work with. Alation can become a data application’s equivalent of the Mac Finder or Windows File Explorer modal that appears upon selecting File > Open.

An application developer can create a webview or an iframe that will load a page from the customer’s Alation instance. That page will provide a search and browse interface over the Alation catalog, with a select button. When the select button is clicked, information about the selected object is made available to the parent application.

Implementation

Alation will provide a Javascript SDK to launch and receive events from Alation Embeddable CatalogChooser. For other programming environments (e.g. Windows or Mac native apps), please contact an Alation representative for more details on the integration.

Including the SDK

The SDK is hosted on the Alation instance itself. You will need to know the URL of the Alation instance in order to load the SDK. This includes the scheme (HTTP or HTTPS, depending on how the customer has configured it), domain, and port. Once you have this information, add a script tag to your application to load the SDK:

<script type="text/javascript"
src="<scheme>://<domain>:<port>/integration/catalog_chooser/v1/sdk.js" />

When the script loads, it will add a globalAlationobject that can be used to access the SDK functions.

Creating the View

To initialize the Alation Embeddable CatalogChooser view, use thecreateChooserfunction:

var alationCatalogChooser = Alation.Catalog.createChooser({
      embedMethod: Alation.Catalog.ChooserEmbedMethod.MODAL, // How to open the chooser (currently MODAL or CUSTOM)
      onSelect: function (data) {}, // Callback for when user selects an object
      onCancel: function () {}, // Callback for when the user cancels
      acceptObjectTypes: [] // List of acceptable oTypes (empty == all)
});

Embed Method

Alation provides a convenient method for opening the chooser in a modal, with some default styling. This is the defaultembedMethod.

If you prefer not to use the modal you can choose theCUSTOMmethod and attach the Chooser element however you’d like. Note, alationCatalogChooser.open() will throw an error in this case.

var alationCatalogChooser = Alation.Catalog.createChooser({embedMethod:
ChooserEmbedMethod.CUSTOM});
document.body.append(alationCatalogChooser.element);

If you use the CUSTOM method, the create Chooser function will create the DOM element without inserting it into the current document. You can insert it into the document however you wish using the element property on the returned object.

Opening the CatalogChooser

If you have chosen the MODAL embed Method, you can activate the CatalogChooser by calling alationCatalogChooser.open(). This will reset the iFrame to the Alation home page, for users to start at. If
using the built in modal, this will also open the modal for the user to see.

Filtering the object types

Alation’s catalog captures a wide variety of types of objects, from tables to queries to articles to users. In any particular instance, your application may only be able to accept certain types of objects. Specify these with the acceptObjectTypesparameter oncreateChooser.

var alationCatalogExplorer = Alation.Catalog.createChooser({
accept **Object** Types: [
      Alation.Catalog.ObjectType. **TABLE** ,
      Alation.Catalog.ObjectType. **QUERY** ,
]
});

You can additionally filter to only data objects in/on particular types of data sources:

var alationCatalogExplorer = Alation.Catalog.createChooser({
  accept DataSource Types: [
      Alation.DataSourceType. BIGQUERY,
      Alation.DataSourceType. DB2,
      Alation.DataSourceType. GREENPLUM,
      Alation.DataSourceType. HIVE2,
      Alation.DataSourceType. IMPALA,
      Alation.DataSourceType. MYSQL,
      Alation.DataSourceType. NETEZZA,
      Alation.DataSourceType. ORACLE,
      Alation.DataSourceType. ORIENT,
      Alation.DataSourceType. POSTGRESQL,
      Alation.DataSourceType. PRESTO,
      Alation.DataSourceType. REDSHIFT,
      Alation.DataSourceType. SAP,
      Alation.DataSourceType. SAS,
      Alation.DataSourceType. SNOWFLAKE,
      Alation.DataSourceType. SQLITE,
      Alation.DataSourceType. SQLSERVER,
      Alation.DataSourceType. SYBASE,
      Alation.DataSourceType. TERADATA,
      Alation.DataSourceType. TERADATAASTER,
      Alation.DataSourceType. VERTICA
    ]
  });

Cleaning up the CatalogChooser

To destroy the Catalog Chooser you can usealationCatalogChooser.destroy(); which will remove elements
from the DOM and clean up event listeners.

Listening to Events

Embeddable CatalogChooser provides two events:

• Cancel event when the user closes the view
• Select event when the user selects an object

Handling Cancellation

When a user cancels the selection process from inside the Alation view, the SDK will destroy all DOM elements that
it created. Then it will notify any handlers registered with theonCancelfunction.

alationCatalogExplorer.createChooser({function () {
console.log("The explorer view is gone");
// Do any other cleanup here
});

If you would like to close the view yourself, you can do so with thedestroyfunction. TheonCancelhandlers will
not be called.

alationCatalogExplorer.destroy(); // Will close the active Chooser Modal

Handling Selection

To listen for selection, register a callback with theonSelectfunction. It is your responsibilityto close and clean up
the Alation view with thedestroyfunction.

alationCatalogExplorer.onSelect(function (selectedObject) {
  if (!isValid(selectedObject)) {
  alert("Please select a different object");
  return;
}
alationCatalogExplorer.destroy();
// handle the selection
});

The selected Object will be an Alation Object ReferenceJSON object as defined below.

Alation Object Reference JSON

See the table below for more details and example outputs from a table.

References to objects in Alation will always have the following fields:

• otype: Object type, one of those specified inAlation.Catalog.ObjectTypes.Currently one of: table and
  query.
• oid: Alation Object ID (these are not unique acrossobject types, so a unique ID requires theotypeas
  well)
• catalogUrl: URL for the catalog page for this object,in the customer’s Alation instance.
• apiUrl: URL for the canonical API resource for thisobject, in the customer’s Alation instance.
• semanticMetadata: The user-contributed metadata capturedby Alation.
• may be Null
• title: The logical title (short, plain text) in Alation.
• description: The logical description in Alation (HTML rich text).

Data objects (tables and columns) will have the followingadditional fields:

• qualifiedName: Fully qualified name for relationalobjects, e.g.
  [database/catalog.]schema.table[.column]
• qualifiedNameParts: Fully qualified name as an arrayof name parts. Note that if the database has
  multipart schema names, they are a single entry in this array. E.g.["catalog.schema", "table",
  "column"]
• location: A JSON object with names of this object’s parents.
  • schema
  • table
  • column
• tsLastExtracted: aDate()object representing thetime Alation last extracted the object.
• dataSource: details about the database / data warehouse/ Hive instance that this object belongs to.
• oid: Alation Object ID.
• catalogUrl: URL for the catalog page for this object,in the customer’s Alation instance.
• apiUrl: URL for the canonical API resource for thisobject, in the customer’s Alation instance.
• semanticMetadata: The user-contributed metadata capturedby Alation.
  • See above
• jdbcUri: URI used to configure the JDBC driver forthis data source.
• type: a string for the source type, e.g. “Hive” or“MySQL”.
• host: IP address or domain name.
• port: TCP port.
• database: The database name to connect to (usuallyadded after the domain and port in the JDBC
  URI)
  * may be Null

Query objects will have the following additional fields:

• currentSqlText: String of the current text contentof the SQL query. May contain multiple SQL
  statements.
• sqlTextApiUrl: an endpoint which returns the currenttext content of the SQL query, for the client to
  display or execute