# Requirements

Workflow requirements let you reference custom fields and other YouTrack entities that must be available for a workflow rule to work. Before YouTrack runs the rule, it checks each declaration and makes the matching entity available in the workflow context.

> **Note: Learn How to Declare Requirements**
> To learn when and how to declare requirements, see [Requirements](requirements.html) in the JavaScript Workflow Reference.

## How Requirements Work

| Role | What YouTrack checks | What the rule can do |
| --- | --- | --- |
| Dependencies |  Checks that each required [custom field](v1-Field.html), field value, [user](v1-User.html), [user group](v1-UserGroup.html), [project](v1-Project.html), [issue](v1-Issue.html), [tag](v1-IssueTag.html), [saved search](v1-SavedQuery.html), or [issue link type](v1-IssueLinkPrototype.html) 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](v1-UserProjectCustomField.html) without specific values. | `Assignee: { type: entities.User.fieldType }` |
| Field with values |  Require an [enum field](v1-EnumField.html), [state field](v1-State.html), [version field](v1-ProjectVersion.html), [owned field](v1-OwnedField.html), or [build field](v1-Build.html) 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](v1-ProjectCustomField.html) that stores multiple values. | `FixVersions: { type: entities.ProjectVersion.fieldType, multi: true }` |

> **Warning: Keep Aliases Stable**
> Changing a requirement alias also changes the property name that you use in `ctx`. To rename a custom field in YouTrack without updating the rule, keep the alias and change the `name` property instead.

### 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](v1-User.html) | `entities.User` | `login` | The required user. |
| [UserGroup](v1-UserGroup.html) | `entities.UserGroup` | `name` | The required user group. |
| [Project](v1-Project.html) | `entities.Project` | `name` | The required project. |
| [Issue](v1-Issue.html) | `entities.Issue` | `id` | The required issue. |
| [IssueTag](v1-IssueTag.html) | `entities.IssueTag` | `name` | The required tag. |
| [SavedQuery](v1-SavedQuery.html) | `entities.SavedQuery` | `name` | The required saved search. |
| [IssueLinkPrototype](v1-IssueLinkPrototype.html) | `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](v1-UserProjectCustomField.html) 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](v1-User.html) 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](v1-PeriodProjectCustomField.html) prototype:

```JAVASCRIPT
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](v1-Requirement.html) 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.

Project-wide field:

This declaration requires an [Assignee field](v1-UserProjectCustomField.html) in every project where the workflow is attached and the rule is active.

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

Field value:

This declaration requires a [Priority field](v1-EnumField.html) and two values in that field. The values are available as `ctx.Priority.Major` and `ctx.Priority.Normal`.

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

System-wide entity:

This declaration requires a [user](v1-User.html) with the specified login and makes the user available as `ctx.QALead`.

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

Issue link type:

This declaration requires an [issue link type](v1-IssueLinkPrototype.html) with the specified outward and inward names.

```JAVASCRIPT
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](v1-Field.html) type or system entity type. This property is required.  |
| `name` |  Fields, field values, [groups](v1-UserGroup.html), [projects](v1-Project.html), [tags](v1-IssueTag.html), and [saved searches](v1-SavedQuery.html)  | The name of the field, value, or entity in YouTrack. If omitted, YouTrack uses the alias. |
| `login` | [User](v1-User.html) requirements | The login for a specific user. Used instead of the `name` property. |
| `id` | [Issue](v1-Issue.html) requirements | The ID of a specific issue, for example `SP-42`. Used instead of the `name` property. |
| `multi` | [Project custom field](v1-ProjectCustomField.html) requirements | A Boolean property. When `true`, the custom field must store multiple values. |
| `outward` | [Issue link type](v1-IssueLinkPrototype.html) requirements | The outward name of the issue link type. |
| `inward` | [Issue link type](v1-IssueLinkPrototype.html) requirements | The inward name of the issue link type. |

> **Note: Nested Field Values**
> Field values are nested inside field requirements. Each nested alias is available as a property of the field alias in `ctx`. For example, `Major: {}` under `Priority` is available as `ctx.Priority.Major`.

### 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.

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

exports.rule = entities.Issue.onChange({
  title: 'Flag unresolved release blockers',
  guard: (ctx) => ctx.issue.fields.isChanged(ctx.State) &&
    ctx.issue.fields.State.name !== 'Fixed',
  action: (ctx) => {
    ctx.issue.fields.Priority = ctx.Priority.Critical;
    workflow.message('Release blocker owner: ' + ctx.ReleaseOwner.fullName);
  },
  requirements: {
    State: {
      type: entities.State.fieldType,
      Fixed: {}
    },
    Priority: {
      type: entities.EnumField.fieldType,
      Critical: {}
    },
    ReleaseOwner: {
      type: entities.User,
      login: 'release.owner'
    }
  }
});
```

## See also

[Requirements](requirements.html) [Requirement](v1-Requirement.html) [Issue](v1-Issue.html) [User](v1-User.html) [Field](v1-Field.html)