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:

Option	Description
Every hour	Triggers the workflow rule once an hour, at the top of the hour.
Every day	Triggers the workflow once per day, at midnight.
Every week	Triggers the workflow once a week, at midnight Sunday evening.
Custom	Specifies a custom schedule for applying the rule as a Java cron expression. 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.

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.

A sample on-schedule rule in the workflow constructor.

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 `Type: {Purchase request}` query makes sure that the updates are only applied to purchase requests.

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: Field: Due Date Happens after: any date Happens before: the rule is triggered 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.

Condition

Description

Date Field Matches Specified Criteria

This condition block is configured with the following settings:

Field: Due Date
Happens after: any date
Happens before: the rule is triggered

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.

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

      exports.rule = entities.Issue.onSchedule({
        title: 'Notify assignee about overdue issues',
        search: '#Unresolved has: {Due Date}',
        cron: '0 0 10 ? * MON-FRI',
        guard: (ctx) => {
          return ctx.issue.fields.DueDate < Date.now();
        },
        action: (ctx) => {
            const issue = ctx.issue;
            let userToNotify = issue.fields.Assignee;
            if (!userToNotify) {
              userToNotify = issue.project.leader;
            }
            const formattedDate = dateTime.format(issue.fields.DueDate);
            
            const notificationText = workflow.i18n('Issue became overdue on <i>{0}</i>:', formattedDate) +
            ' <a href="' + issue.url + '">' + issue.summary + '</a><p style="color: gray;font-size: 12px;margin-top: 1em;border-top: 1px solid #D4D5D6">' +
            workflow.i18n('Sincerely yours, YouTrack') + '</p>';
            userToNotify.notify(workflow.i18n('[YouTrack, Issue is overdue]'), notificationText);
        }, 
        requirements: {
          DueDate: {
              type: entities.Field.dateType,
              name: "Due Date"
          },
          Assignee: {
            type: entities.User.fieldType
          }
        }
      });
    

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.

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

Last modified: 09 October 2024