Tableau Document API – Intro

The release of the new Tableau Document API has been pretty discrete in the Tableau world. To my humble opinion, the reason is because only a handful of functions are available in this first release. I have no doubt that Tableau will add some functionalities to this API that will open a new world of possibilities. Let’s go through the basics and see what the Document Api is and we can do with it by running the example provided by Tableau.

What is the Tableau document API?

The document API allows developers to modify a Tableau workbook programmatically by modifying the underlying XML of a Tableau file. This API works for Tableau workbooks from version 9.x and after. You can modify TWBX and TDSX files.(go here if you are lost already). The API has been created for Python 2.7 or 3.3.



Why Should I care?

Well, if you are a Tableau Fan, this stuff is cool (and will be awesome at some point), so you should naturally care. Otherwise if you work quite often with Tableau you may have found yourself in situations which involves some repetitive and manual work. From now on, you can avoid that work by writing a couple of lines of code to automate your tasks.

What can I do with it?

The Tableau document API is quite limited at the time I write those lines. Only a handful of functions are available and I cannot wait for more capabilities. Here this present list of possibilities (in October 16′).

  • Duplicate a workbook
  • Modify data sources settings
  • Extract a list of fields from a data-source. (great for documentation purpose)

Great, how the ?/’# do I do that?

Tableau released a couple of examples attached with the API. Currently, regarding the small number of Functions that are available, you have an script example wrote for you, for every single function (Yaye). To run one of the example follow the steps below:

  1. Get the tools.
    1. You need to have python installed. Here to download it. Launch Python.
    2. Use Pip to install the Tableau Document API. Type the cmd line in python[snippet id=”17″]
    3. Now you can use the Tableau Document API by simply writing “import tableaudocumentapi” at the top of your script
  2. Download the examples from github here
  3. Extract the files somewhere you can remembrer.
  4. Go back to python and run your first example. We are going to tun the show-fields sample.
    1. Navigate to the folder where you extracted the sample folder, then navigate to the show-fields subfolder
    2. Run the following cmd [snippet id=”18″]
      If everything went well you should get the following response in you command line tool:


You have produced an automated list of all fields that exist in your dataset. Meaning if you want to create a documentation outside of Tableau about your data set, you could get that done quickly. You have all the calculated fields and there repective formulas.

If you look at the code behind the example you can see that in order to pull the formula you simply need to call this function: ‘field.calculation’.

If we were pushing this example a bit further than just the basic Tableau example we could imagine producing a nice csv or create a small visual that maps all fields between them. We sending a complex dashboard to someone it could be a great ressource to send along.


Like every v1.0, it is not perfect. This first release of the Tableau Document API is really a baby step into programmatic dashboarding but showing promising capabilities. I would personally love to be able to change all fonts in one go (Text Marks + Titles + Annotations ), be able to check the results of a calculation to trigger a task, change a filter before replicating a dashboard and of course solve the eternal dynamic parameter problem.

What else would you like to see?




1 Comment on “

  1. Any chance you can help troubleshoot for me?? When I do step 4.2 above (python, I get the following error:

    C:\Python\TabDocumentAPI\document-api-python-master\samples\show-fields>python s
    Traceback (most recent call last):
    File “”, line 9, in
    sourceTDS = Datasource.from_file(‘world.tds’)
    File “C:\Python\lib\site-packages\tableaudocumentapi\”, line 145,
    in from_file
    dsxml = xml_open(filename, ‘datasource’).getroot()
    File “C:\Python\lib\site-packages\tableaudocumentapi\”, line 32, in xm
    tree = ET.parse(filename)
    File “C:\Python\lib\xml\etree\”, line 1195, in parse
    tree.parse(source, parser)
    File “C:\Python\lib\xml\etree\”, line 596, in parse
    self._root = parser._parse_whole(source)
    xml.etree.ElementTree.ParseError: not well-formed (invalid token): line 1, colum
    n 2

Leave a Reply

Your email address will not be published.