Tableau Document API – Intro

Written by Adrien Charles – 18-08-2016

The release of the new Tableau Document API has been pretty discrete in the Tableau world. In my humble opinion, the reason is because only a handful of functions are available in this first release. There is no doubt in my mind that Tableau will add some functionalities to this API that will open a whole new world of possibilities. Let’s go through the basics and see what the Document API is and what 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 involve 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. The following is a list of possibilities (in October 16′).

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

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 a script example written for you, for every single function (Yay). To run one of the examples follow the steps below:

  1. Get the tools.
    1. You need to have python installed. Click here to download. 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 remember.
  4. Go back to python and run your first example. We are going to run 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 a response in your command line.

 

You have produced an automated list of all fields that exist in your dataset. Meaning if you want to create a document outside of Tableau about your data set, you could get that done quickly. You have all the calculated fields and their respective 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. When sending a complex dashboard to someone it could be a great resource to send along with it.

Limitations…?

Like every v1.0, it is not perfect. This first release of the Tableau Document API is really a baby step in programmatic dashboarding but shows 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 show_fields.py), I get the following error:

    C:\Python\TabDocumentAPI\document-api-python-master\samples\show-fields>python s
    how_fields.py
    Traceback (most recent call last):
    File “show_fields.py”, line 9, in
    sourceTDS = Datasource.from_file(‘world.tds’)
    File “C:\Python\lib\site-packages\tableaudocumentapi\datasource.py”, line 145,
    in from_file
    dsxml = xml_open(filename, ‘datasource’).getroot()
    File “C:\Python\lib\site-packages\tableaudocumentapi\xfile.py”, line 32, in xm
    l_open
    tree = ET.parse(filename)
    File “C:\Python\lib\xml\etree\ElementTree.py”, line 1195, in parse
    tree.parse(source, parser)
    File “C:\Python\lib\xml\etree\ElementTree.py”, 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.