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:

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:

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

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, 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 InCloud instance, 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:

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

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 use one of the following options to test your workflows.

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

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.