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.
Creating 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.
Using a Script Field
within 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.
| Tip |
|---|
The Script Field's Search Template determines the field's data type as seen by Dataplane Reports, and influences the reports in which the field is available. |
| Note |
|---|
If you do not configure the field's Search Template, the Script Field will not report any data when used in Dataplane Reports. |
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" - Click Update to save any changes to the field.
Making the Field Available to Reports
| Note |
|---|
1) After creating a new Script Field or editing an existing field's script, you must reindex Jira. This is required to make the field's values visible to Jira and Dataplane. If your Jira version supports it, you can avoid downtime by reindexing only individual Jira projects (if the field is only used in those projects), or by performing a background reindex of Jira. 2) After creating a new Script Field or editing an existing field's Search Template, you must also go to the Dataplane Reports → Administration → Configuration page and click the "Sync Index" button to refresh Dataplane Report's list of Jira fields and their data types. This step is not required if only editing a Script Field's script. |
| Tip |
|---|
Before doing a full reindex of Jira, you can test a newly-added Script Field by performing an edit and save, or a workflow transition, on a single Jira issue. This forces ScriptRunner to recalculate and update the stored field value for that Jira issue. You can then see the script results by viewing the Jira issue (if the Script Field is associated with the current issue screen), or by performing a Jira Issue Navigator search that includes the issue (with the field selected as a search results column). |
Configuring Associated Screens
| Tip |
|---|
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 in order to see and evaluate script results. |
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, in order to be usable in numeric reports.
| Code Block |
|---|
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.
| Code Block |
|---|
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".
| Code Block |
|---|
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.
| Code Block |
|---|
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 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:
| Code Block |
|---|
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 |
| Panel | ||
|---|---|---|
| ||
Page Contents
|