Tableau OCF Connector: Install and Configure

The Tableau OCF connector can be used to catalog objects from Tableau Server or Tableau Cloud. Follow these steps to perform the required configuration on the Tableau side and in Alation.

Prerequisites

Enable Metadata API for Tableau Server

Refer to Enable metadata-services. Enabling Metadata API may take up to 48 hours depending on the volume of metadata.

Note

The Metadata API is enabled by default for Tableau Cloud.

Enable Sensitive Lineage Data Setting

In Tableau:

1. Go to Site Settings > General > Sensitive Lineage Data.

2. Make sure that Show complete lineage (default) is selected.

Note

If this option is not selected, some Tableau objects will not be extracted.

This setting is applicable for both Tableau Server and Tableau Cloud.

Required Information

URI

Use the URL of Tableau Server or Tableau Cloud.

Example: https://tableau2021.alationcatalog.com

Site ID

A site ID is the text after the #/site/ part of the URL of a Tableau page, in front of the next slash. In the example below Sales is the site ID:

https://prod-useast-a.online.tableau.com/#/site/Sales/explore

You can specify multiple site IDs separated with commas.

Tableau Server

The Tableau Server site ID information is used for authentication. You can provide a single valid site ID and the connector will discover all the other sites that the service account has access to. If the field is left empty, the connector will use the default site.

Tableau Cloud

For Tableau Cloud, Alation will only extract metadata from the sites with the IDs you have specified. If the field is left empty, the test connection will fail and no metadata will be extracted.

SSL Certificate

If connecting over SSL, obtain the SSL certificate. It will need to be uploaded in the Tableau BI source settings in Alation.

Authentication

The Tableau OCF connector requires a service account with site administrator privileges. Authentication can be configured on the BI source Settings page.

The following authentication types are supported by Alation:

• Basic authentication with a username and password

• Personal access token

The Tableau OCF connector does not support SSO authentication to Tableau.

Note

For Tableau Cloud, if multi-factor authentication (MFA) is enabled, personal access token authentication is the only choice.

Authentication with Active Directory

Authentication with Active Directory is supported through basic authentication (username and password). Use the following format for the username when configuring the Tableau BI source settings in Alation:

• For Username, use domain_name\ADusername, where ADusername stands for the Active Directory username.

• For Password, use the Active Directory password of the Active Directory username.

Extracting User Permissions Information from Multiple Domains

When permissions mirroring is enabled for a Tableau BI data source, Alation can extract user permissions information from multiple domains. To make extraction from multiple domains possible, perform the following configuration in Tableau and Active Directory:

• In Active Directory, make sure that the domains you will extract from have bi-directional trust with the AD server that has Tableau installed. Users must be able to log into the Tableau instance using the credentials from another AD server.

• Ensure that the Active Directory groups are imported and set up in Tableau.

Configuration in Alation

STEP 1: Install the Connector

Alation On-Premise

Important

Installation of OCF connectors requires Alation Connector Manager to be installed as a prerequisite.

To install an OCF connector:

1. If this has not been done on your instance, install the Alation Connector Manager: Install Alation Connector Manager.

2. Ensure that the OCF connector Zip file is available on your local machine.

3. Install the connector on the Connectors Dashboard page using the steps in Manage Connectors.

Alation Cloud Service

Note

On Alation Cloud Service instances, Alation Connector Manager is available by default.

Depending on your network configuration, you may need to use Alation Agent to connect to databases.

Connection via Alation Agent

1. Ensure that Alation Agent is enabled on your Alation instance. If necessary, create a Support ticket with Alation for an Alation representative to enable the Alation Agent feature on your instance and to receive the Alation Agent installer.

2. Install the Alation Agent.

3. Install the OCF connector on Alation Agent.

Connection Without Agent

To install an OCF connector:

1. Ensure that the OCF connector Zip file is available on your local machine.

2. Install the connector on the Connectors Dashboard page using the steps in Manage Connectors.

STEP 2: Create and Configure a New BI Server Source

This configuration requires the role of Server Admin.

To add a new BI server source:

1. Log in to the Alation instance.

2. From the Apps menu on top right, select Sources. The Sources page will open.

3. On the upper right, click Add and in the list that opens, select BI Server. The Register a Business Intelligence Server screen will open.

4. From the Select a Business Intelligence Server type list, select the OCF connector for Tableau. The connector name appears in this list only after it was installed.

   

5. Specify a Title and a Description (optional) for your Tableau OCF BI source.

   

4. Click Add. You will be navigated to your new BI Server source Settings page.

Configure Tableau OCF BI Source

Note

This section describes configuring settings for credentials and connection information stored in the Alation database. If your organization has configured Azure KeyVault or AWS Secrets Manager to hold such information, the user interface for the General Settings page will change to include the following icons to the right of most options:

By default, the database icon is selected, as shown. In the vault case, instead of the actual credential information, you enter the ID of the secret. See Configure Secrets for OCF Connector Settings for details.

Perform the configuration on the Settings page. Save the values in each section of the settings by clicking Save.

Application Settings

Parameter	Description
Enable Raw Dump or Replay	The options in this drop list can be used to dump the extracted metadata into files in order to debug extraction issues before ingesting the metadata into Alation. This feature can be used during testing in case there are issues with extraction. It breaks extraction into two steps: first, the extracted metadata is dumped into files and can be viewed; and second, it can be ingested from the files into Alation. We recommend to use this feature for debugging only. Enable Raw Metadata Dump: Select this option to save extracted metadata into a folder for debugging purposes. The dumped data will be saved in four files (attribute.dump, function.dump, schema.dump, table.dump) in folder opt/alation/site/tmp/ inside Alation shell. Enable Ingestion Replay: Select this option to ingest the metadata from the dump files into Alation. Off: Disable the Raw Metadata Dump or Replay feature. Extracted metadata will be ingested into Alation.
Disable Automatic Lineage Generation	Select the Disable Automatic Lineage Generation checkbox to skip the creation of lineage data automatically. When automatic lineage generation is disabled, during extraction Alation does not calculate lineage data for this BI source during extraction. For more information, see Automatic Lineage Generation FAQ.
Disable Permission Enforcement	Select this checkbox to disregard user permissions on Tableau server and to not perform permission enforcement. This setting does not disable permission extraction by the connector. By default this checkbox is selected, and Alation will not mirror Tableau permissions.
Disable Certification	Select this checkbox to disable the Tableau Certification feature. If selected, Alation will not propagate flag information to the Tableau server.
Server URI	Enter the server URI to access the Tableau objects.

Connector Settings

Parameter	Description
Server Connection
URI	Enter the URI to access the Tableau instance.
Username	In case of basic authentication, specify the username of the Tableau service account. For Active Directory, specify the username in the following format: domain_name\ADusername
Password	In case of basic authentication, specify the password of the Tableau service account. For Active Directory, use the Active Directory password.
Tableau site ID	Provide site IDs separated with commas. See Site ID for more details.
Tableau Online/Only Extract from SiteIDs above	Select this checkbox if connecting to Tableau Cloud or if you want to limit extraction from Tableau Server to the specified site IDs.
Enable Personal Access Access Token for authentication	Enable this checkbox to use the Personal Access Token and Personal Access Token Secret for authentication instead of username and password.
Token name	Provide the personal access token.
Token secret	Provide the personal access token secret.

Additional Settings

Parameter	Description
Disable Permission Extraction	Select this checkbox to disregard user permissions in Tableau and to not perform permission extraction. By default this checkbox is clear, and Alation will extract Tableau permissions.
Disable SSL Certification	Select this checkbox if not connecting using SSL.
Server SSL Certificate	If connecting over SSL, upload the SSL certificate for Tableau Server.
Disable preview extraction	Select this checkbox for not to extract previews. By default this checkbox is clear, and Alation will extract previews, such as thumbnails, PNG images, and CSV files.
Disable high resolution preview extraction	Select this checkbox to disable extraction of PDFs for reports and dashboards.
Auto-extract Alation-certified projects	Select this checkbox to automatically add Alation-certified projects to the list of projects to extract.
User domain name	Domain name for Tableau users that Alation should extract the permissions for when permissions mirroring is enabled. This is the value of the name attribute of the domains table in Tableau PostgreSQL database. Alation supports extraction from multiple domains. When specifying multiple domains in this field, separate them with commas. Ensure you have performed the required configuration in Active Directory: Extracting User Permissions Information from Multiple Domains.
Project extraction batch size	This parameter sets the batch size for workbook extraction. Note that although this parameter is defined for workbooks, the batch is formed based on the number of projects. In this parameter, you are setting the number of projects for which Alation will extract ALL workbooks in one extraction batch. For example, if you set this parameter to 5, it would mean that workbooks will be extracted in several batches, each batch being “all workbooks from first five projects”, then “all workbooks from the second five projects”, and till the end of the list.
Published datasource extraction batch size	Published data source extraction is batched by the number of data sources that Alation processes in a single batch.
Workbook processing batch size	This parameter sets the batch size for projects. It defines the number of projects Alation will process in a single batch.
Enable MDE for auto-generated embedded datasources	Enable this checkbox to extract auto-generated embedded data sources. Note This field is available from connector version 1.6.7.
Disable auto pagination	Enable this checkbox to disable the auto pagination. By default this checkbox will be disabled. Note This input field is removed from connector version 1.6.7 and pagination is always enabled by default.
Number of workbooks to return per request (Pagination)	Provide the number of workbooks to be returned per extraction. It is recommended to extract 30 to 80 workbooks per extraction Note Reduce the number of workbook count if you get a NODE_LIMIT_EXCEEDED exception for workbooks during extraction. Note This input field is removed from connector version 1.6.7 and pagination is always enabled by default.
Number of datasources returned per request (Pagination)	Provide the number of data sources to be returned per extraction. It is recommended to extract 300 data sources per extraction. Note Reduce the number of datasources count if you get a NODE_LIMIT_EXCEEDED exception for datasources during extraction. Note This input field is removed from connector version 1.6.7 and pagination is always enabled by default.
Number of connections to return per request (Pagination)	Provide the number of results to return when extracting connections/relations/database tables. It is recommended to extract 600 connections per extraction. Note Reduce the number of connection count if you get a NODE_LIMIT_EXCEEDED exception Note This input field is removed from connector version 1.6.7 and pagination is always enabled by default.
Number of fields/columns to return per request (Pagination)	Provide the number of results to return when extracting fields/columns. It is recommended to extract 1000 fields/columns per extraction. Note Reduce the number of fields/columns count if you get a NODE_LIMIT_EXCEEDED exception Note This input field is removed from connector version 1.6.7 and pagination is always enabled by default.
Certified project suffix	Define the suffix for the project certified by Alation. If a workbook is certified in Alation, it will be moved to a new project with the name <project_name - certified project suffix>, for example, <Population Growth Analysis - Alation Certified>.
Enable view data extraction	Enable the checkbox to extract the sample of the distinct values of all report columns. Extraction will become considerably slow if this checkbox is enabled. For example, if the report column names are Connector, Connector Type, and Case Data and the CSV headers are Connector, Connector Type, and Date/Time Opened, only Connector and Connector Type data will be extracted.
View data sample size	Provide the data sample size.
Request timeout in seconds	Provide the download timeout for CSV, low resolution previews, and high resolution previews.

Logging Configuration

Select the logging level for the connector logs and save the values by clicking Save in this section. The available log levels are based on the Log4j framework.

Parameter	Description
Log level	Select the log level to generate logs. The available options are INFO, DEBUG, WARN, TRACE, ERROR, FATAL, ALL.

Test Connection

After specifying the connector settings, under Test Connection, click Test to validate network connectivity.

Extraction

To configure extraction:

1. Under Extraction Settings, turn on Selective Extraction, if required. Selective extraction settings are used to apply a filter to include or exclude a list of projects.

   

2. Click Get List of Projects to first fetch the list of projects from Tableau.

3. The status of the Get Projects action is logged in the Job History table at the bottom of the Settings page.

4. Once the folder synchronization is successful, a drop-down list of projects will become enabled. Select one or more projects to apply the filter.

5. Check if you are using the desired filter option. Available filter options are described below:

   Filter Option	Description
   Extract all Folders except	Extract metadata from all Folders except from the workspaces selected.
   Extract only these Folders	Extract metadata only from the selected Folders.

6. Click Run Extraction Now to extract metadata. The status of the extraction action is also logged in the Job History table at the bottom of the page.

7. If you wish to automatically update the metadata in the catalog, under Automated and Manual Extraction, turn on Enable Automated Extraction and select the day and time when metadata must be extracted. The metadata extraction will be automatically scheduled to run at the selected day and time.

Lineage

Refer to Configure Lineage for OCF Tableau BI Source.

Limitations

• Popularity for workbooks is not supported.

• If Permission Mirroring and Preview features are enabled, they are expected to considerably increase the Metadata Extraction job duration.

• Metadata Extraction will fail if the Tableau Metadata APIs are re-indexing post the Tableau instance upgrade.

• Column Sampling may not fully extract the column sample data of all the views. The connector tries to match the CSV headers from Tableau Rest API with the column metadata received from the graphQL query response. If a column name does not have a corresponding CSV header, the data will not be extracted.

• Cross-System Lineage is not supported for data sources created using Custom SQL and HYPER (.hyper) files. The database hostname and port in the connection information from Tableau API are not received for such data sources.

Troubleshooting

Refer to Troubleshooting.

Type of Error	Reason	Solution
NODE_LIMIT_EXCEEDED	Connector logs show this message: Showing partial results. The request exceeded the ‘n’ node limit. Use pagination, additional filtering, or both in the query to adjust results.	Reduce the number of results returned for the object we were processing before extraction failed. Example: Error while processing/extracting Database Tables (Connections). Error message: NODE_LIMIT_EXCEEDED In this case, reduce results for Connections in the pagination field specific to it.
ApolloNetworkException	When a request takes longer than the configured timeout in seconds.	Increase the Request timeout in seconds input field in the Additional Settings section from default 20 to a higher value.
BACKFILL_RUNNING	Still creating the Metadata API Store. Results from the query may be incomplete at this time.	Wait for the process to complete.