Writing YouTrack Workflows in Your IDE

Scott Adams

When we first introduced YouTrack workflows in JavaScript, we also released a built-in editor for writing workflow rules and scripts. While many users enjoy the convenience of writing workflows directly in YouTrack, it does have its limitations.

If you would rather write code in your favorite IDE, you can turn that frown upside-down right now. We’ve tapped into the power of the npm registry service* to let you manage workflows just as you would any other codebase. With the utilities that we have published to this service, you can enjoy the following advantages:

• Write workflows without leaving your development environment. Enjoy full-featured code completion and keyboard support.
• Edit and refine multiple scripts simultaneously.
• Make iterative offline improvements and deploy updates only when your code is tried and tested.

In this article, we show you how to work with the package manager and update workflows using your own software development tools. With each step, we provide an increasing level of functionality and complexity. This lets you build up your toolkit bit by bit and extend the capabilities of your platform at your own pace.

These instructions are not specific to any single platform. You should be able to configure any environment that supports JavaScript to write and manage workflow scripts for YouTrack.

TL;DR: If you’re already familiar with npm, our custom workflow repository is already set up to support YouTrack workflow development in an IDE. Follow the setup instructions in the README and use our package.json to reverse-engineer your environment.

1 — Lay the Groundwork

Follow the instructions in this section to enable basic support for YouTrack workflows in your IDE.

Install Node.js**

We’ve published two utility packages for workflows to the npm public registry. To work with these packages, you need to install and run Node.js. We recommend that you use Node.js version 8.9.1 LTS or later.

When you install Node.js, the npm package manager is also installed automatically.

Build a package.json File

Node.js uses package.json files to store metadata and project dependencies. You can build the file step-by-step with the npm init command. To build the package.json file:

1. In your command-line interface (CLI), enter npm init.
   This starts a utility that helps you build the JSON file.
2. For each field in the file, specify a new value or press Enter to accept the suggested value. Once you have specified values for all of the fields, the JSON is displayed in the CLI.
3. Confirm the creation of the file by accepting the prompt Is this ok? (yes). The package.json file is added to the current project.

Install the YouTrack Scripting API Package

The first package you want to install contains the complete YouTrack workflow API. When you plug this package into your code editor, your code-completion tools suggest valid functions, methods, and properties for all of the entities that are available in the YouTrack workflow API.

Enter the following command to install the package in your devDependencies:

npm install –save-dev @jetbrains/youtrack-scripting-api

Install the YouTrack Scripting Package

The second package you can install contains utility scripts. These scripts help you manage YouTrack workflows when you work in an external code editor.

Enter the following command to install this package in your devDependencies:

npm install –save-dev @jetbrains/youtrack-scripting

Now, you have a few predefined scripts that you can enter in a command-line interface. These scripts support the following commands:

• list — Lists all of the workflows that are available in your YouTrack installation.
• download — Downloads the specified workflow from your YouTrack installation.
• upload — Uploads the workflow from the specified directory to your YouTrack installation.

For a complete description of each command and its parameters, refer to the YouTrack documentation.

As long as your installation doesn’t use a certificate that is issued by your own certificate authority (CA) or is self-signed, you can establish a connection using a personal permanent token. You can generate your own permanent tokens on the Authentication tab of your Hub profile. For instructions, refer to the YouTrack documentation.

If you are using a certificate that is not issued by a known CA, you need to use specific variables in your Node.js environment to enable a connection between your IDE and the YouTrack installation. Follow the special instructions in the last section of this article.

If you have just a few custom workflows and don’t need to update them very frequently, you might get by with the basic scripting package. For regular updates, the need to specify a host and token with each request is a bit unwieldy. Follow the instructions in the next section to simplify this process and use these commands with fluidity.

2 — Flip the Script

You can streamline the commands that are supported by writing your own script. This script extracts the variables that you use to establish a connection to your YouTrack installation and stores them in your local configuration.

Save Your Token

The first parameter that you want to extract and store locally is the permanent token that you use for authentication. To keep this token safe, you want to store it in your personal configuration file.

To add your permanent token to your per-user config file:

1. Follow these instructions to generate a permanent token. When you generate the token, add the YouTrack service to the Scope input field.
2. Copy the token to your clipboard.
3. Switch to the command-line interface in your IDE and add the token to your per-user config file with the following command:
   npm config set token_prod <token>
   Replace <token> with the permanent token from your clipboard.
   Of course, you can name your variables as you like. But as you continue with this guide, you’ll see that these naming conventions follow a pattern.
4. Verify that the token has been added to your configuration with this command:
   npm config list –json

Save Your Host

Next, you want to save the address of your YouTrack installation that you reference as the host parameter. You can save this parameter in your per-user config file as well.

To store this variable:

1. Enter the following command in your CLI:
   npm config set host_prod <address>
   Replace <address> with the base URL of your YouTrack installation. For an InCloud instance, be sure to include the trailing /youtrack.  
2. Verify that the variable has been added to your configuration with this command:
   npm config list –json

Go Cross-platform

This next step is optional if you’re on a Linux or *nix-based operating system. It’s also not entirely required for Windows users who know how to set their environment variables correctly, but you’ll need to adapt all of the scripts accordingly. For best results, we recommend that you follow these instructions anyway. As you delve deeper into this guide, you’ll see why.

References for environment variables vary by operating system. To ensure that your scripts work in any environment, you can install a package that lets you set and use environment variables across platforms.

Our preferred package is cross-env. It automatically converts each variable to use the correct syntax for your operating system at runtime.

To install this package in your devDependencies, enter the following command:

npm install –save-dev cross-env

Now you can set all of your variables as if you were running on a POSIX system. If you open your package.json file, you’ll see that the package was added to your devDependencies automatically.

If you encounter problems with cross-env, try cross-var instead. You should be able to achieve the same outcome.

Customize Your Commands

The last step is to write a script that references these parameters. You can add these scripts directly to the scripts field in your package.json and run them from the command line. Use the following example as a guide.

{
  "name": "myyoutrackworkflows",
  "version": "1.0.0",
  "description": "Custom workflows for my YouTrack installation",
  "scripts": {
    "list-prod": "cross-env youtrack-workflow list --host=$npm_config_host_prod --token=$npm_config_token_prod",
    "download-prod": "cross-env youtrack-workflow download --host=$npm_config_host_prod --token=$npm_config_token_prod",
    "upload-prod": "cross-env youtrack-workflow upload --host=$npm_config_host_prod --token=$npm_config_token_prod"
  },
  "author": "Me",
  "devDependencies": {
	"@jetbrains/youtrack-scripting": "0.0.20",
	"@jetbrains/youtrack-scripting-api": "2017.4.37672"
	"cross-env": "^5.1.1"
  }
}

At this point, you can run all of the commands that are supported by the youtrack-scripting package without having to specify the variables for your host and token. Use the following commands to run your scripts:

• npm run list-prod
• npm run download-prod — <workflow name>
• npm run upload-prod — <workflow name>

The basic process is as follows:

1. Use the download command to copy workflows from your installation to your development environment.
2. Make your changes.
3. Use the upload command to update the workflow in YouTrack.

Keep in mind that you’re still pushing updates straight to your production environment. For many developers, it’s like playing with fire. If you’d like to work in a more controlled manner, follow the instructions in the next section to play it safe.

3 — Connect to a Test Environment

One of the major advantages of using an external editor to write workflows is that you can connect to multiple YouTrack installations. As with any code development project, you should first upload and test your changes in a sandbox environment. Only when you’re sure it’s working as intended should you deploy the code in production.

We recommend that you use one of the following options to test your workflows.

Build Your Own Sandbox

Our free 10-user plan is a great solution for testing workflows.

• If your production environment is a YouTrack Standalone installation, you can download and install a local copy and use the free plan. You can update your local installation to the same version as your production environment to ensure your workflows behave as expected.
• If you use YouTrack InCloud, you can sign up for a test instance and switch to the free 10-user plan at any time. Our hosted servers are upgraded to the latest version of YouTrack automatically.

Because of license restrictions for the free plan, you can’t test workflows that set or change the visibility for issues and comments.

Play in the Sand at a Public Beach

We have set up a YouTrack InCloud test instance for testing workflows. Anyone can register to access this instance and use it as a sandbox. When you register, you are given the Global Project Admin role and can test custom workflows in any project.

This instance is not subject to any license restrictions and can be used to test workflows that manage issue and comment visibility.

Update Your Development Environment

Once you have set up an account in a test environment, you can add the variables from this installation to your configuration file and update your script. Follow these steps:

1. Store the permanent token from your test environment in your configuration file with the following command:
   npm config set token_test
2. Store the hostname for your test environment with the following command:
   npm config set host_test
3. Update your package.json file to include scripts that let you manage workflows in your test environment. Use the following example as a guide.

{
  "name": "myyoutrackworkflows",
  "version": "1.0.0",
  "description": "Custom workflows for my YouTrack installation",
  "scripts": {
    "list-prod": "cross-env youtrack-workflow list --host=$npm_config_host_prod --token=$npm_config_token_prod",
    "download-prod": "cross-env youtrack-workflow download --host=$npm_config_host_prod --token=$npm_config_token_prod",
    "upload-prod": "cross-env youtrack-workflow upload --host=$npm_config_host_prod --token=$npm_config_token_prod",

    "list-test": "cross-env youtrack-workflow list --host=$npm_config_host_test --token=$npm_config_token_test",
    "download-test": "cross-env youtrack-workflow download --host=$npm_config_host_test --token=$npm_config_token_test",
    "upload-test": "cross-env youtrack-workflow upload --host=$npm_config_host_test --token=$npm_config_token_test"
  },
  "author": "Me",
  "devDependencies": {
	"@jetbrains/youtrack-scripting": "0.0.20",
	"@jetbrains/youtrack-scripting-api": "2017.4.37672"
	"cross-env": "^5.1.1"
  }
}

Now you can play with fire and not get burned! Your typical process would look something like this:

1. Download a workflow from your production environment with the command:
   npm run download-prod — <workflow name>
2. Update the workflow in your IDE.
3. Upload the modified workflow to your test environment with the command:
   npm run upload-test — <workflow name>
4. Test the workflow in your YouTrack sandbox environment.
5. Repeat steps 2 through 4 until your workflow behaves as expected.
6. Upload the final version of your workflow to your production environment with the command:
   npm run upload-prod — <workflow name>

If you are the only person who is responsible for the customization of your YouTrack installation, you might choose to end your journey here. With this setup, you can safely update your workflows while working exclusively in your favorite development environment.

When there are other developers in your organization who write scripts for their own projects, you might want to get everyone to work together. Follow the instructions in the next section and share this setup with your team.

4 — Be a Team Player

One of the biggest advantages of the setup in this section is that supports collaboration. With a few modifications, you can build a platform that other developers can use to manage workflows in your YouTrack installation. As this setup is not specific to any single environment, these developers can be working with any IDE that supports JavaScript in any operating system.

Update Your Script

The first thing you can do is modify your package.json file. Each of the developers who work with this setup will need to generate and store their own personal tokens, but the variables that are used for the host are the same for everybody.

To streamline the setup for other users, you can pull these variables into the package.json file and update the references in your scripts. Use the following example as a guide.

{
  "name": "ouryoutrackworkflows",
  "version": "1.0.0",
  "description": "Custom workflows for our YouTrack installation",
  "config": {
    "host_prod": "https://youtrack.company.com",
    "host_test": "https://workflow.myjetbrains.com/youtrack"
  },
  "scripts": {
    "list-prod": "cross-env youtrack-workflow list --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "download-prod": "cross-env youtrack-workflow download --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "upload-prod": "cross-env youtrack-workflow upload --host=$npm_package_config_host_prod --token=$npm_config_token_prod",

    "list-test": "cross-env youtrack-workflow list --host=$npm_package_config_host_test --token=$npm_config_token_test",
    "download-test": "cross-env youtrack-workflow download --host=$npm_package_config_host_test --token=$npm_config_token_test",
    "upload-test": "cross-env youtrack-workflow upload --host=$npm_package_config_host_test --token=$npm_config_token_test"
  },
  "author": "Me",
  "devDependencies": {
	"@jetbrains/youtrack-scripting": "0.0.20",
	"@jetbrains/youtrack-scripting-api": "2017.4.37672"
	"cross-env": "^5.1.1"
  }
}

Notice how we added these variables to the config field and updated the scripts to read these variables from the package.json file with $npm_package_config instead of just $npm_config.

Go Repo

Repositories are great places for storing collaborative work. Why not do the same with your workflow code? Uploading your workflow project to a repository has the following advantages:

• You provide a centralized location where everyone can access your project files, including the package.json file that supports your scripts.
• Your repository supports version control. You can apply iterative updates to your workflow scripts. If you encounter problems with an updated workflow in production, you can always roll back to the last stable version.
• Multiple users can work on the same script without having their respective changes overwritten.
• You can use branching and pull requests to implement formal development and testing processes.

When you upload your project to a repository, other users can follow these steps and start coding:

1. Connect to the repository and download a local copy of the project. Be sure to include the package.json in your project files.
2. Generate personal permanent tokens for the YouTrack installations that are supported in each script and save them as variables in their personal configuration file.

Now each developer should be able to perform the following actions:

• Download files from the repository.
• Update workflow scripts in their local environment.
• Upload and test their updates in the sandbox until they behave as expected.
• Upload the revised scripts to the production environment.
• Push their changes back to the repository, updating the version of the revised script.

For a real-life example, check out our YouTrack Custom Workflow Repository. Here, we upload workflows that support a range of use cases that are not covered by the default workflows in YouTrack. Everyone is welcome to download scripts from the repository and adapt them to suit specific business cases. If you have a script that you’d like to share with the community, submit a pull request!

Special Instructions for SSL Certificates

If your YouTrack domain uses an SSL certificate that is issued by a known certificate authority, you can establish a connection using just your personal permanent token. Your certificate is already included in CA certificate store that is built into Node.js. For certificates that are issued by a CA that is not recognized automatically or is self-signed, you need to modify the environment variables in Node.js to recognize or ignore your certificate.

Private Certificate Authorities

If your certificate is issued by a CA that is not recognized automatically, you need to add your certificate to the list of certificates that are recognized by Node.js.

To add your certificate, use the environmental variable NODE_EXTRA_CA_CERTS=file in your scripts. This variable is supported in Node.js versions v7.3.0 (or LTS versions 6.10.0 and 4.8.0) and later.

To work with a private certificate:

1. Open your YouTrack installation in a web browser.
2. User your browser tools to export the certificate. Specific instructions vary for different browsers.
3. Store the certificate file in a directory that is accessible from your development environment.
4. Set the reference to the directory in your private configuration. For example:
   npm config set cert_prod <path>
   Replace <path> with the full path to the certificate file.
5. Modify your scripts to reference the extra CA certificate. Use the following example as a guide.

{
  "name": "ouryoutrackworkflows",
  "version": "1.0.0",
  "description": "Custom workflows for our YouTrack installation",
  "config": {
    "host_prod": "https://youtrack.company.com",
  },
  "scripts": {
    "list-prod": "cross-env NODE_EXTRA_CA_CERTS=\"$npm_config_cert_prod\" youtrack-workflow list --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "download-prod": "cross-env NODE_EXTRA_CA_CERTS=\"$npm_config_cert_prod\" youtrack-workflow download --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "upload-prod": "cross-env NODE_EXTRA_CA_CERTS=\"$npm_config_cert_prod\" youtrack-workflow upload --host=$npm_package_config_host_prod --token=$npm_config_token_prod",

  },
  "author": "Me",
  "devDependencies": {
	"@jetbrains/youtrack-scripting": "0.0.20",
	"@jetbrains/youtrack-scripting-api": "2017.4.37672"
	"cross-env": "^5.1.1"
  }
}

Self-signed Certificates

If you work in a closed environment and use a self-signed certificate, you can disable the secure connection over TLS with the environmental variable NODE_TLS_REJECT_UNAUTHORIZED=0.

The following example shows you how to connect to a local machine with the TLS connection disabled.

{
  "name": "ouryoutrackworkflows",
  "version": "1.0.0",
  "description": "Custom workflows for our YouTrack installation",
  "config": {
    "host_local": "http://localhost:8081/",
  },
  "scripts": {
    "list-local": "cross-env NODE_TLS_REJECT_UNAUTHORIZED=0 youtrack-workflow list --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "download-local": "cross-env NODE_TLS_REJECT_UNAUTHORIZED=0 youtrack-workflow download --host=$npm_package_config_host_prod --token=$npm_config_token_prod",
    "upload-local": "cross-env NODE_TLS_REJECT_UNAUTHORIZED=0 youtrack-workflow upload --host=$npm_package_config_host_prod --token=$npm_config_token_prod",

  },
  "author": "Me",
  "devDependencies": {
	"@jetbrains/youtrack-scripting": "0.0.20",
	"@jetbrains/youtrack-scripting-api": "2017.4.37672"
	"cross-env": "^5.1.1"
  }
}

Even though this type of workaround is often done in a development environment, it is not secure. If you are not aware of the potential pitfalls, avoid this practice. Never use this variable to connect to your production environment.

*npm is a trademark of npm, Inc.
**Node.js is a trademark of Joyent, Inc. and is used with its permission. We are not endorsed by or affiliated with Joyent.

Subscribe to YouTrack Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!