Mitto Job: Vizql Export


The Vizql Export job is used to issue HTTP requests to Vizql endpoints on a Tableau server for the purpose of creating and downloading “reports” in PDF, CSV, and png formats. The Vizql Export job can either be run standalone or it can be invoked by the Subscriptions job. This document is relevant for both use-cases.

A total of six requests are issued to create and download a one-page PDF document. Because it can be necessary to modify one or more of these requests to achieve the desired result, extensive configuration is possible. For easy reference, each of the requests have been given a name: AUTH, EMBED, BOOTSTRAP, EXPORT_OPTIONS, EXPORT_SERVER, and DOWNLOAD.

The following sequence diagram summarizes the message flow:

sequenceDiagram Note over client,auth: [AUTH] Authenticate with user/pass client->>+auth: [GET] /api/2.0/auth/signin auth-->>-client: auth token (XML) Note over client,auth: RESP: provides wkgrp_session_id Note over client,views: [EMBED] Get info for use in remaining requests client->>+views: [POST] /views/{workbook}/{view}?:embed=y&:from_wg=true views-->>-client: HTML page Note over client,views: RESP: header provides session_id<br>RESP: HTML "textarea" provides JSON - "stickySessionKey"<br>NOTE: session_id != wkgrp_session_id Note over client,vizql: [BOOTSTRAP] Create a vizql session client->>+vizql: [POST] /vizql/w/{workbook}/v/{view}/bootstrapSession/sessions/{session_id} vizql-->-client: vizql session Note over client,vizql: RESP: text containing multiple JSON strings - "primary", "secondary" Note over client,vizql: [EXPORT_OPTIONS] Request options for PDF export client->>+vizql: [POST] /vizql/w/{workbook}/v/{view}/sessions/{session_id}/commands/tabsrv/pdf-export-options vizql-->>-client: "vqlCmdResponse" Note over client,vizql: RESP: JSON - all valid PDF export options Note over client,vizql: [EXPORT_SERVER] Create PDF file client->>+vizql: [POST] /vizql/w/{workbook}/v/{view}/sessions/{session_id}/commands/tabsrv/pdf-export-server vizql-->>-client: "vqlCmdResponse" Note over client,vizql: RESP: JSON - "tempFileKey" identifies file that was created Note over client,vizql: [DOWNLOAD] Download previously created PDF file client->>+vizql: [GET] /vizql/w/{workbook}/v/{view}/tempfile/sessions/{session_id}?key={tempFileKey} vizql-->>-client: PDF file Note over client,vizql: END

The functionality offered by the Vizql Export can also be accessed from the Export Job.

Job Configuration

Reference: Vizql Export job configuration

The following JSON configuration will be used to illustrate the basics of configuring a Vizql Export job as well as the tableau section of a Subscriptions job.

    /* Tableau server credentials (named credentials are supported) */
    "credentials": {
        "password": "<password>",
        "username": "<username>"
    /* Tableau server configuration */
    "server": {
        "server": "",
        "site": "",
        "user_id_to_impersonate": "5cf3542a-0c46-42fb-b6a5-27a96e41054a"
    /* Vizql parameters to be used in creating the export */
    "export": {
        "retries": 5,
        "timeout": 300,
        "fullpdf": false,
        "log_responses": false,
        "modifications": [
                "action": "update",
                "destination": "files",
                "items": {
                    "clientDimension": "{\"w\": 1280, \"h\": 1024}",
                    "dashboardPortSize": "{\"w\": 1280, \"h\": 1024}",
                    "worksheetPortSize": "{\"w\": 1280, \"h\": 1024}"
                "request": "bootstrap"
        "name": "superstore-fullpdf",
        "options": {
            "imageHeight": "0",
            "imageWidth": "0",
            "pageFitHorizontal": "1",
            "pageFitVertical": "1",
            "pageOrientationOption": "landscape",
            "pageScaleMode": "auto",
            "pageScalePercent": "100",
            "pageSizeOption": "letter"
        "save_responses": true,
        "type": "pdf",
        "view_filters": {
            "State": ["Louisiana", "Texas"],
            "Category": ["Office Supplies"]
        "view": "Overview",
        "workbook": "Superstore"

"credentials" Section

Defines the Tableau server and associated credentials to use to perform the export.

"export" Section

The export section provides extensive control over the Vizql requests that are used to create the exported reports. It is identical to and serves the same purpose as the export section of the Subscriptions job.

  • type - Format in which to create the export. Currently only pdf is supported.

  • fullpdf - If true, the exported report will include all views in the workbook.

  • name - Name to be given the the exported report. The report will be present as an attachment to the email.

  • retries - Number of times to retry failed Vizql requests.

  • timeout - Maximum time to allow a Vizql request to run.

  • modifications - Defines modifications to make to any of the five Vizql requests used to export a report. See Modifications below for more information.

  • options - Defines options to use with one of the five Vizql requests used to export a report. See Options for more information.

Modifications to Vizql Requests

Modifications can be complex. A solid understanding of both Tableau Vizql and the Python Requests package is essential to creating modifications.

Modifications can be made to each of the six Vizql requests. These modifications are specified through the export.modifications parameter of the Vizql Export job configuration. There are four parameters which control each modification to be performed:

  • request - The name of the request to modify. The name is taken from the state diagram in the introduction.

  • destination - The entity that is to be modified.

  • action - The type of modification to perform.

  • items - One or more modifications to apply.

The destination of the Modification

Each HTTP request in the state diagram is issued using the Python Requests package. When using Requests, each HTTP operation (e.g., POST, GET, etc.) is invoked with arguments which control the content and behavior of the HTTP request that is ultimately sent. destination identifies the argument that is to be modified prior to invoking the operation. Possible values for destination are: url, headers, files, data, json, and params.


Modification Walkthrough

This section walks through the motivation for and mechanics behind the modification contained in the example job configuration.

The default BOOTSTRAP request sends values for worksheetPortSize, dashboardPortSize, and clientDimension as multipart-form data. The default values are taken from the composite_sizes parameter included in the server’s earlier response to the EMBED request.

For an optimal PDF layout, it may be necessary to adjust those values. If, instead of the default values, one wished to use 1280x1024, the following modification would achieve that end:

"modifications": [
        "request": "bootstrap",
        "destination": "files",
        "action": "update",
        "items": {
            "clientDimension": "{\"w\": 1280, \"h\": 1024}",
            "dashboardPortSize": "{\"w\": 1280, \"h\": 1024}",
            "worksheetPortSize": "{\"w\": 1280, \"h\": 1024}"

This configuration:

  • Modifies the BOOTSTRAP request shown in the state diagram.

  • Modifies the files parameter when Request.method() is invoked.

  • Updates the value of the files parameter with the contents of items rather than replacing the value entirely.

When using the Requests package, the files argument is used to provide multipart-form data, thus the use of files as a destination. Because the action is update, the remaining default multipart-form data continues to be sent.

Crafting Modifications

The most effective way to understand the content of the Vizql requests is to run the requests through a proxy. Absent that ability, the Vizql Export job can be configured to record similar information. The relevant parameters are:

  • log_requests - If true, the contents of each request issued by Vizql Export is recorded in the job’s log.

  • log_responses - If true, the contents of each response received by Vizql Export is recorded in the job’s log.

  • save_responses - If true, the contents of each response received by Vizql Export is saved in /tmp.

By using these parameters, one can see exactly what is being sent and received by Vizql Export.

Options for Vizql Requests

The options section contains modifications to the default PDF page layout options. The possible options are documented here