Script Fields

Features

• Automatically fills fields of a Work Item by calculating the value with a script written in JavaScript or Groovy.
• The content of the calculated field can be based on any other field(s) of the same Work Item.
• Supports different calculated fields per Work Item type.
• Supports any number of calculated fields.
• The calculated field will be automatically updated whenever a Work Item is changed.
• Includes a Job that forces an update of the calculated field (required when the configuration or the script changes).
• Easy configuration using a Wiki page.

 

Limitations

• The calculation can only access the content of the same Work Item. Access to nested objects (e.g. comments) is limited.
• Changes to the calculated field won't appear in the history.

 

Installation

1. Copy folder com.polarion.alm.extensions.scriptfield to <Polarion Installation>/polarion/extensions
2. Java 8 specific configuration - for running on Java 8, the following Java settings need to be applied in polarion.ini (Windows) or config.sh (Linux):
   -Dosgi.parentClassloader=ext
3. Restart Polarion.

 

Configuration

To configure the extension create a Wiki page called script-field-config in the default wiki space.
You can either create this page on a global level, to define calculated fields that are used in every project or on a project level to define calculated fields that are only used in one project.

Configuration Syntax

scriptfield.<field id>.<property name>=<property value> 
or
scriptfield.[<type id>]<field id>.<property name>=<property value>

• <type id>: ID of the Work Item type for which the property is defined.
• <field id>: ID of the field for which the property is defined.
• <property name>: Name of the property.
• <property value>: Value of the property.

There are two properties with a special meaning:

• script: Defines the file name (relative to the script folder (<Polarion Installation>/scripts by default) of the script to run.
• engine: Defines the name of the scripting engine to use. Defaults to "JavaScript". Use "groovy" as a value to run a Groovy script.

In the script, all properties are available as variables. The variable is the name of the property, the value is the string value of the property.

Configuration Example

scriptfield.[requirement]cost.script=cost.js scriptfield.[requirement]cost.pricePerManhour=50 The configuration will run the script cost.js whenever a (requirement) Work Item is changed to calculate the field cost. A variable called pricePerManHour with the value "50" will be available in the script.

Job Configuration

Usually, the script fields are only updated when a Work Item is changed. However, if you changed the configuration or the script and want to ensure that all Work Items are updated according to the changed settings you should use the update job.

To be able to use the Job you have to configure it in the Scheduler configuration of Polarion (Global Administration > Scheduler). Add the following job definition: <job name="Update Script Fields Global" id="update.script.fields" disabled="true" scope="system"> </job> The job will have to look at every Work Item to determine if it has to be updated. If you have a Polarion installation with many Work Items, you should consider configuring the job for only specific projects by adjusting the scope accordingly.

 

Writing Scripts

As mentioned earlier every property defined in the configuration will be available in the script. Additionally, there is a workItem variable that stores the Work Item. Unfortunately, the type of Work Item is not the type from the open API, but a low-level type called IDataObject. The relevant methods of this type are:

• Object getValue(String fieldId) to get the value of a field.
• Object getCustomValue(String customFieldId) to get the value of a custom field.
• Set<String> getKeySet() to get available field IDs.
• Set<String> getCustomKeySet() to get available custom field IDs.

To work with the value of get*Value(...) you need to know what type you are dealing with. The best way to find out is to use a simple test script that fills the type of a field value in a string field, e.g. the title. To do this you could use the following configuration: scriptfield.title.script=test.js and store the following script as tets.js in your scripts directory: workItem.getValue("author").getClass().toString();

 

Example

Take a look at Calculate Cost from Initial Estimate - this example calculates the cost of a requirement from the Initial Estimate of a Work Item.