Script Fields

Before you start

See our training module to learn about setting up and using script fields.

Broaden your horizons by exploring the Example Scripts for script fields.

What are script fields?

Script Fields are custom fields that dynamically calculate and display values based on built-in and custom scripts. They enable you to display information that would otherwise be unavailable for an issue by calculating or aggregating data from one or more existing fields.

How to use script fields

You could use a script field to:

Pull in data from an external system (such as a connected database).
Show a value from a linked instance.
Show a value calculated from the values of other issue fields.
Show a value calculated from the values of fields in other issues.

When writing a script, it's good practice to keep the scripts as simple as possible so as to reduce loading time.

ScriptRunner Script Fields are not available on the Issue Detail view of scrum or kanban boards.

You cannot manually edit the value, or update the value of a script field as the value is calculated at the time an issue is displayed or updated (in exactly the same way as a custom field plugin). It is possible to search on these values, as explained below.

Searchers

You can run a search on your script fields provided it has a Searcher associated with it.

A searcher is equivalent to the Search Template that come default with custom fields. Built-in script fields are automatically given a searcher. For most custom script fields you have to add your own searcher by selecting the searcher field, selecting the appropriate search template, and performing a re-index.

Image showing how to add a searcher

Make sure to choose the correct template before you create your field because once you have a searcher defined, it may require a full re-index to change it to another Search Template if the types are incompatible.

Be cautious when converting to the Stattable version of indexers. Stattable searchers can be used in gadgets. In instances with hundreds of thousands of possible unique string values, the memory demand of Jira increases and may run out if required to render gadgets for fields using these searchers. Therefore, you should only use these indexers if your script field generates a finite number of possible string values (several thousand should be okay).

Available script fields

We have developed a number of built-in script fields for you to use in your Jira instance:

Database picker: Pick an item from a linked database.
Custom picker: Write your own picker, for example using a REST resource or a Jira object.
Date of first transition: Shows the date when the field first transitioned into a required state.
Issue(s) picker:Select another issue, optionally constrained into a required state.
Number of times In status: Show the number of times a given issue has been in the selected status.
Show parent issue in hierarchy: Show an issue's parent issue where you define what parent means.
Remote issue picker: Select issue(s) from a linked Jira instance, optionally constrained by a JQL query.
Time of last status change: Displays a timestamp of when the issue last had its status changed.
LDAP picker: Pick an LDAP record(s) from a predefined query.

We have also created a number of custom script field examples you can use.

Create a script field

You can create some script fields through the Add custom field button on the Custom fields page, however we recommend you create all of your script fields from within Scriptrunner.

You can create a script field as follows:

From ScriptRunner, select the Fields tab.
Select Create Script Field.
Select the type of script field you want to add and continue to the relevant documentation page:

Caching

The calculated value of a script field is cached for 10 seconds and we can cache up to 40,000 objects. If you refresh an issue and don't see a change, it may be because you're seeing the cached value. If you wait more than 10 seconds then it should reflect the updated value.

If your script relies on data from external system you can invalidate the cache altogether, although you should test first, particularly if you are doing things like running complex JQL queries. To disable the cache add the following line to your code:

groovy
enableCache = {-> false}

You can use any other variables to return a Boolean. You may have to do this if you are computing data from linked issues, however the indexed value should always be correct.

If your field relies on data outside its scope and you want to search on it, we recommend that you write your own searcher (custom JQL).

Performance and execution history

On the Script Fields page we provide Performance and History columns that display performance execution history records for custom script fields.

Please note that performance and execution history records are only available for custom script fields. Performance and History will remain blank in the rows of custom fields created from built-in scripts.