TIBCO Spotfire® Automation Services

User's Guide
Software Release 10.10 LTS (10.10.1)
 ii

Contents

Important Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

TIBCO Documentation and Support Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Creating a job file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Inserting a field in a Spotfire Automation Services job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Duplicating tasks in a job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Job Builder tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Apply Bookmark. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Automated library export and import. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Export Data Table to Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Export Data to File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Export Image. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Export Report to PDF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Export to PDF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Open Analysis from Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Replace Data Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Save Analysis to Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Send Email. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Set Credentials for External Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Set Data Source Credentials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Update Text Area Contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Job file testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Testing a job file locally. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Testing a job file on Spotfire Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Job execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Installing the Client Job Sender. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Authentication options for the Client Job Sender. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Configuring the Client Job Sender. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Configuring the Client Job Sender for OAuth2 authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Running the Client Job Sender. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Scheduling the Client Job Sender. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Client Job Sender monitoring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

TIBCO Spotfire® Automation Services User's Guide

 3

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED
TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY)
OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR
ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE
AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO
SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING
DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF
THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE
LICENSE(S) LOCATED IN THE "LICENSE" FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE
TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO
BE BOUND BY THE SAME.

ANY SOFTWARE ITEM IDENTIFIED AS THIRD PARTY LIBRARY IS AVAILABLE UNDER SEPARATE SOFTWARE LICENSE
TERMS AND IS NOT PART OF A TIBCO PRODUCT. AS SUCH, THESE SOFTWARE ITEMS ARE NOT COVERED BY THE
TERMS OF YOUR AGREEMENT WITH TIBCO, INCLUDING ANY TERMS CONCERNING SUPPORT, MAINTENANCE,
WARRANTIES, AND INDEMNITIES. DOWNLOAD AND USE OF THESE ITEMS IS SOLELY AT YOUR OWN DISCRETION
AND SUBJECT TO THE LICENSE TERMS APPLICABLE TO THEM. BY PROCEEDING TO DOWNLOAD, INSTALL OR USE
ANY OF THESE ITEMS, YOU ACKNOWLEDGE THE FOREGOING DISTINCTIONS BETWEEN THESE ITEMS AND TIBCO
PRODUCTS.

This document is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in
any form without the written authorization of TIBCO Software Inc.

TIBCO, the TIBCO logo, the TIBCO O logo, TIBCO Spotfire, TIBCO Spotfire Analyst, TIBCO Spotfire Automation Services,
TIBCO Spotfire Server, TIBCO Spotfire Web Player, TIBCO Enterprise Runtime for R, TIBCO Enterprise Runtime for R - Server
Edition, TERR, TERR Server Edition, and TIBCO Spotfire Statistics Services are either registered trademarks or trademarks of
TIBCO Software Inc. in the United States and/or other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and
are mentioned for identification purposes only.

This software may be available on multiple operating systems. However, not all operating system platforms for a specific
software version are released at the same time. Please see the readme.txt file for the availability of this software version on a
specific operating system platform.

THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE
PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW
EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE
PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER
DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES
AND "READ ME" FILES.

This and other products of TIBCO Software Inc. may be covered by registered patents. Please refer to TIBCO's Virtual Patent
Marking document (https://www.tibco.com/patents) for details.

Copyright © 1994-2020. TIBCO Software Inc. All Rights Reserved.

TIBCO Spotfire® Automation Services User's Guide

 4

TIBCO Documentation and Support Services

How to Access TIBCO Documentation

Documentation for TIBCO products is available on the TIBCO Product Documentation website, mainly
in HTML and PDF formats.
The TIBCO Product Documentation website is updated frequently and is more current than any
other documentation included with the product. To access the latest documentation, visit https://
docs.tibco.com.

TIBCO Spotfire® Automation Services Documentation

Documentation for TIBCO Spotfire Automation Services is available on the Spotfire Server Product
Documentation page.
The following documents for this product can be found on the TIBCO Documentation site:

● Spotfire® Automation Services User's Manual

● Spotfire® Automation Services API Reference
● Spotfire® Automation Services REST API Reference

Release Version Support

Some release versions of TIBCO Spotfire products are designated as long-term support (LTS) versions.
LTS versions are typically supported for up to 36 months from release. Defect corrections will typically
be delivered in a new release version and as hotfixes or service packs to one or more LTS versions. See
also https://docs.tibco.com/pub/spotfire/general/LTS/spotfire_LTS_releases.htm.

How to Contact TIBCO Support

You can contact TIBCO Support in the following ways:

● For an overview of TIBCO Support, visit http://www.tibco.com/services/support.

● For accessing the Support Knowledge Base and getting personalized content about products you are
interested in, visit the TIBCO Support portal at https://support.tibco.com.
● For creating a Support case, you must have a valid maintenance or support contract with TIBCO.
You also need a user name and password to log in to https://support.tibco.com. If you do not have a
user name, you can request one by clicking Register on the website.

System Requirements for Spotfire Products

For information about the system requirements for Spotfire products, visit http://spotfi.re/sr.

How to join TIBCO Community

TIBCO Community is the official channel for TIBCO customers, partners, and employee subject matter
experts to share and access their collective experience. TIBCO Community offers access to Q&A forums,
product wikis, and best practices. It also offers access to extensions, adapters, solution accelerators, and
tools that extend and enable customers to gain full value from TIBCO products. In addition, users can
submit and vote on feature requests from within the TIBCO Ideas Portal. For a free registration, go to
https://community.tibco.com.

TIBCO Spotfire® Automation Services User's Guide

 5

For quick access to TIBCO Spotfire content, see https://community.tibco.com/products/spotfire.

TIBCO Spotfire® Automation Services User's Guide

 6

Overview

TIBCO Spotfire® Automation Services is a web service for automatically executing multi-step jobs
within your TIBCO Spotfire® environment. You can, for example, use Spotfire® Automation Services to
deliver an analysis file to specific people, in a particular format, at specified times.
The Automation Services feature includes the following components:

● The Spotfire Automation Services Job Builder, which comes with a set of pre-defined tasks for
immediate job creation. The Job Builder is accessed from TIBCO Spotfire® Analyst. No installation
is required, but all users must belong to the group Automation Services Users, and have the
Automation Services Job Builder Tool license enabled.
● An API for developing custom tasks for the Job Builder.
● The Automation Services area of the administration interface for scheduling and executing jobs. For
more information, see "Automation Services job scheduling" in the Spotfire Server help.
● The Client Job Sender command-line tool for executing jobs. To install this tool, you download and
extract the Spotfire Automation Services files from the TIBCO eDelivery website, and copy the files
to a computer in your Spotfire implementation. For details, see Installing the Client Job Sender.

When using the Client Job Sender, you can set the execution schedule by using Windows
Task Scheduler.

TIBCO Spotfire® Automation Services User's Guide

 7

Creating a job file

A Spotfire Automation Services job file is an XML file that is created in the Job Builder. It contains the
set of tasks that are performed each time that the job runs, along with any relevant settings for each
task.
Prerequisites

● To execute Spotfire Automation Services jobs on the server using the Job Builder or the Client Job
Sender, a user must be a member of the group Automation Services Users.
● To run the Job Builder, a user must also have the Automation Services Job Builder Tool license
enabled.
● Analysis files that are used in automation jobs must be in the Spotfire library.
For information on group membership, see the Spotfire® Server help. For information on licenses, see
the help for Administration Manager in Spotfire® Analyst.
Procedure

1. Open Spotfire Analyst.

2. Click Tools > Automation Services job builder.
3. In the Job Builder, click Add and then click the first task in the job.

Any job that contains tasks involving an analysis file must begin with the Open Analysis
from Library task.
4. To the right of the task list, in the Settings pane, adjust the task settings as necessary.
5. Repeat steps 3 and 4 until you have completed the task list and settings. For details on the available
tasks and settings, see Job Builder tasks.
6. Save the job file to the Spotfire library, or to a location of your choice.
7. Optional: If the job was saved to the library, you will see a dialog where you can click on a link and
go to the server to create or edit a schedule for the job.
For more information about schedules, see the Spotfire® Server help.

Inserting a field in a Spotfire Automation Services job

To ensure that the Job Builder creates a new file each time that a particular job runs, you can add one
or several fields, such as the automatically updated date and time fields, to the file name. You can also
insert fields in other text areas, such as an email message that you create for sending a new file to its
recipients.
Procedure

1. From Spotfire Analyst, open the Spotfire Automation Services Job Builder.
2. Open the job file to which you want to add a field.
3. In the Automation Services Job Builder dialog, place the cursor where you want to insert a field,
either in the file name part of the destination path or in another text area.
4. Click Tools > Insert Field, and then select the field you want to add.

TIBCO Spotfire® Automation Services User's Guide

 8

Duplicating tasks in a job

For Job Builder jobs that include executing a task repeatedly, such as opening several analyses and
exporting each one to a PDF file, you can duplicate an existing task, including its settings, as many
times as needed.
Prerequisites

You have created the first instance of the task.

Procedure

1. In the Automation Services Job Builder, in the left pane select the task that you want to duplicate.
2. Click Duplicate.
The new task appears directly below the original task in the task list.
3. Edit the new task as needed and move it to its correct spot in the task list.

Job Builder tasks

These are the tasks that are included in the Spotfire Automation Services Job Builder.
If your version includes different tasks, contact your Spotfire administrator for information on how to
use those tasks.

Apply Bookmark
You can apply bookmarks to your job files to highlight certain aspects of a data set.
For example, you can use bookmarks if you have an analysis file with sales data for a department store
and you want the manager of each department to receive a weekly update on their department.
You can create one job file for each department in the store, basing all the job files on the same analysis.
If you then apply different bookmarks in each job file, each manager can receive a customized view of
the analysis when the jobs are run.

Option Description

Bookmark Specifies the bookmark to apply. All the bookmarks in the analysis are listed in
the Bookmark list.

Automated library export and import

The tasks Export Library Items and Import Library Items have been deprecated in Spotfire Automation
Services.
Instead of Export Library Items and Import Library Items, use the following commands on the Spotfire
Server command line:

● export-library-content
● import-library-content

TIBCO Spotfire® Automation Services User's Guide

 9

Details about these commands are available in the "Command-line reference" section of the Spotfire
Server and Environment Installation and Administration help.
If you decide to use these deprecated tasks in Spotfire Automation Services anyway, these are the
available settings:

Export Library Items

Option Description

Export from library folder Specifies the location and name of the folder to export from the library.

To export a folder and its contents to file you must have Browse +
Access permissions for the folders you want to export. You must also
be a member of the Library Administrator group.

Browse... Opens the Browse Library dialog where you can locate the library folder from
which you want to export items. Only available if you are connected to the
library.

Export to file Specifies a name for the file that will be created. The file will be saved as a zip
archive on the server.

The format of the entire file name will be fileName.part0.zip.

However, you should always specify the name without file name
extensions such as .part0 or .zip.

To include all the exported items, several zip archives may be created
from one single export. The middle part of the file name will reflect
this: fileName.part0.zip, fileName.part1.zip, fileName.part2.zip, and
so on.

Export items of type Specify the type of items you want to export if you want to limit the export to
only a certain type.

Include permissions Select whether or not to include the selected library folder permissions.

Import Library Items

Option Description

Import from file Specifies the name of the file to import. The file must be a zip archive
containing appropriate library content.

The format of the entire file name is fileName.part0.zip. However,

you should always specify the name without any file name
extensions such as .part0 or .zip.

If the zip archive is located in a subfolder to the Shared disk location

folder you must provide the subfolder name as well. Example:
subfolderName/fileName.

To import a folder and its contents to file you must have Browse +
Access + Modify permissions for the destination folder. You must
also be a member of the Library Administrator group.

Import to library folder Specifies the location and the name of the folder in the library to which you
want to import the library items.

Browse... Opens the Browse Library dialog where you can select the folder in the library
to which you want to import. Only available if you are connected to the library.

TIBCO Spotfire® Automation Services User's Guide

 10

Option Description

Import items of type Specify the type of items you want to import if you want to limit the import to
only a certain type of items.

Include permissions Select this check box if you want to include permissions, if such are stored in
the file. If you do not include any permissions, the imported items will inherit
the permissions of the destination folder.

Ignore empty folders Select this check box if you do not want to import any empty library folders.

Remap Data Sources

When you migrate library items from one system to another, it is likely that you will have to remap the
connection strings and/or passwords of the data sources when you import them to the new system.

Option Description

X.509 certificate subject Select a valid X.509 certificate. This is used to protect the security of the
passwords used to connect to data sources when exporting and importing
them. The valid certificates that are installed locally on your computer are
listed in the drop-down list.

The selected certificate must also be installed on the node that runs
the Automation Services jobs.

Data sources library folder Defines the location of the library folder that contains the data sources to be
repmapped.

This is optional. However, if you do not specify a library folder, you

must include the entire path for each data source that you add.

Browse Opens the Browse Library dialog where you can select a library folder. Only
available if you are connected to the library.

Data sources Lists the currently added data sources.

If you have not specified a Data sources library folder, you must
include the entire path for each data source that you add.

Add Opens a dialog where you can specify a new data source. See below

Edit Opens a dialog where you can edit the selected data source. See below.

Remove Removes the selected data source from the list.

Import Opens a dialog where you can select a previously exported file. All the data
sources that are included in the file will be added to the list.

Connection string Specifies the current connection string for the selected data source. To change
it, enter a new connection string in the text field.

Reset Resets the modified connection string to the one that was originally set for the
selected data source.

Password The current password for the selected data source.

Change Opens a dialog where you can enter a new password for the selected data
source.

TIBCO Spotfire® Automation Services User's Guide

 11

Option Description

Reset Resets the modified password to the one that was originally set for the data
source.

Option Description

Name Enter a name for the new or edited data source.

In library folder Displays the location and name of the library folder that contains the data
source.

Export Data Table to Library

You can export a data table from an analysis file and save it to the library as a Spotfire Binary Data File
(SBDF).
If you want to make sure that the data table is saved as a new data table each time that the job is
executed, you can add the date to the file name; for more information, see Inserting a field in a Spotfire
Automation Services job.

TIBCO Spotfire® Automation Services User's Guide

 12

Option Description

Data Table Select the data table that you want to export from the analysis file.

Library Path Specify the library path and file name for saving the data table.

Description Add a description for the data table.

If the data table already has a description, it is displayed here.

Keywords Add keywords for the data table, separated by semicolons.

If the data table already has specified keywords, they are displayed
here.

Export Data to File

You can export the data from a data table, or a tabular visualization, and save it as a file on disk.
If you want to make sure that the data table is saved as a new data table each time that the job is
executed, you can add the date to the file name; for more information, see Inserting a field in a Spotfire
Automation Services job.

Option Description

Export data from Select a tabular visualization or a data table to export data from.

Export data as Select the file format the data should be saved as.

Data exported from a cross table, summary table or graphical table

can only be saved as a tab separated Spreadsheet file.

TIBCO Spotfire® Automation Services User's Guide

 13

Option Description

Export data to Select where to save the exported data.

The file will be saved to the node executing the job. Therefore
you must make sure that the folder you select as destination
folder actually exists on that computer, and that you have writing
permissions for the selected folder.

Allowed file paths may be limited by the allowedFilePaths setting

in the Spotfire.Dxp.Worker.Automation.config file. For more
information, see the Spotfire Server and Environment Installation
and Administration help.

Export Image
You can export an image from an analysis file to a destination of your choice.
If you want to make sure that the image is saved as a new data table each time that the job is executed,
you can add the date to the file name; for more information, see Inserting a field in a Spotfire
Automation Services job.

Option Description

Destination Path Specify the location (on the node running Automation Services) and file name
of the exported image.

The file will be saved to the node executing the job. Therefore
you must make sure that the folder you select as destination
folder actually exists on that computer, and that you have writing
permissions for the selected folder.

Allowed file paths may be limited by the allowedFilePaths setting

in the Spotfire.Dxp.Worker.Automation.config file. For more
information, see the Spotfire Server and Environment Installation
and Administration help.

Visualization Specify the visualization to export.

The exported image only includes the currently visible content.

Hide preview images in list Select to disable rendering of images in visualization list. This significantly
improves response time if there are many available visualizations in the
analysis.

TIBCO Spotfire® Automation Services User's Guide

 14

Option Description

Width Specify the width, in pixels, that the exported image should have.

Height Specify the height, in pixels, that the exported image should have.

Maintain aspect ratio Select this check box to make sure that the aspect ratio of the exported image is
the same as the current ratio of the visualization in the analysis.

Export Report to PDF

You can prepare a report of an analysis and export it to a PDF file that is saved to a destination of your
choice on the computer running Spotfire Automation Services.
The Export Report to PDF task replaces the Export to PDF task. The settings that were made in
the Export to PDF task are included in the report itself. To learn how to prepare reports, see the
Spotfire Analyst help.
If you want to make sure that the document is saved as a new file each time the job is executed, you can
add a field to the file name; for more information, see Inserting a field in a Spotfire Automation Services
job.

Option Description

Destination path Specify the location (on the computer running Spotfire Automation Services)
and file name of the exported PDF file.

The file will be saved to the node executing the job. Therefore
you must make sure that the folder you select as destination
folder actually exists on that computer, and that you have writing
permissions on the selected folder.

Allowed file paths may be limited by the allowedFilePaths setting

in the Spotfire.Dxp.Worker.Automation.config file. For more
information, see the Spotfire Server and Environment Installation
and Administration help.

Report name Select the report to export. All prepared reports of the analysis are available in
the drop-down list.

Export to PDF
The task Export to PDF has been deprecated in Spotfire Automation Services.
Instead of Export to PDF, use the task Export Report to PDF.
If you decide to use the deprecated task in Spotfire Automation Services anyway, see the following
information.

TIBCO Spotfire® Automation Services User's Guide

 15

Export to PDF

You can export parts of an analysis to a PDF file, and save the file to a destination of your choice on the
computer running Spotfire Automation Services.You can choose between two types of PDF export:

● Export selected visualizations or pages as they currently appear in the analysis.

● Export based on bookmarks.
With bookmarks export, you can export all the bookmarks of interest, in one single export operation
and to one single document. Each of the bookmarks will automatically be applied in turn during the
export, and the resulting PDF document will contain one version of the analysis (or parts of it) for each
bookmark.
If you want to make sure that the document is saved as a new file each time the job is executed, you can
add a field to the file name; for more information, see Inserting a field in a Spotfire Automation Services
job.

General tab

TIBCO Spotfire® Automation Services User's Guide

 16

Option Description

Destination Path Specify the location (on the computer running Spotfire Automation Services)
and file name of the exported PDF file.

The file will be saved to the node executing the job. Therefore
you must make sure that the folder you select as destination
folder actually exists on that computer, and that you have writing
permissions on the selected folder.

Allowed file paths may be limited by the allowedFilePaths setting

in the Spotfire.Dxp.Worker.Automation.config file. For more
information, see the Spotfire Server and Environment Installation
and Administration help.

Export what Define which parts of the analysis to export. For more information about
what the options in this drop-down list mean for the different export types,
see the following topics in the Spotfire Analyst help: "Exporting to PDF" and
"Exporting Bookmarks to PDF".

If you export bookmarks, then the PDF file will contain one set of
PDF pages for each bookmark. For example, if you export three
bookmarks and select All pages, then you will get a PDF document
containing all the pages in the analysis times three (that is, one set
of all analysis pages for each of the bookmarks). The descriptions of
the drop-down list options below are based on regular export where
each page or visualization appears only once in the resulting PDF.

Active visualization Exports the active visualization in the analysis (or in the bookmark, for
bookmark export) to a single page in a PDF document.

Tables and trellised visualizations may be extended to more than one

page.

Active page Exports all the visualizations on the active page in the analysis (or in the
bookmark, for bookmark export) to a single page in a PDF document.

Active page (new page for each Exports all the visualizations on the active page in the analysis (or in the
visualization) bookmark, for bookmark export) to one or more pages in a PDF document.
Each visualization on the active page will be exported to a new page in the PDF
document.

Tables and trellised visualizations may be extended to more than one

page.

All pages Exports all the visualizations on all the pages in the analysis. Each page will be
exported to a new page in the PDF document.

All pages (new page for each Exports all the visualizations on all the pages in the analysis. Each visualization
visualization) in the analysis will be exported to a new page in the PDF document.

Tables and trellised visualizations may be extended to more than one

page.

Details-on-Demand Exports the Details-on-Demand to one or more pages in a PDF document.

Select the check box Trellis panels and table rows not visible on screen if you
want to export all the data in Details-on-Demand, including data that is not
visible.

Use entire page When exporting to PDF from Automation Services, this option is not applicable
because the exported parts of the analysis do not have any proportions when
the user interface is not available. Therefore, the result will always be that the
exported parts of the analysis are redrawn to fill the entire space of the selected
page layout.

TIBCO Spotfire® Automation Services User's Guide

 17

Option Description

Include

Visualization title Indicate whether you want the page titles to be included in the export.

Description Indicate whether you want hidden visualization descriptions to be included

in the export. The description will only be visible for visualizations where a
description has been entered. If the description is visible in the visualization
or legend, it will automatically be included in the export as a part of the
visualization.

A long description may be cut off when you export to PDF.

Filter settings Indicate whether you want the filter settings to be included in the export as
textual information. Only the values of the modified filters will be listed.

Page title Indicate whether you want the page titles to be included in the export.

Trellis panels and table rows not visible Indicate whether to include non-visible data in trellis panels and tables in
on screen the export. If a table contains too many rows to fit on one page in the PDF
document, it will be extended to the following pages. Similarly, a trellised
visualization with many panels will be extended to the following pages.

Not available if you select to export Active page or All pages. You
must select an option where each visualization is exported to a new
page.

Page layout Define the size and orientation of the pages in the resulting PDF document.

Margins Define the margins of the page, in pixels.

TIBCO Spotfire® Automation Services User's Guide

 18

Advanced tab

Option Description

Graphics settings

Items to export Lists the parts of the analysis to include in the export. The items in the list may
refer to pages, visualizations, or the Details-on-Demand, depending on the
selection that you made under Export what on the General tab.

Name Shows the names of the pages or visualizations to export.

Graphics mode Here you can change which graphics mode each item will be exported as:
Vector or Raster. This can be useful if you must keep the file size down.

Using raster graphics does not always result in a smaller file size, but
if the file becomes very large when exporting as vector graphics, you
can try exporting as raster graphics instead.

TIBCO Spotfire® Automation Services User's Guide

 19

Option Description

All Vector Graphic Click this button to set all the items in the list to be exported using vector
graphics.

3D scatter plots are always exported as raster graphics.

All Raster Graphic Click this button to set all the items in the list to raster graphics.

Raster graphics quality Here you can specify the quality of the export for parts of the analysis that
will be exported as raster graphics. This can be useful if you need to keep the
file size down. You can specify a value from 1.0 to 5.0, where 1.0 is the lowest
quality and will result in a smaller file size.

Using raster graphics will always result in lower quality than vector
graphics, even if you set the raster graphics quality to the highest
possible value. However, using raster graphics does not always result
in a smaller file size.

Header options

Enable page header Select this check box if you want to include a header on each page in the
resulting PDF document.

Header height Enter a number between 10 and 100 to adjust the height of the header.

Left, Center, Right Make a selection from each drop-down list to specify the position of the header
content, and what to include in the header. The following options are available:

● Custom text (enter the text of your choice in the field below the drop-down
list)
● Page number
● Current date
● Current date and time

Font Settings Specify font, style, and size for the header. The current font settings are
displayed to the right of the button

Footer options

Enable page footer Select this check box if you want to include a footer on each page in the
resulting PDF document.

Footer height Enter a number between 10 and 100 to adjust the height of the footer.

Left, Center, Right Make a selection from each drop-down list to specify the position of the footer
content, and what to include in the footer. The following options are available:

● Custom text (enter the text of your choice in the field below the drop-down
list)
● Page number
● Current date
● Current date and time

Font Settings Specify font, style, and size for the footer. The current font settings are
displayed to the right of the button.

TIBCO Spotfire® Automation Services User's Guide

 20

Bookmarks tab

The Bookmarks tab is used only when you want to export different views of the analysis, which are
defined by selected bookmarks. When you select this option, each of the bookmarks is automatically
applied in turn, and the resulting PDF file contains one version of the analysis (or parts of it) for each
bookmark. See "Exporting Bookmarks to PDF" in the Spotfire Analyst online help for more information
about the result of exporting based on bookmarks.

Option Description

Export selected views based on bookmarks Select this check box to enable export to a PDF file based on
bookmarks. Choose which parts of the analysis to export on
the General tab.

[List of available bookmarks] Select the bookmarks you want to export.

Open Analysis from Library

A job generally starts with a task that opens an analysis file. The job is then based on this file, and all
the tasks are performed on this file.
If you want to use an analysis file that is already open in Spotfire, you can click Set to Current. If you
have opened a job file that is based on an analysis file that is not currently open, you can click Load to
open that file in Spotfire. You can use a configuration block to configure the initial state of the analysis
file that you want to open, such as applying a bookmark, or setting a filter to the analysis before it is
opened.

Option Description

Path Indicate the location and file name of the file to open. Click Browse to navigate to the file, or use
the Set to Current option.

Set to Current Click this button to set the path to the analysis that is currently open in Spotfire.

TIBCO Spotfire® Automation Services User's Guide

 21

Option Description

Load Opens the analysis that is specified in the Path field.

If the Open Analysis from Library task is preceded by the Set Data Source Credentials
task or the Set Credentials for External Connection task, it is not possible to load the file
using this button. It is therefore not possible to edit any following tasks, for example
the Export Image task, either. To be able to do this, open the file from the File menu in
Spotfire Analyst before proceeding with setting up additional tasks.

Configuration block Optionally, use this advanced feature to provide a configuration block to specify the initial state of
the analysis. A configuration block is a piece of code that defines, for example, which page is active
in the analysis when the analysis is opened, or applies a specific bookmark when the analysis.
Example:

SetPage(pageTitle = "Overview");
ApplyBookmark(bookmarkName = "UserRegionOnly");

Replace Data Table

You can replace the contents of a data table with the contents of an SBDF file stored in the library, or,
with a prompted information link.

For an information link, you can specify parameters for the information link to filter by. For example,
you can set the task to show only the column values that are greater than a specified value, or the
values between two specified values.

Option Description

Data table to replace Specify the data table that you want to replace with an
information link.

SBDF library path Indicates the path to the selected SBDF file in the library.
Click on the button next to the field to browse for a file.

TIBCO Spotfire® Automation Services User's Guide

 22

Option Description

Information link Indicates the path to the selected information link. Click on
the button next to the field to browse for an information link.

The information link must have prompts in order

to be useful. If you want to use parameterized
information links instead, you can specify that in
a configuration block when you open the analysis
from the library; see Open Analysis from Library.
To learn more about using information links, see
the Spotfire Analyst help.

Information link parameters Lists the columns with parameters of the selected
information link.

Edit Opens the Edit Information Link Parameters dialog (shown

below) where you can set parameters for the selected
column.

Option Description

Column name Displays the name of the column for which you are currently
editing parameters.

Data type Set the data type of the column.

Expression Set the expression that indicates how the column value
should be compared to the values set in this dialog, and thus
how the data is filtered.

List of values List the values by which you want to filter. The values that
you enter here will replace the %Value% in the selected
expression above.

Save Analysis to Library

This task saves the analysis to a location of your choice in the library.
To save a unique analysis each time that the job runs, instead of replacing the existing one, you can add
a field to the file name; for more information, see Inserting a field in a Spotfire Automation Services job.

TIBCO Spotfire® Automation Services User's Guide

 23

Option Description

Save as Specify the location and name of the file that will be saved.

Set to Current Click to use (in the Save as field) the path of the currently
open document.

Embed data in analysis Select this check box to embed the data in the analysis.

Remove any previously existing bookmarks Select this check box to delete any previously existing
bookmarks when the analysis is saved to the library. Note
that if you select this check box, bookmarks that have been
added by other users will be removed

Description Optionally, type a description of the analysis.

Keywords (not shown in image) Optionally, type one or more keywords specific to the
contents of the analysis.

Send Email
A job can be set up to send an email to a number of recipients when it is executed.
You can write a message with included images, attach an analysis or a file, and add links to the web
clients and library.

To enable this task, you must add SMTP settings to the

Spotfire.Dxp.Worker.Automation.config file; for instructions, see Adding SMTP settings to
the Spotfire.Dxp.Worker.Automation.config file.

TIBCO Spotfire® Automation Services User's Guide

 24

Option Description

To Type the email addresses to which the email should be sent. The separator to
use depends on the regional settings of your computer.

Cc Type the email addresses to which a copy of the email should be sent.

Bcc Type the email addresses to which a hidden copy of the email should be sent.

From Type the email address from which the email should be sent. If the From-
address for a job is unspecified, then the email address from the configuration
file will be used.

Select Click to open a dialog where you can select recipients from your LDAP
directory. This only works if you have an LDAP directory.

Subject Enter a subject for the email.

TIBCO Spotfire® Automation Services User's Guide

 25

Option Description

Message Enter the body text of the email.

Add library link Select the check box to include a link to the analysis in the library.
Optionally, enter text for the link in the text box, such as "Click to open analysis
from the library." If you leave the field blank, the link is shown as the actual
path to the library.

Add Web Player link Select this check box to include a link to the analysis in the web client.
Optionally, enter text for the link in the text field. If you leave the field blank,
the link is shown as the actual path.

Attach analysis (with embedded data) Select this check box to attach the analysis to the email.

Attached visualization images You can include images from visualizations in the email. The images will be
shown in the message body. The data will be embedded in the email. See the
Add Visualization dialog below this table.

Add... Open to select the visualization images to add.

Edit Edit the settings for an added image.

Remove Removes the selected image from the list.

Attached files You can include files in the email, for example a PDF created by the Export
Report to PDF task.

Add... Opens the Select File Attachment dialog, where you select the file to attach,
specify the name of the attachment, and select if the file should be deleted after
the email has been sent.

Only select to delete the file if you are absolutely sure that the file
should be deleted after the email has been sent. It is recommended
to only delete temporary files, such as PDF files created by the
Export Report to PDF task for the sole purpose of being sent
out in an email. To avoid deleting files that should be saved,
files can only be deleted if they have a create or modification
time in the last 30 minutes. The time can be changed in the
allowDeleteOfFilesModifiedLastMinutes setting in the
Spotfire.Dxp.Worker.Automation.config file.

Allowed file paths may be limited by the allowedFilePaths setting

in the Spotfire.Dxp.Worker.Automation.config file. For more
information, see the Spotfire Server and Environment Installation
and Administration help.

Edit Edit the settings for an added attachment.

Remove Removes the selected attachment from the list.

TIBCO Spotfire® Automation Services User's Guide

 26

Option Description

Visualization Select the visualization image that you want to appear in the email.

Hide preview images in list If the check box is selected, the list of visualizations directly above the check
box does not display previews for each visualization. This reduces download
time.

Width You can change the height and width of the image. Select the Maintain aspect
ratio check box to keep the image's original proportions.
Height

Maintain aspect ratio

Add visualization title as text above the If the check box is selected, the title of the visualization, followed by a colon,
image appears just above the visualization. This is the default.

Hide visualization title from the image If the Show title bar check box is selected in the visualization Properties dialog,
select this check box to prevent the visualization title from appearing in the
upper-left corner of the image.
This is the visualization title appearing within the image:

Add extra line breaks above image Select this check box to add space above the image in the email message.

TIBCO Spotfire® Automation Services User's Guide

 27

Adding SMTP settings to the Spotfire.Dxp.Worker.Automation.config file

When you add the Send Email task to a Spotfire Automation Services job, you must also manually
add the SMTP settings to the Spotfire.Dxp.Worker.Automation.config file and assign the new
configuration to a service running Automation Services.
Prerequisites

You must have administrative credentials for Spotfire Server.

Procedure

1. On the computer running Spotfire Server, open a command line as an administrator and change
the directory to the location of the config.bat file (config.sh on Linux). The default location is
<server installation directory>\tomcat\spotfire-bin.
2. On the command line, export the service configuration that you want to modify from Spotfire
Server by using the export-service-config command. Specify the service's capability and the
deployment area, and optionally the configuration name.
By default, all new services receive a "Default" configuration. The properties of the default
configuration cannot be changed, but you can edit the configuration files and save the
resulting configuration with a new name.

If you are editing a service configuration that has been applied to an existing service, you
must verify the name of the active service configuration before you export it. If the name of
the active configuration is not "Default", you must specify the name in the export command.
To find the name of the active service configuration, see "Viewing the name of the active
service configuration" in the Spotfire Server help.
Example for exporting the "Default" Spotfire Automation Services configuration that is in the
Production deployment area:

config export-service-config --capability=AUTOMATION_SERVICES --deployment-

area=Production

Example for exporting a customized configuration:

config export-service-config --capability=AUTOMATION_SERVICES --deployment-

area=Production --config-name=AutomationServicesConfiguration

The configuration files are exported. By default, these files are saved to the <server installation
directory>\tomcat\spotfire-bin\config\root directory.
3. Open the Spotfire.Dxp.Worker.Automation.config file in a text editor or XML editor, and locate
the following section:

<preferences>
<!-- SMTP Host for Email Notification -->
<add name="Spotfire.Automation.SendMail.SMTPHost" value="smtp.company.com" />
<!-- From Address for Email Notification -->
<add name="Spotfire.Automation.SendMail.FromAddress"
value="[email protected]" />
<!-- Timeout (seconds) for the library import operation for the Import Library task
-->
<add name="Spotfire.Automation.LibraryImport.TimeoutInSeconds" value="300" />
<!-- Timeout (seconds) for the library export operation for the Export Library task
-->
<add name="Spotfire.Automation.LibraryExport.TimeoutInSeconds" value="300" />
</preferences>

TIBCO Spotfire® Automation Services User's Guide

 28

4. Edit the following two settings:

● Replace the value of Spotfire.Automation.SendMail.SMTPHost with the SMTP host for email
notification.
● Replace the value of Spotfire.Automation.SendMail.FromAddress with the From address for
email notification.

For information on other Automation Services settings that you can configure, see the topic
"Spotfire.Dxp.Worker.Automation.config" in the Spotfire Server help.
5. On the command line, import the customized configuration file back into Spotfire Server and name
the configuration by using the import-service-config command.
If the configuration to be imported was created from the default configuration, a new name
must be specified.

Importing customized configuration files without the --config-name parameter overrides

the default configuration.

config import-service-config --config-name=ServiceConfiguration

6. Optional: On the command line, assign the created configuration to an existing Automation Services
service:

config set-service-config --service-id=value --config-name=ServiceConfiguration

Use the list-services command to obtain the service ID.

Alternatively to step 6, you can assign the new configuration to a service by editing the
service in the Nodes & Services section of the server's administration interface .

Set Credentials for External Connection

To open an analysis that requires authentication for external data sources (that is, any analysis that uses
Spotfire data connectors), use this task to specify the credentials.
The way that you set credentials with this task is not the same as using a regular credentials
profile.
Usually, credentials profiles are stored in the web service configuration file
Spotfire.Dxp.Worker.Host.exec.config. This is a complementary way of storing and
setting credentials, that you can use if you cannot store a credentials profile in the web service
configuration.
This task should be performed before any "Open Analysis from Library" task. To secure the login
credentials, you must encrypt them using an X.509 certificate. Note that you need to add one Set
Credentials for External Connection task for each credentials profile. The credentials profiles are used
to connect a username and password to an external data source that is used in a specific analysis.

TIBCO Spotfire® Automation Services User's Guide

 29

Option Description

X.509 certificate subject Select a valid X.509 certificate. This is used to protect the security of the
passwords that are used to connect to the external data sources. The valid
certificates that are installed locally on your computer are listed in the drop-
down list.

The selected certificate must also be installed on the node that runs
the Automation Services jobs.

Credentials profile Select the name of the credentials profile. Make sure that the profile matches a
profile that is saved in the analysis file. The profile that is used in an analysis is
saved in the Data Connection Properties dialog in Spotfire.

Username Enter the username for the profile to use when connecting to the data source.

Username is mandatory.

Password Enter the password for the profile.

Password is mandatory.

Set Data Source Credentials

To open an analysis or information link that requires data source authentication, use this task to specify
the credentials.
This task should be performed before any Open Analysis from Library or Replace Data Table with
Information Link tasks. To secure the login credentials, you must encrypt them using an X.509
certificate. Note that you must add one Set Data Source Credentials task for each data source that
requires authentication.

TIBCO Spotfire® Automation Services User's Guide

 30

Option Description

X.509 certificate subject Select a valid X.509 certificate. This is used to protect the security of the
passwords used to connect to data sources. The valid certificates that are
installed locally on your computer are listed in the drop-down list.

The selected certificate must also be installed on the node that runs
the Automation Services jobs.

Data source Select the data source for which you are setting credentials.

Username Enter the username to use when connecting to the specified data source.

Password Enter the password.

Update Text Area Contents

If the analysis has text areas, you can set up the job file to replace the contents of these text areas.
You can also insert time and date by using the Insert Field option on the Tools menu; for more
information, see Inserting a field in a Spotfire Automation Services job.

Option Description

Text Area to Update Select the text area to change.

New Content Enter the new content for the text area in this field.

The new content will completely replace any older content.

TIBCO Spotfire® Automation Services User's Guide

 31

Job file testing

After you set up a job file, you should always make sure that it works as expected by executing it locally
before you run it on a server. When you have checked that it works both locally and on the server, you
can set it up to run regularly with a task scheduler.

Testing a job file locally

After setting up a job file, test it locally and then on the server.
Procedure

1. In the Job Builder, open the file that you want to test.
2. Click Tools > Execute Locally.
If the job does not include the task Send Email, go to step 5. If the job includes Send Email, continue
to step 3.
3. In the first dialog that opens, enter the name of your SMTP host and then click OK.
4. In the second dialog that opens, enter the sender address and then click OK.
5. Check that all the tasks were executed as expected, and then test the job on the server.

Testing a job file on Spotfire Server

After testing your Spotfire Automation Services job locally, test it on Spotfire Server.

Prerequisites

To execute jobs on the server, you must be part of the group Automation Services Users.
Procedure

1. In the Job Builder, open the file that you want to test.
2. Click Tools > Execute on Server.
3. When the job has finished, check that all the tasks were executed as expected.

TIBCO Spotfire® Automation Services User's Guide

 32

Job execution

After you create a job using the Spotfire Automation Services Job Builder, you can schedule the job to
run periodically from the Automation Services area of the administration interface. Alternatively, you
can use the Client Job Sender and Windows Task Scheduler to set up periodic job execution.
For details on using the administration interface, see "Automation Services job scheduling" in the
Spotfire Server Installation and Administration help.
To use the Client Job Sender and Windows Task Scheduler, begin by installing the Client Job Sender.

Installing the Client Job Sender

The Spotfire Automation Services Client Job Sender is installed by copying two files from the
Automation Services package.

Rather than installing and configuring the Client Job Sender and then working in Windows
Task Scheduler, you can schedule your job to run periodically from the Spotfire administration
interface. For details, see "Automation Services job scheduling" in the Spotfire Server help.
Prerequisites

● You have access to the Automation Services package that was downloaded from the TIBCO
eDelivery website.
● The computer on which you plan to install the Job Sender has the .NET Framework version that is
required for the installed Spotfire Analyst client.
Procedure

● From the Automation Services package, copy the following two files to any folder on a computer
in your Spotfire environment, or in the specific site if the environment includes sites. The files must
reside in the same folder.

● Spotfire.Dxp.Automation.ClientJobSender.exe
● Spotfire.Dxp.Automation.ClientJobSender.exe.config

What to do next

Configuring the Client Job Sender

Authentication options for the Client Job Sender

The Spotfire Automation Services Client Job Sender must be configured for authentication to the
Spotfire Server.
These are the available authentication methods for the Client Job Sender. In most cases, administrators
configure the same authentication method that is used in their Spotfire environment, or in a particular
site.

● Username and password

● Kerberos
● NTLM
● X.509 client certificates
● OAuth2

TIBCO Spotfire® Automation Services User's Guide

 33

If your company uses a web-based authentication method such as OpenID Connect, you must
configure OAuth2 authentication for the Client Job Sender; for instructions, see Configuring the
Client Job Sender for OAuth2 authentication.
Otherwise, OAuth2 can be implemented for the Client Job Sender regardless of the authentication
method used in your environment. This could be advantageous in situations such as the following:

● Because the OAuth2 client can only be used to execute jobs, you may choose this method for
security reasons.
● The administration structure at your company may make it more convenient to use OAuth2
authentication, for example if the Active Directory is updated in a different department.

Configuring the Client Job Sender

The configuration file Spotfire.Dxp.Automation.ClientJobSender.exe.config is a standard XML
configuration file. It is used to configure authentication to the Spotfire Server, and the logging and
handling of communication with Spotfire Server.
Prerequisites

If you plan to configure OAuth2 authentication to the server, an administrator must first run a
command on the Spotfire Server command line; for instructions, see Configuring the Client Job Sender
for OAuth2 authentication.
Procedure

● Open the configuration file in an XML editor or a text editor, and edit the following settings as
necessary:

Setting Description

Spotfire.Server.RequestTimeoutSeconds Specify the maximum number of seconds for a single

request to the Spotfire Server. The default value is 600.

Spotfire.MaxJobExecutionTimeSeconds Specify the maximum number of seconds that a job can

run before the application cancels the job. If set to 0 or less,
the application will not cancel the job. The default value is
-1.

If the async flag is used on the command line

when running a job, this setting is ignored.

The specified value in the Spotfire Server setting

max-job-execution-time will also affect the
cancellation of the job. The lowest specified
time will decide when the job is cancelled. For
details on this setting, see the Spotfire Server and
Environment Installation and Administration
help.

Spotfire.Logging.Level Specify the logging level for the

client job execution. The log file
Spotfire.Dxp.Automation.ClientJobSender.exe.log
is located in the same directory as the Client Job Sender
files. The default value is INFO.

TIBCO Spotfire® Automation Services User's Guide

 34

Setting Description

Spotfire.AllowedCertificateValidationErrors If SSL is enabled on the Spotfire Server, certificate errors

can be suppressed by this client by changing this setting.
Set to None to allow no certificate errors. To allow
specific errors, set the value to any or all of these values,
separated by commas: RemoteCertificateChainErrors,
RemoteCertificateNameMismatch,
RemoteCertificateNotAvailable.

Spotfire.AllowedTlsVersions Specify the TLS protocol version to use when

communicating with the TSS server. If multiple values are
used, they should be separated by comma. Possible values
are: Ssl3, Tls, Tls11, Tls12. If the setting is left empty it will
use the default system (machine) settings.

Spotfire.Authentication.Basic.UserName Specify the username for logging in to Spotfire Server,

when Spotfire Server is set up with username and
password authentication. This can also be used when the
server is configured with NTLM or Kerberos if another
user than the one executing the process is to be used when
accessing Spotfire Server. (The domain must be included in
username.)

This user must be a member of the group

Automation Services Users.

Spotfire.Authentication.Basic.Password The password for the specified username.

Spotfire.Authentication.ClientCertificate. Set to True if Spotfire Server requires a client certificate.

Enabled

Spotfire.ClientCertificate.StoreLocation The store location for the installed X.509 client certificate
used to authenticate with Spotfire Server. Can be
CurrentUser or LocalMachine.

Spotfire.ClientCertificate.StoreName The store name for the installed X.509 client certificate
used to authenticate with Spotfire Server. Can be
AddressBook, AuthRoot, CertificateAuthority, My, Root,
TrustedPeople, or TrustedPublisher.

Spotfire.ClientCertificate.SerialNumber The serial number for the installed X.509 client certificate
used to authenticate with Spotfire Server.

Spotfire.Authentication.OAuth2.ClientId The client ID for OAuth2 authentication.

Set this to the clientId that is returned when you run
the register-job-sender-client command-line
interface (CLI) command. For instructions on running
the command, see Configuring the Client Job Sender for
OAuth2 authentication.

TIBCO Spotfire® Automation Services User's Guide

 35

Setting Description

Spotfire.Authentication.OAuth2.ClientSecret The client secret for OAuth2 authentication.

Set this to the clientSecret that is returned when you run
the register-job-sender-client CLI command. For
instructions on running the command, see Configuring the
Client Job Sender for OAuth2 authentication.

If no username and password or client certificate is specified and Spotfire Server uses
Windows authentication (NTLM or Kerberos), then the Client Job Sender will use the
identity of the Windows user that executes the job to authenticate with Spotfire Server.

It is possible to encrypt the password or the client secret that is specified in the configuration
file. To encrypt the password or client secret (whichever setting has a value in the
configuration file), enter the following on the command line:

Spotfire.Dxp.Automation.ClientJobSender.exe -encryptPassword [encryptWithUserScope]

Add the encryptWithUserScope parameter to encrypt using the current Windows user
account; otherwise, the computer account is used. For more information, see https://
msdn.microsoft.com/en-us/library/system.security.cryptography.dataprotectionscope.aspx.
After encryption, the password and clientSecret fields in the configuration file are empty
and new fields (Spotfire.Authentication.Basic.Password.EncryptedUserscope
or Spotfire.Authentication.Basic.Password.EncryptedMachineScope, and
Spotfire.Authentication.OAuth2.ClientSecret.EncryptedUserscope or
Spotfire.Authentication.OAuth2.ClientSecret.EncryptedMachineScope) containing
the encrypted password or client secret are added.

Configuring the Client Job Sender for OAuth2 authentication

If your company uses a web-based authentication method such as OpenID Connect, you must
configure OAuth2 authentication from the Spotfire Automation Services Client Job Sender to the
Spotfire Server. This requires you to run a command on the Spotfire Server command line.
Prerequisites

You must have administrative credentials for Spotfire Server.

Procedure

1. On the computer running Spotfire Server, open a command line as an administrator and change
the directory to the location of the config.bat file (config.sh on Linux). The default location is
<server installation diretory>\tomcat\spotfire-bin.
2. Enter the following command, adding a name for the client to be created:

config register-job-sender-client --name=clientname

The server registers a new Client Job Sender OAuth2 client and displays its client ID and client
secret.

If the Client Job Sender executes jobs that are stored in the library, the created client must
have "read" access to the folders where the jobs are stored. Give access to the user by using
the Library Administration tool in Spotfire Analyst. For instructions, see "Editing Folder
Permissions" in the Spotfire Analyst User's Guide.
3. From the folder where you placed the Automation Services Client Job Sender files, open the
Spotfire.Dxp.Automation.ClientJobSender.exe.config file in an XML editor or a text editor.

TIBCO Spotfire® Automation Services User's Guide

 36

4. In the <appSettings> section, enter the values for the client Id and client secret from step 2 for the
following settings:

Spotfire.Authentication.OAuth2.ClientId
Spotfire.Authentication.OAuth2.ClientSecret

5. Save and close the configuration file.

Running the Client Job Sender

The Client Job Sender, which is run on the command line, executes Automation Service jobs.
Prerequisites

● You have an Automation Services job file that was created by using the Job Builder.
● You are a member of the group Automation Services Users.
● The files Spotfire.Dxp.Automation.ClientJobSender.exe and
Spotfire.Dxp.Automation.ClientJobSender.exe.config are located in the same directory.
● If the job you are executing was saved in the library, you have "read" access to the job file.
Procedure

● On the command line, enter your information in the following format:

"C:\Program Files (x86)\TIBCO\TIBCO Spotfire Automation Services

\Spotfire.Dxp.Automation.ClientJobSender.exe" "http://SpotfireServer:8080" "/Jobs/MyJob"
-useLibraryPath

where:

● C:\Program Files (x86)\TIBCO\TIBCO Spotfire Automation Services

\Spotfire.Dxp.Automation.ClientJobSender.exe is the path to the Job Sender tool.
● http://SpotfireServer:8080 is the URL to the Spotfire Server.
● /Jobs/MyJob is the location of a job stored in the library.

The job may also be stored in a directory outside of the library. In that case, enter the
complete path to the job file. See the second example, below.
● -useLibraryPath indicates that the job is being identified by its library path.

Alternatively, you can identify a job in the library by using its Library ID. In that case,
enter the following text after the ID: -use LibraryId. See the first example, below.

To quickly copy the path to a job file in the library, or the Library ID of the job file, in the
Automation Services Job Builder, click Copy Path or Copy Library ID on the Tools menu.

By default the Client Job Sender waits for the job to finish before the tool closes. To have the
tool close immediately after the job starts, add the -async flag to the end of the command
line. This can be useful if you want to run several jobs simultaneously. See the third example,
below.
For more information, see Client Job Sender monitoring.

TIBCO Spotfire® Automation Services User's Guide

 37

Examples

● To execute a job stored in the library using the Library ID:

"C:\Program Files\TIBCO Spotfire

\Spotfire.Dxp.Automation.ClientJobSender.exe" "http://
SpotfireServer:8080/" "038e181b-d05d-4f3f-9ef7-aef52c96f04b" -
useLibraryId

● To execute a job stored outside of the library:

"C:\Program Files\TIBCO Spotfire

\Spotfire.Dxp.Automation.ClientJobSender.exe" "http://
spotfireserver:8080/" "C:\Temp\jobfile.xml"

● Asynchronous example:

"C:\Program Files\TIBCO Spotfire

\Spotfire.Dxp.Automation.ClientJobSender.exe" "http://
SpotfireServer:8080/" "C:\Path\jobfile.xml" -async

● To encrypt the password or the client secret in the configuration file, also enter
the following command:

"C:\Program Files\TIBCO Spotfire

\Spotfire.Dxp.Automation.ClientJobSender.exe" encryptPassword [-
encryptWithUserScope]

Scheduling the Client Job Sender

To schedule a job to be executed with the Spotfire Automation Services Client Job Sender, use Windows
Task Scheduler
In Windows Task Scheduler, create a new task that executes the Client Job Sender, provide arguments
to it as described in Configuring the Client Job Sender, and set it to run periodically as needed. For
more information about how to use the Windows Task Scheduler, refer to the Microsoft documentation
on the feature.
The status of running jobs and the jobs history is available in Spotfire Server, on the Automation
Services tab of the Monitoring & Diagnostics area. For more information, see the Spotfire Server help.

Client Job Sender monitoring

When running Automation Services jobs with the Client Job Sender, the results of the jobs can be found
in the log file Spotfire.Dxp.Automation.ClientJobSender.exe.log.
This log is available in two places:

● In the same directory as the Client Job Sender files.

● On Spotfire Server, on the Automation Services page in the Monitoring & Diagnostics section.
The Spotfire Automation Services Client Job Sender returns a code reporting if a job succeeded or
failed. If the job failed, the return code also returns a message indicating how it failed. The return
values are stored in the ERRORLEVEL environment variable.
These are the valid return codes:

Return
code value Return code Message

0 Success The job succeeded.

TIBCO Spotfire® Automation Services User's Guide

 38

Return
code value Return code Message

1 CommandLineParameterError An incorrect command-line parameter was

supplied.

2 ServerExecutionError The job failed on the server.

3 ClientExecutionError The client failed to send the job to the server.

TIBCO Spotfire® Automation Services User's Guide