YouTrack Standalone 2017.3 Help

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

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

float

entities.Field.floatType

integer

entities.Field.integerType

string

entities.Field.stringType

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

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.

Last modified: 7 March 2019