Workflow Rules

YouTrack supports four different types of workflow rules. The rule type defines the general conditions that cause the rule to be executed.

When you write workflows in the workflow editor, you add modules to a workflow that define each rule. The editor has different templates for each rule type. You can also write custom scripts that let you organize and structure your code. Use custom scripts to define your own functions and objects and use them in other rules and workflows.

On-change Rules

A on-change rule defines the action that is performed when a change is applied to an issue. These rules replace the stateless rules that were used in older workflows.

Sample On-change Rule

This 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 changes, the issue is automatically assigned to the owner of the subsystem.

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

exports.rule = entities.Issue.onChange({
  title: workflow.i18n('Set subsystem owner as assignee for unassigned issues'),
  guard: function(ctx) {
    return !ctx.issue.fields.Assignee && ctx.issue.fields.Subsystem;
  },
  action: function(ctx) {
    var issue = ctx.issue;
    if ((issue.isReported && (issue.fields.isChanged(ctx.Subsystem) || issue.isChanged('project'))) || issue.becomesReported) {
      issue.fields.Assignee = issue.fields.Subsystem.owner;
    }
  },

  requirements: {
    Subsystem: {
      type: entities.OwnedField.fieldType
    },
    Assignee: {
      type: entities.User.fieldType
    }
  }
});

The components that define this on-change rule are as follows:

All scripts start with a list of require statements. In this rule, we declare a local variable entities and reference the entities module in the workflow API. This means that everything that is contained in this module can be accessed in this script with the entities variable.
Each script exports one rule to the exports.rule property. The rule is declared with the Issue.onChange method, which exports the script that follows the declaration as an on-change rule.

The body of the rule itself contains three properties, as follows:

Property	Description
title	An optional human-readable title. The title is only visible in the administrative interface.
guard	A function that determines the conditions for executing the rule. If the guard condition is not met, the action specified in the rule is not applied to an issue.
action	The actions that should be applied to each issue. The action is declared as a function that accepts a context as an argument. In this example, we check to see if the Subsystem field was set to a non-null value that has a non-null owner. If so, the rule sets the value of the Assignee field.
runOn	Determines which issue events trigger the on-change rule. When not specified, rules are triggered on issue update. This property is extended with the following parameters: `change` — when `true`, the rule is triggered on issue change. `removal` — when `true`, the rule is triggered when an issue is deleted. As the rule in this example is triggered when updates are applied, we don't need to specify values for this property.
requirements	The list of entities that are required for the rule to execute without errors. This property ensures that rules can be attached to projects safely. In this example, the requirements ensure that both the Subsystem and Assignee fields store the correct types and are available in the project to which the rule is attached. If either field is absent, an error is shown in the Workflows list. The rule cannot be enabled until the required fields are attached.

On-schedule Rules

An on-schedule rule defines a set of changes that are applied according to a set schedule. For example, you can periodically check for issues with specific attribute values and notify a user or a group. These rules replace the scheduled rules that were used in older workflows.

On-schedule rules are 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.

Sample On-schedule Rule

This rule executes every day at 10:00. The rule checks for unresolved issues that are assigned and contain a value in the Due Date field. If the due date is in the past, a notification is sent to the assignee.

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

exports.rule = entities.Issue.onSchedule({
  title: 'Notify an Assignee when Due Date is expired',
  search: '#Unresolved has: Assignee has: {Due Date}',
  cron: '0 0 10 * * ?',
  muteUpdateNotifications: false,
  guard: function(ctx) {
    return ctx.issue.fields.DueDate < Date.now();
  },
  action: function(ctx) {
    var issue = ctx.issue;
    issue.fields.Assignee.notify('[YouTrack] Overdue', 'Issue ' + issue.id + ' is overdue.');
  },

  requirements: {
    Assignee: {
      type: entities.User.fieldType
    },
    DueDate: {
      type: entities.Field.dateType,
      name: 'Due Date'
    }
  }
});

The components that define this on-schedule rule are as follows:

Again, the script starts with a require statement that references the entities module in the workflow API. This means that everything that is contained in this module can be accessed in this script with the entities variable.
For this rule, the exports.rule property uses the Issue.onSchedule method. This exports the script that follows the declaration as an on-schedule rule.

The body of the rule itself contains definitions for the following properties:

Property	Description
title	An optional human-readable title. The title is only visible in the administrative interface.
search	A search query that determines which issues are processed by this rule. It can be a string that uses the syntax for a standard YouTrack search query (see Search Query Reference) or a function that recalculates a search string every time the rule is triggered. When you use a function, reference it by name. For example, `search: getSearchExpression`. We strongly recommend that you make the search expression as concrete as possible, instead of adding conditions inside the action.
cron	The schedule for applying the rule, specified as a Java cron expression. In this example, the expression triggers this rule every day at 10:00 in the time zone that is set for your YouTrack server.
muteUpdateNotifications	A flag that determines whether update notifications are sent for changes that are applied by this rule. If you want to apply updates without sending notifications, set to `true`. When `true` this property also suppresses notifications for cascading changes that are applied in the same transaction. For example, when updates that are applied by the on-schedule rule trigger updates from one or more on-change rules, the entire set of changes is applied silently. The value for this property does not affect notifications that are explicitly sent, as with the .notify method that is used in this example. This property is not relevant to this example, as the rule does not apply any issue changes. Even if it were set to `true`, the email notification that is sent using the `.notify` method is still delivered.
guard	A function that determines the conditions for executing the rule. If the guard condition is not met, the action specified in the rule is not applied to an issue.
action	The actions that should be applied to each issue that matches the search condition. This action is triggered separately for each issue. The action itself is performed by the workflow user account. In this example, we use the `Assignee.notify` method to warn the current assignee that the issue is overdue.
requirements	The list of entities that are required for the rule to execute without errors. This property ensures that rules can be attached to projects safely. In this example, the requirements ensure that both the Assignee and Due Date fields store the correct types and are available in the project to which the rule is attached. If either field is absent, an error is shown in the Workflows list. The rule cannot be enabled until the required fields are attached.

Action Rules

An action rule lets you extend YouTrack with actions that can be applied as commands or accessed directly from the issue toolbar.

Sample Action Rule

This rule enables a command that automatically assigns issues to the current user. This command can be applied to one or more issues at once.

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

exports.rule = entities.Issue.action({
  title: 'Take this issue!',
  command: 'take',
  guard: function(ctx) {
    return ctx.issue.isReported;
  },
  action: function(ctx) {
    ctx.issue.fields.Assignee = ctx.currentUser;
  },

  requirements: {
    Assignee: {
      type: entities.User.fieldType
    }
  }
});

The components that define this action rule are as follows:

As usual, the script starts with a require statement that references the entities module in the workflow API.
The exports.rule property uses the Issue.action method to export the script that follows the declaration as an action rule.

The body of the rule itself contains definitions for the following properties:

Property	Description
title	A human-readable title. The title is used as the label for the command in the Apply Command dialog and the item in the Command Dialog list in the issue toolbar. If this property is not set, the command is not added to the menu.
command	The text that is used for the custom command. When this command is applied to one or more issues, the actions that are defined in this rule are executed. Commands are defined server-wide, which means that you cannot have two action rules with the same command even when these rules are attached to different projects.
guard	The condition that determines when the action rule is enabled. If the guard condition is not met, the custom command cannot be applied to an issue. The command is not suggested in the Apply Command dialog and its title is not visible in the issue toolbar.
action	The changes that should be applied to each of the issues that are selected when the command is applied. This action is executed separately for each issue. The changes are made on behalf of the user who applies the command. In this example, we simply assign all of the selected issues to the current user.
requirements	The list of entities that are required for the rule to execute without errors. This property ensures that rules can be attached to projects safely. In this example, we only require that there is an Assignee field that stores a `user` type in the projects to which the rule is attached. If this field is absent, an error is shown in the Workflows list. The rule cannot be enabled until the required field is attached.

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. The actual values are shown to the right. The following image illustrates how the list of allowed transitions for the State field changes based on the current value.

For each transition, you can add one or more actions. Additional properties for each transition determine how these actions are applied.

Transitions that use onEnter and onExit properties 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.
Transitions that use the after property perform an action after the specified time frame. These actions are executed by the workflow user account.

Sample State-machine Rule

This example shows a simplified state-machine rule. This rule defines the transitions that are allowed for the Status field.

The following transitions are defined in this rule:

From the initial Open state, the value can change to In progress. An additional transition with the name reminder includes an after property that reminds the project owner if an issue remains in the Open state for more than two days.
From In progress, the value can change to Fixed or Open. The definition for this transition includes an onEnter property. The function defined in this property assigns the issue to the user who sets the value of the field to In progress.
The final state is Fixed. There are no additional transitions that are defined for this value. Once this value is set, it cannot be changed.

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

exports.TWO_DAYS = 2 * 24 * 60 * 60 * 1000;
exports.rule = entities.Issue.stateMachine({
  title: 'Status state-machine',
  fieldName: 'Status',
  states: {
    Open: {
      initial: true,
      transitions: {
        start: {
          targetState: 'In progress'
        },

        reminder: {
          targetState: 'Open',
          after: exports.TWO_DAYS,
          action: function(ctx) {
            var issue = ctx.issue;
            issue.project.leader.notify('Reminder', 'Check out an issue ' + issue.id);
          }
        }
      }
    },
    'In progress': {
      onEnter: function(ctx) {
        ctx.issue.fields.Assignee = ctx.currentUser;
      },
      onExit: function(ctx) {
      },
      transitions: {
        fix: {
          targetState: 'Fixed'
        },
        reopen: {
          guard: function(ctx) {
            if (ctx.issue.fields.Assignee) {
              workflow.message('You cannot reopen an issue unless you unassign it first');
              return false;
            }
            return true;
          },
          targetState: 'Open'
        }
      }
    },
    Fixed: {
      transitions: {}
    }
  },

  requirements: {
    Assignee: {
      type: entities.User.fieldType
    }
  }
});

The components that define this state-machine rule are as follows:

The require statements reference the entities module and the workflow module in the workflow API.
The exports.TWO_DAYS property sets a local variable that is used to send the reminder for issues that have the Open status. This variable is assigned a value that equals 2 days in milliseconds.
The exports.rule property uses the Issue.stateMachine method to export the script that follows the declaration as a state-machine rule.

The body of the rule itself contains definitions for the following properties:

Property	Description
title	An optional human-readable title.
fieldName	The name of the custom field that is managed by the state-machine.
states	The list of field values and definitions for the transitions between them. Values that contain spaces and special characters are set in single quotes.
requirements	The list of entities that are required for the rule to execute without errors. This property ensures that rules can be attached to projects safely. In this example, we only require that there is an Assignee field that stores a `user` type in the projects to which the rule is attached. If this field is absent, an error is shown in the Workflows list. The rule cannot be enabled until the required field is attached. For a state-machine rule, you do not need to add the field that is managed by the state-machine to the requirements. This field and its values are derived from the `states` property.

Each of the values that are defined in the states property contain definitions for the following additional properties:

Property	Description
initial	A Boolean property that determines which of the values in the list is set when an issue is created. Exactly one value must set this property to `true`. For other values that are not set as the initial value, this property is optional and can be omitted.
onEnter	An optional function declaration that is called when the corresponding value is assigned to an issue. These functions behave similar to actions in other types of rules.
onExit	An optional function declaration that is called when the field value is changed from the current value to another value. These functions behave similar to actions in other types of rules.
transitions	The list of possible target values that can be set for each value in the list. In this example, we only require that there is an Assignee field that stores a `user` type in the projects to which the rule is attached. If this field is absent, an error is shown in the Workflows list. The rule cannot be enabled until the required field is attached. For a state-machine rule, you do not need to list the values that are used by fields that are managed by the state-machine in the requirements. This field and its values are derived from the `states` property.

Each of the values that are defined in the transitions property contain a name property. The name is used to set this value in a command and is also shown in the list of values for a custom field. Each transition name contains definitions for the following additional properties:

Property	Description
targetState	The actual name of the value that is set when the command specified in the `name` property is applied.
after	An optional property that sets an interval for performing an action. The action itself is specified in the `action` property.
action	An optional property for any transition that behaves similar to actions in other types of rules..
guard	An optional condition that determines when the transition is allowed. If the guard condition is not met, the value for the custom field cannot change to the value that is defined for this transition. In this example, for an issue to transition from In progress back to an Open state, the issue must be unassigned. The guard contains a function that uses the `message` method from the `workflow` module to provide feedback to the user who attempts to reopen an issue without unassigning it first.

Last modified: 8 July 2019