Last week I got acquainted with tabcmd, the Tableau Server command line utility. With tabcmd, you can automate various Tableau Server processes from your local machine. In this post, I’ll document some of the publishing processes and automation that are possible with tabcmd, shell scripting and Windows Task Scheduler. The processes listed here are by no means the extent of what tabcmd is capable of, and you can read about all of the other functions here. Philip Mannering also wrote a great blog post about some of the features.
1. Log in to the server
The first example is a simple but fundamental function – logging in to the server with your credentials. Firstly, open the command prompt terminal on your machine. If this is your first time (God help you), you can hit the windows button on your keyboard and search for “cmd”.
This will open a terminal, in which you can enter tabcmd commands. The first step is to navigate to the folder that contains the tabcmd.exe executable file using the ‘cd’ (change directory) command, followed by the tabcmd file path in double quotation marks. In the terminal language (AKA the Windows shell scripting language), it is necessary to wrap any argument that contains whitespace in double quotes, so that the terminal interprets the argument as a whole, and does not split at the whitespace. Once the current directory is set to this folder, you can run any of the tabcmd functions.
To log in to the server, you can use the cleverly named “tabcmd login” function, followed by a host of arguments that pertain to your login credentials for your Tableau Server. Hopefully the following code is fairly self-explanatory, and you can supplement it with your own credentials:
If logged in correctly, you should receive a “Succeeded!” message in the terminal.
2. Publishing a folder of workbooks to server
Let’s say I save all my Tableau workbooks in a folder on my local machine (“C:\Users\Brian\Workbooks\”), and I want to publish all of them to Tableau Server. Rather than logging into the server on a web browser and manually uploading them one by one, I can use the “tabcmd publish” function for this task. Here’s the code:
I’ll explain this one from the inside out. At the core of this statement is the command
tabcmd publish –project “Project name” “%i”
This uses the “tabcmd publish” function to publish a workbook to a project named “My Project” on my Tableau Server. I have wrapped this command in a FOR loop. FOR loops are used to iteratively perform a function on a selection of input variables. In this instance, I am using the FOR loop to iterate through all of the .twxb workbooks in my folder (“C:\Users\Brian\Workbooks\*.twbx”). The argument “%i” acts as a variable placeholder for each of the files that the FOR loop is iterating through.
The last piece of code to explain here is IFS=$’\n’. IFS stands for “internal field separator”. As I previously mentioned, the terminal requires strings with whitespace to be wrapped in double quotation marks, because by default, it considers whitespace to be an “internal field separator”. As you can see, we have already wrapped all of our file paths in double quotes in this piece of code. However, the shell scripting language completely ignores our efforts when we try to use string arguments as variables in FOR loops (just to annoy us). To compensate for this behaviour, we have to explicitly set the IFS to anything BUT whitespace, so we tell it to separate only when it encounters the newline character (‘\n’).
This should allow our loop to run smoothly after we log in to the server, and will publish all of the .twbx workbooks in that folder to my project on the server.
3. Automate with Windows Task Scheduler
We could automate this whole process, and schedule our workbooks to upload on a daily or weekly basis. This could be extremely useful if we want to ensure that all of our local workbooks get backed up to the server, or to keep our server workbooks updated if we are editing them locally.
To do this, we need to save a script of commands to a batch file with a ‘.cmd’ extension. The script for this is an amalgamation of the previous two examples:
A couple of differences you might have noticed, and my attempted explanations for them:
- Instead of navigating to the tabcmd folder using the ‘cd’ function, I have pasted together the filepath and ‘tabcmd’, which calls tabcmd directly from where it is located. In the past, I have found that batch scripts don’t always appreciate when you jump around the file directory, but feel free to try it the previous way!
- You might have noticed that ‘%i’ has turned into ‘%%i’. According to THE INTERNET, two % signs are necessary to specify a variable in a batch file. Big thanks to Rob Carroll for bringing that to my attention, because it might have taken me a long time to crack that one.
Save your script to a file with a ‘.cmd’ extension, e.g. “PublishMyWorkbooks.cmd” and save it to your disk. The final step is to tell Windows Task Scheduler to run that file at your specified schedule. It’s a straightforward process:
- Open Windows Task Scheduler
- From the toolbar select Actions > Create Basic Task
- Name and optionally describe the task
- Select the time schedule for your script to run
- In the Action tab, select ‘Start a program’
- Browse to and select “PublishMyWorkbooks.cmd”
That’s about it. There’s no doubt that shell scripting can be a really useful addition to the tabcmd functions. But be warned, it requires a lot of patience and can potentially ruin your day, so be careful out there.