TIBCO Spotfire Automation Services 7.5. User s Manual

Transcription

1 TIBCO Spotfire Automation Services 7.5 User s Manual Revision date: 15 January 2016

2 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 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. TIBCO Spotfire is covered by U.S. Patent No. 6,014,661 and U.S. Patent No. 7, 216,116. Other patent(s) pending. TIBCO Software Inc. Confidential Information 2 (44) TIBCO Spotfire Automation Services 7.5

3 Contents 1 Introduction 4 2 What is Automation Services? 5 3 How to Use the Job Builder The Job Builder User Interface Creating a Job File 8 4 Job Builder Tasks Apply Bookmark Export Image Export to PDF Open Analysis from Library Replace Data Table with Information Link Save Analysis to Library Send Set Data Source Credentials Set Credentials for External Connection Update Text Area Contents Automated Library Export and Import Export Library Items Import Library Items Remap Data Sources Remap Information Services Catalogs and Schemas 39 5 Testing the Job File 41 6 Scheduling an Automation Services Job Using the Client Job Sender Configuring the Client Job Sender Scheduling the Client Job Sender 44 TIBCO Spotfire Automation Services (44)

4 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 User s Manual. 4 (44) TIBCO Spotfire Automation Services 7.5

5 2 What is Automation Services? 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 about it to a number of co-workers. Opening an analysis, exporting an image, and sending an 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. TIBCO Spotfire Automation Services (44)

6 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 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 Automation Services Job Builder Tool enabled. This is set up in Administration Manager in Spotfire Analyst. For more information, see the Administration Manager help. 6 (44) TIBCO Spotfire Automation Services 7.5

7 3 How to Use the Job Builder 3.1 The Job Builder User Interface How to Use the Job Builder 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 (44)

8 How to Use the Job Builder Top part of the job builder Option File Tools Add Remove Move Up Move Down Description Open this menu to save, open or create a new job file, or to exit the job builder. 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 message. 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. Removes the selected task from the job list. Moves the selected task up in the list. Moves the selected task down in the list. 3.2 Creating a Job File 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. 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 (44) TIBCO Spotfire Automation Services 7.5

9 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 (44)

10 4 Job Builder Tasks 4.1 Apply Bookmark 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. 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 (44) TIBCO Spotfire Automation Services 7.5

11 Option Bookmark Description Specifies the bookmark to apply. All the bookmarks in the analysis are listed in the dropdown list. 4.2 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. TIBCO Spotfire Automation Services (44)

12 Option Destination path Browse... Visualization Description Specifies the location and file name of the image to export. 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. Specifies which visualization to export. Note: The exported image will only include the currently visible content. 12 (44) TIBCO Spotfire Automation Services 7.5

13 Width Height Specifies the width, in pixels, that the exported image should have. Specifies the height, in pixels, that the exported image should have. 4.3 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. TIBCO Spotfire Automation Services (44)

14 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 Destination path Description 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. 14 (44) TIBCO Spotfire Automation Services 7.5

15 Export what Active visualization Active page Active page (new page for each visualization) All pages All pages (new page for each visualization) Details-on- Demand 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. 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. 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. 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. Exports all the visualizations on all the pages in the analysis. Each page will be exported to a new page in the PDF document. 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. 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. TIBCO Spotfire Automation Services (44)

16 Use entire page Include Visualization title Description Filter settings Page title Trellis panels and table rows not visible on screen Options Page layout 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 Select whether or not you want the visualization titles to be included in the export. 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. 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. Select whether or not you want the page titles to be included in the export. 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. 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. 16 (44) TIBCO Spotfire Automation Services 7.5

17 Option Graphics settings Items to export Name Description 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. Shows the names of the pages or visualizations to export. TIBCO Spotfire Automation Services (44)

18 Graphics Mode All Vector Graphics All Raster Graphics Raster graphics quality (5.0 highest) Header options Display page header Header height Left, Center, Right Font Settings... Footer options Display page footer 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. 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. Click this button to set all the items in the list to raster graphics. 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. Select this check box if you want to include a header on each page in the resulting PDF document. Enter a number between 10 and 100 to adjust the height of the header. 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. 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. Select this check box if you want to include a footer on each page in the resulting PDF document. 18 (44) TIBCO Spotfire Automation Services 7.5

19 Footer height Left, Center, Right Font Settings... Enter a number between 10 and 100 to adjust the height of the footer. 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. 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. TIBCO Spotfire Automation Services (44)

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

21 4.4 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 ( Tasks/CreatingConfigurationBlock.aspx). Option Path Set to Current Description Specifies the location and file name of the file to open. Sets the path to refer to the analysis that is currently open in Spotfire. TIBCO Spotfire Automation Services (44)

22 Load Browse... Configuration block 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. Opens a dialog where you can select which file to open from the library. 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 ( Tasks/CreatingConfigurationBlock.aspx) to learn more about using configuration blocks. 4.5 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. 22 (44) TIBCO Spotfire Automation Services 7.5

23 Option Data table to replace Information link Browse... Description Specifies the data table that you want to replace with an 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 21. To learn more about using information links, see TIBCO Spotfire User s Manual. Opens a dialog where you can browse to locate the information link of interest. TIBCO Spotfire Automation Services (44)

24 Information link parameters Edit... Lists the columns with parameters of the selected information link. Opens the Edit Information Link Parameters dialog where you can set parameters for the selected column. See below. Option Column name Data type Expression List of values Description Displays the name of the column for which you are currently editing parameters. Allows you to set the data type of the column. 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. Lists the values that you want to filter by. The value you enter here will replace the %Value% in the selected expression above. 4.6 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. 24 (44) TIBCO Spotfire Automation Services 7.5

25 Option Save as Embed data in analysis Remove any previously existing bookmarks Description Keywords (separated by semicolons) Description Specifies the location and name of the file to save. Select this check box to embed the data in the analysis. 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. Optionally, type a description of the analysis. Optionally, type one or more keywords specific to the contents of the analysis. TIBCO Spotfire Automation Services (44)

26 4.7 Send A job can be set up to send an 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 that was sent in a job. If you test a job that includes a Send 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 41. 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. 26 (44) TIBCO Spotfire Automation Services 7.5

27 Option To Select Subject Message Description Type the addresses to which the should be sent. Note: You can enter many addresses in the field. The separator to use depends on the regional settings of your computer. 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. Enter a subject for the in this field. Enter the body text of the in this field. TIBCO Spotfire Automation Services (44)

28 Add library link Add Web Player link Attach analysis (with embedded data) Added visualization images Add Remove 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. 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. Select this check box if you want the analysis to be attached in the . You can include images from visualizations in the . The images will be shown in the message body. Note: The data will be embedded. Open this menu to select which visualization images to add. Removes the selected image from the list. 4.8 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. 28 (44) TIBCO Spotfire Automation Services 7.5

29 Option X.509 Certificate subject Data source Browse... Username Password Description 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. Specifies the selected data source. Opens a dialog where you can select the data source to which you want to connect. Specifies the username to use when connecting to the specified data source. Specifies the password. TIBCO Spotfire Automation Services (44)

30 4.9 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 X.509 Certificate subject Description 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. 30 (44) TIBCO Spotfire Automation Services 7.5

31 Credentials profile Username Password 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. Specifies the username for the profile to use when connecting to the data source. Specifies the password for the profile 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. TIBCO Spotfire Automation Services (44)

32 Any new content will completely replace any older content of the Text Area. Option Text area to update New content Description Defines which text area in the analysis to change the content for. Enter the new content for the text area in this field. Note: The new content will completely replace any older content 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. 32 (44) TIBCO Spotfire Automation Services 7.5

33 Export Library Items 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 33, Import Library Items on page 35, and Remap Data Sources on page 37 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. 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 User s Manual to learn more about the Library TIBCO Spotfire Automation Services (44)

34 Administrator and permissions. Option Export from library folder Browse... Description Specifies the location and name of the folder to export from the library. 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. 34 (44) TIBCO Spotfire Automation Services 7.5

35 Export to file Export items of type Include permissions 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. Specify the type of items you want to export if you want to limit the export to only a certain type. Select whether or not to include the selected library folder permissions 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 User s 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 TIBCO Spotfire Automation Services (44)

36 be a member of the Library Administrator group. See TIBCO Spotfire User s Manual to learn more about the Library Administrator and permissions. Option Import from file Import to library folder Description 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. Specifies the location and the name of the folder in the library to which you want to import the library items. 36 (44) TIBCO Spotfire Automation Services 7.5

37 Browse... Import items of type Include permissions Ignore empty folders 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. Specify the type of items you want to import if you want to limit the import to only a certain type of items. 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. Select this check box if you do not want to import any empty library folders Remap Data Sources When you migrate library items from one system to another, it is likely 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. TIBCO Spotfire Automation Services (44)

38 Option X.509 certificate subject Data sources library folder Browse... Description 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. 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. Opens the Browse Library dialog where you can select a library folder. Only available if you are connected to the library. 38 (44) TIBCO Spotfire Automation Services 7.5

39 Data sources Add... Edit... Remove Import... Connection string Reset Password Change... Reset 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. Opens a dialog that lets you specify a new data source. See below. Opens a dialog that lets you edit the selected data source. See below. Removes the selected data source from the list. 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. Specifies the current connection string for the selected data source. Enter a new connection string in the text field to change it. Resets the modified connection string to the one that was originally set for the selected data source. The current password for the selected data source. Opens a dialog that lets you enter a new password for the selected data source. Resets the modified password to the one that was originally set for the data source. Option Name In library folder Description Enter a name for the new or edited data source. Displays the location and name of the library folder containing the data source 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 TIBCO Spotfire Automation Services (44)

40 this. Note: You must have Java installed to perform this task. Option Original export file Remapped export file Add... Edit... Import... Description 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. 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. Opens a dialog where you can enter a new remapping. Opens a dialog where you can edit the selected remapping. 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. 40 (44) TIBCO Spotfire Automation Services 7.5

41 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 , continue to step 6. If the job includes Send , 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. TIBCO Spotfire Automation Services (44)

42 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 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. 42 (44) TIBCO Spotfire Automation Services 7.5

43 Scheduling an Automation Services Job Setting Spotfire.Server.Req uesttimeoutseconds Spotfire.MaxJobExec utiontimeseconds Spotfire.Logging. Level Spotfire.AllowedCer tificatevalidatione rrors Spotfire.Authentica tion.basic.username Spotfire.Authentica tion.basic.password Spotfire.Authentica tion.clientcertific ate.enabled Description Specify the maximum number of seconds for a single request to the Spotfire Server. The default value is 600. 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. 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. 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. 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. The password for the specified username. Set to True if Spotfire Server requires a client certificate. TIBCO Spotfire Automation Services (44)

44 Scheduling an Automation Services Job Spotfire.ClientCert ificate.storelocati on Spotfire.ClientCert ificate.storename Spotfire.ClientCert ificate.serialnumbe r The store location for the installed X509 client certificate used to authenticate with Spotfire Server. Can be CurrentUser or LocalMachine. 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. The serial number for the installed X509 client 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 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 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. 44 (44) TIBCO Spotfire Automation Services 7.5