Developer Portal for YouTrack and Hub 2021.4 Help

Action Rules

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

When you create an action rule, an additional setting lets you specify how the rule is triggered using a command.

Setting

Description

Action

Stores the command that is used to run the workflow rule.

You then define the initial criteria for updating issues in the Prerequisites section, then specify which updates to apply in the Actions section.

Sample Action Rule

Here's a workflow rule that lets a user postpone the due date for a purchase request that is overdue and add a comment automatically.

A sample action rule in the workflow constructor.

This sample on-schedule rule behaves in the following way:

Rule Triggers

The rule is configured to be triggered in the following situations:

Setting

Description

Rule name

The name that is assigned to the rule, Postpone overdue requests, is shown in the action menu for single issues. When a user selects this option from the menu, the actions that are described in this rule are applied to the selected issue.

Action

The postpone action can be applied as a command to issues when needed.

Rule Prerequisites

This rule doesn't have any additional preconditions. The option to apply the custom action is available in any issue that belongs to a project where the workflow rule is active.

Rule Actions

Whenever a user applies the custom action to an issue, the workflow automatically applies the following changes:

Action

Description

This action block is configured with the following settings:

  • Issue: Use the current issue

  • Tag: overdue

This removes the overdue tag from the current issue.

This action block is configured with the following settings:

  • Field: Due Date

  • Mode: set

  • To: the rule is triggered

    The setting that stores the time offset from the specified date is set to +1w.

This action updates the value for the Due Date to a date one week from the current date.

This action block is configured with the following settings:

  • Issue: Use the current issue

  • Comment text: We need more time to investigate.

  • Author: Use the current user

This action adds a comment with the specified text to the current issue.

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.

const entities = require('@jetbrains/youtrack-scripting-api/entities'); exports.rule = entities.Issue.action({ title: 'Take this issue!', command: 'take', guard: (ctx) => { return ctx.issue.isReported; }, action: (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: 17 November 2021