As of 2019.2, the Tableau Server REST API only allows logging in for a REST API session using a combination of username and password. This means there is no effective way to directly start a REST API session using a SSO mechanism (SAML, JWT, etc.) Even if you were able to, you might still want to restrict the user to only do certain actions (for example, enabling Querying methods but not Updates or Deletes).
The best practice for working around this is to wrap the Tableau REST API in another REST API service of your own design. Then within that wrapper, use a Server or Site Administrator level account to log in to the Tableau Server REST API. In this article, we’ll discuss how to achieve this using tableau_tools, with both a simple and a more complex but efficient design pattern.
Tableau’s behavior for saving content when using Web Edit follows these rules:
- If you are the Content Owner, you can Save or Save As
- If you are not the Content Owner, you can Save As
Save As is only allowed to Projects where you (or the groups you belong to) have a Save permission set to “Allow”.
Since a newly Saved Workbook will take the Default Permissions of the Project it saves into, if other people also have permissions for that same Project, they will also be able to access that content. This leads to several different strategies for controlling the privacy of content created through Save As.
- A Project Per Team / Group
- A Project Per User
- A REST API script that “fixes” Permissions
- Publishing a New Copy rather than Save As
If you were ever wondering why there is both a REST API and a Document API produced by Tableau, or why we at this blog put out tableau_tools implementing both of those functionalities (and more!), this use case will illustrate it clearly.
The desired action: Specify a workbook on one Tableau Server site to be downloaded and published to a different Tableau Server site (we’ll call this “replicating over”).
Why it is complicated: Best practice with Tableau Workbooks is to Publish their Data Sources separately, to aid in managing the metadata and to provide for unbreakable Row Level Security, among other great reasons. This means we need to download any Published Data Sources that the Workbook is connected to, and publish them over to the new site as well. Simple enough, right?
After a lot of research and testing, the following steps are required to accomplish this correctly:
- Download all of the workbooks you are interested in using the REST API
- Makes sure to do this one Project at a time, because Workbooks can have the same name if they are in different Projects
- Open up each of the workbook files to look at which published data sources (use tableau_tools.tableau_documents)
- Scan through all of the datasource elements in the Workbook XML.
- Check to see if each datasource is a published data sources
- If a published data source is found, find the contentUrl referenced within
- Query all Data Sources using the REST API. Search for any Data Source whose contentURL attribute matches one of those from the workbooks
- Download the matching data sources using the REST API
- Publish the data sources across to the new Site
- You will need to provide the credentials for any data source at publish time, since there is no way to securely retrieve them from the originating site
- Once published, retrieve the details from the new Data Source on the new site, including the new contentUrl property
- Reopen the workbook file, then change the Site and Data Source cotentUrls to match the the newly published Data Sources on the destination site
- Publish the workbook using the REST API
Luckily, all of this is possible using tableau_tools, and there is a sample script available now showing how to do it.
With the release of tableau_tools 4.0.0 and Tableau Server 10.5, most of the pieces are in place in the library and in the product itself to allow for an efficient path for publishing unique extracts for different customers all from a single original data source (or workbook) template.
The basics steps of the technique are:
- Create a template live connection to a database table, Custom SQL or a Stored Procedure in Tableau Desktop. This does not need to be the final table/custom SQL or Stored Proc; you can use a test or QA data source and switch it programmatically to the final source
- Optional: Set up your the appropriate filtering for a single customer / user / etc. — whatever the main filtering field will be. You can instead add this later programmatically.
- Save that file (TDS or TWB)
- Use the tableau_tools.tableau_documents sub-module to programmatically add any additional filters or modify the filters / parameters you set
- Use tableau_tools to alter the actual table / SP / Custom SQL to the final version of that customer
- Add an extract to that data source in tableau_tools. This will use the Extract API / SDK to generate an empty extract with the bare minimum of requirements to allow it to publish and refresh
- Save the new file. It will be saved as a TWBX or TDSX, based on the input file type
- Publish the file to Tableau Server
- Send an Extract Refresh command to Tableau Server using the REST API (using the tableau_tools.tableau_rest_api sub-module).
- Extract will refresh based on the information in the TDS and be filled out with information just for the specified customer/user/whatever you filtered
I haven’t been announcing the minor point releases of tableau_tools lately, but 4.4.0 is out with a lot of good new stuff:
- Updated to work with the Extract API 2.0, so you can add the necessary Hyper extracts to 10.5 data sources and workbooks
- Fully updated and documented mechanism for altering the main table of existing data sources. Change the table name or Custom SQL or…
- Stored Procedure Parameters can be accessed and set
- Tableau Parameters can now be added, removed or modified
As always, preferred install is from PyPi using pip install tableau_tools –upgrade or you can see the source at the Releases on GitHub. See the full documentation in the README .
tableau_tools 4.3.0 is now up and available on PyPi and GitHub!
If you’ve installed before, just run
pip install tableau_tools --upgrade
There’s lots of good stuff in this release:
- 100% implementation of the spec. If it is in the Reference Guide, it’s possible through tableau_tools. There are even a few things that aren’t in the reference guide 😉
- 10.5 / API 2.8 compatibility
- Vastly improved README file, covering almost all topics
- Code refactoring broke up some of the larger library files into easier to understand pieces
- So much more!
As always, please let me know through GitHub if there are any issues.
In tableau_tools 4.2.3, there is a new example called permissions_changing.py . The examples create_site_sample.py and permissions_auditing.py show how to set permissions when you are working with a new site or to look at the permissions that exist on an existing site, but there was not previously an example of updating an existing site, where you might have existing permissions of any sort. The script itself is decently commented, but here I want to explore some of the things I had to think about when putting the script together, to help people doing other variations of this task. Read through the script, which is reasonably well commented, then come back and read more to gain a more full understanding.