Script Field Tutorial

Note: For a video on script fields, see the Using Script Fields training video.

ScriptRunner gives you the ability to create custom fields that rely on an underlying script with a feature called script fields. At the time of this writing, ScriptRunner includes four pre-built custom fields, as well as the ability to apply a custom (or in-line) script to an entirely new field.

This feature is located in the Manage Apps page. (Administration → Manage Apps).

The eight types of script fields available are:

Custom Script Field
This is the function you'd use to create a new custom field and script.
Date of First Transition
Displays the date that an issue was first moved to a designated status.
Issue(s) Picker
Allows you to select another issue, optionally constrained by a JQL query.
No. of Times in Status
Deploying this field informs users of how many times an issue has been in a designated status.
Show Parent Issue in Hierarchy
This field displays the parent issue in the hierarchy, and can be configured to follow Portfolio parent field or alternate links.
Remote Issue(s) Picker
Select an issue(s) from a linked Jira instance, optionally constrained by a JQL query.
Time of Last Status Change
The time stamp of the last status change is displayed in the issue.
Database Picker
Pick an item from a linked database table.

Tip: Fields need to be added to the relevant schemes by a Jira administrator in order to be used.

Why Use Script Fields?

Script Fields can calculate or amalgamate data from one or more existing fields. When your users need calculations displayed in an issue, in reports, or they want to display other information that isn't readily available via custom fields, ScriptRunner script fields give you the ability to meet their needs.

Example of Script Field

In this example, we'll help Great Adventure managers gauge how many times issues are being sent to the In Progress status to determine whether or not excessive re-work is being done. If they find that there are issues, they can drill down and see what is causing the repeat work.

Navigate to the ScriptRunner menu and select Script Fields.
On the Script Fields page that opens, click Add New Item.
The five options of script field type appear.
Click on No. of Times in Status option to open the form in which the script field will be defined.
Enter Count_In_Progress in the Field Name box.
Enter some descriptive text in the Description field.
Select In Progress as the applicable status type from the list provided.
Click Add at the bottom of the form, to create the field, then click Configure Context in the resulting pop-up.
When the Modify Configuration Scheme Context page displays, note that the name of the field can not be changed, but you could alter the description.
Select the Epic, Story, Task and Sub-Task issue types.
Select Apply to Issues Under Selected Projects.
Then, select the Great Adventures Customer Service project from the list provided.
Click Modify to save the changes.
On the next form, click View Custom Fields.
When the custom fields are shown, click the Ellipses icon to the right of the custom field that was just created.
Select Screens.
Then select the Jira Service Desk Screen for the Great Adventures Customer Service project by clicking in the selection box to the right of each entry.
Click Update to finalize the configuration.
Navigate to the Projects page and select the Great Adventures Customer Service project.
The newly-created field should now be visible on any Edit/View and Resolve screen for the Great Adventures Customer Service project.

This field can now be searched using JQL. This permits any user to determine whether an issue has transitioned to the In Progress state more often than would be normal. For example, it could help Jira admins identify tasks managed by people who are not following the internal processes correctly (given that In Progress should not exceed a count of 6-10 before the issue is closed). It could also be used to help identify problems with workflow controls.

For more examples of script fields, see our Example Scripts.