# Action Rules

An action rule lets you extend YouTrack with actions that can be applied as commands or accessed directly from the Show more menu of an issue, article, comment, or attachment.

Action rules are available for the following YouTrack entities:

* Issues

* Articles

* Issue comments

* Article comments

* Issue attachments

* Article attachments

> **Note: Creating Action Rules in the Workflow Constructor**
> The Workflow Constructor currently lets you create action rules only for issues. Action rules for other entities will be supported in the Workflow Constructor in a later version of YouTrack.

Workflow Constructor:

When you create an action rule, additional settings let you specify how the rule will be triggered.

| Setting | Description |
| --- | --- |
| Action | Stores the command that is used to run the workflow rule. |
| User input | Enables the option to require additional input from the user. |
| Object type | Stores the type of object expected from the user. |
| Label | Stores the custom description for the user input dropdown and for the Apply Command dialog. |

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

JavaScript Editor:

Action rules support a specific set of properties that define how the rule is executed.

For reference on JavaScript-based action rules, see [Developer Portal](https://www.jetbrains.com.cn/en-us/help/youtrack/devportal/rule-specific-properties.html#action-rule-properties).

## Sample Action Rule

Workflow Constructor:

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.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/workflow-tutorial-action-rule.png)

This sample action 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.   |
| User input | The toggle is disabled which means that this action rule will not require any additional input from the user.   |

### 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 |
| --- | --- |
| [Remove a Tag](workflow-constructor-actions.html#remove-tag) | 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.   |
| [Update the Value in a Field](workflow-constructor-actions.html#update-value-in-field) | This action block is configured with the following settings:       * Issue: Use the current issue    * 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.   |
| [Add a Comment](workflow-constructor-actions.html#add-comment) | 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.    |

JavaScript Editor:

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.

```JAVASCRIPT
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 list of available actions in the Show more menu of the issue. If this property is not set, the list of actions shows the value from the `command` property. | | 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 Show more menu of the issue. | | 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 assign all 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. |

For samples of action rules for entities other than issues, see the [API reference for the corresponding entity](https://www.jetbrains.com.cn/en-us/help/youtrack/devportal/v1-entities.html).

To learn more about writing workflows in JavaScript, please check out the documentation in our [Developer Portal](https://www.jetbrains.com.cn/en-us/help/youtrack/devportal/Workflows-in-JavaScript.html).

## Action Rules with User Input

You can require additional data from the user who invokes the action rule. When such an action rule is triggered, a dialog prompts the user to provide their input.

You can distinguish action rules that require user input from other actions on the list by the ellipsis points `...` after the title.

![Custom action with input on the list displayed for selection.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/action-rule-with-input-list-lite.png)

When you select the option from the Show more menu, the input dialog appears.

![Action-rule input dialog in the issue list with the target project field.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/action-rule-with-input-dialog-lite.png)

You can also invoke an action rule with user input using a command. In this case, the command dialog itself prompts you for the input.

![Apply Command dialog with the action-rule target project field.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/action-rule-with-input-dialog-classic.png)

## Sample Action Rule with User Input

Workflow Constructor:

Here's a workflow rule that lets a user copy the selected issue to another project. The user selects the target project in the additional input dialog.

![A sample action rule with user input.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/workflow-constructor-action-rule-input.png)

This sample action 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, Clone issue to another project, 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 clone to project action can be applied as a command to issues when needed.   |
| User input | The toggle is enabled which means that this action rule will require additional input from the user.   |
| Object type | This action rule requires a project from the user.   |
| Label | When prompted to provide the name of the target project, the user will see a dialog with a custom label.     Label text: Select target project   |

### 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 |
| --- | --- |
| [Copy the Issue](workflow-constructor-actions.html#copy-issue) | This action block is configured with the following settings:       * Issue: Use the current issue    * Project: Use value provided by the user     This action copies the current issue to the target project selected by the user.   |

JavaScript Editor:

This rule enables a command that creates a copy of the selected issue in another project.

```JAVASCRIPT
var entities = require('v1/entities');

exports.rule = entities.Issue.action({
    title: 'Clone issue to another project',
    command: 'clone to project',
    action: function (ctx) {
        const clone = ctx.issue.copy();
        clone.project = ctx.userInput;
    },
    userInput: {
        type: entities.Project,
        description: 'Select target project'
    }
});

```

The components that define this action rule are as follows:

* 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.     This title serves as the label for the item in the list of available actions in the Show more menu of the issue and the title of the dialog that requests user input.     If this property is not set, the list of actions shows the value from the `command` property.    |
| 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.    |
| 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 copy the issue to a target project selected by the user.    |
| userInput |    The input that this action rule requires from the user.     In this example, the type of the expected object is `Project`. For the full list of object types that you can require as user input, see [Object Types Available for User Input](#available-user-input-types).     In the sample rule, we also set a custom description for the user input dropdown and for the Apply Command dialog.      The user input dropdown:     ![Action-rule input dialog in the issue list with the target project field.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/action-rule-with-input-dialog-lite.png)   The command dialog:     ![Apply Command dialog with the action-rule target project field.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/action-rule-with-input-dialog-classic.png)   > **Note:** > An action rule can only require one object from the user.    |

### Object Types Available for User Input

Here is the complete list of object types that you can require from the user in an action rule. When you set the `type` property for user input, reference the type from the `entities` module as shown below.

| Object type | API notation |
| --- | --- |
| Date and time | `entities.Field.dateTimeType` |
| Date | `entities.Field.dateType` |
| Integer | `entities.Field.integerType` |
| Float | `entities.Field.floatType` |
| Period | `entities.Field.periodType` |
| String | `entities.Field.stringType` or `'string'` |
| Build | `entities.Build` |
| Enum field | `entities.EnumField` |
| Issue | `entities.Issue` |
| Issue tag | `entities.IssueTag` |
| Owned field | `entities.OwnedField` |
| Project | `entities.Project` |
| Project version | `entities.ProjectVersion` |
| State | `entities.State` |
| User | `entities.User` |
| User group | `entities.UserGroup` |

To learn more about working with different field types in action rules, please refer to the documentation in our [developer portal](https://www.jetbrains.com.cn/en-us/help/youtrack/devportal/action-rules.html#sample-action-rule).