Scripted Field

The Scripted custom field types are a set of calculated fields that utilize JavaScript to calculate a return value, usually based on other field values. They are read-only fields.

Within JMCF for Jira Cloud, there are several types of scripted fields, each corresponding to the type of value the script returns (the script must return the data type of the field).

Note: If a scripted field encounters and error during calculation or recalculation, the calculation of that field will pause. Other custom fields in your instance will continue to (re)calculate.

Errors with a scripted field will be displayed in the Error Logs page; errors will not be indicated on issue screens. The only indication of an error in a field recalculation will be:

If the field is new and has never been calculated, the value will remain None.
If the field’s script returns a value of undefined, the value will display None.
If the error occurred during recalculation, the field value will fail to update.

Field types

The following scripted field types are currently available:

Scripted string - Returns a string value.
Scripted datetime - Returns a datetime value.
Scripted number - Returns a number value.
Scripted user - Returns an Atlassian account ID or a user object.
Scripted group - Returns a group ID or a Group object.
Scripted string collection - Returns a collection of string values.
Scripted user collection - Returns a collection of user IDs or user objects.
Scripted group collection - Returns a collection of Group IDs or Group objects.

Add a custom field

Edit a custom field

Configure a new ‘Scripted’ field

If you added a JMCF custom field through the native Jira custom fields screen, see Edit a custom field, above.

Follow the steps above to add a custom field to your Jira instance, then follow these steps:

In the Select Scope step of the wizard, select the projects and issue types to which the custom field should be available.
Click Next.
In the Associate Screens step of the wizard, check the boxes for the screens to which the field should be added.
1. Use the search field above the list of screens to locate a specific screen.
2. Check the box at the top of the column to add the field to all listed screens.
  Note: some team management screens in Jira do not currently support custom fields!
Click Next.
The Configure Field screen will open; from here you can enter the script for the field, configure its dependencies, and test it before saving. See Script Configuration, below, for more information.
Click Save.

You are viewing the documentation for Jira Cloud.

On This Page 1 Field types 2 Add a custom field 3 Edit a custom field 4 Configure a new ‘Scripted’ field 5 Script configuration 6 Testing your script 7 Search templates

On This Page 1 Field types 2 Add a custom field 3 Edit a custom field 4 Configure a new ‘Scripted’ field 5 Script configuration 6 Testing your script 7 Search templates

Figure 1 - Scripted string field

Script configuration

JMCF Scripted fields use JavaScript to calculate an output. The output of your script must match the field type you selected when creating the custom field (e.g. a string or a user object); see Field Types, above, for a list of all supported output types.

When a new custom field is first configured, the script editor (Figure 2, right) will be populated by an example script; replace this with your own script. The script editor window includes standard code editing features, including syntax colorization, error highlighting, code formatting, and code completion.

The editor also includes three shortcut buttons to the right side of the window:

Expand/Contract - Expand the editor to full height, or shrink it back to its original height.
Templates - Pre-written script examples.
Help - Links to JMCF for Jira Cloud documentation, scripted field documentation, and the Appfire support portal.

API access

JMCF Scripted fields have access to a limited set of data through the Jira API. Currently, access is limited to the current issue’s fields including:

All issue fields - api.issue.getField and api.issue.getFields
Issue properties - api.issue.getProperty and api.issue.getProperties
Parent and Child issues - api.issue.getParent and api.issue.getChild
Linked issues - api.issue.getLinkedIssues
Users - api.jira.getUser
Groups - api.jira.getGroup and api.jira.getGroupUsers
Projects - api.jira.getProject

Dependencies

When writing your script, JMCF scans the script for dependencies in the form of references to other fields or properties. When dependencies are detected, they are automatically saved as a part of the scripted field configuration, and the field value will be recalculated whenever necessary.

Figure 2 - Scripted field script editor

Testing your script

The testing features built into Scripted field configuration can greatly assist in building your script and verifying its output before you save it. You can test your script against a specific issue and JMCF will:

Verify that the script output type matches the return type for the custom field (Point 1, Figure 3, right)
Indicate whether the script executed successfully or encountered an error (Point 1, Figure 3, right)
Display the outcome of the script (Point 2, Figure 3, right)
Display the contents of the console (if any) (Point 3, Figure 3, right)

To test your script:

Enter the ID of the issue against which your script should be run (e.g. ‘TEST-19’). Note: currently, searching by Jira ID is not supported.
Click Test.
The result of your script will be displayed below the issue selection (Figure 3, right):
1. If your script runs successfully, a Success badge will show, and the results of the script and any console logs will be displayed.
2. If your script encounters any issues, error will be displayed and the Test result window will show the specific error message, and any console logs will be shown up to the point of the error.