tibco spotfire automation services 7 · automation services job builder. response: the job builder...

TIBCO Spotfire® Automation Services 7.6

User’s Manual

Revision date: 2 May 2016

Important InformationSOME 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

Contents1 Introduction 4

2 What is Automation Services? 5

3 How to Use the Job Builder 73.1 The Job Builder User Interface 73.2 Creating a Job File 8

4 Job Builder Tasks 104.1 Apply Bookmark 104.2 Export Data Table to Library 114.3 Export Image 124.4 Export to PDF 144.5 Open Analysis from Library 224.6 Replace Data Table with Information Link 234.7 Save Analysis to Library 254.8 Send Email 274.9 Set Data Source Credentials 294.10 Set Credentials for External Connection 314.11 Update Text Area Contents 324.12 Automated Library Export and Import 334.12.1 Export Library Items 344.12.2 Import Library Items 364.12.3 Remap Data Sources 384.12.4 Remap Information Services Catalogs and Schemas 40

5 Testing the Job File 42

6 Scheduling an Automation Services Job 436.1 Using the Client Job Sender 436.2 Configuring the Client Job Sender 436.3 Scheduling the Client Job Sender 45

TIBCO Spotfire® Automation Services 7.6 3 (45)

Introduction

1 IntroductionWelcome 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 User’s Manual.


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 builder’s graphical user interface, which is described further in “How to Use the Job Builder” on page 7 and “Job Builder Tasks” on page 10.


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 image—one showing sales figures, for example—to 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.


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.



Option DescriptionFile 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 field—a timestamp, for example—in 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.

Top part of the job builder

Bottom part of the job builderIn 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 FileThe 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.



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.


Job Builder Tasks

4 Job Builder TasksThe 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 BookmarkYou 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.


Job Builder Tasks

Option DescriptionBookmark Specifies the bookmark to apply. All the

bookmarks in the analysis are listed in the dropdown list.

4.2 Export Data Table to LibraryYou 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


Job Builder Tasks

automatically updated timestamp to the file name, thus making it unique.

Option DescriptionData 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 ImageYou 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.


Job Builder Tasks

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


Job Builder Tasks

4.4 Export to PDFYou 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.

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

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


Job Builder Tasks

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

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


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 visualization

Exports the active visualization in the analysis (or 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 page for each visualization)

Exports all the visualizations on the active page in the analysis (or in the 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.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 page for each visualization)

Exports all the visualizations on all the pages in the analysis. Each visualization in the analysis 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-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.


Job Builder Tasks

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

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 table rows not visible on screen

Select whether or not to include non-visible data in trellis panels and tables in 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.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.


Job Builder Tasks

Option DescriptionGraphics settingsItems 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.


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 quality (5.0 highest)

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


Job Builder Tasks

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

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.


Job Builder Tasks

Option DescriptionExport selected views based on bookmarks

Select this check box to enable export to PDF 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.

Select All Click to select all the bookmarks in the list.Deselect All Click to deselect all the bookmarks in the list.


Job Builder Tasks

4.5 Open Analysis from LibraryA 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 DescriptionPath 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.


Job Builder Tasks

4.6 Replace Data Table with Information LinkYou 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.

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.


Job Builder Tasks

Option DescriptionData 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 User’s Manual.

Browse... Opens a dialog where you can browse to locate the information link of interest.


Job Builder Tasks

4.7 Save Analysis to LibraryThis 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.

Information link parameters

Lists the columns with parameters of the selected information link.

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

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


Job Builder Tasks

Option DescriptionSave as Specifies the location and name of the file to save. Embed data in analysis

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

Remove any previously existing bookmarks

Select whether or not previously existing bookmarks should be removed 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 (separated by semicolons)

Optionally, type one or more keywords specific to the contents of the analysis.


Job Builder Tasks

4.8 Send EmailA 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.


Job Builder Tasks

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


Job Builder Tasks

4.9 Set Data Source CredentialsIf 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.

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 embedded data)

Select this check box if you want the analysis to be attached in the email.

Added visualization images

You can include images from visualizations in the 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.


Job Builder Tasks

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


Job Builder Tasks

4.10 Set Credentials for External ConnectionIf 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 DescriptionX.509 Certificate subject

Select a valid X.509 certificate. This is used to 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.


Job Builder Tasks

4.11 Update Text Area ContentsIf 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.

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.


Job Builder Tasks

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

Option DescriptionText 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 ImportYou 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.


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 ItemsThe 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 User’s Manual to learn more about the Library


Job Builder Tasks

Administrator and permissions.

Option DescriptionExport from library folder

Specifies the location and name of the folder to 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.


Job Builder Tasks

4.12.2 Import Library ItemsThe 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 User’s Manual.

Note: In cases where a user opens Automation Service Job Builderto 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

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.


Job Builder Tasks

be a member of the Library Administrator group. See TIBCO Spotfire User’s Manual to learn more about the Library Administrator and permissions.

Option DescriptionImport 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 folder

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


Job Builder Tasks

4.12.3 Remap Data SourcesWhen 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.

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.


Job Builder Tasks

Option DescriptionX.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. Note: 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 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.


Job Builder Tasks

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

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


Job Builder Tasks

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

Option DescriptionOriginal 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 file

Specifies the remapped (output) data export 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.


Testing the Job File

5 Testing the Job FileWhen 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 SimultaneouslyIt 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.


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



Setting DescriptionSpotfire.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 a job

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. Level Specify the logging level for the client job

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.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 comma: RemoteCertificateChainErrors, RemoteCertificateNameMismatch, RemoteCertificateNotAvailable.

Spotfire.Authentication.Basic.UserName

Specify the username to login to Spotfire Server 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.Authentication.Basic.Password

The password for the specified username.

Spotfire.Authentication.ClientCertificate.Enabled

Set to True if Spotfire Server requires a client certificate.



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 SenderTo 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 Microsoft’s 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.

Spotfire.ClientCertificate.StoreLocation

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

Spotfire.ClientCertificate.StoreName The store name for the installed X509 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 X509 client certificate used to authenticate with Spotfire Server.


tibco spotfire automation services 7 · automation services job builder. response: the job builder...

Documents