TIBCO Spotfire Automation Services 7.

6
Users Manual

Revision date: 2 May 2016

 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.

This document contains confidential information that 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 and Spotfire are either registered trademarks or trademarks of TIBCO Software Inc.
and/or subsidiaries 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.

Copyright 1996 - 2016 TIBCO Software Inc. ALL RIGHTS RESERVED.

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.

U.S. Patent Nos. 6,014,661, 7,216,116, and 8,190,619.

TIBCO Software Inc. Confidential Information

2 (45) TIBCO Spotfire Automation Services 7.6

 Contents
1 Introduction 4
2 What is Automation Services? 5
3 How to Use the Job Builder 7
3.1 The Job Builder User Interface 7
3.2 Creating a Job File 8

4 Job Builder Tasks 10

4.1 Apply Bookmark 10
4.2 Export Data Table to Library 11
4.3 Export Image 12
4.4 Export to PDF 14
4.5 Open Analysis from Library 22
4.6 Replace Data Table with Information Link 23
4.7 Save Analysis to Library 25
4.8 Send Email 27
4.9 Set Data Source Credentials 29
4.10 Set Credentials for External Connection 31
4.11 Update Text Area Contents 32
4.12 Automated Library Export and Import 33
4.12.1 Export Library Items 34
4.12.2 Import Library Items 36
4.12.3 Remap Data Sources 38
4.12.4 Remap Information Services Catalogs and Schemas 40

5 Testing the Job File 42

6 Scheduling an Automation Services Job 43
6.1 Using the Client Job Sender 43
6.2 Configuring the Client Job Sender 43
6.3 Scheduling the Client Job Sender 45

TIBCO Spotfire Automation Services 7.6 3 (45)

Introduction

1 Introduction
Welcome to TIBCO Spotfire Automation Services!

Automation Services is a tool that is integrated into TIBCO Spotfire

Analyst and makes it possible to run automated jobs using TIBCO
Spotfire Analyst. The Automation Services Job Builder is used to set
up files for executing these jobs.

Note: This user's manual contains information about the functionality

in TIBCO Spotfire Automation Services. For information about
functionality within the main TIBCO Spotfire Analyst product, please
consult the TIBCO Spotfire Users Manual.

4 (45) TIBCO Spotfire Automation Services 7.6

 What is Automation Services?

2 What is Automation Services?

Automation Services is a tool for running automated jobs using
TIBCO Spotfire Analyst. A job is a set of tasks that should be
performed each time the job runs. Perhaps you want to open an
analysis, export a visualization from that analysis, and send an email
about it to a number of co-workers. Opening an analysis, exporting an
image, and sending an email are three examples of tasks that can be
performed in a job. The tasks included in Automation Services are
described in this manual. However, Automation Services can be
extended with tasks other than those included. Your version of
Automation Services may therefore include more than the tasks
described in this manual.

A normal workflow in Automation Services is to start by creating a

job file in the Automation Services Job Builder, edit the file to contain
the tasks and settings of your choice, and then make sure the job file
works as expected by running it locally and on a server. When the job
file works the way you want it to, you can configure it to be executed
on a regular basis by using a task scheduler. The tasks defined in the
job file will then be executed automatically according to the schedule.
The main focus of this manual is on creating and editing a job file in
the job builder, and will only briefly describe how to set up a
scheduled job.

A job file is an XML file that you can create and edit in the
Automation Services Job Builder, which can be reached from the
Tools menu in Spotfire. In the job builder you can select tasks in the
order they should be performed and specify settings for each of the
tasks. The image below shows the job builders graphical user
interface, which is described further in How to Use the Job Builder
on page 7 and Job Builder Tasks on page 10.

TIBCO Spotfire Automation Services 7.6 5 (45)

What is Automation Services?

An Automation Services job may be defined in a number of different

ways. One common way to set up an Automation Services job is to
open an analysis, save it to the library, and finally send an email with
the updated file to a number of recipients.

Another common way to set up a job file is to start by opening an

analysis from the library, then export an imageone showing sales
figures, for exampleto a web server start page. By setting up the job
to run every night, the start page will be loaded with the latest sales
figures every morning.

Note: All users that execute automation services jobs on the server,
using the Job Builder or the Client Job Sender, must be part of
the group Automation Services Users.
Users running the Job Builder must also have the license Auto-
mation Services Job Builder Tool enabled.
This is set up in Administration Manager in Spotfire Analyst.
For more information, see the Administration Manager help.

6 (45) TIBCO Spotfire Automation Services 7.6

 How to Use the Job Builder

3 How to Use the Job Builder

3.1 The Job Builder User Interface

To reach the Automation Services Job Builder:
1 Open TIBCO Spotfire.

2 Open the Tools menu and select Automation Services Job Builder.

Response: The job builder is opened.

In the job builder, you can create new job files or open and edit
already existing ones. Open the File menu in the job builder to open a
file or to save it. The job builder consists of two parts. The top part is
where you can add tasks and arrange them in the order in which they
should be executed. In the example above, seven tasks have been
added to the task list. The bottom part is where you can adjust the
settings for each of the tasks. In the example, Export Image has been
selected in the list, and in the bottom part of the job builder, the
settings applicable to Export Image are displayed.

TIBCO Spotfire Automation Services 7.6 7 (45)

How to Use the Job Builder

Top part of the job builder

Option Description
File Open this menu to save, open or create a new job
file, or to exit the job builder.
Tools Open this menu to test a file locally or on the
server. From the Tools menu you can also insert a
fielda timestamp, for examplein a file name
or any text field, such as in an email message.
Add Open this menu and select a task to add to the
job.
Note: A new task is always added last in the list.
Use the Move Up and Move Down buttons to
change the order of the list. The order of the tasks
in the list determines the order in which they will
be executed.
Note: A job should generally start by opening an
analysis. To learn more about creating jobs in the
job builder, see Creating a Job File on page 8.
Remove Removes the selected task from the job list.
Move Up Moves the selected task up in the list.
Move Down Moves the selected task down in the list.

Bottom part of the job builder

In this part of the job builder you can define settings for the tasks.
Select the task you want to change the settings for by clicking on it in
the list. The settings for each available task are described in Job
Builder Tasks on page 10.

3.2 Creating a Job File

The job file is an XML file and can therefore be edited in any text
editor, such as Notepad, but the easiest way to create and set up a job
file is to use the Automation Services Job Builder.

To create a job file in the Automation Services Job Builder:

1 Open the Automation Services Job Builder from the Tools menu in
TIBCO Spotfire.

2 Select a task from the Add menu.

Note: Any job containing tasks that interact with an analysis must
begin with the Open Analysis from Library task. In this task, you
must click the Load button to load the analysis. Otherwise, the job
will not work as intended.

8 (45) TIBCO Spotfire Automation Services 7.6

 How to Use the Job Builder

3 Adjust the settings for the task in the bottom part of the job builder.

4 Repeat steps 2 and 3 until you are satisfied with the task list and
settings.

5 Save the file to a location of your choice.

To learn more about the different tasks included in Automation

Services, see Job Builder Tasks on page 10.

TIBCO Spotfire Automation Services 7.6 9 (45)

Job Builder Tasks

4 Job Builder Tasks

The tasks included in the Automation Services Job Builder are
described in this manual. If your version includes other tasks than
those described here, contact your Spotfire administrator to get more
information on how to use those tasks.

4.1 Apply Bookmark

You can apply bookmarks to your job files to highlight different
aspects of a data set. You may, for example, have an analysis file with
sales data for a department store, and you want the manager for each
of the departments to get a weekly update on their respective
department. If you create one job file for each department in the store
based on the same analysis file, and then apply different bookmarks in
each job file, each manager will get a different view of the analysis
file when the jobs are run.

10 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

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

4.2 Export Data Table to Library

You can export a data table from an analysis file and save it to the
library as an SBDF file.

Note: A data table that is located in an external data source (in-

database) cannot be exported.

If you want to make sure the data table is saved as a new data table
each time the job is executed, you can use the Insert Field option in
the Tools menu. Place the cursor at the desired location in the file
name part of the Library Path and select Insert Field to add an

TIBCO Spotfire Automation Services 7.6 11 (45)

Job Builder Tasks

automatically updated timestamp to the file name, thus making it

unique.

Option Description
Data Table Select the data table you want to export from the
analysis file.
Library Path Specify the library path where the data table will
be saved.
Description Add a description for the data table.
Note: If the data table already has a description, it
will be displayed here.
Keywords Add keywords for the data table, separated by
semicolons.
Note: If the data table already has specified
keywords, they will be displayed here.

4.3 Export Image

You can export an image from an analysis file to a destination of your
choice. If you want to make sure the image is saved as a new image
each time the job is executed, you can use the Insert Field option in
the Tools menu. Place the cursor at the desired location in the file
name part of the Destination Path and select Insert Field to add an
automatically updated timestamp to the file name, thus making it
unique.

12 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

Option Description
Destination path Specifies the location and file name of the image
to export.
Browse... Opens a dialog where you can specify a file name
and a location for the image file.
Note: The file will be saved to the node executing
the job, even though the Save dialog will show
folders on your local computer. Therefore you
need to make sure the folder you select as
destination folder actually exists on that machine,
and that you have writing permissions on the
selected folder.
Visualization Specifies which visualization to export.
Note: The exported image will only include the
currently visible content.

TIBCO Spotfire Automation Services 7.6 13 (45)

Job Builder Tasks

Width Specifies the width, in pixels, that the exported

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

4.4 Export to PDF

You can export parts of an analysis to PDF, to a destination of your
choice on the machine running Automation Services. You can choose
between two different types of PDF export. Either you can export
selected visualizations or pages as they currently appear in the
analysis. Or, you can 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 the document is saved as a new file each
time the job is executed, you can use the Insert Field option in the
Tools menu. Place the cursor at the desired location in the file name
part of the Destination path and select Insert Field to add an
automatically updated timestamp to the file name, thus making it
unique.

14 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

General Tab
On the General tab you specify what parts of the analysis to export,
what to include and you can also define the preferred layout.

Option Description
Destination path Specifies the location (on the node running
Automation Services) and file name of the
exported PDF file.
... Opens a dialog where you can specify a file name
and a location for the PDF file.
Note: The file will be saved to the node executing
the job, even though the Save dialog will show
folders on your local computer. Therefore you
need to make sure the folder you select as
destination folder actually exists on that machine,
and that you have writing permissions on the
selected folder.

TIBCO Spotfire Automation Services 7.6 15 (45)

Job Builder Tasks

Export what Defines which parts of the analysis to export. See

Result from regular PDF export and Result from
export based on bookmarks in the online help,
respectively, for more information about what the
options in this drop-down list mean for the
different export types.
Note: If you export bookmarks, then the PDF 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 Exports the active visualization in the analysis (or
visualization in the bookmark, for bookmark export) to a single
page in a PDF document.
Note: 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 Exports all the visualizations on the active page in
page for each the analysis (or in the bookmark, for bookmark
visualization) 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.
Note: 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 Exports all the visualizations on all the pages in
page for each the analysis. Each visualization in the analysis
visualization) will be exported to a new page in the PDF
document.
Note: Tables and trellised visualizations may be
extended to more than one page.
Details-on- Exports the Details-on-Demand to one or more
Demand 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.

16 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

Use entire page When exporting to PDF from Automation

Services, this option is not applicable. This is due
to the fact that 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
Include
Visualization title Select whether or not you want the visualization
titles to be included in the export.
Description Select whether or not 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.
Note: A long description may be cut off when
you export to PDF.
Filter settings Select whether or not 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 Select whether or not you want the page titles to
be included in the export.
Trellis panels and Select whether or not to include non-visible data
table rows not visible in trellis panels and tables in the export. If a table
on screen 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.
Note: 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.
Options
Page layout Defines the size and orientation of the pages in
the resulting PDF document.

Advanced Tab
On the Advanced tab, you can change the graphics settings of the
items you have selected and you can also add headers or footers to the
resulting PDF.

TIBCO Spotfire Automation Services 7.6 17 (45)

Job Builder Tasks

Option Description
Graphics settings
Items to export Lists the parts of the analysis that will be included
in the export. The items in the list may refer to
pages, visualizations, or the Details-on-Demand
depending in the selection you have made under
Export what on the General tab.
Name Shows the names of the pages or visualizations to
export.

18 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

Graphics Mode Allows you to change which graphics mode each

item will be exported as: Vector or Raster. This
can be useful if you need to keep the file size
down.
Note: 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.
All Vector Graphics Click this button to set all the items in the list to
be exported using vector graphics.
Note: 3D scatter plots are always exported as
raster graphics.
All Raster Graphics Click this button to set all the items in the list to
raster graphics.
Raster graphics Lets you specify the quality of the export for parts
quality (5.0 highest) 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.
Note: 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
Display page Select this check box if you want to include a
header 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 the drop-down lists Left,
Center, and/or Right to specify which positions
to place 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, and Current date and time.
Font Settings... Opens a dialog where you can specify font, style,
and size for the header. The current font settings
are displayed to the right of the button.
Footer options
Display page footer Select this check box if you want to include a
footer on each page in the resulting PDF
document.

TIBCO Spotfire Automation Services 7.6 19 (45)

Job Builder Tasks

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

height of the footer.
Left, Center, Right Make a selection from the drop-down lists Left,
Center, and/or Right to specify which position to
place 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, and Current date and time.
Font Settings... Opens a dialog where you can specify font, style,
and size for the footer. The current font settings
are displayed to the right of the button.

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

20 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

Option Description
Export selected views Select this check box to enable export to PDF
based on bookmarks based on bookmarks. Choose which parts of the
analysis to export on the General tab.
[List of available Select the bookmarks you want to export.
bookmarks]
Select All Click to select all the bookmarks in the list.
Deselect All Click to deselect all the bookmarks in the list.

TIBCO Spotfire Automation Services 7.6 21 (45)

Job Builder Tasks

4.5 Open Analysis from Library

A job file should generally start with a task that opens an analysis file.
The file that is opened is the file that the job is based on, and on which
all the tasks are performed. 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. To learn more about configuration
blocks, see Spotfire Technology Network (http://stn.spotfire.com/stn/
Tasks/CreatingConfigurationBlock.aspx).

Option Description
Path Specifies the location and file name of the file to
open.
Set to Current Sets the path to refer to the analysis that is
currently open in Spotfire.

22 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

Load Opens the analysis that is specified in the Path

field.
Note: 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 TIBCO Spotfire before proceeding
with setting up additional tasks.
Browse... Opens a dialog where you can select which file to
open from the library.
Configuration block Optionally, provide a configuration block to
specify the initial state of the analysis. A
configuration block is a piece of code that lets you
define which page should be active in the analysis
when opened, for example, or allows you to apply
a specific bookmark.
Example:
SetPage(pageTitle = "Overview");
ApplyBookmark(bookmarkName =
"UserRegionOnly");
Note: This is an advanced feature. See Spotfire
Technology Network (http://stn.spotfire.com/stn/
Tasks/CreatingConfigurationBlock.aspx) to learn
more about using configuration blocks.

4.6 Replace Data Table with Information Link

You can replace the contents of a data table with the contents of a
prompted information link. You can then set parameters for the
information link to filter by. For example, you can set it up to show
only the column values that are greater than a specified value, or
between two values.

TIBCO Spotfire Automation Services 7.6 23 (45)

Job Builder Tasks

Option Description
Data table to replace Specifies the data table that you want to replace
with an information link.
Information link Shows the path to the selected information link.
Note: 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 on page 22. To learn
more about using information links, see TIBCO
Spotfire Users Manual.
Browse... Opens a dialog where you can browse to locate
the information link of interest.

24 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

Information link Lists the columns with parameters of the selected

parameters information link.
Edit... Opens the Edit Information Link Parameters
dialog where you can set parameters for the
selected column. See below.

Option Description
Column name Displays the name of the column for which you
are currently editing parameters.
Data type Allows you to set the data type of the column.
Expression Allows you to set the expression that decides how
the column value should be compared to the
values set in this dialog, and thus, how the data
will be filtered.
List of values Lists the values that you want to filter by. The
value you enter here will replace the %Value% in
the selected expression above.

4.7 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 the job runs, instead of replacing
the existing one, you can use Insert Field in the Tools menu. Place
the cursor at the desired location in the file name part of the Save as
path and select Insert Field to add an automatically updated
timestamp to the file name, thus making it unique.

TIBCO Spotfire Automation Services 7.6 25 (45)

Job Builder Tasks

Option Description
Save as Specifies the location and name of the file to save.
Embed data in Select this check box to embed the data in the
analysis analysis.
Remove any Select whether or not previously existing
previously existing bookmarks should be removed when the analysis
bookmarks 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 (separated Optionally, type one or more keywords specific to
by semicolons) the contents of the analysis.

26 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

4.8 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, and add links to the web player and library. Below is an
example of an email that was sent in a job.

If you test a job that includes a Send Email task by executing it

locally, some things will not work. To read more about executing
locally and on the server, see Testing the Job File on page 42.

Note: Make sure that the machine and user running the Automation
Services service has access to the SMTP server and that it is not
blocked by any antivirus software.

TIBCO Spotfire Automation Services 7.6 27 (45)

Job Builder Tasks

Option Description
To Type the email addresses to which the email
should be sent.
Note: You can enter many addresses in the field.
The separator to use depends on the regional
settings of your computer.
Select Click to open a dialog where you can select
recipients from your LDAP directory.
Note: This will only work if you have an LDAP
directory.
Subject Enter a subject for the email in this field.
Message Enter the body text of the email in this field.

28 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

Add library link Select this check box if you want to include a link
to the analysis in the library.
Optionally, enter a text for the link in the text field
such as: Click to open analysis from the library.
If you leave the field blank the link will be shown
as the actual path to the library.
Add Web Player link Select this check box if you want to include a link
to the analysis in the web player.
Optionally, enter a text for the link in the text
field. If you leave this field blank the link will be
shown as the actual path.
Attach analysis (with Select this check box if you want the analysis to
embedded data) be attached in the email.
Added visualization You can include images from visualizations in the
images email. The images will be shown in the message
body.
Note: The data will be embedded.
Add Open this menu to select which visualization
images to add.
Remove Removes the selected image from the list.

4.9 Set Data Source Credentials

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

TIBCO Spotfire Automation Services 7.6 29 (45)

Job Builder Tasks

Option Description
X.509 Certificate Select a valid X.509 certificate. This is used to
subject 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.
Note: The selected certificate must also be
installed on the node that runs the Automation
Services jobs.
Data source Specifies the selected data source.
Browse... Opens a dialog where you can select the data
source to which you want to connect.
Username Specifies the username to use when connecting to
the specified data source.
Password Specifies the password.

30 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

4.10 Set Credentials for External Connection

If you are going to open an analysis requiring authentication for
external data sources, that is, any of the Spotfire Data Connectors,
you can specify the credentials to use with this task. This task should
be performed before any Open Analysis from Library task. In order 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 used in a specific analysis.

Option Description
X.509 Certificate Select a valid X.509 certificate. This is used to
subject protect the security of the passwords 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.
Note: The selected certificate must also be
installed on the node that runs the Automation
Services jobs.

TIBCO Spotfire Automation Services 7.6 31 (45)

Job Builder Tasks

Credentials profile Specifies the name of the credentials profile.

Make sure that the profile matches a profile saved
in the analysis file. The profile used in an analysis
is saved in the Data Connection Properties dialog
in TIBCO Spotfire.
Username Specifies the username for the profile to use when
connecting to the data source.
Password Specifies the password for the profile.

4.11 Update Text Area Contents

If the analysis has text areas, you can set up the job file to change the
contents of these text areas. For example, you can insert time and date
by using the Insert Field option in the Tools menu. Place the cursor
at the desired location and select Insert Field to add an automatically
updated timestamp in the file name, thus making it unique.

32 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

Any new content will completely replace any older content of the
Text Area.

Option Description
Text area to update Defines which text area in the analysis to change
the content for.
New content Enter the new content for the text area in this
field.
Note: The new content will completely replace
any older content.

4.12 Automated Library Export and Import

You can create jobs in Automation Services to automate library
export and import. This can be useful if you want to migrate your
Spotfire library, in part or in its entirety, from one system to another,
such as, from a test environment to a production environment.

Typically, you would need to create and run two job files in order to
move library items from a test system to a production system.

TIBCO Spotfire Automation Services 7.6 33 (45)

Job Builder Tasks

The first job exports the library items of interest from the test system
to file. This is done with the job builder task Export Library Items. A
zip archive containing the exported library items will be created when
the job runs.

The second job imports the contents in the zip archive to the
production system. Usually, you also need to remap the connection
strings and/or passwords of the data sources during import. To
perform both the import and the remapping in this job, use the two job
builder tasks Import Library Items and Remap Data Sources.

The job builder tasks are described in Export Library Items on

page 34, Import Library Items on page 36, and Remap Data
Sources on page 38 respectively.

Note: The Automation Services tasks that handle Library export and
import take longer to execute than other Automation Services tasks. It
is therefore important that you increase the timeout period of the
export and import tasks before you attempt to run them.

4.12.1 Export Library Items

The Export Library Items task lets you select from which library
folder to export items. The folder and its contents will be saved as a
zip archive when the job runs. This zip archive will be placed in a
specific folder on a specific machine. This folder is called the Shared
Disk Location. In an environment with only one TIBCO Spotfire
Server, this folder is by default located on the TIBCO Spotfire Server
machine in the folder <server installation directory>/tomcat/
application-data/library/. In an environment with more than one
Spotfire Server, one of them is dedicated to hold Library exports. See
the TIBCO Spotfire Server and Environment Installation and
Administration Manual for more information about how to set this up.

Note: 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. See
TIBCO Spotfire Users Manual to learn more about the Library

34 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

Administrator and permissions.

Option Description
Export from library Specifies the location and name of the folder to
folder export from the library.
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.

TIBCO Spotfire Automation Services 7.6 35 (45)

Job Builder Tasks

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. See above for more information about
where the file will be saved.
Note: 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.
Note: 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, file-
Name.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.

4.12.2 Import Library Items

The Import Library Items task lets you specify a zip archive to import
library items from, as well as a location in the library to import to.
You can only import zip archives containing appropriate library
content. It is not possible to import a single analysis.

To avoid accidentally overwriting any existing items in the library,

before you start importing items we recommend that you read the
section How Are Conflicts Resolved? in TIBCO Spotfire Users
Manual.

Note: In cases where a user opens Automation Service Job Builder

to configure Import Library Items and selects the option to Include
permissions, the files are moved, instead of copied, from the source
directory. This library import conflict mode behavior results because
the import task is defined to adhere to keep new conflict resolution
mode and a GUID conflict results in the operation. Since the newest
version is in the target directory, the files in the source directory are
discarded.

Note: When you are importing information model elements, the

elements should not be accessed from the library or from Information
Designer until after the import task is complete. If the import takes
place on a server used by others, we recommend either no external
access is allowed during the import or that the information model is
temporarily imported into a folder with no access permissions for
other users. After the import has been performed, the permissions for
the import folder can be changed, or the resulting elements can be
moved to another place in the library.

Note: To import any content into the library from file, you must have
Browse + Access + Modify permissions for the destination folder and

36 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

be a member of the Library Administrator group. See TIBCO Spotfire

Users Manual to learn more about the Library Administrator and
permissions.

Option Description
Import from file Specifies the name of the file to import. The file
must be a zip archive containing appropriate
library content.
Note: 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.
Note: 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.
Import to library Specifies the location and the name of the folder
folder in the library to which you want to import the
library items.

TIBCO Spotfire Automation Services 7.6 37 (45)

Job Builder Tasks

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.
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.

4.12.3 Remap Data Sources

When you migrate library items from one system to another, it is
likely you will have to remap the connection strings and/or passwords
of the data sources when you import them to the new system. Use the
Remap Data Sources task in the same job file as the Import Library
Items task to achieve this.

38 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

Option Description
X.509 certificate Select a valid X.509 certificate. This is used to
subject 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.
Note: The selected certificate must also be
installed on the node that runs the Automation
Services jobs.
Data sources library Defines the location of the library folder
folder containing the data sources that need to be
repmapped.
Note: This is optional. However, if you do not
specify a library folder, you must include the
entire path for each data source you add.
Browse... Opens the Browse Library dialog where you can
select a library folder. Only available if you are
connected to the library.

TIBCO Spotfire Automation Services 7.6 39 (45)

Job Builder Tasks

Data sources Lists the currently added data sources.

Note: If you have not specified a Data sources
library folder, you must include the entire path for
each data source you add.
Add... Opens a dialog that lets you specify a new data
source. See below.
Edit... Opens a dialog that lets you edit the selected data
source. See below.
Remove Removes the selected data source from the list.
Import... Opens a dialog that lets you select a previously
exported file. All the data sources included in the
file will be added to the list.
Connection string Specifies the current connection string for the
selected data source. Enter a new connection
string in the text field to change it.
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 that lets you enter a new password
for the selected data source.
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 containing the data source.

4.12.4 Remap Information Services Catalogs and

Schemas
When you migrate library items from one system to another, you may
have to remap Information Services catalogs or schemas. Use the
Remap Information Services Catalogs and Schemas task to achieve

40 (45) TIBCO Spotfire Automation Services 7.6

 Job Builder Tasks

this.
Note: You must have Java installed to perform this task.

Option Description
Original export file Specifies the original (input) export file.
Note: Use the path to the file on the node that will
run the task, not on your computer, if you have
the file there as well.
Remapped export Specifies the remapped (output) data export file.
file Note: Use the path to the file on the node that will
run the task, not on your computer.
Add... Opens a dialog where you can enter a new
remapping.
Edit... Opens a dialog where you can edit the selected
remapping.
Import... Opens a dialog where you can select a local
version of the original (input) export file and
import the existing catalogs or schemas from it.

TIBCO Spotfire Automation Services 7.6 41 (45)

Testing the Job File

5 Testing the Job File

When you have set up a job file, you should always make sure 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.

To execute locally for testing:

1 Open the job file you want to test locally.

2 Open the Tools menu and select Execute Locally for Testing.

Response: If the job does not include the task Send Email, continue to
step 6. If the job includes Send Email, continue to step 3.

3 In the dialog that appears, enter the name of your SMTP host, then
click OK.

4 In the dialog that appears, enter the sender address, then click OK.

5 When the job is finished, click Close in the dialog.

6 Check that all the tasks were executed as expected, and then test the
job on the server.

To execute on server:
1 Open the job file you want to execute on the server.

Note: To executes jobs on the server, you must be part of the group
Automation Services Users.

2 Open the Tools menu and select Execute on Server.

3 When the job has finished, check that all the tasks were executed the
way you expected before you set it up in a task scheduler.

Running Multiple Jobs Simultaneously

It is possible to run several jobs simultaneously on the server by
executing several jobs from the Tools menu. When you run a job on
the server the Execution Report dialog is shown, showing you the
progress of the job. To hide this dialog click Run in background in
the Execution Report dialog.

To view the progress of hidden running jobs click the Running

Server Jobs menu and select the jobs you want to see the Execution
Report dialog for. If several dialogs are open, it is possible to close all
of them by selecting Close All Jobs.

42 (45) TIBCO Spotfire Automation Services 7.6

 Scheduling an Automation Services Job

6 Scheduling an Automation
Services Job
When you create a job using the Job Builder, the job can either be
executed immediately, or set up to be executed periodically. The latter
method uses a tool called
Spotfire.Dxp.Automation.ClientJobSender.exe. This tool is found in
the downloaded Automation Services bundle, together with its
configuration file
Spotfire.Dxp.Automation.ClientJobSender.exe.config. Install these
two files onto any machine that can communicate via HTTP (or
HTTPS, if you have set this up) with the Spotfire Server. The
executable file and the config file must reside in the same directory.

6.1 Using the Client Job Sender

To use the Client Job Sender, you must have a job file created with
the Job Builder. The Client Job Sender takes two arguments when
executed: The URL to the Spotfire Server, and the full path to the job
file to be executed.

Example:
C:> C:\Program Files\TIBCO Spotfire\Spotfire.Dxp.Automation.ClientJobSender.exe http://
spotfireserver[:port] C:\Temp\jobfile.xml

To run the jobs asynchronously, that is, without waiting for the result
of the job, add async at the end of the example above. This can be
useful if you want to run several jobs simultaneously.

Note: When running the jobs asynchronously with the Client Job
Sender the result of the jobs can be found in the log file
Spotfire.Dxp.Automation.ClientJobSender.exe.log located in the
directory where the Client Job Sender files are located and in the
Automation Services tab in Monitoring & Diagnostics on the Spotfire
server.

6.2 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 the authentication to the
Spotfire Server, logging and handling of communication with the
Spotfire Server.

To configure these settings, open the file in a text editor.

TIBCO Spotfire Automation Services 7.6 43 (45)

Scheduling an Automation Services Job

Setting Description
Spotfire.Server.Req Specify the maximum number of seconds for a
uestTimeoutSeconds
single request to the Spotfire Server. The default
value is 600.
Spotfire.MaxJobExec Specify the maximum number of seconds a job
utionTimeSeconds
can execute for before the application cancels the
job. If set to 0 or less, the application will not
cancel the job. The default value is -1.
Note: If the async flag is used on the command
line when running a job, this setting is ignored.
Note: 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. See
the Spotfire Server and Environment Installation
and Administration manual.
Spotfire.Logging. Specify the logging level for the client job
Level
execution. the log file
Spotfire.Dxp.Automation.ClientJobSender.
exe.log is located in the directory where the
Client Job Sender files are located. The
default value is INFO.
Spotfire.AllowedCer
If SSL is enabled on the Spotfire Server,
tificateValidationE certificate errors can be suppressed by this client,
rrors 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
comma: RemoteCertificateChainErrors,
RemoteCertificateNameMismatch,
RemoteCertificateNotAvailable.
Spotfire.Authentica
Specify the username to login to Spotfire Server
tion.Basic.UserName with, when Spotfire Server is setup 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 (domain must be
included in username).
Note: This user must be a member of the
group Automation Services Users.
Spotfire.Authentica
The password for the specified username.
tion.Basic.Password
Spotfire.Authentica Set to True if Spotfire Server requires a client
tion.ClientCertific
ate.Enabled certificate.

44 (45) TIBCO Spotfire Automation Services 7.6

 Scheduling an Automation Services Job

Spotfire.ClientCert The store location for the installed X509 client

ificate.StoreLocati
on certificate used to authenticate with Spotfire
Server. Can be CurrentUser or LocalMachine.
Spotfire.ClientCert The store name for the installed X509 client
ificate.StoreName
certificate used to authenticate with Spotfire
Server. Can be AddressBook, AuthRoot,
CertificateAuthority, My, Root, TrustedPeople or
TrustedPublisher.
Spotfire.ClientCert The serial number for the installed X509 client
ificate.SerialNumbe
r certificate used to authenticate with Spotfire
Server.
If no username and password or client certificate is specified and
Spotfire Server uses Windows authentication (NTLM or Kerberos),
then 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 specified in the configuration

file. To encrypt the password, 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 machine account is
used. For more information see https://msdn.microsoft.com/en-us/
library/system.security.cryptography.dataprotectionscope.aspx.

After encryption, the password field in the configuration file is empty

and a new field
(Spotfire.Authentication.Basic.Password.EncryptedUserscope or
Spotfire.Authentication.Basic.Password.EncryptedMachineScope)
containing the encrypted password is added.

6.3 Scheduling the Client Job Sender

To schedule a job to be executed with the Client Job Sender, use
Windows Task Scheduler. Create a new task that executes the Client
Job Sender, provide arguments to it as described above, and set it to
run periodically as needed. For more information about how to use
the Windows Task Scheduler, refer to Microsofts documentation on
the feature.

The status of running jobs and the history of run jobs can be found in
the Automation Services tab in Monitoring & Diagnostics on the
Spotfire server. For more information, see the TIBCO Spotfire Server
and Environment Installation and Administration Manual.

TIBCO Spotfire Automation Services 7.6 45 (45)