App Settings - Help | Developer Portal for YouTrack and Hub

Define App Settings

To define custom app settings, add a file named settings.json to the app package. The settings.json file must comply to the JSON Schema 2020-12 to be validated on the YouTrack side. For more details about the JSON Schema 2020-12, see JSON Schema Docs.

Sample Settings File

Here you can find an example of a settings.json file of an app.

          {
              "$schema": "http://json-schema.org/draft-07/schema#",
              "type": "object",
              "title": "App Settings",
              "description": "Here you can provide values for the app settings",
              "properties": {
                  "stringSetting": {
                      "title": "Name",
                      "type": "string",
                      "minLength": 1
                  },
                  "booleanSetting": {
                      "type": "boolean"
                  },
                  "integerSetting": {
                      "type": "integer",
                      "x-scope": "GLOBAL"
                  },
                  "numberSetting": {
                      "type": "number",
                      "x-scope": "PROJECT"
                  },
                  "secretSetting": {
                      "type": "string",
                      "format": "secret"
                  },
                  "arraySetting": {
                      "type": "array",
                      "items": {
                          "x-entity": "User",
                          "type": "object"
                      } 
                 },
                  "userSetting": {
                      "type": "object",
                      "x-entity": "User"
                      }
              }
          }
        

Supported Setting Types

You can use one of the following entity types for the custom app settings:

string
integer
number
boolean
array
object

Setting Declaration

A settings.json file has the following fields:

Field	Type	Description	Required
`type`	string	The type of the entity that is located at the root of the `settings.json` file. The value of this field must always be `object`.	✓
`title`	string	The title of the file with the setting declaration. This title is displayed on the Settings tab of the app. You can use this title to give app users more information about the settings that this app allows to configure.
`description`	string	The description of the file with the setting declaration. It is displayed under the title on the Settings tab of the app. You can use this description to give app users more details and context about the settings that this app allows to configure.
`properties`	object	An object that contains definitions of app settings.	✓
`required`	Array.<string>	An array of properties that represent required app settings.

Properties

Each app setting must be declared as a field of the properties object in the settings.json file.

Each key of the properties object represents the key name of a setting, while the field value is an object defining the setting.

YouTrack apps support property parameters from the JSON Schema Draft 07.

Properties are defined with the following parameters:

Parameter

Type

Description

Required

const

any

The value that the property is restricted to.

description

string

The description of the setting. It will be displayed in the UI as a text label under the setting.

enum

Array.<any>

Defines a closed list of values that the user will be able to choose from. Each element of the list must be unique.

exclusiveMaximum

number

The exclusive upper limit for a numeric value. This parameter is only applicable to settings of the integer and number types.

exclusiveMinimum

number

The exclusive lower limit for a numeric value. This parameter is only applicable to settings of the integer and number types.

format

string

The format of the expected value. YouTrack apps support formats from the JSON Schema Draft 07.

Here you can find more details about some of the available formats:

Format	Description
`secret`	Use this format for passwords and other input values that should be hidden.
`date`	A date. A setting with this format displays a calendar for the user to select a date.

items

object

This parameter must be used for the array-typed parameters. The value of this parameter is an object that contains a reference to one of the core YouTrack entities. For more details, see Arrays.

maximum

number

The non-exclusive upper limit for the values that are allowed for this setting. This parameter is only applicable to settings of the integer and number type.

maxLength

integer

The maximal length of the string that this setting accepts. This parameter is only applicable to settings of the string type.

minimum

number

The non-exclusive lower limit for the values that are allowed for this setting. This parameter is only applicable to settings of the integer and numbertype.

minItems

integer

The minimal number of items in the array. This parameter is only applicable to settings of the array type.

To make an array-typed setting required, use this parameter while also listing the setting in the array of required settings.

minLength

integer

The minimal length of the string that this setting accepts. This parameter is only applicable to settings of the string type.

multipleOf

number

A value is valid only if division by this parameter's value results in an integer. The value must be strictly greater than 0.

This parameter is only applicable to settings of integer and number types.

readOnly

boolean

When true, the value of the setting is read-only and cannot be updated.

title

string

The name of the setting as it will be displayed in the app settings in the YouTrack UI.

✓

type

string

The type of the entity expected as the setting value. The following types are allowed:

string
integer
number
boolean
array
object

The array and object types can only represent YouTrack core entities. For details about these types and how to use them in the app settings, see Using YouTrack Entities for Setting Values.

✓

x-entity

string

This parameter refers to YouTrack core entities that you can use in the app settings. This is a special setting parameter that can only be used for settings of the array and object types.

For the array-typed settings, the value of this parameter represents the type of entities in the array.

For more details, see Using YouTrack Entities for Setting Values.

x-scope

string

Defines the scope of the setting.

Possible values:

Scope	Description
`GLOBAL`	Settings with this scope can only be configured on the global level.
`PROJECT`	Settings with this scope can only be configured on the project level.

Arrays

Each array-typed property must be defined with the following parameters:

Parameter	Type	Description	Required
`x-entity`	string	This parameter refers to YouTrack core entities that you can use in arrays in the app settings. This is a special setting parameter that can only be used for settings of the `array` and `object` types. For the `array`-typed settings, the value of this parameter represents the type of entities in the array and should match the value of the corresponding `x-entity` parameter of the `array`-typed property. For more details, see Using YouTrack Entities for Setting Values.	✓
`type`	string	Defines the type of the parameter. For the `items` object, this parameter must always be set to `object`.	✓

Parameter

Type

Description

Required

x-entity

string

This parameter refers to YouTrack core entities that you can use in arrays in the app settings. This is a special setting parameter that can only be used for settings of the array and object types.

For the array-typed settings, the value of this parameter represents the type of entities in the array and should match the value of the corresponding x-entity parameter of the array-typed property. For more details, see Using YouTrack Entities for Setting Values.

✓

type

string

Defines the type of the parameter. For the items object, this parameter must always be set to object.

✓

Using YouTrack Entities for Setting Values

In app settings with array and object types, you can use some of the core YouTrack entities for the setting values. The x-entity setting parameter defines the exact type of the YouTrack entity that the app expects in a particular setting.

You can use the following YouTrack entities in the app settings:

Issue
Article
Project
User
UserGroup

Configuring Values for App Settings

When you’re configuring an installed app in YouTrack, you can provide settings for the app on the global or project level. Settings configured on the project level have higher priority and overwrite the global settings. If you don't set any project-level values for app settings, the global-level values for these settings are applied.

To set values for app settings on the global level:

From the Administration menu, select Apps.
Select the target app from the list.
Open the Settings tab for this app.
Update values for the settings of the app.
When ready, click the Save button.
- The values for the app settings are saved on the global level.
- The values are updated in all projects where this app is attached and where the app settings are synchronized with the global app settings.

To set values for app settings on the project level:

In the project settings, open the Apps tab.
Select the target app from the list.
Open the Settings tab for this app.
Set values for the settings of the app.
When ready, click the Save button.
- The values for the app settings are saved on the project level.
- The values you've just set overwrite any global-level values for these settings.
- The settings that you've updated stop being synchronized with the global app settings.

Working with Settings for Secrets

When you declare a setting that is formatted to store a secret, YouTrack handles values stored in the setting differently than it does for other settings. These values are stored securely, ensuring that only authorized parts of the application can access them. This means users can store their authentication tokens and credentials for authorizing the app without having this information fall into the hands of others.

YouTrack handles values stored as secrets in the following manner:

Once a secret has been stored, no one else can read it anywhere in YouTrack. The real value is used only in the http.js package when it is needed to authenticate an HTTP request, namely:
- bearer token authentication flows. For an example, see Using Setting Values in the Scripts below.
- basic token authentication.
- addHeader and setHeader methods. For example, for example, connection.addHeader('My-Token-Header', ctx.settings.secretToken)
- as the value for a queryParam parameter in methods like getSync and others. For example, connection.getSync(url, { apiKey: ctx.settings.apiKey) }, the apiKey is stored as a secret.
HTTP requests sent using the http.js package are processed inside the JVM, so values stored in secret settings don't appear anywhere in logs.

Using Setting Values in the Scripts

You can refer to a setting value as ctx.settings.<settingName> in any JavaScript-based script within the app package. For example, you can use setting values in HTTP handlers, workflow rules, import scripts, and other JS scripts.

Here is a code sample for using setting values in an HTTP handler:

            const entities = require('@jetbrains/youtrack-scripting-api/entities');

              exports.httpHandler = {
                  endpoints: [
                      {
                          method: 'GET',
                          path: '/test',
                          scope: 'issue',
                          handle: function (ctx) {
                              const issue = ctx.issue;
                              issue.description = ctx.settings.stringSetting;
                              if (ctx.settings.booleanSetting) {
                                  console.log('integer: ' + ctx.settings.integerSetting);
                                  console.log('number: ' + ctx.settings.numberSetting);
                                  console.log('array size: ' + ctx.settings.arraySetting.size);
                              }
                              issue.Assignee = ctx.settings.userSetting;
                          }
                      }
                  ],
                  requirements: {
                      Assignee: {
                          type: entities.User.fieldType
                      }
                  }
              };
        

Here is a code sample for an HTTP handler that uses a setting of the secret format:

          const http = require('@jetbrains/youtrack-scripting-api/http');
          const URL = "http://some-third-party-service.io/api";
          
          exports.httpHandler = {
              endpoints: [
                  {
                      method: 'POST',
                      path: '/test',
                      handle: function (ctx) {
                          let connection = new http.Connection(URL);
                          // set 'Authorization: Bearer <token>' header with the secret app setting
                          connection.bearerAuth(ctx.settings.secretSetting);
                          connection.addHeader('Content-Type', 'application/json');
                          let response = connection.postSync("/test", {}, requestJson);
                      }
                  }
              ]
          };
        