doc(ingestion): tableau quick ingestion guide (#7682)

Co-authored-by: MohdSiddiqueBagwan <[email protected]> Co-authored-by: John Joyce <[email protected]>
datahub-project · Apr 4, 2023 · 6a1abc8 · 6a1abc8
1 parent 06bc1c3
commit 6a1abc8
Show file tree

Hide file tree

Showing 4 changed files with 255 additions and 0 deletions.
diff --git a/docs-website/sidebars.js b/docs-website/sidebars.js
@@ -85,6 +85,13 @@ module.exports = {
                 "docs/quick-ingestion-guides/snowflake/configuration",
               ],
             },
+            {
+              Tableau: [
+                "docs/quick-ingestion-guides/tableau/overview",
+                "docs/quick-ingestion-guides/tableau/setup",
+                "docs/quick-ingestion-guides/tableau/configuration",
+              ],
+            },
           ],
         },
       ],

diff --git a/docs/quick-ingestion-guides/tableau/configuration.md b/docs/quick-ingestion-guides/tableau/configuration.md
@@ -0,0 +1,150 @@
+---
+title: Configuration
+---
+# Configuring Your Tableau Connector to DataHub
+
+Now that you have created a DataHub-specific user with the relevant access in Tableau in [the prior step](setup.md), it's now time to set up a connection via the DataHub UI.
+
+## Configure Secrets
+
+1. Within DataHub, navigate to the **Ingestion** tab in the top, right corner of your screen
+
+<p align="center">
+  <img width="75%" alt="Navigate to the &quot;Ingestion Tab&quot;" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/guides/common/common_ingestion_ingestion_button.png"/>
+</p>
+
+:::note
+If you do not see the Ingestion tab, please contact your DataHub admin to grant you the correct permissions
+:::
+
+2. Navigate to the **Secrets** tab and click **Create new secret**
+
+<p align="center">
+   <img width="75%" alt="Secrets Tab" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/guides/common/common_ingestion_secrets_tab.png"/>
+</p>
+
+3. Create a `username` secret
+
+  This will securely store your Tableau `username` within DataHub
+
+   * Enter a name like `TABLEAU_USERNAME` - we will use this later to refer in recipe
+   * Enter the `username`, setup in the [setup guide](setup.md)
+   * Optionally add a description
+   * Click **Create**
+
+  <p align="center">
+    <img width="70%" alt="Tableau Username Secret" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-username-secret.png"/>
+  </p>
+
+4. Create a `password` secret
+
+  This will securely store your Tableau `password` within DataHub
+
+   * Enter a name like `TABLEAU_PASSWORD` - we will use this later to refer in recipe
+   * Enter the `password` of the user, setup in the [setup guide](setup.md)
+   * Optionally add a description
+   * Click **Create**
+
+  <p align="center">
+    <img width="70%" alt="Tableau Password Secret" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-user-password-secret.png"/>
+  </p>
+
+## Configure Recipe
+
+5. Navigate to on the **Sources** tab and then **Create new source**
+
+<p align="center">
+  <img width="75%" alt="Click &quot;Create new source&quot;" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/guides/common/common_ingestion_click_create_new_source_button.png"/>
+</p>
+
+6. Select Tableau
+
+<p align="center">
+  <img width="70%" alt="Select Tableau from the options" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-new-ingestion-source.png"/>
+</p>
+
+7.  Fill in the Tableau Recipe form:
+
+    You need to set minimum following fields in the recipe:
+
+    a. **Host URL:** URL of your Tableau instance (e.g., https://15az.online.tableau.com/). It is available in browser address bar on Tableau Portal.
+
+    b. **Username:** Use the TABLEAU_USERNAME secret (e.g., "${TABLEAU_USERNAME}").
+
+    c. **Password:** Use the TABLEAU_PASSWORD secret (e.g., "${TABLEAU_PASSWORD}").   
+
+To filter for specific site and project, use the `site` and `project_pattern` fields.
+
+    config:
+         ...
+         site: "ProductionSalesSite"
+         project_pattern:
+            allow:
+              - "SalesProject"
+
+Your recipe should look something like this:
+<p align="center">
+  <img width="70%" alt="tableau recipe in form format" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-recipe.png"/>
+</p>
+
+Click **Next** when you're done.
+
+## Schedule Execution
+
+Now it's time to schedule a recurring ingestion pipeline to regularly extract metadata from your Tableau instance.
+
+8. Decide how regularly you want this ingestion to run-- day, month, year, hour, minute, etc. Select from the dropdown
+
+<p align="center">
+    <img width="75%" alt="schedule selector" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/guides/common/common_ingestion_set_execution_schedule.png"/>
+</p>  
+
+9. Ensure you've configured your correct timezone
+<p align="center">
+    <img width="75%" alt="timezone_selector" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/guides/common/common_ingestion_set_execution_timezone.png"/>
+</p>  
+
+10. Click **Next** when you are done
+
+## Finish Up
+
+11. Name your ingestion source, then click **Save and Run**
+<p align="center">
+  <img width="75%" alt="Name your ingestion" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-ingestion-save-and-run.png"/>
+</p>  
+
+You will now find your new ingestion source running
+
+<p align="center">
+  <img width="75%" alt="ingestion_running" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-ingestion-running.png"/>
+</p>  
+
+## Validate Ingestion Runs
+
+12. View the latest status of ingestion runs on the Ingestion page
+
+<p align="center">
+  <img width="75%" alt="ingestion succeeded" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-ingestion-succeeded.png"/>
+</p>  
+
+13. Click the plus sign to expand the full list of historical runs and outcomes; click **Details** to see the outcomes of a specific run
+
+<p align="center">
+  <img width="75%" alt="ingestion_details" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-ingestion-history.png"/>
+</p>
+
+14. From the Ingestion Run Details page, pick **View All** to see which entities were ingested
+
+<p align="center">
+  <img width="75%" alt="ingestion_details_view_all" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-ingestion-run-detail.png"/>
+</p>  
+
+15. Pick an entity from the list to manually validate if it contains the detail you expected  
+
+<p align="center">
+  <img width="75%" alt="ingestion_details_view_all" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-ingestion-assets.png"/>
+</p>  
+
+**Congratulations!** You've successfully set up Tableau as an ingestion source for DataHub!
+
+*Need more help? Join the conversation in [Slack](http://slack.datahubproject.io)!*
diff --git a/docs/quick-ingestion-guides/tableau/overview.md b/docs/quick-ingestion-guides/tableau/overview.md
@@ -0,0 +1,38 @@
+---
+title: Overview
+---
+# Tableau Ingestion Guide: Overview
+
+## What You Will Get Out of This Guide
+
+This guide will help you set up the Tableau connector to begin ingesting metadata into DataHub.
+
+Upon completing this guide, you will have a recurring ingestion pipeline that will extract metadata from Tableau and load it into DataHub. This will include to following Tableau asset types:
+
+* Dashboards
+* Sheets 
+* Embedded DataSource
+* Published DataSource
+* Custom SQL Table
+* Embedded or External Tables
+* User
+* Workbook
+* Tag
+
+The pipeline will also extract:
+
+* **Usage statistics** help you understand top viewed Dashboard/Chart
+* **Table- and Column-level lineage** automatically index relationships between datasets and columns
+
+## Next Steps
+
+Continue to the [setup guide](setup.md), where we'll describe the prerequisites.
+
+## Advanced Guides and Reference
+
+If you want to ingest metadata from Tableau using the DataHub CLI, check out the following resources:
+
+* Learn about CLI Ingestion in the [Introduction to Metadata Ingestion](../../../metadata-ingestion/README.md)
+* [Tableau Ingestion Source](https://datahubproject.io/docs/generated/ingestion/sources/tableau)
+
+*Need more help? Join the conversation in [Slack](http://slack.datahubproject.io)!*
diff --git a/docs/quick-ingestion-guides/tableau/setup.md b/docs/quick-ingestion-guides/tableau/setup.md
@@ -0,0 +1,60 @@
+---
+title: Setup
+---
+# Tableau Ingestion Guide: Setup & Prerequisites
+
+In order to configure ingestion from Tableau, you'll first have to enable Tableau Metadata API and you should have a user with Site Administrator Explorer permissions.
+
+## Tableau Prerequisites
+
+1. Grant `Site Administrator Explorer permissions` to a user
+
+   A. Log in to Tableau Cloud https://sso.online.tableau.com/public/idp/SSO.
+
+   B. Navigate to `Users`.
+
+   <p align="center">
+   <img width="75%" alt="Navigate to the Users tab" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-user-navigation-window.png"/>
+   </p> 
+
+
+   C. **For New User**: Follow below steps to grant permission for new user.
+
+      -  Click `Add Users` -> `Add Users by Email`
+
+      <p align="center">
+      <img width="75%" alt="Navigate to the Users tab" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-add-user.png"/>
+      </p> 
+
+      -  Fill `Enter email addresses`, set `Site role` to `Site Administrator Explorer` and Click `Add Users` 
+
+      <p align="center">
+      <img width="75%" alt="Navigate to the Users tab" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-new-user-site-role.png"/>
+      </p> 
+
+
+   D. **For Existing User:**  Follow below steps to grant permission for existing user.
+
+      - Select a user and click `Actions` -> `Site Role`
+
+      <p align="center">
+      <img width="75%" alt="Actions Site Role" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-user-list.png"/>
+      </p> 
+
+      -  Change user role to `Site Administrator Explorer`
+
+      <p align="center">
+      <img width="75%" alt="tableau site role" src="https://raw.githubusercontent.com/datahub-project/static-assets-fork/main/imgs/guides/tableau/tableau-site-role.png"/>
+      </p> 
+
+2. **Enable Tableau Metadata API:** This step is required only for Tableau Server. The Metadata API is installed with Tableau Server but disabled by default.
+
+   - Open a command prompt as an admin on the initial node (*where TSM is installed*) in the cluster
+   - Run the command: `tsm maintenance metadata-services enable`
+
+
+## Next Steps
+
+Once you've done all of the above in Tableau, it's time to [move on](configuration.md) to configuring the actual ingestion source within DataHub.
+
+*Need more help? Join the conversation in [Slack](http://slack.datahubproject.io)!*