Requirements

Workflow rules and app HTTP handlers can declare a requirements object that identifies the custom fields, field values, and system-wide entities that their code expects to find. For a component that is used in a project, YouTrack validates these dependencies against that project. At runtime, YouTrack exposes resolved fields and entities as aliases in the component context.

This mechanism is not available to widgets, utility modules, or custom MCP tools. It is also separate from required app settings declared in settings.json.

Supported Components

Component	Support	Details
Workflow rule	Supported	Declare `requirements` in the rule object passed to the rule constructor. This also applies to workflow rules included in an app package.
App HTTP handler	Supported	Declare `requirements` in the object assigned to `exports.httpHandler`. The requirements apply to every endpoint in the handler.
Custom MCP tool	Not supported	The object assigned to `exports.aiTool` does not process a `requirements` property.
Utility module	Not supported	A utility module is imported by another backend component and uses values passed to it by the caller.
Widget	Not supported	Widget code runs in the browser and accesses YouTrack through the Host API.

Requirement Categories

Category	Purpose	Examples
Project-wide	Identifies custom fields that must be attached to the project associated with the component, including required field values and cardinality.	Priority field with a Major value, or a multi-value Assignee field.
System-wide	Identifies entities that must exist in YouTrack independently of a specific project.	Users, groups, projects, issues, tags, saved searches, and issue link types.

Validation

For a component that is used in a project, YouTrack validates its requirements against that project. If a required field, value, or entity cannot be resolved, YouTrack reports a problem for the component and does not make it available in that project until the problem is fixed.

A global HTTP handler does not have a project context. It can use system-wide requirements to expose entity aliases, but project-wide requirements can provide field aliases only when the handler invocation has a corresponding project context.

Context Aliases

Every entry in a requirements object has an alias. By default, the alias is also used as the name of the required field, value, or entity. Set the name property when the actual name is different.

A system-wide entity is available as ctx.<alias>.
A custom field is available as ctx.<field-alias> when the context contains a project.
When the context contains an issue, a required field value is available as ctx.<field-alias>.<value-alias>, and the issue field value can also be accessed through ctx.issue.fields.<field-alias> or the actual field name.

Examples

Workflow Rule Example

The following on-change rule requires the Priority and Assignee fields, the Major priority value, and a user with the qa.lead login. The rule uses aliases from the requirements to update an issue.

          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: {}
              },
              Assignee: {
                type: entities.User.fieldType
              },
              QALead: {
                type: entities.User,
                login: 'qa.lead'
              }
            }
          });
      

HTTP Handler Example

The following issue-scoped handler declares a project field and a system-wide user requirement. Because an issue-scoped invocation has both issue and project context, the handler can use the field and value aliases as well as the user alias.

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

          exports.httpHandler = {
            endpoints: [
              {
                method: 'GET',
                path: 'required-values',
                scope: 'issue',
                handle: (ctx) => {
                  ctx.response.json({
                    priority: ctx.Priority.Major.name,
                    qaLead: ctx.QALead.login
                  });
                }
              }
            ],
            requirements: {
              Priority: {
                type: entities.EnumField.fieldType,
                Major: {}
              },
              QALead: {
                type: entities.User,
                login: 'qa.lead'
              }
            }
          };
      

Requirement Properties

Property	Required	Description
`type`	Yes	The field type or entity constructor used to resolve and validate the requirement.
`name`	No	The actual name of the field, field value, or named entity. When omitted, YouTrack uses the requirement alias as the name. Users, issues, and issue link types use their type-specific identifying properties instead.
`multi`	No	For a custom field requirement, set to `true` when the field must store multiple values. The default is `false`.

Custom Field Types

Custom field type	`type` value
Build	`entities.Build.fieldType`
Enum	`entities.EnumField.fieldType`
Group	`entities.UserGroup.fieldType`
Owned field	`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`

System-wide Entity Types

Entity	`type` value	Identifying property
User	`entities.User`	`login`
User group	`entities.UserGroup`	`name`
Project	`entities.Project`	`name`
Issue	`entities.Issue`	`id`
Tag	`entities.IssueTag`	`name`
Saved search	`entities.SavedQuery`	`name`
Issue link type	`entities.IssueLinkPrototype`	`inward` or `outward`

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

Custom Field Value Aliases

For an enum, state, owned, version, build, user, or group field requirement, each additional property represents a required value from the field's value set. The property key is the value alias. Add name when the actual value name is different from the alias.

          requirements: {
            P: {
              type: entities.EnumField.fieldType,
              name: 'Priority',
              M: {name: 'Major'},
              Normal: {}
            }
          }
      

This example exposes the field as ctx.P, the Major value as ctx.P.M, and the Normal value as ctx.P.Normal.

10 September 2026