Developer Portal for YouTrack and Hub Help

Converting Old Workflows to JavaScript

Prior to YouTrack 2017.2, workflows were written in a domain-specific language in an external YouTrack Workflow Editor. YouTrack 2018.3 requires that all new workflows are written in JavaScript.

Later this year, we plan to remove the logic that supports legacy workflows completely. As a result, any legacy workflow that is still attached to a project in YouTrack will stop working.

In YouTrack 2020.5, the logic that supported legacy workflows has been removed completely. As a result, any legacy workflow that is still attached to a project in YouTrack will stop working.

If you still rely on legacy workflows to support your business processes, follow these instructions to migrate them to JavaScript.

Convert Workflows Manually

To ensure that your old workflows work exactly as they did before, we recommend that you rewrite them yourself in JavaScript. Use the information that is provided in this section of the documentation to learn how to manipulate issues in this programming language.

The main advantage of rewriting your own workflows is that you can increase your knowledge and discover new applications for workflows in your projects. We've added new methods to JavaScript workflows that give you even greater control over when and how you can update issues.

Convert Workflows Automatically

For those without the time or patience to rewrite their workflows from scratch, we offer a web-based tool for converting old workflows.

To convert an old workflow to JavaScript:

  1. In the Core Features section of the Administration menu, select Workflows.

  2. Select one or more workflows from the list. To export multiple workflows, your browser must allow pop-ups for YouTrack.

  3. Click the Export button in the toolbar.

    Export workflows
    • The selected workflows are exported from the server and downloaded to your local directory as ZIP archive.

  4. Open the JetBrains YouTrack Workflow Converter.

    Workflow converter upload

  5. Click the Browse button and select a ZIP archive that you exported from YouTrack.

  6. Click the Convert button.

    • The workflow converter unpacks the archive and converts the workflow to JavaScript. The conversion job status is shown as WAITING.

    Workflow converter waiting

    This process may take some time. Don't close the browser tab or navigate away from the page. When finished, the conversion job status is shown as COMPLETED.

    Workflow converter completed
  7. Click the Download JS workflow link.

    • The converted workflow workflow downloads to your local directory as ZIP archive.

  8. Return to the Workflows page in YouTrack.

  9. Click the Import workflow button in the header, then select the ZIP archive that contains the converted workflow.

    Import workflow
    • The converted workflow is imported into YouTrack.

The conversion scripts are designed to generate valid workflows in JavaScript, but will never be as concise and readable as code that was written by a human. Once you have imported your converted workflows, you can open the scripts in the built-in workflow editor and use the code inspection tool to optimize them.

Workflow converter code inspection

We also strongly recommend that you attach converted workflows to a test project and verify that they work as expected before using them in a live project.

Workflow Support

Whether you rewrite your workflows manually or use the automated converter, we're here to help make sure your new workflows behave exactly as expected. If you're struggling with a workflow that isn't doing what you want it to, reach out.

  • Join our YouTrack Workflow Community in Slack. Here, you can interact directly with our developers and learn from other users who support their own use cases with workflows.

  • Submit a support request. Our support engineers are workflow-savvy and can help you sort out any problem you encounter.

Last modified: 24 February 2023