Zuar Runner Job: Tableau Export

Introduction

Important

The Tableau Export job is deprecated; use the Export Job instead. Users creating new jobs for exporting reports from Tableau should use the Export job. This documentation remains as an aid to users maintaining existing Tableau Export jobs.

Tableau Export allows one to specify one or more Tableau reports to be exported using the tabcmd command. The specification for each report, which can be thought of as a row in a spreadsheet or a database, defines the contents and format of the report to be exported as well as the email address(es) of the recipient(s).

The job is controlled by a JSON configuration that is passed in on the command line or provided via the Zuar Runner user interface. The JSON configuration contains a basic configuration for the application as well as a configuration for the reports specifications.

Tabcmd

If tabcmd is not present on the Zuar Runner instance, it must be installed. Because it is a Java application, Java must be installed as well. Run the following commands in a shell window to install both Java and tabcmd:

sudo apt install openjdk-8-jdk openjdk-8-jre
cd /tmp
wget https://downloads.tableau.com/esdalt/2019.4.1/tableau-tabcmd-2019-4-1_all.deb
sudo dpkg -i /tmp/tableau-tabcmd-2019-4-1_all.deb
rm /tmp/tableau-tabcmd-2019-4-1_all.deb

Configuration

The remainder of this document briefly describes the contents of each section.

For a detailed configuration reference, which describes all possible configuration options, see this Zuar Runner documentation for job_tableau_export.

Example Configuration

The following is an example of a JSON configuration for this job:

{
  "tabcmd_export": {
    "tabcmd": {
      "server": "https://tableau.zuar.com",
      "site": null,
      "user": "username",
      "password": "password",
      "no_certcheck": true
    },
    "smtp": {
      "server": "localhost",
      "port": 25,
      "require_tls": false
    },
    "report_specifications": {
      "type": "json",
      "source": [
        {
          "view": "Superstore/Overview",
          "report_type": "pdf",
          "pagelayout": "landscape",
          "pagesize": "letter",
          "report_name": "report_name_01",
          "mail_to": "bob@zuar.com",
          "mail_subject": "pytest: Report 01 is attached",
          "mail_from": "carol@zuar.com",
          "mail_cc": "ted@zuar.com,alice@zuar.com",
          "mail_bcc": "operations@zuar.com",
          "parameter_01": "Category",
          "value_01": "Office Supplies",
          "parameter_02": "State",
          "value_02": [
            "Texas",
            "Louisiana"
          ]
        }
      ]
    }
  }
}

The job’s behavior is entirely defined by the contents of tabcmd_export.

Within tabcmd_export are three subsections: tabcmd, smtp, and report_specifications.

"tabcmd"

When run, the job invokes tabcmd export once for each report defined by a report specification. The settings in this section are applied to each invocation of tabcmd.

Refer to the tabcmd man page to learn more about the available options.

"smtp"

The settings in this section are used to control how each report is delivered using SMTP. The easiest way to send mail is to use the postfix application present on all Zuar Runner instances. The values shown in the config above work properly in that context.

Additional values can be provided to use other SMTP servers, authenticate to those servers, specify user names, passwords, etc.

"report_specifications"

This section defines each report that will be exported and emailed. Each report is specified by one report specification. A report specification has both mandatory and optional fields. Refer to the job configuration reference for detailed information on all fields.

"type" can have one of three values: "json", "csv", or "sql".

"type": "json"

When "type" is "json", "source" must be an array of report specifications, each of which must be valid JSON. Each item in the list defines the contents of a report as well as the recipients.

"type": "csv"

When "type" is "csv", "source" must be a string containing a path to a CSV formatted file. Each row in the file represents one report specification. The CSV file must contain a header.

"type": "sql"

When "type" is "sql", "source" can take on either of two forms, each of which must be an SQL query. Each row returned by the query corresponds to one report specification. A value for "dbo" must be provided.

In the first form, "source" is a single string containing an SQL query.

In the second form, "source" is a list of strings which, when combined, will form a SQL query.

Filtering Data

Users familiar with the Tableau user interface will be accustomed to filtering the data presented by a Tableau by embedding parameter/value pairs in the URL string. These pairs are embedded in the URL following the ? and are generally in the form param1=val1&param2=val2&.... In the example configuration above, parameter_01 / value_01 and parameter_02 / value_02 perform the identical function.

A report specification can have zero or more parameter_NN / value_NN pairs, where NN is a two-digit number.

The following URL in the Tableau user interface would be equivalent to the above configuration:

https://tableau.zuar.com/#/views/Superstore/Overview?Category=Office%20Supplies&State=Texas,Louisiana

Caution: there is one significant difference between the embedding of parameter / value pairs in the Tableau URL and the Zuar Runner Tableau Export job. In the case of the former, the user must carefully and manually URL encode characters that are not URL-safe; this can be an error-prone process. When configuration parameter / value pair for the Zuar Runner Tableau Export job, it’s perfectly fine to use any unencoded Unicode character – Zuar Runner will take care of the proper encoding for you.