Workflow Rules
YouTrack provides three different types of workflow rules. The rule type defines the general conditions that cause the rule to be executed.
Stateless Rules
A stateless rule defines the action to be performed when a change is applied to an issue. The when statement defines the initial guard condition that must be met for the rule to be executed.
A stateless rule is executed by the user who applies the change that matches the guard condition.
ExampleThis rule performs the following actions when a change is applied to an issue:
YouTrack checks for a change to the value in the Subsystem field.
If the value in the Subsystem changed, the issue is automatically assigned to the owner of the subsystem.
rule Set Assignee to a Subsystem Owner
when issue.Subsystem.changed {
issue.Assignee = issue.Subsystem.owner;
}Scheduled Rules
A scheduled rule defines a set of changes that are applied according to a time-based guard condition. For example, you can periodically check for issues with specific attribute values and notify a user or a group.
A scheduled rule is executed by a special workflow user. This is a system user account that is granted a full set of permissions. The permissions for this account cannot be modified. The workflow user account is not included in the license restrictions and is not displayed in the users list.
The guard conditions that you can use in a scheduled rule are limited. You can only use queries that are optimized by the database. These include queries that reference specific fields (for example, issue.Priority == {Critical} or issue.Due Date > now). A guard condition that uses a method or operation (for example, issue.isResolved()) requires significant system resources to process. Guard conditions that contain methods or operations in the expression are not supported.
This rule defines a schedule for the following periodic action:
- Each day at 08:00, YouTrack checks issues that contain a value in the Due date field. If the issue is due in fewer than two days, a notification is sent to the assignee. The notification is formatted as follows:
Subject line
Issue is due in less than two days
Message body
You have less than two days remaining to resolve the following issue: <issueID>
schedule rule Check for Due date and notify assignee
daily at 08 : 00 : 00 [issue.Due date <= (now + 2 days)] {
issue.Assignee.notify("Issue is due in less than two days", "You have less than two days remaining to resolve the following issue:" + issue.getId());
}The schedule uses the date constant 08 : 00 : 00, which uses the time zone setting for your YouTrack server. The issue.Due date references a custom field that stores the date and time as 12:00 UTC. If, for example, your office is in California (UTC-7) and you want your users to be notified for all issues that are due in less than two days, you need to offset the due date by seven hours. For more information, see Working with Dates and Times.
State-machine Rules
A state-machine rule regulates the transitions from one value to another for a custom field. You can apply a state-machine rule to any custom field. However, the most common use case for a state-machine rule is to regulate transitions between values for the State field or another custom field that stores a state type.
When a state-machine rule is applied to a project, the options that are shown in the drop-down list for the field are restricted to the transitions that are defined in the state-machine rule for the current state. Custom fields that are regulated by a state-machine rule are marked with a Workflow-driven field icon. The action that is defined for each value in the state-machine rule is displayed in the drop-down list, followed by the actual value in parenthesis. The following image illustrates how the list of allowed transitions for the State field changes based on the current value.
State-machine rules use two types of conditional statements.
The
enter,exit, andonstatements perform an action when the value for the field is set. These actions are executed by the user who changes the value of the field.The
instatement performs an action after the specified time frame. These actions are executed by the workflow user account.
This rule defines the transitions that are allowed for the State field. This field is referenced with the for field declaration in the first line.
The
initial statedeclaration sets the value that is assigned to new issues. Here, an issue starts with the Submitted state.- The block statement that follows the initial state defines which transitions are allowed from the original value. These transitions are defined with one or more conditional statements. These statements let you apply changes to an issue when the value for this field changes to the specified value. You can even define optional conditions that must be met to apply the specified changes. For more information about the statements that are used in this block, see Rule-specific Statements.
In this example, the value can only transition from Submitted to Open.
- Following the initial state, you see a series of
statedeclarations. These declarations let you specify the transitions that are allowed for each value in the field. The transitions are defined in the block statements that follow the declaration.The following transitions are defined in this example:
From Open, the value can change to Fixed, Duplicate, or Can't Reproduce.
From Fixed, the value can change to Verified or Reopened. When the value changes to Fixed, the value of the Subsystem field is set to Testing.
From Duplicate, the value can only change to Reopened.
From Can't Reproduce, the value can only change to Reopened.
From Verified, there are no transitions defined for this value. Once this value is set, it cannot be changed.
From Reopened, the value can only change to Fixed.
In most of the block statements that follow the state declarations contain the following components:
An
onstatement that defines the action that is associated with this value. This action creates an alias for the field that is used in commands to set this value. The action is also displayed in the drop-down list for the custom field.An optional guard condition for applying additional changes to an issue when the field is set to this value. By default, the changes are always applied. This is represented by the
[always]placeholder in the editor. Here, you can insert a Boolean expression that applies the changes if it resolves to the valuetrue.A
doelement that introduces an optional block statement. This block statement is represented by the<define statements>placeholder in the editor. Here, you can define a set of changes that are applied to an issue and the conditions that must be met for the changes to be applied. Basically, you can insert the same instructions that are used in stateless and scheduled rules.A
transit todeclaration that specifies the value to set for the field when the action that is specified in theonstatement is applied to an issue. When you specify a value for thetransit todeclaration, a newstatedeclaration for the specified value is added to the state-machine rule.
The Fixed value uses an enter statement. This statement automatically applies the specified changes to an issue when the value for this field is set to Fixed.
statemachine State lifecycle for field State {
initial state Submitted {
on Open[always] do {<define statements>} transit to Open
}
state Open {
on Fix[always] do {<define statements>} transit to Fixed
on Duplicate[always] do {<define statements>} transit to Duplicate
on Can't reproduce[always] do {<define statements>} transit to Can't Reproduce
}
state Fixed {
enter {
issue.Subsystem = {Testing};
}
on Verify[always] do {<define statements>} transit to Verified
on Reopen[always] do {<define statements>} transit to Reopened
}
state Duplicate {
on Reopen[always] do {<define statements>} transit to Reopened
}
state Can't Reproduce {
on Reopen[always] do {<define statements>} transit to Reopened
}
state Verified {
}
state Reopened {
on Fix[always] do {<define statements>} transit to Fixed
}
}