Rule-specific Properties
All scripts that set a value for the exports.rule property are interpreted as workflow rules. Each type of rule supports a specific set of properties that define how the rule is executed.
Each module can only store a single object for the exports.rule property. When a script contains more than one definition for this property, the last definition in the script is exported. For example, if a script sets the exports.rule property to entities.Issue.onChange (the declaration for an on-change rule) then later sets this property to entities.Issue.action, the script is interpreted as an action rule. All of the properties that are set for the on-change rule are ignored.
This page lists all of the properties for each workflow rule by type. For examples that show you how these properties are used in actual rules, see Workflow Rule Types.
On-change Rule Properties
For YouTrack versions 2024.1 and older, only issue-based on-change rules are available. Starting from YouTrack version 2024.2, on-change rules are available for issues and articles.
On-change Rules for Issues
The Issue.onChange method exports an object that is interpreted as an on-change rule. On-change rules support the following properties:
Property | Description |
|---|---|
title | An optional human-readable title of the rule. 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. |
runOn | Determines which issue events trigger the on-change rule. When not specified, rules are triggered on issue update. |
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. |
The runOn property supports the following extended properties:
Property | Description |
|---|---|
change | An extension of the |
removal | An extension of the |
On-change Rules for Articles
The Article.onChange method exports an object that is interpreted as an on-change rule. On-change rules support the following properties:
Property | Description |
|---|---|
title | An optional human-readable title of the rule. 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 article. |
action | The actions that should be applied to the article. The action is declared as a function that accepts a context as an argument. |
runOn | Determines which article events trigger the on-change rule. When not specified, rules are triggered on article update. |
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. |
The runOn property supports the following extended properties:
Property | Description |
|---|---|
change | An extension of the |
removal | An extension of the |
On-schedule Rule Properties
The Issue.onSchedule method exports an object that is interpreted as an on-schedule rule. On-schedule rules support 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 https://www.jetbrains.com.cn/en-us/help/youtrack/cloud/?Search-and-Command-Attributes) 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, |
cron | The schedule for applying the rule, specified as a Java cron expression. |
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. |
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 When The value for this property does not affect notifications that are explicitly sent with the .notify method. |
modifyUpdatedProperties | A flag that determines whether the changes applied by this rule will update the value for the Available since 2023.1 |
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. |
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. |
Action Rule Properties
For YouTrack versions 2024.1 and older, only issue-based action rules are available. Starting from YouTrack version 2024.2, action rules are available for the following entities:
Action Rules for Issues
The Issue.action method exports an object that is interpreted as an action rule. Action rules for issues support 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 Show more menu of the issue. 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 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. | ||||||
userInput | The input from the user that the action requires. This rule property defines the type of the expected object and the properties of the action input dialog.
| ||||||
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. |
Action Rules for Articles
The Article.action method exports an object that is interpreted as an action rule. Action rules support the following properties:
Property | Description | ||||||
|---|---|---|---|---|---|---|---|
title | A human-readable title. The action appears on the list of actions in the Show more menu of the article under this title. If this property is not set, the action is not added to the menu. | ||||||
guard | The condition that determines when the action rule is enabled. If the guard condition is not met, the action cannot be applied to an article. The action is not visible in the Show more menu. | ||||||
action | The changes that should be applied to the article. | ||||||
userInput | The input from the user that the action requires. This rule property defines the type of the expected object and the properties of the action input dialog.
| ||||||
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. |
Action Rules for Issue Comments
The IssueComment.action method exports an object that is interpreted as an action rule. Action rules support the following properties:
Property | Description | ||||||
|---|---|---|---|---|---|---|---|
title | A human-readable title. The action appears on the list of actions in the Show more menu of the issue comment under this title. If this property is not set, the action is not added to the menu. | ||||||
guard | The condition that determines when the action rule is enabled. If the guard condition is not met, the action cannot be applied to an issue comment. The action is not visible in the Show more menu. | ||||||
action | The changes that should be applied to the issue comment. | ||||||
userInput | The input from the user that the action requires. This rule property defines the type of the expected object and the properties of the action input dialog.
| ||||||
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. |
Action Rules for Article Comments
The ArticleComment.action method exports an object that is interpreted as an action rule. Action rules support the following properties:
Property | Description | ||||||
|---|---|---|---|---|---|---|---|
title | A human-readable title. The action appears on the list of actions in the Show more menu of the article comment under this title. If this property is not set, the action is not added to the menu. | ||||||
guard | The condition that determines when the action rule is enabled. If the guard condition is not met, the action cannot be applied to an article comment. The action is not visible in the Show more menu. | ||||||
action | The changes that should be applied to the article comment. | ||||||
userInput | The input from the user that the action requires. This rule property defines the type of the expected object and the properties of the action input dialog.
| ||||||
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. |
Action Rules for Issue Attachments
The IssueAttachment.action method exports an object that is interpreted as an action rule. Action rules support the following properties:
Property | Description | ||||||
|---|---|---|---|---|---|---|---|
title | A human-readable title. The action appears on the list of actions in the Show more menu of the issue attachment under this title. If this property is not set, the action is not added to the menu. | ||||||
guard | The condition that determines when the action rule is enabled. If the guard condition is not met, the action cannot be applied to an issue attachment. The action is not visible in the Show more menu. | ||||||
action | The changes that should be applied to the issue attachment. | ||||||
userInput | The input from the user that the action requires. This rule property defines the type of the expected object and the properties of the action input dialog.
| ||||||
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. |
Action Rules for Article Attachments
The ArticleAttachment.action method exports an object that is interpreted as an action rule. Action rules support the following properties:
Property | Description | ||||||
|---|---|---|---|---|---|---|---|
title | A human-readable title. The action appears on the list of actions in the Show more menu of the article attachment under this title. If this property is not set, the action is not added to the menu. | ||||||
guard | The condition that determines when the action rule is enabled. If the guard condition is not met, the action cannot be applied to an article attachment. The action is not visible in the Show more menu. | ||||||
action | The changes that should be applied to the article attachment. | ||||||
userInput | The input from the user that the action requires. This rule property defines the type of the expected object and the properties of the action input dialog.
| ||||||
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. |
State-machine Rule Properties
The Issue.stateMachine method exports an object that is interpreted as a state-machine rule. State-machine rules support the following base properties:
Property | Description |
|---|---|
title | An optional human-readable title. |
fieldName | The name of the custom field that is managed by the state-machine. The template for state-machine rules per issue type uses the alias |
stateFieldName | An alias for |
typeFieldName | This optional property identifies the enumerated custom field that dictates which state-machine per issue type is applied to the managed field. This property is only used to script state-machines per issue type. For basic state-machine rules, skip this property. |
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. In the template for state-machine rules per issue type, this property is replaced with the alias |
defaultMachine | An alias for |
alternativeMachines | For state-machines per issue type, this property defines the collection of field values and definitions for the transitions between them for each specified value in the field that regulates which state-machine applies to the managed field. |
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. 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 |
Each of the values that are defined in the states property contains definitions for an additional set of properties.
In a state-machine per issue type, these properties are specified for the defaultMachine, which is an alias of the states property, as well as each of the values that are listed for the alternativeMachines property.
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 |
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. 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 |
Each of the values that are defined in the transitions property contains 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 |
after | An optional property that sets an interval for performing an action. The action itself is specified in the |
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. |
SLA Rule Properties
The Issue.sla method exports an object that is interpreted as an SLA policy rule. SLA rules support the following properties:
Property | Description |
|---|---|
title | A human-readable title. This title is visible in the list of SLA rules in the helpdesk project settings. |
guard | The condition that determines when the SLA rule is applied to a ticket. |
onEnter | The changes that should be applied to the ticket when the SLA policy starts applying to it. For example, this function initialises the timers according to the SLA settings. The ticket is updated on behalf of the user who made updates after which the SLA began applying to the ticket. |
action | The changes that should be applied to the ticket. For example, this function can pause the timers or resume them when there is a new comment from the customer. The ticket is updated on behalf of the user who made updates after which this function was called. |
onBreach | The changes that should be applied to the ticket when one of the SLA goals is breached. In the The special workflow user is considered to be the actor for triggering this function. This is a system user account that is granted a full set of permissions. |
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. |