Links
TrackStudio Enterprise 3.5
Script Concepts

Use scripts to calculate custom field values, define triggers, define CSV import rules and define String custom field lookup values.

TrackStudio uses a Java-like language based on BeanShell to evaluate expressions. It means that you can create not only basic mathematical expressions, but also more complex expressions (if, for, or while). You can use in your scripts classes defined in the trackstudio.script property in the trackstudio.properties file. 

The following constants are also available:

Constant 
Type 
Value 
Description 
DAYS 
long 
86400000 
msec/day 
HOURS 
long 
3600000 
msec/hour 
MINUTES 
long 
60000 
msec/minute 
SECONDS 
long 
1000 
msec/second 
Task / Custom Field Value and User / Custom Field Value:

Use scripts of these types to calculate the values of custom fields. To create a calculated custom field, you should create a custom field and then specify a script for it. No results are saved to the database for a calculated field. 

An object of the SecuredTaskBean class available in the task variable can be used in a script of the Task / Custom Field Value type. This object corresponds to the task the custom field value is calculated for. Use this object to access task properties. 

An object of the SecuredUserBean class available in the user variable can be used in a script of the User / Custom Field Value type. 

The type of the value returned by the script depends on the custom field type. If the expression is incorrect or if the calculated value type does not match the field type, the result will be an empty field (null). 

TrackStudio allows you to create calculated custom fields of the same types as static custom fields. (i.e. Integer, Float, String, Date, List, etc.). You should make sure that the result matches the required type. For example, to get the result of date calculation in milliseconds (long), convert it to the Date type:

new Date(milliseconds)
Task / Custom Field Lookup and User / Custom Field Lookup

Use scripts of these types to create a list of possible values for custom fields of the String type. 

An object of the SecuredTaskBean class available in the task variable can be used in a script of the Task / Custom Field Lookup type, while an object of the SecuredUserBean class available in the user variable can be used in a script of the User / Custom Field Lookup type. The script must return a list of strings that will be offered to the user specifying a value for a custom field of the String type:

List list = new ArrayList();
list.add("value1");
list.add("value2");
return list;
Trigger / *

Triggers are special types of scripts that are defined to execute automatically before, in place of or after data modifications. They can be executed automatically on the Create Task, Add Message, Update Task triggering actions. 

There are three different types of triggers in TrackStudio. They are BEFORE triggers, INSTEAD OF triggers and AFTER triggers. These triggers differ from each other in terms of their purpose and when they are fired.

  • Use BEFORE triggers for data validation and correction before editing existing tasks, or adding new tasks or messages. BEFORE triggers execute before the triggering action.
  • Use INSTEAD OF triggers to avoid new task or message creation or task updating. INSTEAD OF trigger replaces the normal triggering action with the actions defined in the trigger. For example, if an Add Message / INSTEAD OF trigger exists and a message is added, TrackStudio will not add a message to the task, but rather execute the trigger, which may or may not add a message to the task.
  • Use AFTER triggers to generate change history, move tasks to another project after editing existing tasks, or adding new tasks or messages. AFTER triggers execute following the triggering action. You cannot change properties of the created or edited object using the AFTER trigger.

You can define a BEFORE, an INSTEAD OF and an AFTER trigger on the same object for the same operation.

Trigger Type 
Parameter 
Returns 
Trigger / Create Task / * 
SecuredTaskTriggerBean task 
SecuredTaskTriggerBean 
Trigger / Edit Task / * 
SecuredTaskTriggerBean task 
SecuredTaskTriggerBean 
Trigger / Add Message / * 
SecuredMessageTriggerBean message 
SecuredMessageTriggerBean 

To notify user about invalid data submission, throw the UserMessageException exception. In this case, event processing will be interrupted and user will be returned to the initial data entry form with error message.

CSV Import

Use a script of this type to import objects from a CSV file. Source data is stored in the inputMap object of the Map class. Each field in the header line is a key while the value is the corresponding field from the line being processed in the CSV file. This script must return Map or a collection of objects of the Map class. The corresponding TrackStudio object will be created for each object in this collection.