Workflow Tutorial

Prerequisites

• You have permission to create and edit workflows. These tasks require that you have the Read Project and Update Project permissions in at least one project. Users with the Low-level Administration permission can create workflows and edit any workflow in the system.

• You are familiar with your YouTrack configuration. This means that you know how your projects are configured and the fields that are used in issues for each project.

• You have a basic understanding of JavaScript.

• You have verified that the existing workflows do not support your use case. You need to write new rules and attach them to one or more projects.

• You have created a backup of your YouTrack database. Errors in custom workflows can lead to the inadvertent removal of important data or corruption of the database. We strongly recommend that you back up your YouTrack database before you update workflows. This task requires the Low-level Admin Write permission.

Use Case

Let's say your team follows a Kanban process and would like to use the YouTrack Agile Board. The columns of the board represent each department. Your team has a set process for moving issues from one department to the next. Team members can see which department is working on an issue at the moment. The color of the issue card represents the time left until the deadline. The card starts out green and then, based on a specific workflow, turns yellow and then red as the deadline approaches.

Your task is to set up the project and create workflows to support the board as described above.

Set Up the Project

To have colored cards on the board, you need an enumerated field in your project. Let's call the project WebDev and name the field DeadlineApproach. You add this field to your project and add the following set of values:

• More than a week

• 1 week

• 4-6 days

• 2-3 days

• 1 day

You define the colors when you add values to the set of values available for the field.

You also need to add a Due Date field to your project to store the deadline.

Now that you have defined the color scheme for the custom field, you need to apply this color scheme to the cards on your agile board.

Create the Workflow

Workflows are really nothing more than a container for the modules that define your rules. First, you create the workflow. Then you add modules that contain the rules to it.

Create an On-change Rule

You need to add two rules to the workflow:

• An on-change rule that runs when an issue is changed, when a new issue is created, and the Due Date field is updated.

• An on-schedule rule that updates the color of the cards daily.

Now let's define the on-change rule.

You can copy and paste this block of code directly into the editor.

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

exports.DAY_IN_MS = 24 * 60 * 60 * 1000;

exports.rule = entities.Issue.onChange({
  title: 'Apply color by due date',
  guard: function(ctx) {
    return (ctx.issue.becomesReported || ctx.issue.fields.isChanged(ctx.DueDate)) &&
      ctx.issue.fields.DueDate;
  },
  action: function(ctx) {
    var issueFields = ctx.issue.fields;
    var diffInDays = Math.round((issueFields.DueDate -
      Date.now()) / exports.DAY_IN_MS);
    if (diffInDays > 7) {
      issueFields.DeadlineApproach = ctx.DeadlineApproach.moreThanAWeek;
    } else if (diffInDays > 6) {
      issueFields.DeadlineApproach = ctx.DeadlineApproach.oneWeek;
    } else if (diffInDays > 3) {
      issueFields.DeadlineApproach = ctx.DeadlineApproach.fourToSixDays;
    } else if (diffInDays > 1) {
      issueFields.DeadlineApproach = ctx.DeadlineApproach.twoToThreeDays;
    } else {
      issueFields.DeadlineApproach = ctx.DeadlineApproach.oneDay;
    }
  },
  requirements: {
    DueDate: {
      type: entities.Field.dateType,
      name: 'Due Date'
    },
    DeadlineApproach: {
      type: entities.EnumField.fieldType,
      moreThanAWeek: {
        name: 'More than a week'
      },
      oneWeek: {
        name: '1 week'
      },
      fourToSixDays: {
        name: '4-6 days'
      },
      twoToThreeDays: {
        name: '2-3 days'
      },
      oneDay: {
        name: '1 day'
      }
    }
  }
});

When finished, click the Save button.

Create an On-schedule Rule

The next step is to create the on-schedule rule. This rule checks all of the issues in the project on a set schedule and updates the color scheme that is applied to each card on the Kanban board based on how near each issue is to its due date.

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

exports.DAY_IN_MS = 24 * 60 * 60 * 1000;

exports.rule = entities.Issue.onSchedule({
  title: 'Change color over time',
  search: '#Unresolved has: {Due Date}',
  cron: '0 0 9 1/1 * ? *',
  action: function(ctx) {
    var issueFields = ctx.issue.fields;
    var diffInDays = Math.round((issueFields.DueDate -
      Date.now()) / exports.DAY_IN_MS);
    if (diffInDays > 7) {
      issueFields.DeadlineApproach = ctx.DeadlineApproach.moreThanAWeek;
    } else if (diffInDays > 6) {
      issueFields.DeadlineApproach = ctx.DeadlineApproach.oneWeek;
    } else if (diffInDays > 3) {
      issueFields.DeadlineApproach = ctx.DeadlineApproach.fourToSixDays;
    } else if (diffInDays > 1) {
      issueFields.DeadlineApproach = ctx.DeadlineApproach.twoToThreeDays;
    } else {
      issueFields.DeadlineApproach = ctx.DeadlineApproach.oneDay;
    }
  },
  requirements: {
    DueDate: {
      type: entities.Field.dateType,
      name: 'Due Date'
    },
    DeadlineApproach: {
      type: entities.EnumField.fieldType,
      moreThanAWeek: {
        name: 'More than a week'
      },
      oneWeek: {
        name: '1 week'
      },
      fourToSixDays: {
        name: '4-6 days'
      },
      twoToThreeDays: {
        name: '2-3 days'
      },
      oneDay: {
        name: '1 day}'
      }
    }
  }
});

Here's a basic explanation of what happens in this script:

• First, you set the search property. This is necessary because you only want this rule to be applied to unresolved issues.

• Next, you set the schedule. The schedule is determined by the cron property.

• Then you have a series of if statements that check how close the Due Date is to the current date.

• The Date.now method returns a value that corresponds to the current date and time in UTC.

• As with the on-change rule, we set the requirements for custom fields and their values. These requirements must exist in the project for the workflow to execute properly.

With these two rules, your workflow looks as follows:

Attach the Workflow to a Project

The last step is to attach the workflow and enable the rules in your project.

If there are projects that do not meet the workflow requirements, the requires setup flag is shown. This can mean that the project does not use the required custom fields, values are missing from the set of values in a custom field, or that there are groups, saved searches, projects or other system-wide entities that do not exist in YouTrack.

The attached workflow starts working immediately. If you edit to a workflow that is currently attached to a project, the changes take effect when you save your changes in the workflow editor. However, if you add requirements to the workflow that require additional setup, the workflow will not execute properly until the requirements are met.