Requirements | YouTrack Developer Portal Documentation

How Requirements Work

Role	What YouTrack checks	What the rule can do
Dependencies	Checks that each required custom field, field value, user, user group, project, issue, tag, saved search, or issue link type is available to the rule.	YouTrack reports missing requirements on the workflow administration pages and does not run the rule until all requirements are available.
References	Makes each matching entity available under its requirement alias in the `context` object.	Use aliases such as `ctx.Priority.Major`, `ctx.Assignee`, and `ctx.QALead` instead of repeating names in the rule code.

Requirement Categories

Project-Wide Requirements

Use project-wide requirements to list custom fields that must be attached to every project where the workflow is attached and the rule is active. You can also require specific field values that the rule reads, assigns, or compares.

Requirement pattern	Usage	Example declaration
Field type only	Require a user field without specific values.	`Assignee: { type: entities.User.fieldType }`
Field with values	Require an enum field, state field, version field, owned field, or build field with specific values.	`Priority: { type: entities.EnumField.fieldType, Major: {} }`
Alias with explicit name	Map a stable JavaScript alias to a custom field name that can be longer, localized, or renamed.	`P: { type: entities.EnumField.fieldType, name: 'Priority' }`
Multi-value field	Require a custom field that stores multiple values.	`FixVersions: { type: entities.ProjectVersion.fieldType, multi: true }`

System-Wide Requirements

Use system-wide requirements to list entities that belong to the YouTrack instance rather than a specific project. YouTrack makes each matching entity available in the workflow context.

Entity	API type	Identifier property	Value in the context
User	`entities.User`	`login`	The required user.
UserGroup	`entities.UserGroup`	`name`	The required user group.
Project	`entities.Project`	`name`	The required project.
Issue	`entities.Issue`	`id`	The required issue.
IssueTag	`entities.IssueTag`	`name`	The required tag.
SavedQuery	`entities.SavedQuery`	`name`	The required saved search.
IssueLinkPrototype	`entities.IssueLinkPrototype`	`outward` or `inward`	The required issue link type.

Field Values, Field Types, and Field Prototypes

These expressions refer to different parts of a custom field and are not interchangeable:

Expression	Represents	Typical use
`ctx.issue.fields.Assignee`	The value stored in the Assignee field for the current issue.	Read or update the issue's field value.
`entities.User.fieldType`	The type of a custom field that stores users.	Require a project-wide custom field in `requirements`.
`ctx.Assignee`	The custom field prototype that matches the `Assignee` requirement.	Pass the field itself to API methods or call methods defined on its project-field type.
`entities.User`	The User entity type.	Require a specific system-wide user, for example by `login`.

You can read the value of an attached field through ctx.issue.fields without adding the field to requirements. Add the field when YouTrack must check that it exists, when the rule references field values by alias, or when the field prototype must be available through ctx.

In this example, ctx.issue.fields.PeriodField is the value stored in the issue, while ctx.PeriodField is the PeriodProjectCustomField prototype:

action: (ctx) => { const periodValue = ctx.issue.fields.PeriodField; const formattedValue = ctx.PeriodField.getValuePresentation(ctx.issue); // Use periodValue or formattedValue. }, requirements: { PeriodField: { type: entities.Field.periodType } }

Requirement Properties and Examples

Common Requirement Patterns

All requirement declarations follow the same structure for project-wide fields, field values, and system-wide entities. The type property identifies the field or entity type. Additional properties identify the specific field, value, or entity.

This declaration requires an Assignee field in every project where the workflow is attached and the rule is active.

requirements: { Assignee: { type: entities.User.fieldType } }

This declaration requires a Priority field and two values in that field. The values are available as ctx.Priority.Major and ctx.Priority.Normal.

requirements: { Priority: { type: entities.EnumField.fieldType, Major: {}, Normal: {} } }

This declaration requires a user with the specified login and makes the user available as ctx.QALead.

requirements: { QALead: { type: entities.User, login: 'qa.lead' } }

This declaration requires an issue link type with the specified outward and inward names.

requirements: { Depends: { type: entities.IssueLinkPrototype, outward: 'is required for', inward: 'depends on' } }

Requirement Properties

Each entry in the requirements object has an alias and a set of properties. The type property is required. The available properties depend on the entity type.

Property	Applies to	Description
`type`	Every requirement	The field type or system entity type. This property is required.
`name`	Fields, field values, groups, projects, tags, and saved searches	The name of the field, value, or entity in YouTrack. If omitted, YouTrack uses the alias.
`login`	User requirements	The login for a specific user. Used instead of the `name` property.
`id`	Issue requirements	The ID of a specific issue, for example `SP-42`. Used instead of the `name` property.
`multi`	Project custom field requirements	A Boolean property. When `true`, the custom field must store multiple values.
`outward`	Issue link type requirements	The outward name of the issue link type.
`inward`	Issue link type requirements	The inward name of the issue link type.

Complete Workflow Rule Example

This on-change rule combines project-wide and system-wide requirements. When the issue state changes to a value other than Fixed, the rule sets the priority to Critical and displays a message that names the release owner.