How the Issue Picker Works from an End User's Perspective

Learn how people use Issue Picker fields in Jira Cloud: where the field appears, which work items it offers, how to search and pick, and what the work item view shows.

1. Where People Use an Issue Picker

Required Jira Role: Jira User

An Issue Picker is a Jira custom field. People can fill it wherever the Jira admin has added it to a screen:

  • Create: in the create dialog of a work item
  • View: inline on the work item view
  • Transition: on the transition screens of a workflow
  • Portal: on request forms in the Jira Service Management portal

To fill the field, a person also needs the Jira permission to create or edit the work item.

â„č Transition screens:

Jira shows app fields such as the Issue Picker on transition screens only in the new transition experience. If the field is missing there, ask your Jira admin to turn it on.

2. Which Work Items the Picker Offers

Required Jira Role: Jira User

The Jira admin decides what each Issue Picker offers. Every time the list opens, the field runs a Jira search; nothing is copied or cached in advance.

  • Selection filter: a JQL query, for example only open risks: issuetype = Risk AND statusCategory != Done
  • Contexts: the same field can use a different filter per space and work type.
  • Dynamic JQL: the filter can use values of the work item you are filling, for example only work items of the same customer.
  • Current space: the list can be limited to the space of the current work item.
  • Subtasks: subtasks of the current work item can be offered in addition.

The work item you are editing is never offered. The list is sorted by key, unless the filter has its own ORDER BY.

An Issue Picker field named Risks offers only open risks. The list ends with a more link and the counter 100+ work items found.

2.1 Whose Permissions the Search Uses

With Use app permissions for the search switched on, the search runs with the app's permissions, so the list can contain work items you cannot open yourself. Switched off, it runs with your own Jira permissions and shows only work items you can browse. The admin sets this per Issue Picker and per context.

2.2 Long Lists

The picker loads the first 100 work items. Click more or scroll to the end of the list to load the next 100. The line at the bottom, for example 100+ work items found, counts the work items loaded so far. There is no limit to how many work items a picker can offer; to find one quickly, search for it.

2.3 Dynamic JQL on Different Screens

If the filter uses values of the current work item:

  • On the create screen, the list updates when you change one of these values, for example after choosing the customer.
  • On the work item view and on transition screens, the saved values of the work item are used.
  • In the portal, only the space and the request type are known. Other values count as empty, and the fallback set by the admin decides.

3. How to Search

Required Jira Role: Jira User

  • Text: type words of the summary. The picker finds work items with summary words that start with what you type, e.g. deliv finds “Vendor delivery slips to Q3”.
  • Key: type a complete work item key, e.g. RISK-204. The matching work item is listed first. Partial keys such as RISK-2 do not find work items by key.

If the admin has turned on Hide key in picker or Deactivate key search, only the text search is available.

The picker uses Jira's own JQL search, so the same rules apply as in Jira's search, e.g. for special characters.

4. Picking and Removing Work Items

Required Jira Role: Jira User

  • Single select: picking another work item replaces the current one. The clear button empties the field.
  • Multi select: pick as many work items as you need. Picked work items disappear from the list. Remove one with its ✕ or with Backspace.
  • On the work item view, your changes are saved when you leave the field. Press Esc to discard them.

4.1 Links Follow Your Picks

If the admin has set a Link type, each picked work item also gets a native Jira link, and removing it from the field removes the link. Depending on the settings, it also works the other way round: linking a work item in Jira adds it to the field, and deleting the link removes it. These updates run in the background and can take a few seconds.

Risks picked in the field appear under Linked work items with the link type has risk.

5. What the Work Item View Shows

Required Jira Role: Jira User

The field shows one row per picked work item. The admin chooses which of these parts are shown:

  • Work type icon
  • Key, as a link to the work item
  • Summary
  • Status
  • Assignee
  • Priority

The rows are sorted by key. An empty field shows None.

Jump to: