YouTrack Workflows — how do we customize our project managing tool
Before we start — read why we changed our project managment tool and migrated from Jira to Youtrack!
Last time we explained, why we have moved from Jira to YouTrack. Today we would like to share our thoughts about one of the best features provided by YouTrack — Workflows.
What are YouTrack Workflows?
Workflows are sets of custom rules that hook up into YouTrack system. They are executed automatically when certain events occur periodically with CRON-like specified time schedule. Those events can be any issue-related changes, for example issue creation, update or transition between states.
What is the benefit of using Workflows? One can customize how YouTrack works according to company’s policy, project management style or developers’ needs. You change your tool to match your needs, not the other way.
Possible use cases
You are mostly limited by your imagination, as the Workflows can for example:
- change issue state or field values in response to events,
- send email notifications to defined users,
- prevent doing some changes in specified conditions,
- integrate with external services performing HTTP requests,
- automate changes you do by hand.
Or as the documentation says:
With workflows, you can easily notify teams about events, enforce policies, execute periodic tasks, and support the processes followed by your organization.
How to start
So, if you want to start with Workflows, you will need to have a global Low-level Administration permission. It will be required for all further actions.
When you make sure you have the right permissions, firstly check out default Workflows available in your YouTrack instance. To do so, go as admin to http://your.youtrack.address.com/admin/workflows. There you will see a list of Workflows currently installed in your system.
Each Workflow on the list contains one or more rules, that you can see expanding the Workflow. Each Workflow and rule has a pretty self-explanatory name, but if you are not sure what does it do, you can click it and investigate custom rule script in details panel on the right. Rule scripts are easy to read too, and we will get into detail about them later.
On some Workflows you will see an “auto-attach” label. That means that Workflow will be automatically added to new project you create. You should spend some time getting familiar with available Workflows and decide, which would you like to have added to new projects. For this purpose select some Workflows and click “Enable / Disable auto-attach” button above the list.
Changing “Auto-attach” will not affect existing projects. To add Workflow to a project:
- select chosen Workflow, click on the plus button in the details panel and select the project,
- go to “edit project” page, select “Workflows” tab, click on the “Attach workflow” button and select chosen Workflow from the dropdown list.
Workflows requirements
When you attach some Workflows to your project, you may end up with unmet requirements. Let’s look at the example. I want to add inbuilt Workflow “Mandatory Field” to my project. This Workflow has only one rule that prevents users from creating issues without setting value for “Due Date” field. When someone tries to submit an issue leaving this field blank, he will get the error message. Pretty useful, it assures all issues will have all fields filled in, which we need in our process.
After I attach this Workflow to my project, by the project settings page, it shows up on the list with a red “requires setup” label on it and on the rule inside.
When I click on the rule, in details panel, I can see an error description. The “Due Date” field, on which the rule operates, does not exist in this project.
To fix this, you can add this field to the project manually or let YouTrack do the job for you by simply clicking the “Configure project” button and confirming changes.
You should always check Workflows attached to the project when you change / remove fields from the project or create a new project to make sure that all attached rules work. If any rule has unmet requirements, it will simply have no effect.
Getting more Workflows
Inbuilt YouTrack Workflows are good point to start, but obviously the possibilities are much greater than using just them. After you get familiar with Workflows shipped with YouTrack, the best place for the next step is the official Custom Workflow Repository. It’s GitHub repo with over 40 different Workflows. Each one of them has described requirements about fields and groups required for them to work. Getting familiar with examples from this repo gives you some knowledge, what you can use Workflows for in your system.
To install the chosen Workflow into your YouTrack instance, just follow instructions from the Readme. It’s rather straightforward — just download .zip file and import it, either locally into a single project or globally in Workflows administration page. From then on, you can benefit from new Workflows in your projects.
How to create your own workflows?
We’ll cover this topic in our next post, so stay tuned!
Author: Maciej Radzikowski — Senior Developer at BlastLab Ltd. Java EE developer and database architect focused on making work of others programmers easier.
Join our Hardware group and support polish community!
And click this ❤ if you like what you read!
