Page Comparison

Dataplane supports reporting on (and charting of) calculated custom fields created with the ScriptRunner add-onapp from Adaptavist.

Image RemovedImage Added

ScriptRunner allows administrators to create customized and programmable Scripted 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.

Image Removed

Using ScriptRunner with Dataplane

Dataplane can use your existing Scripted Fields, or you can add new fields to be used in conjunction with Dataplane.

Dataplane supports scripted fields that contain numeric, date, and text data. Scripted Fields can be used in most reports in DataplaneImage Added

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

To add a Scripted Field for use with Dataplane, follow the steps below. Existing scripted fields can also be used, so long as the Search Template is configured for the appropriate data type (as described below).

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

Creating a Script Field

Image Added

To create a new Scripted ScriptRunner Script Field:

• Install the ScriptRunner add-on app.
• Navigate to Toolgear » Issues » Custom Fields
• Click Add Custom Field
• Click on the Advanced tab on the left-hand side of the dialog
• Find the Scripted Field field type and click Next
• Give the new field a name and then click Create
• If you do not want the scripted field to be visible to end users, do not associate the field with any screens. You may, however, want to associate the field with the Default or View screens for initial testing purposes, since you will not otherwise be able to see the rendered results of your field.
• Scroll down the custom field list to find your newly-created field, click the toolgear icon on the right hand side, and select Edit
• Configure the field's Search Template option based on the type of data you wish to store in the fieldJira 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.

Using a Script Field in Dataplane Reports

The following are important configuration considerations and usage tips in order for Dataplane Reports to successfully report on ScriptRunner Script Fields.

Configuring the Search Template

Whether using a new or existing Script Field with Dataplane Reports, you must verify that its Search Template is configured for the appropriate data type.

Image Added

To configure the Script Field's Search Template:

• Navigate to Jira Administration (gear icon) → Issues → Custom Fields.
• Search for your Script Field.
• Click on 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:

  To use the field in Dataplane as...	...select for Search Template:
  Numeric data	"Number Search" or "Number Range Searcher"
  Date	"Date Time Range Picker"
  Text	"Free Text Searcher"

  
  

• Finally, click Click Update to save the any changes to the field. 

Writing a Script for the Scripted Field

To define the functionality of the newly added Scripted Field:

• Navigate to Toolgear » Add-ons and select Script Fields on the left-hand navigation menu
• Scroll down to find your field, click the edit link, and write the script for your field

Making the Field Available to Reports

Configuring Associated Screens

Script Examples

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

The ScriptRunner documentation on Scripted 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, in order to be usable in numeric reports.

def price = getCustomFieldValue("Product Price")

if (price) {
    return price * 0.5;
}
else {
    return null
}

Date

Script Field

The following is a simple script that subtracts one week from the value of an existing Date custom field called "Payment Date".

The field for this script must be configured with a Search Template of "Date Time Range Picker", as described above, in order to be selectable as a Date Basis in reports that support dates.

def paymentDate = getCustomFieldValue("Payment Date") 
 
if (paymentDate) { 
	def cal = new java.util.GregorianCalendar();
 
	cal.setTimeInMillis(paymentDate.getTime()); 
	cal.add(java.util.Calendar.DAY_OF_MONTH, -7);
 
	return new java.sql.Timestamp(cal.getTimeInMillis()); 
} 
else { 
	return null 
}

String

Script Field

In this example we take the current value of an existing, select list field named "Team" and map that value to a geographic location. 

The field for this script should be configured with a Search Template of "Free Text Searcher".

final Map<String,String> LOCATION_MAP = new HashMap<String,String>() {{
    put("Team A",    "San Francisco")
    put("Team B",    "San Francisco")
    put("Team C",    "Montreal")
    put("Team D",    "Montreal")
    put("Team E",    "Montreal")
}};

def cfValue = getCustomFieldValue("Team")
    
if (cfValue != null) {
    def location = LOCATION_MAP.get(cfValue.toString())
	if (location != null) {
        return location
    }
}
return ""   // no match found

In the following example we use the same remapping concept to group an issue's possible statuses into a smaller set of values.

This is a common solution for presenting reports to management using a less granular view of the engineering workflow.

import com.atlassian.jira.issue.status
 
final Map<String,String> STATUS_MAP = new HashMap<String,String>() {{
    put("Open",    					"New")
    put("In Triage",    			"New")
    put("Assigned",    				"In Engineering")
    put("Work in Progress",    		"In Engineering")
    put("In QA",    				"In Engineering")
    put("Waiting for Customer",    	"Waiting")
    put("Waiting for Approval",    	"Waiting")
    put("QA Approved",    			"Ready")
    put("Ready for Deployment",    	"Ready")
    put("Closed",    				"Done")
    put("Reopened",    				"In Engineering")
}};

def origStatus = issue.getStatus().getSimpleStatus().getName()
def newStatus = STATUS_MAP.get(origStatus)
 
return (newStatus != null) ? newStatus : origStatus

First Level of a Cascading Select List Field

Dataplane directly supports reporting on Jira Cascading Select List custom fields, and will aggregate report results based on each unique combination of first and second level selections as in "US : San Francisco", "US : New York", "Canada : Toronto" and "Canada : Montreal".

Sometimes it can be useful though 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 custom field 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