Requirements

The requirements object serves two purposes.

First, it functions as a safety net. It specifies the set of entities that must exist for a rule to work as expected. Whenever one or more rule requirements are not met, corresponding errors are shown in the workflow administration UI. The rule is not executed until all the problems are fixed.
Second, it functions as a reference. Each entity in the requirements is plugged into the context object, so you can reference entities from inside your context-dependent functions (like an action function).

There are two types of requirements: project-wide and system-wide.

Project-wide requirements contain a list of custom fields to be attached to each project which uses the rule as well as the required values from the sets of values for each custom field.
System-wide requirements contain a list of other entities that must be available in YouTrack. This includes users, groups, projects, issues, tags, saved searches, and issue link types.

Common Usage

Use requirements to describe the entities that your rule expects to find, then use the requirement aliases in the rule body. If the project that uses the rule does not have a matching field, value, or entity, YouTrack reports the problem in the workflow administration UI before the rule runs.

The following on-change rule requires a Priority field with the Major and Normal values, and a user with the qa.lead login. When an issue becomes unresolved, the rule changes the issue priority to Major and assigns the issue to the required user.

      const entities = require('@jetbrains/youtrack-scripting-api/entities');

      exports.rule = entities.Issue.onChange({
        title: 'Escalate reopened issues',
        guard: (ctx) => ctx.issue.becomesUnresolved,
        action: (ctx) => {
          ctx.issue.fields.Priority = ctx.Priority.Major;
          ctx.issue.fields.Assignee = ctx.QALead;
        },
        requirements: {
          Priority: {
            type: entities.EnumField.fieldType,
            Major: {},
            Normal: {}
          },
          Assignee: {
            type: entities.User.fieldType
          },
          QALead: {
            type: entities.User,
            login: 'qa.lead'
          }
        }
      });

In this example, Priority, Assignee, and QALead are aliases. For the Priority and Assignee fields, the aliases match the actual field names, so the name property is omitted. The Major and Normal aliases represent required values in the Priority field. In the action, ctx.Priority.Major references the required Major value, and ctx.QALead references the required user.

Example

Here's an example of a requirements statement that includes the definitions for a custom field and the values that are required for this field, followed by a list of system-wide requirements.

      requirements: {
        P: {
          type: entities.EnumField.fieldType,
          name: 'Priority',
          M: { name: 'Major' },
          Normal: {}
        },
        ImportantPerson: {
          type: entities.User,
          login: 'superadmin'
        },
        OurTeam: {
          type: entities.UserGroup,
          name: 'integration-team'
        },
        Int: {
          type: entities.Project,
          name: 'Integration'
        },
        Ref: {
          type: entities.Issue,
          id: 'INT-483'
        },
        ToBeReleased: {
          type: entities.IssueTag,
          name: 'To be released'
        },
        Untested: {
          type: entities.SavedQuery,
          name: 'Not tested yet'
        },
        Depend: {
          type: entities.IssueLinkPrototype,
          outward: 'is required for',
          inward: 'depends on'
        }
      }

Properties

Every entity that is specified in the requirements statement is identified by an alias. In the example above, the Priority field is assigned the alias P. When you assign an alias to an entity in the requirements, you use the alias to reference the entity in context. For example, the Priority field can be referenced as ctx.P, issue.fields.P, or issue.fields.Priority.

Each requirement that is specified in the requirements statement has the following properties:

Property

Description

type

The data type of the entity. This property is required. Here is the complete list of types for custom fields:

build	entities.Build.fieldType
enum	entities.EnumField.fieldType
group	entities.UserGroup.fieldType
ownedField	entities.OwnedField.fieldType
state	entities.State.fieldType
user	entities.User.fieldType
version	entities.ProjectVersion.fieldType
date	entities.Field.dateType
date and time	entities.Field.dateTimeType
float	entities.Field.floatType
integer	entities.Field.integerType
string	entities.Field.stringType
text	entities.Field.textType
period	entities.Field.periodType

The following types are used for system-wide entities:

users	entities.user
groups	entities.UserGroup
projects	entities.Project
issues	entities.Issue
tags	entities.IssueTag
saved searches	entities.SavedQuery
issue links	entities.IssueLinkPrototype

Project teams are represented as user groups. To specify a project team in requirements, use entities.UserGroup and set the name property to the project team name.

name

The name of the entity. This property is optional. If a name is not set, it is considered to be equal to the alias.

For specific system-wide entities, this property is ignored entirely.

Users are identified by the login property.
Issues are identified by the id property.
Issue links are identified by the inward or outward properties.

In addition, there are properties that are only available for specific entity types. These properties are listed below:

Entity	Property	Description
custom fields	value	Any property that is defined for an entity that is not one of the known properties listed above is considered to be the requirement for a value in the set of values for a custom field. Each `value` property also has an optional `name` property. In the example above, the value `Major` in the `Priority` custom field can be referenced as `ctx.P.M` or `ctx.P.Major`. The value of the custom field can be changed to `Major` with `issue.fields.P = ctx.P.M;`.
custom fields	multi	A Boolean property. When `true`, the custom field must store multiple values.
issue links	outward	The outward name of the issue link type.
issue links	inward	The inward name of the issue link type.
users	login	The login for a specific user. Used instead of the `name` property.
issues	id	The ID of a specific issue. Used instead of the `name` property.

14 May 2026