Report & Distribution Commands

Configuring the DSA Report and Distribution Commands

The commands are stored in a table format. 

• For DSA Cloud AD the report and distribution commands table is stored on a SQL Server table on DataSelf's cloud server.

• For DSA AD running 'on-prem' (on a client's server) the the report and distribution commands table is stored in a .csv file.

DSA AD & DSA Cloud AD Diagrams

Diagrams

DSA Cloud AD.  The Commands Database in the upper right is stored in a SQL Server database.  The job scheduler, the final element in the automation, is not shown.

DSA AD.  Versions of DSA AD that run 'on-prem' (on your companies server) stores the Commands Table in a .csv file. The job scheduler, the final element in the automation, is not shown.

DSA AD & DSA Cloud AD in a broader context.

Columns in the Report Commands table

ID

Any name or id value you make up.  The ID is helpful for tracking/tracing each row of commands in log files. 

URL

A segment of the URL that opens a worksheet in workbook in DataSelf Analytics/Tableau Web Server.
To obtain this string of text:

1. Use the DSA/Tableau Web Server to navigate to the workbook or view (tab) you want to distribute.

2. Copy the URL from the web browser's URL window

3. Delete everything in the URL text string except the part after "/view/" and before question mark ("?")

4. Copy the remaining text to the URL column.

Example:

When the URL shown in the web browser is one of:

• http://localhost:8000/views/TestA/Sheet3    or

• http://localhost:8000/views/TestA/Sheet3?id=1

• http://localhost:8000/views/TestA/Sheet3?AcctManagerID=BBSet

the text for the URL column should be:   TestA/Sheet3

Notes:

• "404 Not Found",  "Failed to create a VizQl session" error messages - see Error Messages. 

• See also the "fullpdf" option in the Output-Format column.

• Dashboards call other worksheets. A URL to a worksheet (tab) that is configured as a dashboard will run all the worksheets specified in the dashboard.

URL-Filters

The filter parameters (or query string) portion of the URL that is passed to DataSelf Analytics Web Server.

• When output is a dashboard the filters will apply to all filters on the views included in the dashboard.

• When output is of all views in a workbook the filters will apply to all views. (see the fullpdf option of the Output-Format column)

• Tableau documentation refers to string in the URL-Filters column as the "query string".

Example of a filter parameter in URL-Filters: (all these elements are covered in the examples below):

?AcctManagerID=AA,BB&Salesperson Name=John Smith&:refresh=yes

Example 1: Filter for AcctManagerID identified by code "BB".

URL-Filters = ?AcctManagerID=BB

For Testing: The complete URL copied to the browser might be
After Testing: Copy the part before the "?" to the URL column, copy the question mark and the query string after it to the URL-Filters column.

Example 2:  Older versions of DSA AD - Spaces in Field Names or Values

%20 in place of spaces is allowed but not required in DSA Cloud AD.

Replace spaces with %20

URL-Filters = ?Salesperson%20Name=John%20Smith

For more see: DSA Server - Filter Views using URL Parameters

Example 3: More than One Field Name (USE OF THE & CONNECTOR)

Combine filter parameter segments with "&".

The URL-Filter for Salesperson John Smith in Region 20 :  ?Salesperson%20Name=John%20Smith&Region=20   

Example 4: More than One Value for Filter

Separate multiple values for a filter with a comma.

URL-Filter for Regions 20 and 22:    ?Region=20,22

URL-Filter for Salespersons John Smith and James Wesson:   ?Salesperson%20Name=John%20Smith,James%20Wesson

URL Encoding: The %20 in the example above is an example of URL Encoding.  This encoding is required if you test the filters on your web browser.  In the URL-Filter column the more common encodings are supplied by AD.

Example 5: Force a Fresh Data Query with ":refresh=yes"

Add the parameter ?:refresh=yes to the end of the end of the URL_Filter to  force a fresh data query instead of pulling the results from the cache.

Example: Refresh=yes option added after the filter part:    ?AcctManagerID=AA&:refresh=yes

:refresh=yes Option 

See Example 5 above.  We recommend including the :refresh=yes option on the first row of every batch.  

Tableau is supposed to see when the extract file has been updated.   However, in the past the automatic refreshing of the internal cache from the latest extract file has not worked properly.   This is the workaround.   

For more information see:  URL Encoding,    DSA Server - Filter Views using URL Parameters

Recipient-Email-Address

A email address or list of addresses (optional).
The email address in the list will be send a email with the contents as specified in the current row. 

• Use a blank or the word "NONE" in this column to skip distributing by email.

Address List - more than one address

Separate addresses with semi-colons.

Example:   joe@domain.com; sue@domain.com

Recipient-Name

Optional and informational only.  Can be any name you specify. Usually the name of the email recipient. 

Output-Path

Window's file system path to the file specified in the Output-File-Name column.

• The folders specified in the Output-Path must already exist.

Output-File-Name

Name of a file to save the .png, .pdf or .csv file to.  Default is blank or NONE.

• If delivered by email then this will also be the name of the report file attached to the email.

• We recommend using file names that do not contain spaces or special characters.

• File names containing spaces may have to be delimited by quotes.

• File names cannot contain special characters such as / \ ? % * ; : “ < > .

• For file names with non-ASCII characters see Non-ASCII characters and PDF exports

Output-Format

Required. Must be either pdf, png, fullpdf or csv.

• This value may need to match the .png or .pdf extension, if any, ending of the URL column.

• Use pdf or png to output a view or a dashboard in a workbook.

  • Note: The optional dashboard features called web page objects won't be included in the PDF.

fullpdf

fullpdf outputs all views in a workbook to a pdf file, one view per page in the .pdf file.

• To export a workbook, it must have been published with Show Sheets as Tabs selected in the Tableau Desktop Publish dialog box.

csv

• csv output is also known as "crosstab" output.

• Use csv only for one view at time.

Click here to expand section on CSV output

WARNING: It's easy to create views that Tableau cannot accurately render in .csv format output.
Most views have complex structures that cannot be rendered in .csv format. The software gives no warning when this condition occurs and the .csv output that results is unpredictable.

See also: Tableau - Export measure fields to csv

Notes:

• The csv option is also variously known as crosstab or crosstab to Excel on some DSA/Tableau screens and in documentation.

• The output to csv must be a simple table with column labels from a single view. Do not put row labels, totals or other so-called "crosstab" features in the view.

• We recommend mentally translating "crosstab" to "raw data in a widely used format".

• Earlier versions of DSA AD did not allow this option because of the unpredictable nature of the output.

Subject-Line

Text that will appear in the subject line of the email.  Optional.
Ignored if Recipient-Email-Address is blank or "NONE".

Body-Line

Text that will appear in the body of the email.  Optional.

Process

Set to "Yes" to process this row.
The software recognizes two codes - "NO" and "TEST".
Any value other than "NO" or "TEST" is ignored and the line is processed normally.

When Process = NO this line is skipped.When Process = TEST no email is sent but the log file will display the email settings that would have been used.

Options

Optional PDF format options for pagelayout, pagesize, width and height.

Example:

--pagelayout portrait --width 800

--pagelayout

Sets the page orientation (landscape or portrait) of the exported PDF.If not specified, its Tableau Desktop setting will be used.

Example:  --pagelayout portrait

--pagesize

Sets the page size of the exported PDF as:  unspecified, letter, legal, note folio, tabloid, ledger, statement, executive, a3, a4, a5, b4, b5, or quarto.

Default is letter.unspecified asks the software to dynamically adjust the size to fit the report.

Example: --pagesize legal

Example:  Landscape mode, adjust page size to fit the data.
--pagelayout landscape --pagesize unspecified

Use of --pagesize unspecified

--pagesize unspecified may cause problems with the PDF output and how the PDF file is read by Abobe's PDF Reader.

--width

Sets the width in pixels.Default is 600 pixels (px). ?

Example: --width 600

--height

Sets the height in pixels.  Default is 800 pixels.