Report on calculated values with ScriptRunner

Dataplane supports reporting on custom fields created with the ScriptRunner app from Adaptavist.

ScriptRunner allows administrators to create customized and programmable Script Fields that can be used almost anywhere that a regular Jira field can be used, and which can perform arbitrary calculations on issue-related data using the Groovy language.

In Dataplane Reports, ScriptRunner Script Fields can be used in most reports to report on numeric, date, or text data.

Info*Since ScriptRunner Script Field values are calculated on the fly and changes to a Script Field are not stored in the Jira issue changelog, Dataplane Reports can only report on the current value of a Script Field, not any prior, historical value of the field.

Dataplane Reports can use existing ScriptRunner Script Fields, or you can add a new Script Field for Dataplane Reports use.

Create a script field

To create a new ScriptRunner Script Field:

Install the ScriptRunner app.
Navigate to Jira Administration (gear icon) > ScriptRunner. Select Fields from the left sidebar or from the tab options.
Click the Create Script Field button.
Select from the available Script Field templates, or choose Custom Script Field to create your own.
Write your script and select the appropriate Template to define the type of returned value.
Save the new Script Field.
Navigate to Jira Administration (gear icon) > Issues > Custom Fields
Scroll down the custom field list to find your newly-created field, click the Actions menu ("...") for the field, and select Edit details or Edit.
Set the field's Search Template to match the type of data returned by the script:
Click Update to save any changes to the field.

The custom field's Search Template option controls the datatype of the field, as seen by Dataplane Reports, and it influences the reports in which the custom field is available.

If you do not configure the Search Template option, the new custom field will not report any data when used in Dataplane Reports.

Make the field available to reports

After creating a new Script Field or changing an existing field's selected Search Template, you must reindex Jira and also click the Sync Index button on the Dataplane. Reports > Administration > Configuration page. These two steps are required to make the field's values visible to Jira and Dataplane Reports.

You must also reindex Jira after modifying an existing field's script. This is required to make the field's new values visible to Jira and Dataplane Reports. If you have only updated the script, reindexing Jira itself is sufficient; no additional Dataplane Reports operations need to be performed.

The following tips are helpful for script testing and for speeding up a Jira reindex:

If you do not want the Script Field to be visible to end users outside of Dataplane Reports, do not associate the field with any Jira issue screens. However, for initial script testing, it can be useful to temporarily associate the field with the Default or View issue screen to see and evaluate script results.
To test your script before doing a full reindex of Jira, you can edit any field value or perform a status transition in a single Jira issue. ScriptRunner will automatically update the value of the Script Field for that one issue. You can then see the issue's Script Field value in your Dataplane reports.
If your version of Jira supports it, you can perform a background Jira reindex without downtime.
Performing a Jira reindex of only a single project is also possible.

Script examples

This section provides examples of a few scripts that access issue data.

The ScriptRunner documentation on Script Fields provides many more examples of how to use scripted fields. Most Groovy language concepts can be used within scripted fields, including the ability to access other custom field values, perform arithmetic, and call arbitrary Java or Groovy APIs.

Numeric script field

The following is an example of a very simple script that obtains the value of an existing custom field named Product Price, multiplies the value by 50%, and returns the result.

The field for this script must be configured with a Search Template of Number Search or Numeric Range Searcher, as described above, to be usable in numeric reports.

def price = getCustomFieldValue("Product Price")

if (price) {
    return price * 0.5;
}
else {
    r”

Sometimes, though, it can be useful to aggregate report results based only on the first-level selection in the Cascading Select List field, as in US and Canada in the above examples. To do this, set up a new ScriptRunner Script Field configured with a Search Template of Free Text Searcher.

Use the following script to return just the first level selection in the Cascading Select List field:

import com.atlassian.jira.component.ComponentAccessor
import com.atlassian.jira.issue.CustomFieldManager
import com.atlassian.jira.issue.customfields.option.Option
import com.atlassian.jira.issue.fields.CustomField

// don't change any of these
def SELECT_LEVEL_1 = null	
def SELECT_LEVEL_2 = "1"	
def EMPTY_STRING = ""

// modify these
def CASCADING_SELECT_FIELD_NAME = "My Field"	// name of your cascading select field
def SELECT_LEVEL = SELECT_LEVEL_1				// grab either the 1st or 2nd level only

CustomFieldManager customFieldManager = ComponentAccessor.getCustomFieldManager()
CustomField cf = customFieldManager.getCustomFieldObjectByName(CASCADING_SELECT_FIELD_NAME)
 
HashMap<String, Option> value = (HashMap<String, Option>)issue.getCustomFieldValue(cf)
return (value != null) ? value.get(SELECT_LEVEL) : EMPTY_STRING