How to execute an IronPython script on initial load of an analysis using Data Functions in Spotfire

Product: Spotfire Analyst
Versions:All Versions

Summary:
This articles describes a few methods for how to execute an IronPython script on initial load of an analysis using a data function in Spotfire

Details:
Normally, IronPython scripts cannot be set to automatically execute when a report is opened, but instead must be manually triggered with an action control button/link or on a property change.

One method is to use the Custom DateTime Data Function for TIBCO Spotfire found in the TIBCO Community Wiki.

Another method to trigger the script to execute automatically is to use a data function, which executes when the report is opened to update a document property configured to execute the IronPython script on a property change. A data function is used because it will execute automatically when the report is opened, and it can pass the current date time (which will always be unique and not the same as a previous execution) to a document property, which can then be used as the trigger to execute the IronPython script.

Resolution:
 

Option 1:
Use the Custom DateTime Data Function for TIBCO Spotfire as explained in the TIBCO Community Wiki.

Option 2:
Step 1. IronPython script to be executed on report load.

First, create the IronPython script to be executed on report load. For example:

Name: ExecuteOnLoad
Script:

import clr
clr.AddReference("System.Windows.Forms")
 
from System.Windows.Forms import MessageBox
MessageBox.Show("This script ran automatically on load")

Step 2. Document Property which is configured to execute the IronPython script on property change.

Create a document property that will be used as the trigger for the IronPython script. For example:

1) Edit > Document Properties > Properties' tab > New.. > Give it the name "CurrentDateTimeProperty" and value "5/21/2015 10:53 AM" (or any valid value).
2) Edit > Document Properties > Properties' tab > Select 'CurrentDateTimeProperty' property > "Script" button.
3) Script - Act on Property Change > Each time the property value changes, perform this action > Select "Execute the script selected below".
4) Select the "ExecuteOnLoad" script to run (or other script that will run on document load).

Property Name: CurrentDateTimeProperty

Script: ExecuteOnLoad

Step 3. Data Function which executes on report load.

Create a data function that outputs the system time to a document property 'CurrentDateTimeProperty' as created in Step 2. This executes automatically when the report is opened.

This can be created here:

1) Edit > Data Function Properties > Register New
2) Enter a name: Update_CurrentDateTimeProperty
3) In the 'Script' tab, enter the script:

output <- Sys.time()

4) In the 'Output Parameters' tab, click 'Add...' and give it the name 'output'. This matches the variable name in the data function script. The Type can remain as the default 'Type: Value'.
5) Click 'Run' button in the top options which will open the 'Edit Parameters' dialog.
6) Check Refresh Function Automatically
7) In the 'Output' tab, select the 'output' parameter.
8) In the 'Output handler' options, select 'Document property'.
9) On the right in the Property list, select the 'CurrentDateTimeProperty' property.
10) Click OK.

Name: Update_CurrentDateTimeProperty
Script:

output <- Sys.time()

Output parameter:
  - Name: output
  - Type: Value
  - Output: Document property:CurrentDateTimeProperty

Note:
Ensure the "Sys.time()" function used in this example is available on the statistical engine you are using. This is available in TERR and R by default. The function is case sensitive.

Requirements:
Since this uses a data function as the trigger, it requires a statistics engine to work. TERR is included in the TIBCO Spotfire installed client starting in version 5.0. There are no additional requirements for this to work in those clients. For this to work on the Web Player, you need to configure Spotfire to point to a TIBCO Spotfire Statistics Services (TSSS) server instance. This TSSS URL must be configured according to the TIBCO Spotfire Statistics Services Installation and Administration Manual (see documentation in references).

Example:

 - See the attached (Filename: Execute IronPython Script Automatically On Report Load.dxp). Requires Spotfire version 6.5 or higher.

Scheduled Updates:
If the report is cached in Scheduled Updates, the data function will not execute as defined above since the report is cached. In this case, you will need to define an input parameter for the "Update_CurrentDateTimeProperty" data function that is based on a column from a data table which is reloaded for each user. Do (Edit > Data Table Properties > select the data table > Scheduled Updates tab > Check "Reload the following data for each user" for the data table) so that there is an update when the cached report is opened by the end user which will trigger the data function execution.

For example:

Name: Update_CurrentDateTimeProperty
Script:

input
output <- Sys.time()

Input Parameter:
  - Name: input
  - Type: value
  - Input: Expression: First([myDataTable].[myColumn])
Output parameter:
  - Name: output
  - Type: Value
  - Output: Document property:CurrentDateTimeProperty