Work Item Picker Fields

Use work item picker fields to create custom fields that let users select one or more work items returned by a JQL query. 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

The following work item picker fields are available, both based on 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 run a script, the output panel shows:

  • Anything logged with console.log(...)
  • The final JQL string returned by your script with return

Use console.log(...) for messages, intermediate values, or debugging, and include a return statement for the work items you want to display. When testing, each time you select Run, the output panel is cleared and refreshed with the latest logs and return value.

Execution history

Saved work item picker fields keep a full execution history, so you can review when they were run and what the output was, making it easier to audit and troubleshoot. Execution history is stored for two weeks before it is refreshed.

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:

  1. In Jira administration, select Marketplace apps.
  2. Under Apps, select ScriptRunner.js.
  3. Select Work item picker fields.
  4. Select Create.
  5. Enter a Name and, optionally, a Description.
  6. Select the Field type you wish to create. For more information, see the available work item picker fields above.

    You can't change the Field type after a work item picker field has been created. If you need a different field type with similar behavior, create a new work item picker field and configure it separately.

  7. 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.

      Real-time update limitations

      Scripts do not respond in real time to field changes, except to space and work type. If your script uses another field (for example, a select list) within the JQL query, the picker will not update the available options until the work item is saved and reopened.

      Examples

      To help you write scripts, you can select Example scripts directly in the script editor.

  8. If using Script, choose who you want the script to Run as. Select whether the work item picker field runs with ScriptRunner app permissions or as a specific user.
  9. Select Save.

    Custom field ID

    The custom field ID is automatically generated when you create a work item picker field. 

  10. Associate your new field with relevant screens. See Atlassian's documentation for more information.

Edit a work item picker field

To edit a work item picker field:

  1. In Jira administration, select Marketplace apps.
  2. Under Apps, select ScriptRunner.js.
  3. Select Work item picker fields.
  4. Find your work item picker field in the list and select Edit.
  5. Modify the work item picker field as needed. You can update the static JQL filter or the script that returns JQL.
  6. Select Save.

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:

  1. In Jira administration, select Marketplace apps.
  2. Under Apps, select ScriptRunner.js.
  3. Select Work item picker fields.
  4. Find your work item picker field in the list and select Edit.
  5. 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:

  1. In Jira administration, select Marketplace apps.
  2. Under Apps, select ScriptRunner.js.
  3. In ScriptRunner, select Work item picker fields.
  4. Locate the work item picker field you want to enable or disable.
  5. 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:

  1. In Jira administration, select Marketplace apps.
  2. Under Apps, select ScriptRunner.js.
  3. Select Work item picker fields.
  4. Find the work item picker field you want to remove.
  5. Open the ellipsis (…) menu for that work item picker field.
  6. Select Delete.
  7. 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 full execution 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:

  1. In Jira administration, select Marketplace apps.
  2. Under Apps, select ScriptRunner.js.
  3. Select Work item picker fields.
  4. Use the filter and select Deleted to view deleted work item picker fields.
  5. Find the work item picker field you want to restore.
  6. Open the ellipsis (…) menu for that work item picker field.
  7. Select Restore.
On this page