Custom DateTime Data Function for TIBCO Spotfire®

Spotfire Extension to update a DateTime Document Property in Spotfire, allowing secondary automatic triggering of IronPython scripts or Data Functions, simulating execution on Document Open, Marking and Filter changes.

Compatible Products

TIBCO Spotfire®

Provider

TIBCO Software

Compatible Versions

Spotfire 7.5.0 and above

License

TIBCO Component Exchange License

Overview

The main goal of the Custom DateTime Data Function for TIBCO 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.

This is achieved by the DateTime Data Function enabling the update of a Spotfire Document Property whenever a chosen event occurs in the form of a simple Date and Time when the Data Function was executed, allowing this Document Property change to in turn trigger the execution of an IronPython script, or a second DataFunction.

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 Document Property update event can in turn be used to trigger other changes to the analysis files, such as automatically runing IronPython scripts on analysis open. Some examples include:

  • Updating a Document Property
  • Updating 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)

Release(s)

Release 1.0.0

Published: April 2020

Initial release. 

Review (1)
5
hector_martinez 9:43am 05/30/2020

Thank you for this extension.  This is a very valuable functionality that I wish Spotfire had OOB.  Since its release here on the community i have been really been leveraging it in may projects. 

 

 

Custom DateTime Data Function for TIBCO Spotfire®

Introduction

The main goal of the Custom DateTime Data Function for TIBCO 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:

https://community.tibco.com/modules/custom-datetime-data-function-tibco-spotfirer

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.spotfire.com/sr.asp.

 

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

 

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

 

View the Wiki Page