Developer Portal for YouTrack and Hub 2021.1 Help

JavaScript Workflow Reference

YouTrack lets you write workflows in JavaScript. A domain-specific programming language that was used for workflows in earlier versions of YouTrack was deprecated and completely dropped in YouTrack 2020.5.

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 JavaScript Workflow Reference.

JavaScript Compatibility

Our current JavaScript implementation is based on GraalVM JavaScript. One of the stated goals of this project is to be fully compatibility with the latest ECMAScript specification.

The JavaScript runtime that was included in earlier versions of YouTrack offered limited support of ES6/JS2015. This meant that you were limited to roughly 22% of the complete JavaScript feature set when writing workflows in YouTrack.

Major Changes from the Legacy 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 legacy workflow API:

  1. 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.

  2. 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
  3. 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)
  4. 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)

  5. Some methods are changed completely:

    MPS-based API

    JavaScript API

    loggedInUser.createNewIssue(<project name>) new entities.Issue(<user>, <project>, <summary>)
Last modified: 8 April 2021