# 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](Workflow-Rules.html).

## 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 `runOn` property that determines whether changes are applied on issue change. When `true`, the rule is triggered on issue change. |
| removal | An extension of the `runOn` property that determines whether changes are applied when an issue is logically deleted. When `true`, the rule is triggered when an issue is logically deleted. |

### On-change Rules for Articles

> **Note:**
> Available since YouTrack version 2024.2.

> **Note:**
> When you create a new on-change rule, the rule template is automatically built with reference to the `Issue.onChange` method. To get your rule triggered on changes applied to articles, edit the rule script to refer to the `Article.onChange` method instead.

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 `runOn` property that determines whether changes are applied on article change. When `true`, the rule is triggered on article change. |
| removal | An extension of the `runOn` property that determines whether changes are applied when an article is logically deleted. When `true`, the rule is triggered when an article is logically deleted. |

## 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](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, `search: getSearchExpression`. We strongly recommend that you make the search expression as concrete as possible, instead of adding conditions inside the action. |
| cron | The schedule for applying the rule, specified as a [Java cron expression](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html).     > **Note: Cron Expression Format** > YouTrack evaluates cron expressions using the Quartz Job Scheduling Library. To ensure that your cron expressions are interpreted correctly: > > > > * Specify values for six fields (second, minute, hour, day of the month, month, day of the week), not five. > > * Specify the day of the week as a value between 1 and 7, where 1 represents Sunday. It also accepts three-letter abbreviations for SUN-SAT. Expressions that use values between 0 and 7 where both 0 and 7 represent Sunday will not be parsed as expected. > > > > If a malformed cron expression prevents the rule from being scheduled, the error is recorded in workflow logs. For troubleshooting tips, see [Troubleshooting Workflows](troubleshooting-workflows.html).              The Due Date field stores the date and time as 12:00 UTC. If, for example, your office is in California (UTC-7) and you want your users to be notified for all issues that are due in less than two days, you need to offset the due date by seven hours. For more information, see [Working with Dates and Times](workflow-working-with-dates-times.html).             |
| 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 `true`.     When `true`, this property also suppresses notifications for cascading changes that are applied in the same transaction. For example, when updates that are applied by the on-schedule rule trigger updates from one or more on-change rules, the entire set of changes is applied without sending notifications.     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 `updated` and `updated by` properties in the issue. If you want to update these properties, set this flag to `true`.     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:

* [Issues](#issue-action-rules)

* [Articles](#article-action-rules)

* [Issue comments](#issue-comments-action-rules)

* [Article comments](#article-comments-action-rules)

* [Issue attachments](#issue-attachments-action-rules)

* [Article attachments](#article-attachments-action-rules)

### 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.     \| Property \| Description \| \| --- \| --- \| \| type \|    Required. The type of the object that the action rule expects from the user.    \| \| description \|    Optional. The description of the object that the action rule expects from the user. The action dialog shows this description as the label for the input 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.  |

### Action Rules for Articles

> **Note:**
> Available since YouTrack version 2024.2.

> **Note:**
> When you create a new action rule, the rule template is automatically built with reference to the `Issue.action` method. To make the action in your rule applicable to articles, edit the rule script to refer to the `Article.action` method instead.

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.     \| Property \| Description \| \| --- \| --- \| \| type \|    Required. The type of the object that the action rule expects from the user.    \| \| description \|    Optional. The description of the object that the action rule expects from the user. The action dialog shows this description as the label for the input 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.  |

### Action Rules for Issue Comments

> **Note:**
> Available since YouTrack version 2024.2.

> **Note:**
> When you create a new action rule, the rule template is automatically built with reference to the `Issue.action` method. To make the action in your rule applicable to articles, edit the rule script to refer to the `IssueComment.action` method instead.

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.     \| Property \| Description \| \| --- \| --- \| \| type \|    Required. The type of the object that the action rule expects from the user.    \| \| description \|    Optional. The description of the object that the action rule expects from the user. The action dialog shows this description as the label for the input 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.  |

### Action Rules for Article Comments

> **Note:**
> Available since YouTrack version 2024.2.

> **Note:**
> When you create a new action rule, the rule template is automatically built with reference to the `Issue.action` method. To make the action in your rule applicable to articles, edit the rule script to refer to the `ArticleComment.action` method instead.

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.     \| Property \| Description \| \| --- \| --- \| \| type \|    Required. The type of the object that the action rule expects from the user.    \| \| description \|    Optional. The description of the object that the action rule expects from the user. The action dialog shows this description as the label for the input 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.  |

### Action Rules for Issue Attachments

> **Note:**
> Available since YouTrack version 2024.2.

> **Note:**
> When you create a new action rule, the rule template is automatically built with reference to the `Issue.action` method. To make the action in your rule applicable to articles, edit the rule script to refer to the `IssueAttachment.action` method instead.

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.     \| Property \| Description \| \| --- \| --- \| \| type \|    Required. The type of the object that the action rule expects from the user.    \| \| description \|    Optional. The description of the object that the action rule expects from the user. The action dialog shows this description as the label for the input 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.  |

### Action Rules for Article Attachments

> **Note:**
> Available since YouTrack version 2024.2.

> **Note:**
> When you create a new action rule, the rule template is automatically built with reference to the `Issue.action` method. To make the action in your rule applicable to articles, edit the rule script to refer to the `ArticleAttachment.action` method instead.

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.     \| Property \| Description \| \| --- \| --- \| \| type \|    Required. The type of the object that the action rule expects from the user.    \| \| description \|    Optional. The description of the object that the action rule expects from the user. The action dialog shows this description as the label for the input 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.  |

## 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` for this property.   |
| stateFieldName | An alias for `fieldName`. |
| 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`. For state-machines per issue type, this property defines the transitions that apply when an alternative state-machine is not defined for the value in the field that regulates which state-machine applies to the managed field.   |
| defaultMachine | An alias for `states`. |
| 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 `states` property.   |

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 `true`. For other values that are not set as the initial value, this property is optional and can be omitted. |
| 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 `states` property.   |

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 `name` property is applied. |
| after | An optional property that sets an interval for performing an action. The action itself is specified in the `action` property. |
| 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

> **Note:**
> It's only possible to create and attach SLA rules to a helpdesk project.

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.     > **Note:** > When deciding which SLA policy to apply to a ticket, YouTrack checks existing policies following the order of the policies in the list in the project settings. If a ticket matches the `guard` condition in a custom SLA rule, but it has already matched another policy, the first matched policy will apply.    |
| 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 `ctx.breachedField` parameter of this function, YouTrack stores the timer custom field where the time goal has been breached for this ticket.      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.  |