On-schedule Rules
An on-schedule rule defines a set of changes that are applied according to a set schedule. For example, you can periodically check for issues with specific attribute values and notify a user or a group. These rules replace the scheduled rules that were used in older workflows.
On-schedule rules are executed by a special workflow user. This is a system user account that is granted a full set of permissions. The permissions for this account cannot be modified. The workflow user account is not included in the license restrictions and is not displayed in the Users list.
Sample On-schedule Rule
When you build an on-schedule rule in the workflow constructor, use the following settings to define the trigger for running the workflow:
Setting | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Schedule | Defines the schedule for running the rule by choosing one of the following options:
All times are set using the time zone from the Global Settings for your instance. | ||||||||||
Filter | Stores a search query that determines which issues are considered for processing by this rule. Use the standard syntax for searching for issues in YouTrack. For more information, see Search Query Reference. |
You then 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 checks once a day for overdue purchase requests and adds a tag to requests that are past their due date.
This sample on-schedule rule behaves in the following way:
Rule Triggers
The rule is configured to be triggered in the following situations:
Setting | Description |
---|---|
Schedule | The Every day option runs the rule once a day at midnight according to the time zone that is configured for the YouTrack instance. |
Filter | The |
Rule Prerequisites
Once per day, issues that match the initial filter criteria are checked for the following condition:
Condition | Description |
---|---|
Date Field Matches Specified Criteria | This condition block is configured with the following settings:
This checks to see if the value that is stored in the Due Date field occurs before the time when the rule is triggered. If the current issue doesn't match this criteria, the rule ignores this issue and continues processing the next issue. |
Rule Actions
If the condition described in the Prerequisites block is met for the current issue, the workflow automatically applies the following change:
Action | Description |
---|---|
Add a Tag | This action adds the overdue tag to the current issue. |
This rule executes every day at 10:00. The rule checks for unresolved issues that are assigned and contain a value in the Due Date field. If the due date is in the past, a notification is sent to the assignee.
The components that define this on-schedule rule are as follows:
Again, the script starts with a
require
statement that references theentities
module in the workflow API. This means that everything that is contained in this module can be accessed in this script with theentities
variable.For this rule, the
exports.rule
property uses theIssue.onSchedule
method. This exports the script that follows the declaration as an on-schedule rule.The body of the rule itself contains definitions for 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.
In this example, the expression triggers this rule every day at 10:00 in the time zone that is set for your YouTrack server.
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, as with the .notify method that is used in this example.
This property is not relevant to this example, as the rule does not apply any issue changes. Even if it were set to
true
, the email notification that is sent using the.notify
method is still delivered.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 that matches the search condition. This action is triggered separately for each issue. The action itself is performed by the workflow user account.
In this example, we use the
Assignee.notify
method to warn the current assignee that the issue is overdue.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 Assignee and Due Date 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.