---
schema: rendered-html/v1
title: "Action Rules | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/action-rules.html
generated_at: 2026-06-11T14:44:09.945095+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- JavaScript Workflow Quick Start Guide
- Create a Workflow
- Edit a Workflow
- Workflow Rule Types
- On-change Rules
- On-schedule Rules
- State-machine Rules
- [Action Rules](action-rules.html)
- SLA Rules
- Custom Scripts
- Transactions
- Use Cases for Workflows
- Web-based Workflow Editor
- Using an External Code Editor
- Default Workflows
- Custom Workflow Repository
- JavaScript Workflow Reference
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Hub REST API

1. YouTrack Workflows
2. Workflow Rule Types
3. [Action Rules](#0)

# Action Rules﻿

Last modified: 13 May 2026

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

For YouTrack versions 2024.1 and older, only issue-based action rules are available. Starting from YouTrack version 2024.2, you can apply action rules to the following YouTrack entities:

- Issues
- Articles
- Issue comments
- Article comments
- Issue attachments
- Article attachments

## 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 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 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. |

  >

For samples of action rules for entities other than issues, see the API reference for the corresponding entity.

## Sample Action Rule 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](https://crawler.prototype.prolicht.digital/l/B2Y4Si)

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

![User input for an action rule](https://crawler.prototype.prolicht.digital/l/lApovK)

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.

![User input for an action rule from the command dialog](https://crawler.prototype.prolicht.digital/l/V0jzqE)

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

```
const entities = require('@jetbrains/youtrack-scripting-api/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](/help/youtrack/devportal/action-rules.html#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: User input for an action rule The command dialog: User input for an action rule 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` |

For example, to let the user select a value from an enum field, set the input type to `entities.EnumField`. In this case, `ctx.userInput` contains the selected enum value, so you can assign it directly to a compatible field or read its properties, such as `name`.

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

exports.rule = entities.Issue.action({
  title: 'Update type',
  command: 'update type',
  action: function(ctx) {
    ctx.issue.fields.Type = ctx.userInput;
  },
  userInput: {
    type: entities.EnumField,
    description: 'Select a type'
  },
  requirements: {
    Type: {
      type: entities.EnumField.fieldType
    }
  }
});
```

- [Action Rules](/help/youtrack/devportal/action-rules.html)
- [Sample Action Rule](/help/youtrack/devportal/action-rules.html#sample-action-rule)
- [Sample Action Rule with User Input](/help/youtrack/devportal/action-rules.html#sample-action-rule-with-user-input)

State-machine RulesSLA Rules

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.

![](https://bat.bing.com/action/0?ti=5220035&tm=gtm002&Ver=2&mid=9ed87c9e-b284-453b-999e-cf2830ba487f&bo=4&sid=452929b065a111f19a7fe7356f74a419&vid=aa3122f0648711f1a10d6d095e10fd87&vids=0&msclkid=N&pi=918639831&lg=en-US&sw=1920&sh=1080&sc=24&tl=Action%20Rules%20%7C%20Developer%20Portal%20for%20YouTrack%20and%20Hub%20Documentation&p=https%3A%2F%2Fwww.jetbrains.com%2Fhelp%2Fyoutrack%2Fdevportal%2Faction-rules.html&r=&lt=695&pt=1781189047290,52,52,,,1,1,1,1,1,,2,29,31,56,264,264,265,694,694,695&pn=0,0&evt=pageLoad&sv=2&asc=G&cdb=AQAS&rn=628366)

![](https://crawler.prototype.prolicht.digital/l/KCDU1A)![](https://crawler.prototype.prolicht.digital/l/ug0O9P)
