1) What is Tableau’s Document API?

With the release of Tableau 10, Tableau released a python utility called the Tableau Document API (or TDA for short). TDA allows users to easily programmatically modify tableau workbooks. Modifying tableau workbooks without using Tableau Desktop was possible before as tableau files .twb are actually just xml files. However, manually editing the xml of .twb files could easily result in a corrupted workbook. Fortunately with the release of this tool it is now much less risky to modify workbooks without using Tableau Desktop.

2) Using Tableau’s Document API

TDA is written in Python so using it is as simple as pip install TableauDocumentApi and import TableauDocumentApi. For example if you needed to update the connection strings in a dozen local tableau files you could use the following script to update them all.

import TableauDocumentApi as tda
import glob, os

os.chdir("my_folder")
for file in glob.glob("*.twb"):
  tableau_workbook = tda.Workbook(file)
  for datasource in tableau_workbook.datasources:
    for connection in datasource.connections:
      connection.server = 'my-new-host'
tableau_workbook.save()

3) Tableau’s Query Bands & Initial SQL

Taking a step away from TDA for a moment Tableau has two less visible but still immensely useful features: Initial SQL & querybands. I’ve personally used these features to stage temporary tables & tag each query (there are so many…) that tableau runs.

4) How does this relate to the TableauDocumentAPI

The first version I used of Tableau’s Document API did not support modifying initial sql & query bands. After being faced with modifying thousands of workbooks to use query bands I decided to review the library and see if support could be easily added. Glancing at the source code I could see that each of the properties of a connection was cleanly defined. Using Port as an example I was able to submit a pull request implementing the functionality. Fortunately, the Tableau team was very responsive and quickly merged the pull request.

5) Tying it all together

So now if you find yourself in a situation where you need to modify the query bands or the initial sql in your workbooks you can use the TDA to save yourself some time.

Update: Looks like Tableau was even kind enough to mention this new feature in the release notes of 10.2 Search for “and with our Document API”

Cheers!