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

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.

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

exports.rule = entities.Issue.onSchedule({
  title: 'Notify an Assignee when Due Date is expired',
  search: '#Unresolved has: Assignee has: {Due Date}',
  cron: '0 0 10 * * ?',
  muteUpdateNotifications: false,
  guard: function(ctx) {
    return ctx.issue.fields.DueDate < Date.now();
  },
  action: function(ctx) {
    var issue = ctx.issue;
    issue.fields.Assignee.notify('[YouTrack] Overdue', 'Issue ' + issue.id + ' is overdue.');
  },

  requirements: {
    Assignee: {
      type: entities.User.fieldType
    },
    DueDate: {
      type: entities.Field.dateType,
      name: 'Due Date'
    }
  }
});

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

Again, the script starts with a require statement that references 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.
For this rule, the exports.rule property uses the Issue.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.

Last modified: 28 October 2020