---
schema: rendered-html/v1
title: "Requirements | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/requirements.html
generated_at: 2026-06-11T15:08:25.742488+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- JavaScript Workflow Quick Start Guide
- Create a Workflow
- Edit a Workflow
- Workflow Rule Types
- Transactions
- Use Cases for Workflows
- Web-based Workflow Editor
- Using an External Code Editor
- Default Workflows
- Custom Workflow Repository
- JavaScript Workflow Reference
- Rule-specific Properties
- Context
- [Requirements](requirements.html)
- Using the Workflow API
- Building Integrations with Slack
- Using REST API Methods in JavaScript Workflows
- Working with Dates and Times
- Working with Periods
- Localized Workflow Messages
- Troubleshooting Workflows
- [Remote Debugger](jetbrains__com__help__youtrack__devportal__remote-debugger.md)
- YouTrack Workflow API
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Hub REST API

1. YouTrack Workflows
2. JavaScript Workflow Reference
3. [Requirements](#0)

# Requirements﻿

Last modified: 14 May 2026

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;`. |
| multi | A Boolean property. When `true`, the custom field must store multiple values. |
| issue links | outward | The outward name of the issue link type. |
| 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. |

- [Requirements](/help/youtrack/devportal/requirements.html)
- [Common Usage](/help/youtrack/devportal/requirements.html#requirements-common-usage)
- [Example](/help/youtrack/devportal/requirements.html#requirements-example)
- [Properties](/help/youtrack/devportal/requirements.html#requirements-properties)

ContextUsing the Workflow API

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.

![](https://bat.bing.com/action/0?ti=5220035&tm=gtm002&Ver=2&mid=6714ae9f-908f-4409-a97c-9884239de971&bo=4&sid=452929b065a111f19a7fe7356f74a419&vid=aa3122f0648711f1a10d6d095e10fd87&vids=0&msclkid=N&pi=918639831&lg=en-US&sw=1920&sh=1080&sc=24&tl=Requirements%20%7C%20Developer%20Portal%20for%20YouTrack%20and%20Hub%20Documentation&p=https%3A%2F%2Fwww.jetbrains.com%2Fhelp%2Fyoutrack%2Fdevportal%2Frequirements.html&r=&lt=872&pt=1781190503000,54,54,,,3,3,3,3,3,,4,50,50,58,268,268,268,871,872,872&pn=0,0&evt=pageLoad&sv=2&asc=G&cdb=AQAS&rn=914634)
