Work Item Picker Fields

Learn how to create and manage custom fields that let users select one or more work items from a list.

Each picker is configured with either a static JQL filter or a script that returns JQL, which controls which work items are available for selection. You could use a work item picker field to:

Let users link to a related work item from a curated, JQL-defined list.
Restrict selection to work items that meet specific criteria (for example, only open bugs in a given project).
Dynamically surface related work items by writing a script that generates JQL based on the values of other fields.

Work item picker fields appear on any screens you assign them to.

Available work item picker fields

Two work item picker fields are available. Both can use either a JQL query or a script that returns JQL:

Work item picker (single): Allow users to select only one work item.
Work item picker (multiple): Allow users to select multiple work items.

Output and logging

When you test a work item picker, the output panel shows two tabs:

Rendered: a preview of the field as users will see it, listing the work items that currently match your filter.
Raw: the JQL string your script returned.

The output panel also shows anything logged with console.log(...), and the error if the script failed, with the full untrimmed error behind Full error.

Use console.log(...) for messages, intermediate values, or debugging, and include a return statement for the JQL that selects the work items you want to offer.

Note: The Rendered and Raw tabs appear only while testing. In the activity panel you see the returned JQL on its own.

Activity history

Saved work item picker fields keep activity history, so you can review when they were run and what the output was, making it easier to audit and troubleshoot. For how long activity is kept, see Run history retention.

Create a work item picker field

You can create work item picker fields directly in ScriptRunner, or create them in Jira like any other custom field and then configure the script in ScriptRunner. To create a work item picker field in ScriptRunner:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
Select Work item picker fields.
Select Create.
Enter a Name and, optionally, a Description.
Optionally, add Labels to group this field with others.
Start typing to reuse an existing label. Labels are saved in lowercase, with hyphens instead of spaces.
Select the Picker type you wish to create. For more information, see the available work item picker fields above.
Note: You can't change the Picker type after a work item picker field has been created. If you need a different picker type with similar behavior, create a new work item picker field and configure it separately.
Choose your filter mode:
- JQL filter: Enter a JQL query directly. The same filter applies every time the field is displayed.
- Script: Write a script that returns a JQL string. Use this when the filter needs to be dynamic; for example, based on the current work item's fields or context. The script should only build and return a query.
Note: Real-time update limitations
If your JQL depends on another field's value, such as a select list, the picker does not pick up a change to that field straight away. The user has to refresh the work item before the available options update. Changing the space or the work type is the exception. The picker updates immediately for both.
Tip: Switching between a JQL filter and a script
If you have already entered a JQL filter, turning on Generate JQL with a script gives you a script that returns that query, so you can build on it instead of starting from scratch.
Turning it off again rebuilds the script from your JQL filter, so any changes you made to the script are lost.
If using Script, choose who you want the script to Run as: the current user, ScriptRunner app permissions, or a specific user. The default is the current user.
Optional: Select Test work item picker field, then Run, to preview which work items currently match your filter (see Test a work item picker field for more details).
- No test data is needed. The preview runs your current filter, whether that is the JQL filter or the script.
- The Rendered tab shows the picker as it will appear on a work item, in single or multiple mode to match your picker type.
- The Raw tab shows the JQL that was used.
- The preview runs with your own permissions, not the Run as you configured, so results may differ from what another user sees.
Select Publish.
Note: Custom field ID
The custom field ID is automatically generated when you create a work item picker field. It appears under Custom Field Id, below the picker type.
Associate your new field with relevant screens. See Atlassian's documentation for more information.

Test a work item picker field

You can test your work item picker fields before using them on real screens. This lets you confirm that your filter returns the work items you expect, and see the picker as your users will see it.

Unlike other script types, work item picker fields need no test data. The filter is either the JQL filter you entered or the JQL your script returns, so ScriptRunner runs whichever you have configured and shows you the result.

Test your work item picker field as follows:

When creating or editing a work item picker field, select Test work item picker field.
A testing panel displays.
Select Run.
ScriptRunner resolves your filter and searches for the work items that match it.
Review the results on the Rendered tab.
This shows the picker as it will appear on a work item, in single or multiple mode to match your picker type. Select a work item in it to see what your users will see.
Note: The interactive preview only appears in the testing panel. Elsewhere, such as when viewing activity, you see the raw output instead.
Optional: Select the Raw tab to see the JQL that was used.
This is useful when the preview returns nothing, because an empty result and a broken query look the same in the picker. If the JQL is empty, your script returned an empty string rather than a query.
If necessary, edit your JQL filter or script and test again until the results match your expectations.
Warning: If your script does anything other than return a query, for example creating or updating work items, those changes are applied to your Jira instance when you run a test. Test in a non-production environment first.

The preview runs with your own permissions, not the Run as you configured for the field. A field that runs as the app, or as a specific user, may return different results for your users than it does for you in the preview.

Edit a work item picker field

To edit a work item picker field:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
Select Work item picker fields.
Find your work item picker field in the list and select Edit.
Modify the work item picker field as needed.
You can update the static JQL filter or the script that returns JQL. Your changes are saved automatically as a draft. The published version keeps running until you publish again.
Optional: Select Test work item picker field, then Run, to preview which work items currently match your filter (see Test a work item picker field for more details).
- No test data is needed. The preview runs your current filter, whether that is the JQL filter or the script.
- The Rendered tab shows the picker as it will appear on a work item, in single or multiple mode to match your field type.
- The Raw tab shows the JQL that was used.
- The preview runs with your own permissions, not the Run as you configured, so results may differ from what another user sees.
Select Publish changes.

Find the custom field ID for a work item picker field

The custom field ID is automatically generated when you create a work item picker field. To find the custom field ID:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
Select Work item picker fields.
Find your work item picker field in the list and select Edit.
The field ID displays as a read-only field on the page.

Enable and disable a work item picker field

Disabling a work item picker field stops it from returning work items to choose from. Its JQL or script is not run and the picker is inactive, so users cannot search for or select work items through it. On screens, the field appears disabled, but it stays on your screens and contexts, keeps its configuration, and any values already saved on work items are not changed. Enabling the field restores normal behavior and the picker again returns selectable work items.

To enable or disable your work item picker field:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
In ScriptRunner, select Work item picker fields.
Locate the work item picker field you want to enable or disable.
Open the ellipsis (…) menu for that work item picker field and select Disable or Enable.

Delete a work item picker field

When you delete a work item picker field, it's removed from work items and screens so users can no longer see or use it, but it isn't permanently removed. You can still access it in ScriptRunner (using the Deleted filter) or in the Deleted fields area of the Jira admin settings, and restore it later if needed. The custom field ID is retained and will be the same if you restore the field.

To delete a work item picker field:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
Select Work item picker fields.
Find the work item picker field you want to remove.
Open the ellipsis (…) menu for that work item picker field.
Select Delete.
When prompted, confirm that you want to delete the work item picker field.

Restore a deleted work item picker field

When you restore a work item picker field, it becomes active again in Jira and ScriptRunner. Its activity history is available, it's re‑added to all the screens and work items it was associated with before deletion, and it keeps the same custom field ID it had originally.

To restore a deleted work item picker field:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
Select Work item picker fields.
Use the filter and select Deleted to view deleted work item picker fields.
Find the work item picker field you want to restore.
Open the ellipsis (…) menu for that work item picker field.
Select Restore.