Mitto Job: Vizql Export¶
Introduction¶
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: ENDThe 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": "https://tableau.zuar.com",
"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 onlypdf
is supported.fullpdf
- Iftrue
, 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
.
References:
Implementation documentation for the ``Request` class <https://github.com/psf/requests/blob/1b417634721ec377abb7f17bc1f215e07202c2f7/requests/models.py#L198>`_.
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 whenRequest.method()
is invoked.Updates the value of the
files
parameter with the contents ofitems
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
- Iftrue
, the contents of each request issued by Vizql Export is recorded in the job’s log.log_responses
- Iftrue
, the contents of each response received by Vizql Export is recorded in the job’s log.save_responses
- Iftrue
, 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.