On-change Rules

An on-change rule defines the action that is performed when a change is applied to an issue or an article.

On-change rules don't have any special properties for initial triggers. They run any time a new issue or article is created or when any change is applied to an existing issue or article in the project where the rule is active.

Sample On-change Rule

When building an on-change rule in the workflow constructor, you define the initial criteria for updating issues in the Prerequisites section, then specify which updates to apply in the Actions section.

Here's a workflow rule that automatically assigns purchase requests to the person who is responsible for their review and sets the due date to two weeks in the future.

A sample on-change rule in the workflow constructor.

This sample on-change rule behaves in the following way:

Rule Prerequisites

Whenever an issue is created or updated in the project where the rule is active, it checks the issue for the following conditions:

Condition	Description
Issue Exists or Is Created	This condition checks for any issue that exists or is created in the projects where the rule is active. When the Issue setting is set to Use the current issue, this means that every issue that is created or updated in the project is evaluated to match the criteria defined in the Preconditions section of the rule.
Field Matches Specified Criteria	This condition block is configured with the following settings: Field: Type Condition: is Value: Purchase request This checks to see if the new or existing issue is assigned Purchase request as an issue type. If the current issue doesn't match this criteria, the rule ignores this issue and continues processing the next issue.
Field Matches Specified Criteria	This block is nested inside a NOT block and has been configured with the following settings:: Field: Assignee Condition: changes from Value: Any value to: Any value This means that the rule will stop processing if the value for the Assignee field is changed in the update that triggers the workflow. The presence of this block means that users can manually reassign the issue to someone other than the person who is responsible for purchase requests. Without it, the rule would react to the change by assigning the issue as prescribed in the Actions section.

Condition

Description

Issue Exists or Is Created

This condition checks for any issue that exists or is created in the projects where the rule is active.

When the Issue setting is set to Use the current issue, this means that every issue that is created or updated in the project is evaluated to match the criteria defined in the Preconditions section of the rule.

Field Matches Specified Criteria

This condition block is configured with the following settings:

Field: Type
Condition: is
Value: Purchase request

This checks to see if the new or existing issue is assigned Purchase request as an issue type.

If the current issue doesn't match this criteria, the rule ignores this issue and continues processing the next issue.

Field Matches Specified Criteria

This block is nested inside a NOT block and has been configured with the following settings::

Field: Assignee
Condition: changes from
Value: Any value
to: Any value

This means that the rule will stop processing if the value for the Assignee field is changed in the update that triggers the workflow.

The presence of this block means that users can manually reassign the issue to someone other than the person who is responsible for purchase requests. Without it, the rule would react to the change by assigning the issue as prescribed in the Actions section.

All the conditions in the Preconditions section of the rule are joined with implicit AND operators. This means that the workflow will only apply the changes specified in the Actions section if all these conditions are satisfied.

Specifically, this means that the rule only updates issues that are created or updated in the project that the rule is attached to where the value for the Type field is set to Purchase request and the update does not explicitly change the value for the Assignee field.

Rule Actions

If all these conditions are met for the current issue, the workflow automatically applies the following changes:

Action	Description
Update the Value in a Field	This action sets the value for the Assignee field to the person who is responsible for handling purchase requests. This block is configured with the following settings: Field: Assignee Mode: set To: references the user who is responsible for handling purchase requests.
Update the Value in a Field	This block is nested inside an IF block, which allows for this action to be applied only when an additional condition is true. The additional condition is defined using a Field Matches Specified Criteria block which has been configured as follows: Field: Due Date Condition: is not set This means that the action that is specified in this block will only apply to issues where the Due Date has not been set. The action is configured with the following settings: Field: Due Date Mode: set To: the rule is triggered For the setting that stores the time offset from the specified date, enter +2w. This sets the value for the Due Date field to a date two weeks in the future. Using the IF statement to ignore issues where the due date has already been set lets you manually reschedule the due date as needed without triggering the rule again.

Action

Description

Update the Value in a Field

This action sets the value for the Assignee field to the person who is responsible for handling purchase requests. This block is configured with the following settings:

Field: Assignee
Mode: set
To: references the user who is responsible for handling purchase requests.

Update the Value in a Field

This block is nested inside an IF block, which allows for this action to be applied only when an additional condition is true.

The additional condition is defined using a Field Matches Specified Criteria block which has been configured as follows:

Field: Due Date
Condition: is not set

This means that the action that is specified in this block will only apply to issues where the Due Date has not been set.

The action is configured with the following settings:

Field: Due Date
Mode: set
To: the rule is triggered
For the setting that stores the time offset from the specified date, enter +2w.

This sets the value for the Due Date field to a date two weeks in the future.

Using the IF statement to ignore issues where the due date has already been set lets you manually reschedule the due date as needed without triggering the rule again.

This rule performs the following actions when a change is applied to an issue:

YouTrack checks for a change to the value in the Subsystem field.
If the value in the Subsystem changes, the issue is automatically assigned to the owner of the subsystem.

      const entities = require('@jetbrains/youtrack-scripting-api/entities');
      const workflow = require('@jetbrains/youtrack-scripting-api/workflow');

      exports.rule = entities.Issue.onChange({
        title: 'Set subsystem owner as assignee for unassigned issues',
        guard: (ctx) => {
          return !ctx.issue.fields.Assignee && ctx.issue.fields.Subsystem;
        },
        action: (ctx) => {
          const issue = ctx.issue;
          const fs = issue.fields;
          if ((issue.isReported && (fs.isChanged(ctx.Subsystem) || issue.isChanged('project'))) || issue.becomesReported) {
            if (fs.Subsystem.owner) {
              if (ctx.Assignee.values.has(fs.Subsystem.owner))
                fs.Assignee = fs.Subsystem.owner;
              else
                workflow.message(workflow.i18n(
                    "{0} is set as the owner of the {1} subsystem but isn't included in the list of assignees for issues in this project. " +
                    "The workflow that automatically assigns issues to the subsystem owner cannot apply this change.",
                    fs.Subsystem.owner.fullName, fs.Subsystem.name));
            }
          }
        },
        requirements: {
          Assignee: {
            type: entities.User.fieldType
          },
          Subsystem: {
            type: entities.OwnedField.fieldType
          }
        }
      });
    

The components that define this on-change rule are as follows:

All scripts start with a list of require statements. In this rule, we declare a local variable entities and reference the entities module in the workflow API. This means that everything that is contained in this module can be accessed in this script with the entities variable.
Each script exports one rule to the exports.rule property. The rule is declared with the Issue.onChange method, which exports the script that follows the declaration as an on-change rule.

The body of the rule itself contains three properties, as follows:

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. In this example, we check to see if the Subsystem field was set to a non-null value that has a non-null owner. If so, the rule sets the value of the Assignee field.
runOn	Determines which issue events trigger the on-change rule. When not specified, rules are triggered on issue update. This property is extended with the following parameters: `change` — when `true`, the rule is triggered on issue change. `removal` — when `true`, the rule is triggered when an issue is deleted. As the rule in this example is triggered when updates are applied, we don't need to specify values for this property.
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, the requirements ensure that both the Subsystem and Assignee fields store the correct types and are available in the project to which the rule is attached. If either field is absent, an error is shown in the Workflows list. The rule cannot be enabled until the required fields are attached.

For a sample of an on-change rule for articles, see the API reference in the Developer Portal.

To learn more about writing workflows in JavaScript, please check out the documentation in our Developer Portal.

Last modified: 09 October 2024