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 that you can import into your code editor.

Package Installation

To work with the scripting package, 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 package in your development environment. The installation process varies based on the tool that you use to write your code. If you’re working with an IDE from JetBrains, follow the instructions provided in the documentation:

The easiest way to get started is to install the package globally with the following command:

npm install -g <package name>

@jetbrains/youtrack-scripting-api

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

@jetbrains/youtrack-scripting

The second package contains utility scripts that help 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` — The domain name of your YouTrack installation. `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 profile. 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. Here, you also need to specify values for the `--host` and `--token` parameters to gain authorized access to YouTrack. This command uses the following syntax: `youtrack-workflow download <workflowName> [--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. Specify values for the `--host` and `--token` parameters to gain authorized access to YouTrack. This command uses the following syntax: `youtrack-workflow upload <dir>`

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 — The domain name of your YouTrack installation.
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 profile. 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.
Here, you also need to specify values for the --host and --token parameters to gain authorized access to YouTrack.
This command uses the following syntax:

youtrack-workflow download <workflowName> [--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.
Specify values for the --host and --token parameters to gain authorized access to YouTrack.
This command uses the following syntax:

youtrack-workflow upload <dir>

Last modified: 7 March 2019