# 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`: ```bash 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]( ../json_schemas/jobs.job_tableau_export.TabcmdExportSection.md ). ## Example Configuration The following is an example of a JSON configuration for this job: ```json { "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](https://help.tableau.com/current/online/en-us/tabcmd.htm) 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]( ../json_schemas/jobs.job_tableau_export.TabcmdExportSection.md ) 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¶m2=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: ```bash 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.