Using an External Code Editor

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:

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

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.

note

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

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.

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.

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.

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

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

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