JavaScript Workflow Reference
Starting from YouTrack 2017.2, you don't have to write workflows in a domain-specific programming language. Just use JavaScript!
JavaScript is arguably the most popular programming language in the world today. If you yourself aren't familiar with it, chances are that there is someone in your organization who is fluent. By switching to JavaScript, we hope to make writing workflows for YouTrack more accessible than ever.
That said, to create your own workflows, you do need write some code. This requires a basic understanding of JavaScript. Luckily, there are a lot of resources available on the web, one of the best of which is provided by the Mozilla Foundation, who continues to oversee the development of the language.
This also means that you don't need to do anything out of the ordinary when you write workflows in JavaScript. You can use any of the declarations, variables, constants, data types, literals, functions, expressions, and operators that are supported in JavaScript when you write a workflow.
This section of the documentation provides a few guidelines that help you understand how to work with the custom properties and methods that are specific to the workflow API. For a complete list of functions, properties, and methods, refer to the YouTrack Workflow API.
Updates for YouTrack 2018.1
Our JavaScript implementation is based on Rhino. For the 2018.1 release, we adopted Rhino version 1.7.7.2. This means that all of the features from ES6 /JS2015 that are supported in this version of Rhino are also available for workflows in YouTrack.
Major changes include:
Support many ES6 additions to the
Math
class.Support many ES6 additions to the
Number
class.Support ES6 additions to the
String
class.Initial support for ES6 method definitions.
Conversion of native
Error
instances to JSON.Compatibility fixes for
Date
,Array
, andString
, among others.Support for methods
Array.find()
andfindIndex()
.Support for methods
String.trimLeft()
andtrimRight()
.Support for V8
Error
extensions, includingError.captureStackTrace
.Support for typed arrays.
Support for attaching "external data" as the indexed properties of any object.
To see which of the advanced JavaScript features from ES5, 6, and 7 are available for workflows in YouTrack, refer to the Rhino compatibility table. All of the features that are compatible with rhino177 are supported.
Major Changes from the Previous Workflow Programming Language
Switching to JavaScript changes how you reference specific entities and properties when you write a workflow. Here is a short list of the major changes in comparison to the previous API:
The
issue
reference is never omitted. You can't call an issue method assuming that it references an issue from the context — you must reference the issue explicitly.- Property-related methods are spelled differently. Also, these functions are now properties. Get methods are simplified.
MPS-based API
JavaScript API
issue.becomesResolved(), issue.becomesReported()
issue.becomesResolved, issue.becomesReported
issue.getId(), issue.getUrl()
issue.id, issue.url
- Fields-related keywords are now methods.
MPS-based API
JavaScript API
X.required
issue.fields.required(ctx.X, <message>)
X.changed
issue.fields.isChanged(ctx.X)
X.becomes
issue.fields.becomes(ctx.X, <ctx.X.value>)
X.oldValue
issue.fields.oldValue(ctx.X)
- Global keywords and warning statements have changed.
MPS-based API
JavaScript API
message
workflow.message(<message>)
(see '@jetbrains/youtrack-scripting-api/workflow' module)assert
workflow.check(<condition>, <message>)
(see '@jetbrains/youtrack-scripting-api/workflow' module)loggedInUser
ctx.currentUser
now
Date.now()
(standard JS date API) - Some methods are changed completely:
MPS-based API
JavaScript API
loggedInUser.createNewIssue(<project name>)
new entities.Issue(<user>, <project>, <summary>)