# Oktul Work Item Selector for Jira

> A Jira Cloud custom field that offers only the work items a JQL query returns, single or multi select, with Automation, JQL functions and a workflow validator.
>
> Documentation for Oktul Work Item Selector for Jira, for Jira Cloud, by Oktul: https://oktul.com/docs/plugins/work-item-selector/

Oktul Work Item Selector for Jira adds two custom field types for picking work items. Each field
context has a JQL query, and the field offers only the work items it returns. Jira's own link
offers every work item the person can read.

| Field type | Holds |
|---|---|
| **Oktul Work Item Selector (Single Select)** | exactly one work item |
| **Oktul Work Item Selector (Multi select)** | up to 100 work items, the limit Atlassian Forge sets |

<Figure
  loading="eager"
  src="/images/docs/work-item-selector/highlight-work-item-view.77b05a5c.webp"
  alt="A Related Work Items field on a work item, holding two selected work items as cards, each with its work type, key, summary, priority, status and assignee."
  caption="Selected work items on the work item view, with the columns the field context chose."
  width={2592}
  height={1022}
/>

## What it does

- **A JQL scope per field context.** The query decides which work items the picker offers,
  and it can take placeholders such as `{{issue.key}}` and `{{user.accountId}}`, so the
  scope follows the work item and the person editing it. See [JQL scope](./jql-scope/).
- **A permission mode per field context.** `RESPECT_USER` searches with the editor's own
  Jira permissions; `IGNORE_USER` searches as the app, inside the scope. See
  [permission mode](./permission-mode/).
- **Columns on the selected work items.** One to seven of work type, key, summary,
  priority, status, assignee and custom fields. See [set up the field](./set-up-the-field/#columns).
- **Native Jira links, if you want them.** Each selection can be mirrored as a Jira link
  of a type you choose. See [Jira links](./set-up-the-field/#jira-links).
- **Automation and JQL.** An Automation action that replaces, adds to, removes from or
  clears a selection, and four JQL functions: `workItemsSelectedBy`, `workItemsSelecting`,
  `workItemsWithSelection` and `workItemsSelectedByAny`. See
  [automation and JQL](./automation-and-jql/).
- **A workflow validator.** Five rules a transition can enforce on the selection,
  including a check for circular dependencies. See [workflow validation](./workflow-validation/).

## Where the field works

- The work item view, create and transition screens.
- The Jira Service Management portal. Under `RESPECT_USER` a customer is offered their own
  requests. An anonymous visitor always gets `RESPECT_USER`.
- Everywhere else the field is a plain text box.

## How it keeps the relationships

Each selection is written to a work item property on both work items and indexed. JQL, the REST
API and Atlassian's Teamwork Graph can read the relationship without a native link. See
[how the index stays correct](./automation-and-jql/#how-the-index-stays-correct).

The app declares no external permissions, so nothing leaves your Atlassian site. See
[privacy and data handling](./privacy/).

## What it does not do

- **It is not an access control.** The JQL scope limits what the picker offers, not what a
  person can open. See [the scope is a selection constraint](./jql-scope/#the-scope-is-a-selection-constraint-not-an-access-control).
- **It is not in Automation's Edit work item field list.** No Forge field is
  ([FRGE-1108](https://ecosystem.atlassian.net/browse/FRGE-1108)), so the app ships its own
  action.
- **It is Jira Cloud only.** There is no Data Center or Server version.

## Common questions

**How is it different from a Jira issue link?**

Each field context has a JQL scope, and the field offers only the work items it returns. Jira's own link offers every work item the person can read.

**How many work items can one field hold?**

One in the Single Select field, up to 100 in the Multi select field, the limit Atlassian Forge sets.

**Can Automation set the field?**

Yes, with the app's own action, which replaces, adds to, removes from or clears a selection. No Forge field is in Automation's Edit work item field list.

**Can I search by selected work items in JQL?**

Yes, with four JQL functions: `workItemsSelectedBy`, `workItemsSelecting`, `workItemsWithSelection` and `workItemsSelectedByAny`.

**Does the JQL scope control access?**

No. It limits what the picker offers, not what a person can open.

**Does it work on the Jira Service Management portal?**

Yes. Under `RESPECT_USER` a customer is offered their own requests, and an anonymous visitor always gets `RESPECT_USER`.

## Start here

1. [Install the app](./install/) from the Atlassian Marketplace.
2. [Create a Work Item Selector field](./set-up-the-field/) and put it on a screen.
3. [Limit the field with a JQL scope](./jql-scope/) and choose its [permission mode](./permission-mode/).