Tableau Extract Refresh¶

Note

The Tableau with MFA user authentication method is supported starting in version 2.9.8 by leveraging personal access tokens. See below for further instructions.

The Tableau Extract Refresh plugin creates a Zuar Runner job that refreshes a Tableau Extract on Tableau Server or Tableau Online. The Tableau Extract can either be an extract embedded in a workbook or a published data source.

Best practice for using a Tableau Extract Refresh job in most cases is to add this job to the end of a Zuar Runner sequence. This way the Tableau data is refreshed immediately after the data is refreshed in Zuar Runner.

The Tableau Extract Refresh plugin uses the Tableau Rest API to essentially press the “Run Now” button:

Tableau Steps¶

Publish a Tableau workbook with an embedded extract or publish an extract as a published data source.
Set an extract refresh schedule. In order to refresh a Tableau Extract with Zuar Runner, the extract must have a refresh schedule. Best practice is to set an infrequent refresh schedule (e.g. once a month, 1x per week on the weekend, etc.) so the Zuar Runner triggered extract refresh doesn’t conflict with the Tableau refresh schedule.

NOTE: Since Tableau Cloud resources are shared with all customers using a given pod, Tableau deprioritizes refreshes triggered on-demand via API Tableau documentation by defaulting to prioirty 50. The API call is the only method available for Zuar Runner to trigger a refresh. This may result in longer queue times for API extract refreshes vs. Tableau Cloud triggering the refresh via it’s built-in schedules. As such, very frequent extracts are not recommended in most scenarios as Tableau Hyper Extract file format were not designed for this. Instead, it is recommended to consider a live connection when data needs to be refreshed more frequently than 1x/hour.

How to Create an Extract Job via Wizard¶

Click +Add Job. and Choose “Tableau Extract Refresh”.

For Source of credentials, choose Provide credentials now, to be saved under Credential Name. (If this is not your first time creating a Tableau Extract Refresh job, you can choose Use existing name credentials and select the saved credential name)

From here you have 2 credential options:

Basic Credentials (username and password)
Personal Access Token Credential (PAT for MFA use case)

Provide Personal Access Token (PAT)¶

This credential type was initial developed for Tableau users that have enabled Multi-Factor Authentication as their user authentication type.

Note

PATs expire after 1 year and will need to be recreated. Further, if a generated PAT is not used for 15 days, they will expire and need to be recreated.

Fill in the form.

Creating a PAT thru the Tableau UI (My Account Settings)

Server URL - This is the “base” URL of your Tableau Server/Cloud. In these examples, the Server URL is in bold: https://tableau.zuar.com/#/home and https://us-east-1.online.tableau.com/#/site/zuar/home
Token Name - This is the name of your generated Personal Access Token, which you can generate by Signing into Tableau Cloud or Tableau Server > Navigate to My Account Settings under your user profile > Provide a Token Name > Create new token. In this step you will input the Token Name. See Tableau’s documentation for Personal Access Tokens here.
Personal Access Token - This is the token generated in the previous step. Save this token somewhere safe as you will not be able to retrieve it again once you close the window.
Site - This is your Tableau Server/Cloud site. For Tableau Server’s default site you can leave this field blank (e.g. https://tableau.zuar.com/#/home). Tableau Cloud always has a site and it must be input into the form. In these examples, the Site is in bold: https://tableau.zuar.com/#/site/Demo/home and https://us-east-1.online.tableau.com/#/site/zuar/home

Click Next

Note

This credential info will now be encrypted and saved in Zuar Runner’s Credential manager and can be used for future jobs.

The saved credential will be given an autogenerated name. If you would like to edit the/create your own saved credential:

Navigate to the saved Credentials page in Zuar Runner
Add Credential
Select Credential Type: Generic
Give the credential a name
Paste the following JSON into the Value section and insert details related to your deployment:

{
    "server_url": "https://prod-useast-b.online.tableau.com/",
    "token_name":"zuar-pat",
    "personal_access_token": "paste pat here!",
    "site":"zuar"
}

Zuar developer docs can be found here!

Provide username and password¶

Fill in the form.

Tableau Extract Basic Creds Zuar Runner UI

Server URL - This is the “base” URL of your Tableau Server/Cloud. In these examples, the Server URL is in bold: https://tableau.zuar.com/#/home and https://us-east-1.online.tableau.com/#/site/zuar/home
User Name - This is your Tableau Server/Cloud username.
Password - This is your Tableau Server/Cloud password.
Site - This is your Tableau Server/Cloud site. For Tableau Server’s default site you can leave this field blank (e.g. https://tableau.zuar.com/#/home). Tableau Cloud always has a site and it must be input into the form. In these examples, the Site is in bold: https://tableau.zuar.com/#/site/Demo/home and https://us-east-1.online.tableau.com/#/site/zuar/home

Click Next.

Select Tableau Extract¶

Pick a Tableau extract from the dropdown list.

The naming convention for the dropdown list is as follows:

{name of extract} [{type of extract - workbook or datasource}] {extract id from Tableau}

So in the example screenshot above, the Tableau extract is named “All Customers Service Delivery Reports (MC)”, the extract is embedded in a workbook, and has an ID of b6884188-5193-4de9-bc65-61a85dd65bd2.

Click Next.

Give the job a title.

Best practice is to title the job as follows:

[Tableau Extract Refresh] {name of extract} [{type of extract - workbook or datasource}] {id}

Zuar Runner will attempt to generate a name that matches the above structure.

Click Done.

Extract Job Templates¶

Examples of Zuar Runner extract jobs and associated credential examples can be found in Zuar’s Github repo mitto-job-templates.

Considerations¶

Changing the refresh schedule on an existing Tableau extract or removing the extract will break the corresponding Zuar Runner job. The error will look something like:

Traceback (most recent call last):
  File "/opt/mitto/builtin/extract/jobs/job_extract.py", line 57, in <module>
    sys.exit(main())
  File "/opt/mitto/builtin/extract/jobs/job_extract.py", line 41, in main
    raise RuntimeError(f"Target not found: {config.target_id}")
RuntimeError: Target not found: 3df17c06-3489-45c7-a724-1b6698694567

Simply go through the job wizard again and recreate the job.

When a Tableau Extract Refresh job succeeds, the command to refresh the extract was sent to Tableau Server/Online. Zuar Runner does not know if the extract job succeeded or failed on the Tableau side. You can review the Job log in Tableau for more information about the run: