Dataplane supports reporting on and charting fields created with the free Script Runner add-on by Jamie Echlin.
Script Runner allows administrators to create customized and programmable Scripted 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.
Using the Script Runner Add-On 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 Dataplane.
Since Scripted Field values are calculated on the fly and changes to a Scripted Field are not stored in the JIRA changelog, only the current values of Scripted Fields (and not the historical previously-calculated values) can be used in Dataplane.
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).
Creating a Scripted Field
To create a new Scripted Field:
- Install the Script Runner add-on
- 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 Scripted 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. (However, you may 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 on the right hand side, and select "Edit"
- Configure the Search Template based on the type of data you wish to store in the field (see below), then save the field.
The Search Template controls the data type of the field as seen by Dataplane, and it influences the reports in which the custom field is available.
|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"|
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
- If you have added the script for a custom field, or if you have updated the script for an existing field, you need to reindex JIRA so that the updated values of the field become available to JIRA and to Dataplane:
- For testing purposes, before doing a full reindex of JIRA, you can also perform an edit and save on a single issue, or perform a transition on a single issue, and Script Runner will update the value of the scripted field for that issue only. You can then see the results in the Issue Navigator columns list (by adding the Scripted Field column) or when viewing the issue (if you added the custom field to the appropriate screen)
- If your version of JIRA supports it, you can perform a background reindex so that no downtime is required.
- Performing a reindex of only a single project is also possible.
- After adding a Scripted Field to the system, you must also navigate to Dataplane Reports->Administration and click the "Sync Index" button to refresh the list of custom fields available in Dataplane reports. Performing this synchronization is required only after adding an entirely new field (or changing the Search Template of an existing field). If you have simply updated the script for a field, the JIRA reindex from the step above will be sufficient, and no additional Dataplane operations need to be performed.
Scripted Field Examples
This section provides examples of a few scripted fields that access issue data.
The Script Runner documentation on Scripted 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.
Example Numeric Field
The following is an example of a very simple scripted field that obtains the value of an existing custom field named "Product Price", multiplies the value by 50%, and returns the result.
This field 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.
Example Date Field
The following is a simple scripted field that subtracts one week from the value of an existing Date custom field called "Payment Date".
This field 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.