# 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

<Steps
  items={[
    {
      title: 'Open Settings, the gear icon at the top right, then Work items',
    },
    {
      title: 'Select Fields in the left menu',
    },
    {
      title: 'Find your field, then select the three dots beside it and Contexts and default values',
    },
    {
      title: 'Select Edit custom field config',
    },
    {
      title: 'Write the JQL',
      body: '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.',
    },
    {
      title: 'Choose the order',
      body: '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.

```text title="JQL"
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

<Aside type="caution" title="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.
</Aside>

## 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](../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](../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:

```text title="JQL"
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:

```text title="JQL"
project = SUPPORT AND resolution IS EMPTY ORDER BY created DESC
```

## Related

- [Permission mode](../permission-mode/), which decides whose permissions the search runs with
- [Set up the field](../set-up-the-field/)
- [Automation and JQL](../automation-and-jql/), where the scope decides what a rule may write
- [Workflow validation](../workflow-validation/)
- [Privacy and data handling](../privacy/)

---

A problem or a question? Write to [support@oktul.com](mailto:support@oktul.com) or open a request in the [Help Center](https://oktul.atlassian.net/servicedesk/customer/portals). Both reach the same service desk, so either way the request gets a reference and an SLA measuring the response.