Issue Picker

A field whose options come from a JQL query, with optional real Jira links.

What it does. Jira lets you link any issue to any issue. It does not let you say “these are the issues this field accepts”. The Issue Picker does: you write a JQL query, and the field offers exactly the issues that query returns.

Typical uses. “Affected service” pointing at a service catalogue project. “Caused by change” pointing at your change project. “Parent programme” pointing at an epic-level project.

Jira → Settings → Issues → Custom fields → Issue Picker → Contexts → Edit configurationIllustration

Issue Picker configuration

Save Configuration

JQL to limit search options

project = OPS AND type = Incident AND statusCategory != Done ORDER BY created DESC

Issues returned by this JQL will be shown as options in the dropdown.

Test JQLValid — 42 issue(s) found

Scope and permissions

Limit field options to current project

Use App Permissions

Selection

Allow to select multiple Issues

Multi Select

Max Results

Maximum issues returned (1-200)

Issue links

Add an Issue Link towards the selected Issue

Link Type

relates to

Delete all Issue Links of selected type when unselected

Display Columns

Key ✓Summary ✓Status ✓Assignee ✓+ Priority+ Issue Type

Quick Filters

Allow users to quickly narrow results using filter buttons. Up to 5 filters.

Assigned to meUnresolvedOpen Sprints+ Add Custom Filter

The JQL query

JQL to limit search options is the only required setting. Whatever the query returns becomes the list of options.

Example: only open incidents, newest first

project = OPS AND type = Incident AND statusCategory != Done ORDER BY created DESC

Test JQL: Validates the query and tells you how many issues it currently returns. Always use it: a query that returns nothing gives your users an empty field and no explanation.
Limit field options to current project: Scopes the query to the project of the issue being created or edited, so one configuration works across many projects.
Max Results: How many issues come back, 1 to 200. Users narrow the list by typing, rather than scrolling.

Whose permissions run the query

By default the query runs as the person using the field, so nobody sees an issue they could not already see. Use App Permissions switches it to the app's own access instead. That is useful when the picker must offer issues from a project the user cannot browse, but it means the dropdown can show issue keys and summaries they are not otherwise allowed to see. Turn it on deliberately, not by default.

Single or multiple selection

Allow to select multiple Issues switches between Single Select and Multi Select. Multi-select fields show each selection as a removable chip on the issue.

Creating real Jira links

A field value is data. An issue link is something Jira understands everywhere: in the issue view, in JQL, in reports. Add an Issue Link towards the selected Issue makes the app create a real link of the type you choose whenever a selection is made, including on the create screen.

Links for a value set at creation arrive a moment later

On an existing issue the link is made as you save. On the create screen there is no issue to link to yet, so a background trigger picks it up once the issue exists — normally within a second or two. That trigger is the one part of this feature that needs an active app licence.

Link Type: Any link type configured on your site, such as relates to, blocks or duplicates.
Delete all Issue Links of selected type when unselected: Removes the links again when the field is cleared. Leave this off if people also create links of that type by hand — the cleanup does not know who created a link.

The selection dialog

Jira issue → Related incidents (Issue Picker) → Select issuesIllustration

Select Issues✕

Search issues...

Assigned to meUnresolvedOpen Sprints

Key	Summary	Status	Assignee
`OPS-4412`	Checkout latency spike in eu-west-1	In progress	MR
`OPS-4380`	Payment webhook retries exhausted	Waiting	JL
`OPS-4361`	Elevated 5xx from the search service	To do	AS

42 issue(s) available

CancelDone (2)

Setting	What it does	Recommendation
Display Columns	Which columns the dialog shows: Key, Summary, Status, Assignee, Priority, Issue Type.	Include whatever makes the choice obvious. A list of keys and summaries alone is often ambiguous.
Quick Filters	Up to five one-click filters. Three presets ship — Assigned to me, Unresolved, Open Sprints — and you can add your own with a label and a JQL snippet.	Add one for the case your users pick 80% of the time.
Preload issues	Loads results as soon as the dialog opens.	On, unless the query is very large.
Show Issue Count during edit	Shows how many issues match, under the dropdown.	On while you are tuning the query.

How selections look on the issue

Show status of selected Issues adds the status next to each selection, so a stale reference is obvious.
Show Issue Key of selected Issues prefixes each selection with its key, for example OPS-4412.