doc(ingestion): tableau quick ingestion guide

docs-website/sidebars.js

@@ -77,6 +77,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",
+              ],
+            },
           ],
         },
       ],

docs/quick-ingestion-guides/tableau/configuration.md

@@ -0,0 +1,149 @@
+---
+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 the **Sources** tab and click **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.  Enter details into the Tableau Recipe
+
+    You need to set minimum following fields in the recipe:
+
+    a. **Host URL:** URL of your tableau instance. It is available in browser address bar on Tableau Portal. For example: https://15az.online.tableau.com
+
+    b. **Username:** You can use the TABLEAU_USERNAME secret you've previously created by providing the secret name surrounded by "${}". For example, "\${TABLEAU_USERNAME}"
+
+    c. **Password:** You can use the TABLEAU_PASSWORD secret you've previously created by providing the secret name surrounded by "${}". For example, "\${TABLEAU_PASSWORD}"    
+
+By default, this will ingest all project from default tableau site. 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>
+
+After you've successfully completed the recipe, click **Next**.
+
+## 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)!*

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** to help you understand top viewed Dashboard/Chart
+* **Table- and Column-level lineage** to automatically define interdependencies 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)!*

docs/quick-ingestion-guides/tableau/setup.md

@@ -0,0 +1,42 @@
+---
+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. **Allow Site Administrator Explorer permissions:**
+
+   a. login 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. Select particular user and click on `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> 
+
+   d. 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)!*