HomeGuidesRecipesAPI ReferencePython SDK
Alation Help Center
Guides
Alation Help Center

VS BI Quick Start

Suggest Edits

Requirements

Role

The use of this API requires the role of a Server Admin.

Overview

New Business Intelligence (BI) APIs, or Generic Business Intelligence Model (GBMv2) APIs, permit admin users to create, update, delete, and read catalog pages of BI sources. The key advantage of using GBMv2 APIs is that admins can build the catalog from any BI source in a structured way.

The GBM V2 APIs are described using the Open API 3.0 Specification (OAS). OAS is a broadly adopted industry standard for describing APIs. OAS 3.0 specification (Swagger) describing GBMv2 APIs can be found at the following URL:

<alation_instance_url>/openapi/gbmv2/

The RESTful operations supported by GBM V2 APIs permit developers to build integrations to manage resources using a set of CRUD operations referring to Create (POST), Read (GET), Update (PATCH) and Delete (DELETE).

This document will show BI catalog pages for explanation of the use of GBM V2 API for generating the catalog structure.

GBM V2 APIs primarily provide building BI catalog pages with the following APIs:

  • BI Server APIs APIs for managing catalog for the top container of all BI objects: BI Server catalog page
  • BI Folder APIs APIs for managing catalog for Site, Project, and Workbook pages: they all use one common template.
  • BI Report APIs APIs for managing catalog reports, views. Both Report and Dashboard objects use one common template.
  • BI Report Column APIs APIs for managing catalog for fields
  • BI Data Source APIs APIs for managing catalog for Data sources used to create BI reports
    • When Alation draws lineage from supported BI sources, it will connect to the source table with a BI Data Source connection that then connects to the BI report/dash
  • BI Data Source Column APIs APIs for managing catalog for BI Datasource columns
  • BI Connections APIs APIs for managing catalog for Connection used in BI
  • BI Users APIs APIs for managing BI Users in Alation
  • BI Permissions APIs APIs for managing permissions between Alation users and BI catalog pages

The GET API requests from this set of APIs will work for any BI server sources on GBM V2. All other methods can only be used to manage virtual BI server sources that are managed using APIs only. To give an example using Tableau, the Tableau catalog pages map to GBM V2 API model as follows:

1027

BI Server APIs

BI Server APIs provide Open API based Bulk and individual endpoints that permit you to create BI server catalog pages:

1444

The BI Server page has built-in and custom fields currently associated with the BI Server template in your Alation instance. It has two tabs:

  • Overview
  • Datasources

The Overview page includes any custom and built-in fields associated with the page template and the list of its child objects.

The server APIs permit you to create a BI Server. The BI Server page is a top catalog page that links to all the other pages:

1600

The BI Server name configuration permits you to change catalog page names of Report, Folder, Data Source and Connection. With this, you can change the catalog page name from default values. In this example, Report appears as BI_Report:

[
    {
      "uri": "www.bi.com",
      "title": "Generic BI v2 API",
      "description": "Generic BI v2 API",
      "name_configuration":
      {
        "bi_report": "BI_Report",
        "bi_folder": "BI_Folder",
        "bi_datasource": "BI_DataSource",
        "bi_connection": "BI_Connection"
      }
    }
  ]

BI Folder APIs

BI Folder APIs provide open API-based bulk and individual endpoints that permit you to create BI Folders as below:

1404

The BI Folder APIs permit you to create projects and BI sites and those will be listed in the Folders table. To view data for each specific project, click its Name. The page displays built-in and custom fields currently associated with the BI Folder template. The page has four tabs:
Overview
 Reports
Sources
 Fields

Not all tabs are required. for example, Reports, Sources, and Fields may not be used for the site objects.

The BI Folders API also permits you to create a project page that lists the child projects and workbooks for the current project. The projects and workbooks for the parent project can be found in the Folders field under the Overview tab. To view data for each specific project or workbook, click its Name. The Data Sources tab displays the published data sources used by workbooks in this project. Tabs Reports and Fields not used for the projects remain empty. The BI Folder API also permits you to create BI workbook page that displays built-in and custom fields currently associated with the BI Folder template:

1600

BI Report APIs

BI Report APIs provide Open API-based bulk and individual endpoints that permit you to create BI reports catalog page as shown below.

708

Each BI report view page, Sheet or Dashboard, is based on the BI Report template and includes:

* Overview tab with a preview (in the future version)
* the fields (measures and dimensions) used in this view, on the **Fields** tab
* Data sources that are used in this view, on the **Sources** tab
* table-level data lineage, on the **Lineage** tab.

The num_accesses and popularity parameters in the BI Report API are used as input for popularity calculation then shown in UI. To open the dedicated catalog page of a specific view, datasource, or field, click its Name. The views in the workbook are created using the BI Reports API and are on the Reports tab of the page:

1000 1600

BI Report Column APIs

BI report column APIs provide Open API-based bulk and individual endpoints that permit you to create BI fields catalog page in BI reports:

606

Each report column or view field has a catalog page based on the BI Report Column template. The API permits you to provide data type, role, expression. Based on the data provided with API, the Properties field on the right will indicate if this field is a measure or a dimension and what data type it holds. The formula used to calculate the field can be found under Expression.

The report columns in the report are created using the BI Reports Column API and will be on the Fields tab of the Report page:

732

BI Report Images

BI report images APIs provide Open API-based individual endpoints that permit you to add preview images in BI reports:

1488 1600

BI Data Sources APIs

BI data sources APIs provide Open API-based bulk and individual endpoints that permit you to create BI data sources catalog pages:

1312

The BI data source is the actual data source used to create the BI views. Its page is based on the BI Datasource template and includes the Overview tab that displays the built-in and custom fields currently associated with the template.

1424

The BI data source API permits you to create data sources that are displayed on the data sources tab:

1600

BI Data Sources Columns APIs

Click a BI datasource name on any of the catalog pages where it exists to bring you to the dedicated page for this datasource.

1328 1340

Click the name of a datasource field takes you to its dedicated page, which is based on the BI Datasource Column template. The Expression field shows how the data in this field is calculated.

BI Connections APIs

The BI connections APIs provide Open API based Bulk and individual endpoints that permit you to create connection catalog page:

1238

The BI connections API permits you to show the connection information for the datasource and points to the source of the data, outside the BI server. For example, it shows if the datasource is a live database connection and what database connection it comes from. The type of connection is indicated under Connection Type in Properties on the right of the page. The connection UI displays only after creating a data source that has connection as parent.

1600

BI User

BI users APIs provide Open API-based bulk and individual endpoints that permit you to create, update, delete and read BI users. The key use case for BI users API is to mirror BI permission in Alation. There is no catalog page corresponding to BI users API.

1600

The user details can be created as shown below:

{
  "name": "[email protected]",
  "external_id": "U_003",
  "created_at": "2019-12-08T02:22:55.482Z",
  "last_updated": "2019-12-08T02:22:55.482Z",
  "source_url": "www.looker.com",
  "bi_object_type": "Standard User",
  "description_at_source": "Generic BI Standard User",
  "username": "[email protected]",
  "domain_name": "LOCAL"
  }
]

BI Permissions

BI Permissions APIs provide Open API-based bulk and individual endpoints that permit you to create, update, delete and read BI permissions. This and the Users API permits you to mirror BI permission model for Alation BI catalog pages.

As an example, the following two report pages show differences in reports available based on users’ permission levels:

User 1 with Permission to Sales and Samples reports:

1386

User 2 with Permission to Sales and Samples and Dashboard reports:

1000

To use permissions, make sure to uncheck Disable Permission Enforcement in the BI server settings:

1056 1600

Lineage to BI Objects

You will need to leverage the BI Source (GBMv2) Overview API and the Lineage & Dataflows Overview API.

It is recommended to connect lineage via Source Table-> BI Data Source -> BI Report/Dash as this will mirror Alation's automated lineage for the supported BI sources.

In order to connect the lineage together, you will need:

  • Table key formatted <datasource_id>.<schema_name>.<table_name>
    • example: 3.test_profiling_main.stpsale
    • example: 3.test_profiling_main.stpsalesample
  • BI Data Source key formatted <bi_server_id>.bi_datasource.<external_id>
    • example: 1.bi_datasource.ce4d5948-69ae-11ec-90d6-0242ac120003
  • BI Report/Dash key formatted <bi_server_id>.bi_report.<external_id>
    • example: 1.bi_report.6d4b174b-9407-4c04-8bbf-a2faf65231f7

The below JSON payload will generate the below output:

{
    "dataflow_objects": [],
    "paths": [
        [
            [
                {"otype": "table", "key": "3.test_profiling_main.stpsale"},
                {"otype": "table", "key": "3.test_profiling_main.stpsalesample"}
            ],
            [
                {"otype": "bi_datasource", "key": "1.bi_datasource.ce4d5948-69ae-11ec-90d6-0242ac120003"}
            ],
            [
                {"otype": "bi_report", "key": "1.bi_report.6d4b174b-9407-4c04-8bbf-a2faf65231f7"}
            ]
        ]
    ]
}
722

BI Object Type Reference

  • BIReport = bi_report
  • BIReportColumn = bi_report_column
  • BIDataSource = bi_datasource
  • BIDataSourceColumn = bi_datasource_column
  • BIFolder = bi_folder
  • BIConnection = bi_connection
  • BIConnectionColumn = bi_connection_column

Updated about 1 year ago