TSC Part 1: Intro to Tableau Server Client

Hello there! And welcome to this introduction of Tableau Server Client!

This is the first part of a mini-series I’m hoping to provide on TSC. Tableau’s APIs are a powerful weapon to add to your arsenal and I believe TSC is a great intro to their capabilities.

Tableau Server Client

As with most things with Tableau, the documentation is excellent (at least compared to many other applications). Official documentation can be found here and on GitHub. The only thing that I wanted to call out is how the GitHub repository is organized. Specifically Items vs Endpoints. This is important as the documentation site is not always immediately updated so this will help you navigate the API as new versions are pushed.

Items

Items are the specific objects on the server. Whenever you want to know what attributes exist for an object (workbook, project, user, etc.), this is where you’ll want to look. You can find this information under tableauserverclient/models. For each item you can view the init statement to see the list of properties to query.

Endpoints

You can think of endpoints as the methods to interact with Items. The endpoints scripts are stored in tableauserverclient/server/endpoint. If you want to know the full list of things you can do with a workbook then you’d head to the workbooks endpoint. Depending on the method you can also view which parameters are required. So, let’s get started!

Set-Up

Below are set-up steps I’d recommend to complete prior to starting. As for me: I’m operating on macOS (Big Sur) with the built-in Terminal and Atom IDE. Feel free to use whatever you’re comfortable with!

Tableau Developer Program

Tableau recently released a new Developer Portal here. These examples are based on the use of a free Sandbox through the program, which I’d highly recommend utilizing! Like much of below, this is to your benefit as you can test things out without risking your own environment.

Tableau Developer Portal

Fork Sample Repo

This repository can be found on my tsc-examples repo. I’d recommend forking the repo for ease of following along and then clone to your computer. Once that’s done, navigate to the root of the repository.

PyEnv For Local Version

This is a great way to separate your python environments between projects. I found this intro to be great. 

brew install pyenv
pyenv local 3.9.1
# use this to check version:
pyenv versions

Virtual Environment

Similarly, we can make a virtual environment so you can install packages specific to these examples (so we know they work!).

python -m venv venv
souce venv/bin/activate

Install Dependencies

For more information about why visit this link. Now be sure you’re in the root of your directory and then run:

pip install -r requirements.txt

Create .env File

An .env file is a great way to host your credentials and avoid entering over and over. Here we’ll be using Personal Access Tokens for authentication. Create Tokens

tokenName='TokenName'
tokenSecret='TokenSecret'
url='https://10ax.online.tableau.com'
site='SiteName'

Create New Projects

Assuming your Sandbox Site is up and running and you’ve cloned the repository, you can now make some sample projects to use.

python 0_setup/CreateProjects.py

Authentication

Essentially the first step to every script will be to pass your credentials into the script and authenticate/login. To do this we must use the .env file we made previously. In python we can use the dotenv to easily find this file. We must import the package to tell our script how:

from dotenv import load_dotenv, find_dotenv

In the main portion of the script, we assign these using:

tokenName, tokenSecret, serverurl, sitename = getCredentials('.env')

And in the function we access these values: 

def getCredentials(env):
    load_dotenv(find_dotenv(env))
    return os.environ.get('tokenName'), os.environ.get('tokenSecret'), os.environ.get('url'), os.environ.get('site')

We will use this in each script, but you could put this into a separate script and import that to avoid repetition if so desired.

Project Hierarchy 

Our first example is a question I’ve seen on the Forums a few times. People often want to know where things live on their Tableau Online/Server instance. We can easily grab the project of a workbook, but that doesn’t help us visualize how to navigate to it. To do this, we must recursively iterate over our projects.

The first step is to get our list of projects in the getProjects function. The documentation provides several ways to do this, but since we want all projects, this should suffice:

all_projects = list(TSC.Pager(server.projects))

We will do a few things with this list.

1.     Create a pandas dataframe (aka table) with relevant attributes

2.     Dictionary of Project to Parent Project

3.     Dictionary of Project to Name

Once these are generated, we’ll use our getProjectHierarchy function to add the Path and the Level. This is where the trick lies. We have a separate getHierarchy function that recursively adds the Parent Project to the Parent List. Whenever there’s a parent project ID present, it will loop through and append to the list before returning the completed list. Then we can use the apply function in pandas to simply count the length of the list to calculate the Path Level.

Key Functions

Lastly, we output to a CSV for easy viewing. Huzzah!

I hope this has been a helpful introduction to Tableau Server Client! Up next we’ll look at assigning project permissions. Stay tuned!