# Zuar Runner 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:

.. mermaid::

   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_export.md).


## Job Configuration

Reference: [Vizql Export job configuration](
/json_schemas/jobs.job_vizql_export.md 
)

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.

```javascript
{
    /* 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](job_subscriptions.md).

* `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](#modifications) below for more information.
* `options` - Defines options to use with one of the five Vizql requests used to export
  a report.  See [Options](#options) for more information.

.. _modifications:

## 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](https://2.python-requests.org/en/master/) 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:
* [General documentation on request parameters](
  https://2.python-requests.org/en/master/user/quickstart/#more-complicated-post-requests).
* [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:

```javascript
"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:

## Options for Vizql Requests

The `options` section contains modifications to the default PDF page layout options.
The possible options are documented [here](
/json_schemas/jobs.job_vizql_export.md#exportlayoutoptions
)