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.
Workflows consist of rules. There are three types of rules: stateless, state-machine, and scheduled. This tutorial describes how to create new rules or modify existing ones, how to make a particular workflow, and how to use the workflow language.
Read this tutorial if you want to make workflows and rules for YouTrack.
Whether you wish to create a workflow from scratch or modify an existing one, you need Workflow Editor, the application for working with workflows.
- Have YouTrack installed and configured (or have YouTrack InCloud).
- Understand your YouTrack configuration, i.e. know which projects are configured and which fields the issues in the projects have.
- Read the tutorial What Is a Workflow and Why You Should Care.
- Check and make sure that there are no suitable existing rules for YouTrack that would customize your project as required, and that you do need to make your own rules and activate them for your project.
Section 1 describes how to set up Workflow Editor and assign the appropriate permissions in YouTrack.
Section 2 shows the process of making a new workflow and rules for a particular use case. Your requirements could be different from what we took as an example, but you can follow the same pattern.
Section 3 wraps the process up with the necessary steps for new workflow activation in your YouTrack instance.
Download and install Workflow Editor from Get YouTrack website page. Workflow Editor is a separate Java application required to create or modify workflows.
Note: If you run Workflow Editor on Linux, please ensure you run it with Java 6, as higher JRE versions are not supported on Linux.
When you run YouTrack Workflow Editor for the first time, configure it by providing YouTrack server URL, as well as the username and password for a user who has low-level administration permissions in YouTrack.
Ensure you have appropriate privileges.
Low-level administrator permissions are required to create and edit workflows. Only the Admin role has such permissions by default. You can always customize roles by assigning ‘Low-level Administration’ permissions to other roles, by selecting Settings | Roles in YouTrack.
Then you can assign a role with these permissions to a user, by selecting Settings | Users in YouTrack as shown below:
Upon start, synchronize workflows in Workflow Editor and YouTrack server. To have the most recent workflows, always download them from the server before creating/modifying them. Likewise, upload your workflows to YouTrack as soon as you finish working on them.
Note: Mistakes in custom workflow rules may lead to the inadvertent removal of important data or YouTrack database corruption. Therefore, we strongly recommend backing up your YouTrack database before updating workflows. To do so, select Settings | Database Backup in YouTrack as shown below:
Along with workflows, Workflow Editor also downloads a scheme of your projects. If you’ve changed the set of fields or available fields' values in your project, download the workflows again, as shown below.
Suppose your team follows a Kanban process and would like to utilize YouTrack Agile Board. Board columns will stand for departments, and the team has a process of issue transition from one department to another. Team members see which department is processing the 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.
Our task now is to set up the project and create workflows to implement the board as described above.
To have colored cards on the board, you need a field of enumeration type in your project. Let's call the project WebDev and the field DeadlineApproach, with the following values:
- More than a week
- A week
- 4-6 days
- 2-3 days
- 1 day
Define the colors when you add new values to the set of values available for the field.
Also, the project should have a Due Date field where the deadline is specified.
Workflows consist of rules. We'll create the workflow first, then create rules in it.
We will make two rules: one stateless, triggered when an issue is changed, to handle the creation of the new issues and changes of Due Date in existing ones, and the other scheduled, to update the color of the cards daily.
Run Workflow Editor and create a new workflow:
Let's call the workflow ColoringOnDueDateApproach in our example. Then click the appropriate icon to create a rule, and start editing:
Name the new rule and start writing the code. Workflow Editor provides helpful advice on syntax, names and methods that you can use in your rules. Feel free to press Ctrl+Space anywhere inside the rule code to look for completion options. Changes are saved automatically.
Note that copy-and-paste works in Workflow Editor for some fragments of code, but generally you cannot copy-and-paste the whole workflow. In particular, it means that you can't copy text from this tutorial and paste to Workflow Editor.
A rule code starts with the rule name followed by statements. A stateless rule has a trigger condition. For example, in our first rule, ColorOnDeadLineApproach, the rule starts when an issue is created or modified:
After the rule triggers are defined, we decide what to do next.
In the example above we use if statements to check how close Due Date is to the current date. You can use reserved word now to refer to the current date. Field names are pre-defined variables in workflow code, and the fields must exist in the project for the workflow to be attached and executed for project issues.
We defined which DeadlineApproach field value corresponds to which color. Select DeadlineApproach in Agile Board Settings | Field for color-coded cards, and YouTrack will color the cards automatically.
Now let's create another rule, which is triggered every morning to follow a regular timeline regardless of changes in issues. A rule running on a schedule is called a scheduled rule. It also has a name in the first line, and then defines the time it runs at.
The code of the rule is similar to that of the stateless rule: It checks the same conditions and makes the same assignments.
With two new rules your workflow looks as follows:
When you are finished with editing your rules, upload them to your YouTrack server. This is required for your changes to take effect.
To attach a new workflow in YouTrack:
- Open Administration | Projects page, open your project and navigate to the Workflow tab.
- Click the Attach Workflow link and select the workflow you want to attach.
- Click Save.
If you would like to attach the same workflow to several projects:
- Click the Workflow link in the left-hand bottom corner of the Settings page.
- Click Attach next to your workflow.
- Choose the projects you wish to attach the workflow to.
The attached workflow starts working immediately. If you modified a workflow that had been previously attached to the project, it remains attached and the changes take effect upon upload.
When you need to update an existing workflow instead of creating a new one, click it in Workflow Editor and see the rules it contains. For example, you may want to do this if you realize you made an error in the code of some rule(s).
Choose the rule you want to modify, double-click it and edit the same way you would a new rule.
The only difference is that you don't have to assign a new name to an existing rule.
You may also add new rules to an existing workflow, or delete rules if they are no longer necessary.
Make sure to upload workflows to your YouTrack server after modification, the same way you do after creating a new one.