Extension Properties

Apps can extend core YouTrack entities with custom properties. We refer to these as extension properties. With extension properties, you can store custom values for core YouTrack entities. An app can then work with these custom properties and their values in its JavaScript-based modules.

Extension properties are declared in a separate file named entity-extensions.json.

An app has access only to those properties that it declares itself. An app cannot access extension properties of other apps.

When you remove an app from YouTrack, all values of the app's extension properties are deleted. When you reimport an app after deleting or renaming some of its extension properties, their old values are also deleted.

Supported Types

Here is the list of all types that are available for extension properties:

Type	Allowed Values
`integer`	-9223372036854775808 to 9223372036854775807
`float`	4.94065645841246544e-324d to 1.79769313486231570e+308d (positive or negative)
`boolean`
`string`
YouTrack entity	Any YouTrack entity supported by the Workflow API

You can declare an extension property that stores multiple values by adding the "multi": true parameter. Extension property declared with this parameter returns a Set.

Sample Extension Property Declaration

Here you can see an example of an entity-extensions.json file. In this example, you can see declarations of extension properties of all possible types. These properties are declared for the issue entity. You can declare similar extension properties for other YouTrack entities. For the full list of entities that you can declare extension properties for, see YouTrack entities.

            {
                "entityTypeExtensions": [
                  {
                    "entityType": "Issue",
              
                    "properties": {
                      "stringProp": {
                        "type": "string"
                      },
                      "integerProp": {
                        "type": "integer"
                      },
                      "floatProp": {
                        "type": "float"
                      },
                      "booleanProp": {
                        "type": "boolean"
                      },
                      "issueProp": {
                        "type": "Issue"
                      },
                      "issuesProp": {
                        "type": "Issue",
                        "multi": true
                      }
                    }
                  }
                ]
              }
        

You can refer to an extension property of an entity in a JavaScript script as entityName.extensionProperties.propertyName. Here are some examples:

ctx.issue.extensionProperties.stringProp
entities.Issue.findById("DEMO-1").extensionProperties.stringProp

For JavaScript code samples that use extension properties, see How to Use Extension Properties.

App Global Storage

An app can declare extension properties at the global app level without linking these properties to a specific entity. You can access global extension properties through the script context (ctx) in any JavaScript-based module in the app. To declare this kind of extension property, use AppGlobalStorage as the entity type.

            {
                "entityTypeExtensions": [
                  {
                    "entityType": "AppGlobalStorage",
              
                    "properties": {
                      "globalCounter": {
                        "type": "integer"
                      },
                      "globalIssuesSet": {
                        "type": "Issue",
                        "multi": true
                      }
                    }
                  }
                ]
              }
        

You can refer to a global extension property as ctx.globalStorage.extensionProperties.propertyName.

For a JavaScript code sample that uses global extension properties, see code sample below.

How to Use Extension Properties

You can refer to an extension property of an entity in a JavaScript script as entityName.extensionProperties.propertyName. Here are some examples:

ctx.issue.extensionProperties.stringProp
entities.Issue.findById("DEMO-1").extensionProperties.stringProp

Here is a code sample that shows how you can access extension properties declared in the sample above in a JavaScript app script.

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

          exports.rule = entities.Issue.action({
              command: 'test',
              action: function (ctx) {
                  const printValues = () => {
                      return 'stringProp:' + ctx.issue.extensionProperties.stringProp + ';'
                          + 'integerProp:' + ctx.issue.extensionProperties.integerProp + ';'
                          + 'booleanProp:' + ctx.issue.extensionProperties.booleanProp + ';'
                          + 'issueProp:' + ctx.issue.extensionProperties.issueProp?.id + ';'
                          + 'issuesProp:' + ctx.issue.extensionProperties.issuesProp?.first()?.id + ';'
                  }
                  ctx.issue.addComment(printValues());
              }
          });
        

You can refer to a global extension property as ctx.globalStorage.extensionProperties.propertyName.

Here is an example of how you can access global extension properties declared in a sample above in a JavaScript app script.

          const entities = require('@jetbrains/youtrack-scripting-api/entities');
          
          exports.rule = entities.Issue.action({
              command: 'test',
              action: function (ctx) {
                  ctx.globalStorage.extensionProperties.globalCounter++;
                  ctx.globalStorage.extensionProperties.globalIssuesSet.add(ctx.issue);
              }
          });
        

Last modified: 7 November 2024