YouTrack App Architecture

The runtime environment for YouTrack apps facilitates seamless integration and extension of YouTrack’s capabilities using modern JavaScript. Apps run in a sandboxed environment to ensure security and stability while allowing interaction with YouTrack entities such as issues, users, and projects through well-defined APIs.

A diagram that represents the environment for running apps in YouTrack.

The environment for running apps in YouTrack consists of several components that are described here.

Frontend Sandbox Environment

The YouTrack frontend contains a sandboxed environment for running app widgets. This sandbox is implemented as an IFrame with a sandbox attribute, which isolates its internal code from the host environment. YouTrack supplies this sandbox IFrame with a limited set of APIs to facilitate communication with the rest of the frontend as well as with the backend application.

These IFrames let you embed another HTML document into the YouTrack UI for presenting customized content. The content inside the IFrame is isolated from the frontend. This means the CSS and JavaScript used to display information in YouTrack's frontend do not affect the IFrame content directly and vice versa.

This isolation comes with both advantages and disadvantages. On the positive side, it enhances security and prevents interference between different web components. However, it also means that the information displayed by apps might not always be visually synchronized with the rest of the user interface. To ensure that your custom views have a similar look and feel to the parent app, we strongly recommend that you build your widgets using components from JetBrains' open-source RING UI library.

This environment allows for extensive customization of the YouTrack UI, letting you add custom panels, controls, and views that enhance the user experience. These customizations can be accessed through predefined extension points. For a complete list and a description of each available extension point, see Extension Points.

API Layer

YouTrack uses a RESTful API to facilitate communication between the frontend and the backend application using standard HTTP methods. A subset of the HTTP methods used by the application are also exposed for use by apps. The Host API lets apps send HTTP requests to YouTrack or communicate with it using YouTrack APIs. It also lets apps communicate with custom HTTP handlers stored in the backend.

The sandboxed code is also capable of making HTTP requests to third-party services.

Backend Sandbox Environment

Like the frontend application, the YouTrack backend application also contains a sandbox. Here, the sandbox operates as a GraalVM engine, enabling the execution of JavaScript code in an isolated environment. This backend sandbox is responsible for running workflow rules and HTTP handlers.

The backend is equipped with an API that allows these components to access the database. This gives an app access to read and store data in core entities, like issues and articles. It also lets an app read and store data in its own global storage.

Workflow Rules

The backend sandbox contains a dedicated runtime environment for workflows. This lets you extend and automate YouTrack functionality and behaviors using JavaScript. Workflow rules are an internal extension point for apps that allow interaction with YouTrack entities in response to specific events or conditions.

Workflows are event-driven triggers that let you implement custom business logic in YouTrack. This means you can automate updates in response to changes in field values, states, or on a set schedule. You can also extend the user interface by adding custom actions that are triggered manually by users but run logic on the backend. There's even a module that lets you establish connections and send requests to external sites.

If you're looking to build a solution that only relies on workflow rules, these can be written and stored directly in YouTrack. If you don't plan to use any of the frontend extension points to customize the user interface, you can save yourself a lot of time and effort by working exclusively with the workflow engine.

You can always package a group of workflow rules and publish them as an app or include a set of workflows in an app package alongside widgets for other extension points. When this happens, these workflows are identified by the app that provides their functionality in the workflow list.

To learn more about workflows in YouTrack, see JavaScript Workflow Quick Start Guide.

To learn how to add a workflow rule to your app, see JavaScript Modules.
For help writing workflows in JavaScript, read our JavaScript Workflow Quick Start Guide.

HTTP Handlers

YouTrack's backend sandbox environment provides support for custom HTTP handlers. This lets you expose additional endpoints to interact with external systems or custom apps. These handlers allow you to define server-side logic that responds to specific HTTP requests and operates within YouTrack's sandboxed environment. This functionality is a key extension point for integrating other tools or creating custom interactions with the REST API.

For further information, see HTTP Handlers.

Data Storage

Apps are able to provision global storage in the YouTrack database. This lets apps dynamically store and retrieve app-specific data in isolation from other entities defined by YouTrack.

To learn how to set up dedicated data storage for your app, see How to Use Extension Properties.

19 March 2025