This help center has been deprecated and moved to a new address, please follow this link to open an active help center.

Thank you and sorry for inconvenience!

What Is a Workflow and Why You Should Care

Workflows in YouTrack are a way to automate tasks. With workflows you can easily notify teams about events, enforce policies, execute periodic tasks, and maintain a smooth flow of existing business processes.

Prerequisites: You have YouTrack installed and configured, and you understand your YouTrack configuration, i.e. you know what projects are configured and what kinds of fields your issues have.

What’s a workflow in YouTrack?

In issue tracking in general, the term workflow means the set of states and transitions that an issue can go through during its lifecycle. In YouTrack, however, a workflow is also a set of logically related rules addressing a particular task. A rule is, basically, a script that YouTrack executes. Scripts are written in a specific DSL (Domain Specific Language) for YouTrack, which is easy to comprehend and work with. A language reference guide is available.

Types of rules

There are stateless rules, state-machine rules, and scheduled rules.

  • Stateless rules execute when an issue created or changed. Use them when desired actions depend on the issue field value.
  • State-machine rules define how an issue transits between different states. The only reason to use them is to define the entire lifecycle of an issue.
  • Scheduled rules run on a timer. Use them in case you need actions to be done at particular time, or when actions depend on a planned event, such as a deadline.

Common stateless rule

Use case

An issue in YouTrack can be a parent issue for a number of subtasks. If someone tries to close the parent issue without closing all its subtasks, this workflow can prevent them from doing so.

Rule code

rule Do not close parent issue if subtasks are not closed yet
when State.changed && !State.oldValue.isResolved && State.isResolved && parent for.isNotEmpty  {
     for each subtask in parent for {
     assert subtask.State.isResolved : "Please resolve all subtasks before closing the parent task";

Note that "parent for" is a single lexical unit referring to the array of child objects of the current object. If the syntax looks confusing, keep in mind that workflow language allows object properties to have spaces in their names.

Typical state-machine rule

Use case

You have an SLA with your customer defined as follows: the support team has to answer all questions submitted to your issue tracker within 1 hour. The simple workflow shown below requires the support team to open an issue within 1 hour after submission and take appropriate action. If the issue remains "Submitted" or "In progress" for a longer time, it becomes "Expired." (Additional rules can be created to send notifications when an issue is expired.)

Rule code

statemachine Maintenance for field State {  
initial state Submitted {
 on Open [always] do {<define statements>} transit to In Progress
 in 1 hour [State != {Answered} ] do {<define statements>} transit to Expired
state In Progress {
 in 1 hour [ State != { Answered } ] do { <define statements> } transit to Expired
 on Fix [ always ] do { <define statements> } transit to Answered
state Expired {
 on Fix [ always ] do { <define statements> } transit to Answered
state Answered {
 on Open [ always ] do { <define statements> } transit to In Progress

Common scheduled rule

Use case

The project lead would like to receive a report every Monday for all tasks fixed last week.

Rule code

schedule rule Report issues fixed last week   
weekly on Monday at 09:00:00 [ issue.State.isResolved ]  {
 var str = "";
 var user = issue.project.leader;
 if ( issue.resolved > now - 7 days ) {
    str = str + " " + issue.getId ();
    user.notify("Issues fixed last week", str , true );

Where to get workflows?

There are three ways of using a workflow in a YouTrack project:

  • attach a bundled workflow,
  • download a workflow from the repository and import it, or
  • create your own workflow.

Attach bundled workflow

Many workflows are bundled with YouTrack. Some of them attach to new projects automatically, while others do not. To check which workflows are already attached to your projects, go to Settings | Workflow:

Click the "Attach" link at the end of a line to attach a workflow to your project.

If you need to attach many workflows to a single project, proceed to Settings | Projects, select your project and click "Add workflow" on the Workflows tab.

If necessary, you can detach a workflow that you don’t need by clicking "Detach" on the right.

Import a workflow from the repository

The workfow repository can be found at Browse it to find workflow(s) you need. Each workflow includes a description of its rules, to help you find the right workflow for your projects.

The workflows that solve the most popular tasks are described below. Their titles are shown in italic.

Issue properties management

Several workflows aimed at automating issue properties modification. For example, 'Open' Assigned Issues workflow changes the state of the issue to Open when an assignee is added, and 'Waiting for Reply' Tag Management workflow replaces 'waiting for reply' tag with 'answered' tag when a developer adds a comment.

Enforce guidelines

If you would like to prevent developers from ‘fixing’ issues with a reason only, attach the workflow Comment Won't Fix State. If you want users to describe bugs in a unified manner, attach the workflow New Issue Description Template.

Pomodoro time tracking

Pomodoro technique is a popular time-tracking practice, described in detail in the YouTrack blog post. Attach the Pomodoro Timer workflow to assist you in using the technique in your project.

User notifications

It's convenient to have users notified of what has happened with the issues they reported or are responsible for. Workflows such as Notify Reporter To Approve Fix, Notify User Mentioned in Comment User, and User Comment(s) Awaiting Reply Notificationare useful for reminding users to approve a fix of the bug they reported. They notify users about any comments they were mentioned in, and periodically notify the support team of issues recently commented by customers.

Duplicates management

Do your users tend to create duplicate issues? Consider the following workflows to make duplicate management easier:

  • Duplicate Issues Only With Same Visibility Group: Disable duplicating issues with different visibility groups.
  • Intelligent Duplicates Management: Automatically relink all duplicates directly to the main duplicated issue; prevent users from removing all duplicate links from an issue in Duplicate state; set issue state to Duplicate when a Duplicate link is added; raise the Priority of a duplicated issue; and require adding a duplicate link when changing issue state to Duplicate.
  • Last Submitted Date for Duplicate Exception: Show the Last Submitted Date for the main issue when a new 'is duplicated by' link is added to it.

Access rights management

YouTrack allows you to set which issues are visible for given users and groups. To warn a user that visibility has changed, use the Change Visibility Warning workflow.

Attaching a workflow from the repository to your project

Choose a workflow that suits your needs and download it, as a ZIP package. Click Import workflow to perform the import. To do that, go to Settings | Workflow or open project properties by using the Workflow tab.
After you’ve imported the workflow you need, attach it to a project as described above.

Creating a workflow

If you can’t find a workflow that fits your needs, you can modify an existing one or create your own. Install the Workflow Editor and follow the steps described in the tutorial How to create workflows and rules for YouTrack.

Have more questions? Submit a request


Powered by Zendesk