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.

Last modified: 28 October 2020