Custom DateTime Data Function for Spotfire®

Introduction

The main goal of the Custom DateTime Data Function for Spotfire® is to enable the running of IronPython scripts on Analysis Open, Filter and Marking changes. The Custom DataTime Data Function allows one to trigger IronPython scripts without having to use a TERR/statistical Data Function for only that purpose.

The DateTime Data Function runs whenever a chosen event occurs.  The output is simply the Date and Time when the Data Function was executed.

The triggering event can be one of many different types, such as: 

• The initial opening of an analysis file
• A Document Property change
• A Marking or Filtering selection change
• Data Table or Column Property changes

Using the built-in features of Spotfire, the DateTime value can be used to make other changes to the DXP:

• Updating a Document PropertyUpdating a Table / Column Property
• Triggering an IronPython Script (via Document Property change)
• Triggering a Data Function (via Document Property change)
• Changing Visualization Properties (via Document / Table / Column Property change)
• Updating a Custom Expression (via Document / Table / Column Property change)

Figure 1 : DateTime Data Function Usage
 

Installing the DateTime Data Function

Download

The extension can be downloaded here.

Package Contents

The installation package consists of a zip file that contains the following folders:

• "For Spotfire Server" - this folder contains the deployable modules for the Extension.  These Spotfire Packages (SPK files) must be deployed onto the Spotfire Server by your System Administrator.
• "Documentation" - this folder contains this User Guide.
   

System Requirements

This version of the Extension can only be used with Spotfire 7.5 and above.  The minimum requirements for your version of Spotfire can be found at the Spotfire Support Site http://support.tibco.com.
 

Software Prerequisites

There are no additional prerequisites for the Extension.

Installation

The Extension is installed by adding the .SPK file from the "For Spotfire Server" folder to a Spotfire Distribution on the Spotfire Server:

•  SpotfirePS.DataFunctions.DateTimeNowDataFunction.spk

This is the same process that is used for Hotfix installation.

See the following section in the Spotfire Server Installation and Administration Manual for more details:

• Adding software packages to a deployment area

When Spotfire Analyst is next started it will prompt that updates are available and the packages will be downloaded.  However, the Web Player and Automation Services Servers must be updated manually as described in the following sections.

Updating Web Player and Automation Services

Web Player and Automation Services will need to be updated using the Spotfire Server web administration portal. See the following sections in the Spotfire Server Installation and Configuration Manual for more details:

• Updating Services

Spotfire Licenses

Access to the Custom Data Function "Add DateTime Data Function" tool menu entry is controlled via the standard Administration Manager Licensing functionality.  The Data Function license can be found under the Spotfire Extensions group.

This license is only necessary for the user that is authoring or modifying the analysis and will be adding the Data Function to the document. Once added to an analysis file, it will also run for users that do not have access to the "Add DateTime Data Function" tool menu item as long as the data function .spk has been installed on the server and clients have updated their deployments.

Figure 2 : DateTime DateFunction License

Validating the Installation

Once the Extension is correctly installed, licensed users should see an entry on their Spotfire Tools Menu whenever a DXP is open.
 

Figure 3 : Indications of a Correct Installation

Using the DateTime Data Function

Open a DXP File

The menu to insert a Data Function will only be enabled when a DXP file is open.

Insert a Data Function

Click on the Tools Menu and select "Add DateTime Data Function..."

The Setup Dialog will appear:

In the minimal use case of writing a document property with a new DateTime timestamp every time the analysis file is opened, no more configuration is needed.

If the OK button is clicked while leaving everything as per default without making any changes at this point, a pre-populated document property specified in the output section will be updated with the current UTC time stamp.

In this case, the document property as below will simply receive a new timestamp every time the analysis file is opened.

However, at this stage the user can proceed to optionally configure inputs  and outputs for more advanced scenarios, including adding multiple data functions in the same file and reacting to filtering and markings.

Adding multiple DateTime Data Functions to the same Analysis

If there is a need to have multiple instances of the DateTime DataFunction, proceed to the File->Document Properties menu and a target document property of the type "DateTime" with a suitable name.

Subsequently use this document property for the next instance of DateTime Data Function by selecting it as output in the Output section of the Data Function  setup dialog.

Using the DateTime Data Function

The following are some scenarios in which the Data Function can be used.

Executing a Script on Document Open

A common requirement is to run an IronPython script when the DXP file is first opened.

• Leave each of the Input handlers set to "None"
• Set the Output handler to "Document Property", and make sure the intended target document property is selected
• Trigger the IronPython Script to run whenever the Document Property changes

Executing a Script on Marking / Filtering Change / Data Change

Another common requirement is to execute an IronPython Script whenever a user changes a Marking or Filtering selection.

• Use the "ColumnInput" or Table Input type
• Choose the Table, Column and Marking / Filtering settings
• Set the Output handler to "Document Property", and make sure the intended target document property is selected
• Trigger the IronPython Script to run whenever the Document Property changes

Executing a Data Function

• Use the "ColumnInput" Input
• Choose the Table, Column and Marking / Filtering settings
• Set the Output handler to "Document Property", and make sure the intended target document property is selected
• Trigger the required Data Function to run to whenever the Document Property changes by adding the document property in the previous step to the other Data Function that should be triggered.

Configuring an Analysis for Scheduled Updates 

The concept and goals of Scheduled Updates and the DateTime DataFunction are conflicting; one aims to reduce recalculation and reloading of data when opening an analysis file and the other is designed, first and foremost to always run on opening the analysis file. This creates the need for a work-around to ensure that the DateTime document property is indeed updated when a user opens the analysis, also for a scheduled file on the Web Player service.

1. Create an Information Link that returns a "Now" column containing the result NOW(); in your database's SQL flavor, lets call it "NowLink"
2. Add a datatable "NowTable" to the analysis file from the "NowLink"
3. Go to the menu "Data>Data Table Properties > Scheduled Updates" and check the "Reload the following data for each user" checkbox for "NowTable".
4. Add the DateTime DF, and set the data function input to use the datatable's "Now" column as input.
5. Save the file to the Library and add it to the schedule.

All users using the scheduled file should now get both fresh "Now" table data and a updated document property from the DateTime DF when opening the analysis.

Trouble Shooting

Tools Menu Entry is Missing

Confirm that the client software deployment has been successfully updated by going to Help->Support Diagnostics and Logging -> Product File Information and locate the entry  "SpotfirePS.DataFunctions.DateTimeNowDataFunction.dll" in the file list. If it is not available, please proceed to verify that the client distribution on the Spotfire Server contains has been updated with the DateTime Data Function spk file and make sure to update the client distribution on the client machine.

Confirm that the License has been assigned to your User / Group.

Data Function Is Not Executing

Confirm that the "Refresh function Automatically" option is Enabled.

If it is not executing on the web player, please proceed to verify that the client distribution on the Spotfire Server contains has been updated with the DateTime Data Function spk file and make sure to update the client distribution on the web player instance machine.