# Workflow validation

The **Work Item Selector dependency validator** enforces rules on a field at a transition.
Add it to any transition where the selection has to satisfy something before the work item
can move.

It is configured on the workflow rather than on the field context, which is the one part of
this application that lives somewhere other than the field. The same field can therefore be
optional on one transition and mandatory on another.

## The five rules

| Rule | Blocks the transition when |
|---|---|
| **Require a selection** | The field is empty |
| **Require all statuses** | Any selected work item is outside the statuses you name |
| **Require any status** | No selected work item is in the statuses you name |
| **Allowed projects** | A selected work item belongs to a project you did not allow |
| **Prevent circular dependencies** | The selection creates a loop back to this work item |

<Aside type="note" title="Require any status passes on an empty field">
There is nothing to violate the rule when nothing is selected, so an empty field satisfies
it. Combine it with **require a selection** to make the field mandatory as well.
</Aside>

<Figure
  src="/images/docs/work-item-selector/workflow-validator-rule.webp"
  alt="The Edit Rule dialog for the Work Item Selector dependency validator, on a transition into In Review. It asks which Work Item Selector fields the rules apply to, with WIS Multi chosen, then offers a Selection section holding a Require at least one selected work item toggle, and a Status section listing the statuses every selected work item must be in. Under the statuses is the message shown when the rule blocks a transition, with the placeholders that can be used in it listed beneath."
  caption="Each rule carries its own message, and leaving a rule's list empty skips that rule rather than failing it."
  width={1752}
  height={920}
/>

## The message a person sees

Each rule has a default message, and an administrator can replace it. The defaults are:

```text title="Default messages"
Select at least one work item in "{{field.name}}" before this transition.
Every work item in "{{field.name}}" must be in one of the required statuses. {{workItem.key}} is not.
At least one work item in "{{field.name}}" must be in one of the required statuses.
Work items in "{{field.name}}" must belong to an allowed project. {{workItem.key}} does not.
This selection creates a circular dependency back to {{issue.key}}.
```

Tokens are substituted when the rule fires, and unknown tokens are dropped rather than
printed. Messages are capped at **500 characters** and truncated past that.

If your template renders empty, which happens when it is made only of tokens that are blank
for the rule that fired, `{{workItem.key}}` on *require a selection* for instance, the
default is rendered instead. A blocked transition with an empty dialog tells the person
nothing and they cannot fix the configuration that caused it.

## What the cycle check does at scale

<Aside type="caution" title="The circular dependency check fails open">
The check runs inside a synchronous transition, so it is bounded by both node count and
depth. If the graph exceeds that budget the **transition is allowed** rather than blocked,
and a warning is logged.

Refusing legitimate work is worse than missing a deep loop. If cycle prevention is a hard
requirement on a very large graph, this rule is not the control you want.
</Aside>

## The configuration screen

The screen reads the field, status and project lists from Jira directly, as the signed-in
user, so it shows exactly the fields and projects that person can already see. Each list
loads independently: one failing lookup leaves the other rules editable instead of replacing
the dialog with an error.

<Aside type="note" title="New workflow editor only">
Atlassian supports create and edit screens for validators of this kind only in the new
workflow editor. This is also the one screen in the application that is not Atlassian UI
Kit, because Forge rejects native rendering for validator configuration. Everything a person
uses day to day, the picker, the field view and the context configuration, is UI Kit.
</Aside>

## Related

- [Automation and JQL](../automation-and-jql/), which writes and reads the same selections
- [Set up the field](../set-up-the-field/)
- [JQL scope](../jql-scope/)

---

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.