Tableau REST Api example (in PHP) - List workbooks by tags

Tableau REST API was introduced (officially) in version 8. This opens endless options for handling workbooks, datasources, users etc. I will introduce the REST API by creating a list of all workbooks ordered by tags. This could be an interesting case if you wanted to show off your workbooks on the company intranet and to dynamically update the list when new workbooks are published.

I will use PHP to communicate with the REST API but you will be able to perform the same action in .NET, Python or whatever your favorite languages is. You could also build the list with drag-n-drop in Alteryx.

First we need to open up for REST API on the Tableau Server. Open the command prompt on the server and run the following lines. Remember to change the path and version number in the first line according to your own environment.

1 cd "C:\Program Files\Tableau\TableauServer\9.0\bin"2 tabadmin stop3 tabadmin set api.server.enabled true4 tabadmin configure5 tabadmin start

Now we can start query the API using our favorite programming language. If you want to skip the walkthrough you can download the full script here.

First lets set some variables that will tell the username, password, site and path to our server.

1 $username = "_USERNAME_";2 $password = "_PASSWORD_";3 $sitename = ""; // blank for default4 $URL = "_URL_";

To get access to the API we must first request a token by sending our username and password to the server. When in production you should use the https protocol for security reasons. For our "intranet example" I will use a user that has access to all the required workbooks.

1 $token = curlTableauToken($username, $password, $URL);23 function curlTableauToken($username,$password,$URL){4 5 $payload = '6 <tsRequest>7 <credentials name='.$username.' password="'.$password.'" >8 <site contentUrl="" />9 </credentials>10 </tsRequest>11 ';12 13 $ch = curl_init($URL."/api/2.0/auth/signin");14 curl_setopt($ch, CURLOPT_POST, 1);15 curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: text/xml'));16 curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);17 curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);18 $output = curl_exec($ch);19 curl_close($ch);20 21 $xml = simplexml_load_string($output);22 $token = $xml->credentials->attributes()->token;23 return $token;24 25 }

With the token we just obtained we can start to request information from the Tableau server. If we include the following function we can save some lines of codes. The function will take an URL to the Tableau REST API and a token and return a XML class with the requested information.

1 function curlTableauXML($url, $token = ""){2 3 $ch = curl_init($url);4 curl_setopt($ch, CURLOPT_HTTPHEADER, array("X-tableau-auth: $token"));5 curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);6 $output = curl_exec($ch);7 curl_close($ch);8 $xml = simplexml_load_string($output);910 if($xml->error->detail != null){11 die("Error: ".$xml->error->detail);12 }13 14 return $xml;15 16 }

To get to the workbook tags and be able to link to them we must complete the following steps

  • Get the site ID
  • Get the user ID
  • Get the workbooks on the site that is readable by user
  • Get the first view in each workbook (used for the URL)
Get The Site ID

We know the name of the site, but need the siteID to query the users on the site. Therefore we list all the sites and loop through them to find the ID of the site we specified in the top.

1 $xml = curlTableauXML($URL."/api/2.0/sites", $token);2 foreach($xml->sites->site as $site){3 if($site->attributes()->contentUrl == $sitename){4 $siteID = $site->attributes()->id;5 }6 }
Get The User ID

With the siteID in hand we can query all the users on the site and loop through them to find the ID of the user we specified in the top.

1 $xml = curlTableauXML($URL."/api/2.0/sites/$siteID/users", $token);2 foreach($xml->users->user as $user){3 if($user->attributes()->name == $username){4 $userID = $user->attributes()->id;5 }6 }
Get The Workbooks on The Site That Is Readable By User

Finally we are able to list all the workbooks and see the associated tags. Tags, name and URL of the workbook are saved in an array for use later on.

1 $xml = curlTableauXML($URL."/api/2.0/sites/$siteID/users/$userID/workbooks", $token);2 foreach($xml->workbooks->workbook as $workbook){3 $id = $workbook->attributes()->id->__toString();4 $books[$id]["name"] = $workbook->attributes()->name;5 $books[$id]["contentUrl"] = $workbook->attributes()->contentUrl;67 foreach($workbook->tags->tag as $tag){8 $name = $tag->attributes()->label->__toString();9 $tags[$name][] = $id;10 }11 }
Get The First View In Each Workbook (User For The URL)

A link to the workbook requires that we know a view in the workbook. The following snippet will query the views in each workbook and save the first view in an array.

1 foreach($books as $id=>$book){2 $xml = curlTableauXML($URL."/api/2.0/sites/$siteID/workbooks/$id/views", $token);3 $books[$id]["view"] = $xml->views->view[0]->attributes()->contentUrl;4 }

We now have all the information we need to list the tags together with the workbooks associated with it. With the following code we can produce a quick layout:

1 foreach($tags as $tag=>$wb){2 echo "<h2>".$tag."</h2>";3 foreach($wb as $id){4 $url = "$URL/".(($sitename == "") ? "" : "site/".$sitename)."views/".str_replace("sheets/","",$books[$id]["view"]);5 echo "<h4><a href='$url'>".$books[$id]["name"]."</a></h4>";6 }7 }

And it would look like this:

Find the complete REST API reference in the latest documentation that is always available on

Back to blog

Subscribe for updates