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

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. 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-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 Search Query Reference) 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.
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.
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

The Issue.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 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.
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 contain 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 contain 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.

Last modified: 16 March 2020