YouTrack Workflows — how do we customize our project managing tool (part II)

Before you start reading this text, we recommend to read intro (Jira vs. YouTrack) and first part?

Creating your own YouTrack Workflows

Of course, sooner or later, you will come to the point when you want to create own custom rules or editing existing ones to better fit your needs. Until now Workflows were described by specific DSL, which you have seen in details panel of build-in rules. Recently, in YouTrack 2017.2, there was introduced experimental function of creating Workflows in JavaScript. Here we will investigate both methods.

Firstly, we will extend the “Scrum” Workflow. We will use DSL to add rule that prevent adding User Story type issues to Sprint if they don’t have Story Points set. Secondly, we will create new Workflow with JS rule that will prevent to change some fields values by some users. Both rules are real use cases from our company and I will describe them in next chapters.

Creating YouTrack Workflows using DSL — the old method

As I said, we would like to add rule that issue of type User Story, added to Sprint, you should have set value for Story Points field. Need of such rule came up after we forgotten few times to fill this field during YouTrack update after Sprint Planning.

To create rules using DSL you need to download YouTrack Workflow Editor. It’s Java desktop app based. Unfortunately, for some reason it requires Java 5 or 6, not newer!

Java Version Mismatch error

So, unless you are working on some legacy Java project or deal with different Java versions installations on your computer, the best and easiest option is to use our Docker image.

As this requires launching desktop GUI app in Docker container, described here method for launching Workflow Editor works out of the box only for Linux. For Windows configuration please see this topics: topic 1, topic 2.

Assuming you have Docker installed and configured, all you have to do is set X11 settings and run image:

xhost +
export DISPLAY=:0.0
docker run -it -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix blastlab/youtrack-workflow-editor

If everything went well, you should get Workflow Editor running.

Preview of the workflow editor window

Now you have to:

  • connect to your YouTrack instance,
  • download current Workflows from it,
  • make changes,
  • send updated Workflows to YouTrack.

Connecting to YouTrack instance

To connect to your YouTrack select “Workflow / Connection Settings…” from the menu or just simply click on link in yellow “Connection Problem” alert. There pass URL to your instance (the same path as when you launch YouTrack in browser) and your login and password. Test the connection, and if everything is good confirm with the “OK” button.

Downloading current Workflows from YouTrack instance

The next step is to download current configuration from YouTrack. To do it just select “Workflow / Download workflows from server”. In a few seconds the list on the left should be filled with the same Workflows you saw earlier on the admin page. Most of them (or all, if you didn’t load any custom ones) will be build-in Workflows with name starting with “jetbrains-youtrack-”.

Creating new rule in Scrum Workflow

Now you may edit existing rules or create new one. We will do the second — lets add new rule to existing Workflow, “jetbrains-youtrack-scrum”.

To do this select Workflow on the list and select “Workflow / Create Stateless Rule” from the menu. Now you should have open editor for the new rule.

In the rule there are 3 main parts. First one is the rule name, second is the condition in which it will be run, and third is the actual action to perform. Each part is now marked with comment in angle brackets.

As Workflow Editor has some formatting and syntax enforcing features, it may be easier to rewrite code given below than trying to copy and paste it.

rule User Stories added to sprint must have story points
when issue.Type == {User Story} && issue.Sprints.isNotEmpty && issue.isReported() {
assert issue.Story points != null: “User Story added to Sprint must have story points”;
}

Let’s dive into this code.

First line, as we said before, defines rule name. That name will be visible in YouTrack, so it should be a good, short description of what it does.

when in second line determines that it’s stateless rule, executed on issue creation or update. Next to it we have conditions that must be met to execute rule. We can access all issue properties by simple syntax issue.<property name>.

Firstly, we want this rule to work only for issues with type User Story. As we want to assure that all issues added to sprint have some fields filled, next we check if field Sprints containts at least one value (as it’s multiple-choice set). Finally we check if issue is reported (or becomes reported in result of current operation), which means it’s not a draft.

If issue fullfills all of above requirements we get to the point of our rule. Here it’s very simple, one line check — in line 3 we check if value of field Story points is set, and otherwise we display error message. This will prevent saving changes by user.

Importand notice is that you may see text messages wrapped in l10n() function in build-in rules. If you are putting own messages or editing existing ones you must place it directly, without l10n(), as it works only for translations provided inside YouTrack distribution.

Sending updated Workflow to YouTrack

After new rule is finished, it must be send to the YouTrack. For this purpose you may either select “Workflow / Upload Workflows to Server” from the menu to send all Workflows or right-click on edited Workflow (the one we added new rule) and select “Force Upload Workflow to Server”. In both cases the Workflow will be validated and, if everything will be ok, it will be uploaded.

Now you may check on the admin page if new rule is visible. From now if any user will try to set Sprints field for the issue before setting Story Points in project with this Workflow attached, he will get the error popup and Sprints value will not be changed.

Creating Workflows using JavaScript — the new method

As a second change we will create own Workflow preventing users with role Reporter from editing the “Fix versions” field value. Why such thing? Currently YouTrack supports only single level of restricting visibility by “private field” option. Those private fields may be shown or hidden from given users, but there is no option to hide some fields and show some others in read-only mode. Actually, there is an open issue for that.

To create Workflows in JavaScript you will have to:

  • have YouTrack 2017.2 or never,
  • enable “New Workflow Editor” experimental feature as described here.

As it’s experimental feature API may change without backward compatibility. Code below is tested on YouTrack 2017.2 build 32582.

After fullfilling those requirements go to Workflows administration page and click “Create workflow…” button. In popup provide name for this Workflow and for a single rule.

Creating new workflow form

After submitting form scroll down to new added Workflow, expand the list and click on rule name. You should find yourself in interactive editor with empty content. Here pass the following script:

var entities = require(‘v1/entities’);
var workflow = require(‘v1/workflow’);
exports.rule = entities.Issue.onChange({
title: ‘Prevent readonly fields edit by Reporters’,
action: function(ctx) {
var issue = ctx.issue;
var user = ctx.currentUser;
if (user.hasRole(‘Reporter’, issue.project)) {
var fs = ctx.issue.fields;
var isRestrictedFieldchanged = fs.isChanged(ctx.FixVersions);
workflow.check(!isRestrictedFieldchanged, “You don’t have permissions to change this field.”);
}
},
requirements: {
FixVersions: {
type: entities.ProjectVersion.fieldType,
name: ‘Fix versions’,
multi: true
}
}
});

First two lines provides us build-in objects with access to system data and functions. Then we define our rule — the “onChange” is type of rule that replaced “Stateless” type from old DSL.

The rule has 3 properties — title, action and requirements. As the title is pretty obvious lets look at the other two, starting with requirements.

requirements defines base conditions for the project or system that must be met to allow our rule work. Here we define that there shuold be available Fix versions field of the type ProjectVersion, which may take multilpe value. This field is then available in our rule in context (ctx) object. If we try to attach this rule to the project without Fix versions field, we will see the error message with auto-fix proposition.

The action is main part of our rule. Here we take the issue object on which rule was fired from the context, as well as the user. Then we check, if the user has Reporter role in the current (issue’s) project. If so, if our field, previously set in requirements and now taken from the context, was changed, we show the error. The workflow.check function takes the boolean value and shows the error if it’s false.

Preview of the code of workflow function

Finally all there is to do is to click the magic wand icon to reformat code and save the rule. The new workflow is visible on the list and may be attached to any project, that has Fix versions field.

Is that all?

Here we created two rules for our Workflows. Both were simple, Stateless / On Change rules. YouTrack allows to create also On Schedule and State Machine rules, with other possibilites. And in the new JavaScript Editor we can also create Actions. What are those? Actions are custom actions that user may run on issue. One (and the only one right now) of the build-in is the “Clone issue” action. But now there is no obstacle to create more, own ones.

Just please remember that the new Workflow Editor is currently an experimental feature, so not everything may work well.

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!

Like our fan page,

Follow us on Twitter,

And click this ❤ if you like what you read!


YouTrack Workflows — how do we customize our project managing tool (part II) was originally published in The Official BlastLab Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.