JQL scope

Every Work Item Selector field has a JQL scope, and it is required. The scope is the candidate set: it decides which work items the picker offers, and nothing else appears in the list.

It is set per field context, not per field. One field can therefore behave differently in different projects or for different work types, which is how a single field named “Blocked by” can offer engineering work items on one project and support requests on another.

Setting it

Open Settings, the gear icon at the top right, then Work items
Select Fields in the left menu
Find your field, then select the three dots beside it and Contexts and default values
Select Edit custom field config
Write the JQL
It is validated live against Jira’s own parser as you type. A green tick means it parses and matches work items, a red cross means it does not parse, and an amber tick means it parses but currently matches nothing. An approximate count of what is in scope is shown alongside.
Choose the order
An ORDER BY you write is honoured and controls the order candidates appear in. Without one, the picker shows most recently updated first.

Placeholders

The JQL scope accepts dynamic values. A placeholder is written into the scope like any other value and is substituted from the work item the field is being edited on, so one configuration behaves differently on every work item it appears on. Without them a scope is a fixed query, and a field named “Blocked by” would offer the same candidates from every work item in the project.

parent = {{issue.key}}
project = {{issue.project.key}}
assignee = {{user.accountId}}
"Team" = {{issue.customfield_12345}}
labels in ({{issue.labels}})

Every field works, system or custom, nested to any depth.

Values are quoted and escaped for you. That is why a scope which quotes its own placeholder is rejected: writing summary ~ "{{issue.summary}}" would let a work item summary rewrite the query it is substituted into, and refusing it is the rule that prevents that.

When a placeholder has no value on the current work item, the picker says which field is empty rather than showing an unexplained empty list.

The scope is a selection constraint, not an access control

Read this before relying on the scope

The scope defines what the picker offers. It does not restrict what the field can hold.

CSV import and the Jira REST API can both store a work item the picker would never have offered, because neither goes through the picker. Jira Automation’s advanced JSON edit takes the REST path too.

Use Jira’s own project and issue permissions for access control. Use the scope to keep a picker useful.

What the scope does not control

Two things are configured separately, and confusing them with the scope is the most common mistake:

Who can see what is permission mode. The scope narrows the candidate list; permission mode decides whose permissions the search runs with. Under IGNORE_USER a person can select work items they cannot browse, and the scope is what bounds that.
How many work items a field holds is decided by which of the two field types you chose. See set up the field.

Worked example

A field named “Blocked by” on an engineering project, scoped so it only offers open work items in the same project, most urgent first:

project = {{issue.project.key}} AND statusCategory != Done ORDER BY priority DESC

On a support project the same field can carry a different context with a different scope, so the two never offer each other’s work items:

project = SUPPORT AND resolution IS EMPTY ORDER BY created DESC

Permission mode, which decides whose permissions the search runs with
Set up the field
Automation and JQL, where the scope decides what a rule may write
Workflow validation
Privacy and data handling

A problem or a question? Write to support@oktul.com or open a request in the Help Center. Both reach the same service desk, so either way the request gets a reference and an SLA measuring the response.