Skip to end of metadata
Go to start of metadata

Overview

The main workflow rules types are the stateless rule, the scheduled rule and the state machine.

The rule raises 'Priority' when the 'State' field is changed to the 'Open'.

Every field has the .becomes() method and the .changed property:
  • field .becomes({Value}) is true if the current change is setting the value to {Value}
  • field .change is true, if the field's value is just changing in the current transaction.
    You can also refer for more detailed description here
Each day at 10:00, this rule sends emails to a project's administrator about all 'Show-stoppers'.

The scheduled rule is triggered by a timer that can be set to go off every minute, hourly, daily, weekly, monthly, yearly or by an arbitrary cron expression.
You can also refer for more detailed description here
A simple state machine that defines allowed transitions between issue states.

State machine is based on states provided by the state machine's specified field and by the transitions between these states. More detailed description is available here.
In particular, there are :
  • initial state <State> — it's the start state
  • on 'event name' .do {<statements>} transit to <State> — define the custom transition
  • enter {} — executed on entering to the state
  • exit {} — executed on exiting from the state
  • in time [condition] do {<statements>} transit to <State> — in the time period, if the condition is satisfied, do something and transit to the target state

As any respective programming language, the workflow language has keywords, variables, collections and iterators, and standard statements. Also there are specific to the workflow language statements, controls, methods and customs working with dates, strings and more.
All rules are worked on context of issue. Workflow cannot handle bundles changes, user registration/modification, report building, tag or saved search modifications and so on.

Please note, the workflow language does not support functions, closures, pairs and tuples.

Back to top>>

Keywords

There are five main keywords: loggedInUser, now, null, true, false.

The loggedInUser references to the current logged in user, the current 'change' executor.
The current moment in workflow is now.
Standard expressions true, false, null, which function as expected.

Back to top>>

Variables

Variable is declared with a keyword var followed by variable name. Optionally, initial value can be specified after '=' sign, like in JavaScript language.

The simple variable assignment.
The simple split variable assignment.
Any field has the oldValue parameter, which is the reference to the previous value of the field; the value that the field had prior the current change.

Back to top>>

Iterators and collections

Workflow language supports two main iterators for each and while and the following predefined collections: issues, comments, tags, users, issue links, enum elements, versions, builds, ownedFields, groups, states, bundle static elements, strings.

Please note that there is no possibility to create an own collection within the workflow.

Send notification to a project leader about the overdue 'Fix version'.
Any collection has the fields first, last, isEmpty, isNotEmpty and the following methods:
  • added — a collection of items that were added during the current transaction
  • removed — a collection of items that were removed during the current transaction
  • contains(<element>) — check whether a collection contains the specified element or not
    The tags, enum[], *state[], *version[], *builds[], *groups[], *user[]* have also the add() and clear() methods.
The while loop has the standard behaviour of iteration by the condition.

The example provided here shows how you can calculate the Pi number within workflow rule.

Back to top>>

Operators

The workflow language provides several specific operators: assert, message and, of cause, the 'branch' operator.

The assert statement stops the rule execution if condition is false and roll-backs all changes to the initial issue(s) state.

Workflows can be invoked by the chain. For example, one workflow rule changes issue attributes in such way that the issue starts to match another workflow rule conditions, and so on. In such case all changes made by these workflows will be roll-backed.
The if operator has the standard branch operator behavior.
Also there are additional else { } and else if { } operators.

Back to top>>

Controls

The are specific to the workflow language operators required, message and also family of logging operators: debug, info, warn, error, fatal.

Every field has the required(<message>) control. If the field value is null it is highlighted and the provided message is shown up.
The message statement shows up the blue pane on the screen top with the provided message text.
All these methods log the messages into the log files worklfow.log, youtrack.log. The errors and fatal also logs messages into the errors.log.

Back to top>>

Issue-specific methods

There are more interesting and important issue-specific methods in the workflow language: applyCommand(), addComment(), addTag(), removeTag(), clearAttachment(), isReported(), hasTag().

The method applyCommand(<command>) applies the specified by text command to the source issue.
The method addComment(<comment>) adds the new comment provided by the text parameter.
The method addTag(<tag>) adds the tag provided by the text parameter.
The method clearAttachments() deletes all issue attachments.
The method removeTag(<tag>) removes the tag provided by the text parameter.
isReported() is true for existing issues. The draft context is defined by !isReported() method.
The method hasTag(<tag>) answer whether issue has specified tag or not.
The isResolved() method is true, if all state-type fields are resolved. It there is at least one state-field in unresolved state, this method returns false.
The method sendMail(<email>, <subject>, <body>) sends the letter by the specified email.

Back to top>>

Working with dates

YouTrack workflow language provides the built-in DSL for dates, which allows you to format, compare, sum, and subtract dates.

The format(<format_string>) method gets the string representation of a date.
The following format options are available:
  • custom format — complete '#' and set the suite of date variables, e.g. "y M d";
  • shortDate, shortDateTime, shortTime, mediumDate, mediumDateTime, mediumTime, fullDate, fullDateTime, fullTime, longDate, longDateTime, longTime
Date constants are presented in the language by the pattern year-month-day.
Dates can be summed/subtracted with a period-type constant. The following period constants are supported:
  • millisecond(s)
  • second(s)
  • minute(s)
  • hour(s)
  • day(s)
  • week(s)
  • month(s)
  • year(s)
The result of the dates subtraction is period.
There is possibility to get 'milliseconds' value for a time period.

Back to top>>

Static references

It's allowing to reference some entity statically by the construction {category: static_entity_name}, {group: group_name}, {issue: issueID}, {project: project_shortName}, {savedSearch: savedSearchName}, {tag: tagName}, {user: username}.

All member of the group 'QA Engeneers' will be notified.
The issue 'IDEA-99999' must have the type "Feature".
The 'Currency' field values are taken for the project "Business Trips".
The loop by 'reported by current user but not assigned for it' issues.
The tag 'regression' is added onto the reopening issue.
Different static entities are using.

Back to top>>

User-related methods

The workflow user entity references a YouTrack user. It allows getting user's login, full name, and email attributes and supports a number of methods.

Get issues by the query.
  • getIssues(<saved search>, <query>);
Check if user can vote for the issue and do it if can.
  • canVoteIssue(<issue>);
  • voteIssue(<issue>);
  • unvoteIssue(<issue>);
  • canUnvoteIssue(<issue>);
Get shared and private issue tags.
  • getSharedTag(<tag_name>);
  • getTag(<tag_name>, <create_new>);
Creates new issue. Note, in the same workflow it's need to set the issue *summary *because issue can be created with empty summary.
  • createNewIssue(<projectName>);
    Also there additional methods:
  • getVisibleName();
Check if user has appropriate permissions.
  • watchssue(<issue>);
  • unwatchIssue(<issue>);
  • hasRole(<role_name>);
  • isInGroup(<gropp_name>);
Send letter to the project leader.
  • notify(<title>, <content>, <ignoreNotifyOnOwnChangesSetting>) (and its alias sendMail(<subject>, <body>)).
  • sendJabber(message);

Back to top>>

String methods

There are a lot of methods to working with strings, e.g. startsWith(), substring(), indexOf() etc. Look details on the Apache StringUtils reference.

This piece of code parses the expression to terms.
This rule extracts mentioned in comment user login from the "@username" substing and sends the notification to it.

Back to top>>

Fields-specific methods

There are number of methods which are specific to entity types project, comment, tag, group, enum filed, state, owned field, version, build, integer, period.

Project

One can access the project properties shortName, leader, name, issues, fields, description, createdBy. The methods getUser(<name>) and valuesFor(<field>) are available as well.

The simple way to create new issue on behalf of given user in the selected project.
The rule shows up the message if at least one of 'Fix versions' is overdue.
The way to get all project issues.

Back to top>>

Comment

The comment entity has the properties author, created, issue, permittedGroup, text, updated, updatedBy and the method getUrl().

The 'Assignee' is set to the just added comment reporter.
The 'Due date' is set to the last existing comment created date.
If the word "fix:" is met on the adding new comment than the 'State' becomes 'Fixed'.
Prohibit to restrict adding a new  comment by the group not equal to the issue visibility group.

Back to top>>

Tags

The tag entity has two properties: name and owner.

Check if user is trying to add not own tag.

Back to top>>

Other fields

Groups

The group has properties addNewUser, allUsersGroup, description, name and methods getUsers(), notifyAllUsers().

Gets all the group 'Assignees group' users.
The rule notifies all the members of the issue permitted group before its changing.

Back to top>>

Enums

The standard fields 'Priority', 'Type' have the type 'enum'. Enum fields has the properties name, description, ordinal, colorIndex and method getPresentation().

The rule constructs the 'Property' field presentation text.
Show the message if getPresentation() is differed from the name. It seems it shouldn't appears ever :)

Back to top>>

States

State entity has isResolved, description, name, ordinal and getPresentation() method.

This code calculates the highest state along the 'State' values.

Back to top>>

Owned field

The standard 'Subsystem' field has the type 'ownedField'. It has the properties owner, description, name, ordinal and getPresentation() method.

Set current 'Subsystem' owner to the 'Assignee'.

Back to top>>

Version

The field of type 'Version' has the properties archived, released, releasedDate, description, name, ordinal and getSprint(), getPresentation() methods.

The sprint cab be accessed by the version.getSprint(<project>) and has two properties start and finish.

This rule shows up the current sprint start and finish dates.

Back to top>>

Build

The field of type 'Build' has the properties assembleDate, description, name, ordinal and getPresentation() method.

The build assemble date is set to the 'Due date' field.

Back to top>>

Integer

A field of the 'Integer' type inherits all standard properties as any other issue field but also behaves as the primitive type, and thus supports the following standard operations: +, -, &, /, %, comparison operations: <, <=, >, >=+, increment/decrement i++, i--, ++i, --i.

Increases the 'Internal number' by 1.

Back to top>>

Period

The 'period' type time field is often used in combination with the date fields.

The 'Spent time' period is a result of subtracting the given time stamp 'Due date' from the current time stamp.

Back to top>>

Localization

Generally, we assume that users will use text strings (notifications, messages, etc.) in one same language. That is, we assume that users create not multi-lingual workflows.
If you create a workflow rule without specific tag for localization, then text strings in such rules will be shown in the same language and will not be auto-translated with the change of the system language. For example, let's say you use Spanish localization, and you create a workflow with texts in Spanish. In this case, if you choose to switch the system language back to English, your custom workflow will still have texts in Spanish.

However, there is a way to create a multi-lingual workflow that will be auto-translated along with the UI texts and default workflows when you switch to another system language.
To implement such workflow, you should use l10n construction for your texts. Please see the example below.

This workflow shows the French text independently of the chosen system language.
There is a way to localize you own workflow on different languages:
  1. Copy any l10n( text ) entity from any of the default workflows and past it wherever needed.
  2. Standing on the l10n open the 'Inspector panel' in the right bottom corner of Workflow Editor (Alt+2)
  3. Create new unique id for the string and replace the existing one.
  4. Add this key with the text string to all of the translation files that you need. For more details, please refer to the reference

Back to top>>

Project-based Reports

In YouTrack, generally, all workflow rules are applyed in the context of an issue. However, in some cases it would have been useful to apply rules in a more global context - in the context of a project, which would provide us opportunity to implement, for example, project-based reports. Luckily, we have a trick allowing us to invoke stateless/schedule rule in the project context.

The example below shows how you can implement a weekly report about unassigned issues in a project. Such report is sent on Mondays, at noon to the project's Leader.

A-1 — is a random issue that virtually implement rule's context and is not actually used in the rule. This workflow sends the weekly report containing list of all unassigned issues in the project A.

Back to top>>

Labels:
reference reference Delete
workflow workflow Delete
language language Delete
method method Delete
type type Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.