# 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 packages to the [npm registry service](https://www.npmjs.com/) 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. > **Note:** > npm is a trademark of npm, Inc. ## Workflow API Package The [youtrack-scripting-api](https://www.npmjs.com/package/@jetbrains/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. ## YouTrack App Tools The [youtrack-apps-tools](https://www.npmjs.com/package/@jetbrains/youtrack-apps-tools) package contains utilities that help you manage YouTrack app packages when you work in an external code editor. This lets you write and update apps and 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 app packages 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](Manage-Permanent-Token.html). This command uses the following syntax: ```SHELL youtrack-app list --host --token ``` | | download | This command downloads the referenced app package from your YouTrack installation. If you don't specify a directory with the output parameter, a directory with the name is created in the current working directory. The app package files are extracted into the new directory. Otherwise, the app package is downloaded into the directory that is specified in the output parameter. This command uses the following syntax: ```SHELL youtrack-app download --host --token [--output, --overwrite] ``` | | upload | This command uploads the app package from the specified directory to your YouTrack installation. First, the script checks the reference directory for a `manifest.json` file that contains the name of the app. For compatibility with older workflow packages, the script also accepts a `package.json` file. If neither file is present or the file does not specify the app name, the name of the directory is used as the name of the uploaded app. This command uses the following syntax: ```SHELL youtrack-app upload --host --token ``` | ## Package Installation To work with these packages in your IDE, you need to install and run [Node.js](https://nodejs.org/en/). 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 API package and app tools in your development environment. The easiest way to get started is to install the package globally with the following commands: ```SHELL npm install -g @jetbrains/youtrack-scripting-api npm install -g @jetbrains/youtrack-apps-tools ``` If you prefer to install packages as dependencies in your development environment, enter: ```SHELL npm install --save-dev @jetbrains/youtrack-scripting-api npm install --save-dev @jetbrains/youtrack-apps-tools ``` 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](Manage-Permanent-Token.html#obtain-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](#special-instructions-ssl-certificates). If you have just a few custom workflows and don't need to update them very frequently, you might get by with basic commands. 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 Environment Variables You can streamline app tool commands by storing your connection details in environment variables instead of passing them to every command. The `youtrack-app` command reads the following environment variables: * `YOUTRACK_HOST` - the base URL of your YouTrack installation. For YouTrack Cloud instances hosted on `myjetbrains.com`, include the trailing `/youtrack`. * `YOUTRACK_API_TOKEN` - a permanent token that grants access to the YouTrack service. You can generate your own permanent tokens on the Authentication tab of your Hub account. For instructions, see [Create a Permanent Token](Manage-Permanent-Token.html#obtain-permanent-token). Store these values in your shell profile, IDE run configuration, or secret manager. If you also pass `--host` or `--token` to a command, the command-line values take precedence over the environment variables. > **Note:** > Do not store permanent tokens in `package.json` or commit them to a version control system. The last step is to write scripts that run the supported commands. The quickest way is to create a `package.json` file and add your scripts to the scripts field. This `package.json` file is an npm project file that stores command scripts and development dependencies. The descriptor file for the app or workflow package is `manifest.json`. Procedure: 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. ```JSON { "name": "myyoutrackworkflows", "version": "1.0.0", "description": "Custom workflows for my YouTrack installation", "scripts": { "list-prod": "youtrack-app list", "download-prod": "youtrack-app download", "upload-prod": "youtrack-app upload" }, "author": "Me", "devDependencies": { "@jetbrains/youtrack-apps-tools": "0.0.XX", "@jetbrains/youtrack-scripting-api": "20XX.X.XXXXX" } } ``` Set the values for the `@jetbrains/youtrack-apps-tools` and `@jetbrains/youtrack-scripting-api` parameters to match the current versions of these packages. At this point, you can run the commands without specifying the values for your host and token. Use the following commands to run your scripts: * `npm run list-prod` * `npm run download-prod -- ` * `npm run upload-prod -- ` The basic process is as follows: 1. Use the `download` command to copy an app package from your installation to your development environment. 2. Make your changes. 3. Use the `upload` command to update the app package in YouTrack. Keep in mind that you're still pushing updates straight to your production environment. If you'd like to work in a more controlled manner, follow the instructions in the next section. ## 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 use the test environment values when you run your app tool commands. Procedure: To adapt your script to connect to a test environment: 1. Generate a permanent token in your test environment. 2. Set `YOUTRACK_HOST` to the base URL of your test environment. 3. Set `YOUTRACK_API_TOKEN` to the permanent token from your test environment. 4. Run the same scripts that you use for production. The app tools use the host and token from the current environment. Your typical process would look something like this: 1. Download an app package from your production environment with the command: ``` npm run download-prod -- ``` 2. Update the workflow in your IDE. 3. Switch `YOUTRACK_HOST` and `YOUTRACK_API_TOKEN` to the values for your test environment. 4. Upload the modified package to your test environment with the command: ``` npm run upload-prod -- ``` 5. Test the workflow in your YouTrack sandbox environment. 6. Repeat steps 2 through 5 until your workflow behaves as expected. 7. Switch `YOUTRACK_HOST` and `YOUTRACK_API_TOKEN` back to the values for your production environment. 8. Upload the final version of your package to your production environment with the command: ``` npm run upload-prod -- ``` 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 it 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 commit a shared npm `package.json` file. Each developer who works with this setup needs to generate and store their own personal token, but the scripts can be shared by everyone. Use the following example as a guide. ```JSON { "name": "ouryoutrackworkflows", "version": "1.0.0", "description": "Custom workflows for our YouTrack installation", "scripts": { "list": "youtrack-app list", "download": "youtrack-app download", "upload": "youtrack-app upload", "validate": "youtrack-app validate" }, "author": "Me", "devDependencies": { "@jetbrains/youtrack-apps-tools": "0.0.XX", "@jetbrains/youtrack-scripting-api": "20XX.X.XXXXX" } } ``` The scripts read the host and token from `YOUTRACK_HOST` and `YOUTRACK_API_TOKEN`. This lets each developer choose the target YouTrack installation in their local environment without changing the shared project files. 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 npm `package.json` file in your project files. * Generate personal permanent tokens for the YouTrack installations that they use and save them as environment variables. 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](https://github.com/JetBrains/youtrack-workflows). 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 environment 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. Procedure: To work with a private certificate: 1. Open your YouTrack installation in a web browser. 2. Use 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 `NODE_EXTRA_CA_CERTS` to the full path to the certificate file in the same environment where you store `YOUTRACK_HOST` and `YOUTRACK_API_TOKEN`. 5. Run your `youtrack-app` scripts as usual. Node.js reads the extra certificate from the environment variable. ### 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 environment variable `NODE_TLS_REJECT_UNAUTHORIZED=0`. Set this variable in the same environment where you store the host and token for your local installation. Then run the `youtrack-app` commands as usual. 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.