Developer Portal for YouTrack and Hub Help

Using an External Code Editor

You can use the web-based workflow editor to make a quick edit or write a simple rule. But if you’re used to working in a full-featured development environment, you can actually write your workflows in any IDE that supports JavaScript.

To let you work where you're most comfortable, we've put together and published two packages to the npm registry service that you can install in your development environment. This functionality is 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.

Workflow API Package

The youtrack-scripting-api package 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 API.

Workflow Scripting Package

The youtrack-scripting package contains utilities that help you manage YouTrack workflows when you work in an external code editor. This lets you write and update workflows for YouTrack in JavaScript in your preferred development environment.

The package includes scripts that let you synchronize local changes with your YouTrack installation. The following commands are available:

Command

Description

list

This command lists all of the workflows that are available in your YouTrack installation. To use this command, specify the following parameters:

  • host — Your YouTrack base URL.

    For YouTrack Cloud instances hosted on myjetbrains.com, your base URL includes the trailing /youtrack. For example: https://company.myjetbrains.com/youtrack

  • token — A permanent token that grants access to the YouTrack service.

    You can generate your own permanent tokens to authenticate with YouTrack on the Authentication tab of your Hub account. For more information, see Manage Permanent Tokens.

    This command uses the following syntax:

    youtrack-workflow list --host --token

download

This command downloads the referenced workflow from your YouTrack installation.

If you don't specify a directory with the output parameter, a directory with the name <workflowName> is created in the current working directory. The workflow files are extracted into the new directory. Otherwise, the workflow is downloaded into the directory that is specified in the output parameter.

This command uses the following syntax:

youtrack-workflow download <workflowName> --host --token [--output]

upload

This command uploads the workflow from the specified directory to your YouTrack installation. First, the script checks the reference directory for a package.json file that contains the name of the workflow. If the file is not present or does not specify the workflow name, the name of the directory is used as the name of the uploaded workflow.

This command uses the following syntax:

youtrack-workflow upload <dir> --host --token

Package Installation

To work with these packages in your IDE, you need to install and run Node.js. This also installs the npm package manager that lets you work with the scripting package in your projects.

Next, install the workflow packages in your development environment. The easiest way to get started is to install the package globally with the following commands:

npm install -g @jetbrains/youtrack-scripting-api npm install -g @jetbrains/youtrack-scripting

If you prefer to install packages as dependencies in your development environment, enter:

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

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 account. For instructions, see Create a Permanent Token.

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. For instructions, see Special Instructions for SSL Certificates.

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.

Working with Custom Commands

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.

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. Generate a permanent token as described here. 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.

  4. Verify that the token has been added to your configuration with this command:

    npm config list --json

Next, 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 the host variable in your per-user config file:

  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 Cloud instance hosted on myjetbrains.com, be sure to include the trailing /youtrack.

  2. Verify that the token has been added to your configuration with this command:

    npm config list --json

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.

One such 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.

The last step is to write a script that references these parameters. The quickest way is to create a package.json file and add your scripts to the scripts field.

To create the file and build your script:

  1. In your CLI, enter the command 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 accept the suggested default. 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.

  4. Open the package.json file and edit the scripts field. You can also remove irrelevant fields from the file. 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.XX", "@jetbrains/youtrack-scripting-api": "20XX.X.XXXXX", "cross-env": "^5.1.1" } }

    Set the values for the @jetbrains/youtrack-scripting and @jetbrains/youtrack-scripting-api parameters to match the current version of the youtrack-scripting and youtrack-scripting-api packages, respectively.

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.

Connecting 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 create your own sandbox environment. Our free plan is a great solution for testing workflows.

  • If your production environment is a YouTrack Server 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 Cloud, you can register for a separate instance that uses the free plan. Our hosted servers are upgraded to the latest version of YouTrack automatically.

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.

To adapt your script to connect to a test environment:

  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.XX", "@jetbrains/youtrack-scripting-api": "20XX.X.XXXXX", "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 stop here. With this setup, you can safely update your workflows while working exclusively in your favorite development environment.

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

Working as a Team

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.

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.youtrack.cloud" }, "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.XX", "@jetbrains/youtrack-scripting-api": "20XX.X.XXXXX", "cross-env": "^5.1.1" } }

Notice how the references to the host are stored in the config field. The script is updated to read these variables from the package.json file with $npm_package_config instead of just $npm_config.

The last step is to upload your project to a repository. When you upload your project to a repository, other users can follow these steps and start coding:

  • Connect to the repository and download a local copy of the project. Be sure to include the package.json in your project files.

  • 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 project 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.XX", "@jetbrains/youtrack-scripting-api": "20XX.X.XXXXX", "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": "https://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.XX", "@jetbrains/youtrack-scripting-api": "20XX.X.XXXXX", "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.

Last modified: 7 October 2024