Entity Property

You can build this with Forge

Jira entity properties are available in Forge, our next-generation cloud app development platform.

Already have a Connect app? Start adding Forge features in less than an hour.

Entity properties allow apps to add key/value pairs to Jira entities, such as issues or projects. This module allows you to request those entity properties to be indexed by Jira and able to be queried via JQL searches. They are also available in the following conditions:

  • entitypropertyequalto
  • entitypropertyequaltocontext
  • entitypropertycontainsany
  • entitypropertycontainsall
  • entitypropertycontainscontext

Note that authenticated users can access entity and app properties using the REST APIs. For this reason, never store private user data or configuration information using entity or app properties.

Overview

The purpose of this module is to specify what data from which entity properties should be extracted and indexed. Pretend that an app developer has an issue entity property with the key attachment and in that entity property they store the following data:

1
2
3
4
5
6
7
8
9
10

  
 {
     "size": 14231,
     "name": "new-years-jam",
     "extension": "mp3",
     "updated": "2016-12-25T20:55:59"
 }
  
 

In this example the developer wants to make the size, extension and updated fields under the attachment key searchable via JQL. To do that they start by declaring that the entityType to index will be an 'issue' entity type; this is specified at the top level of their module. Then they need to specify which entity property key they wish to extract data from: so they add a single entry to keyConfiguratons with propertyKey set to 'attachment'. If there are multiple issue entity properties that an app developer wanted to index then they could add more keyConfigurations to declare those extra properties. From there the app developer specifies which data they want to extract from the JSON value that is stored in this issue entity property.

In this example they would add three extractions for the size, extension and updated paths under the attachment key being clear to specify the type of data being extracted and what alias should be made available to JQL queries.

Note that array types can be indexed too; the type field in the extraction should be the type of each element in the array. Extraction fields in key configuration need to be non-empty

You can see the resultant module definition in the example below.

For more information, please see the Jira documentation on entity properties.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "modules": {
    "jiraEntityProperties": [
      {
        "keyConfigurations": [
          {
            "extractions": [
              {
                "objectName": "size",
                "type": "number",
                "alias": "attachmentSize"
              },
              {
                "objectName": "extension",
                "type": "text",
                "alias": "attachmentExtension"
              },
              {
                "objectName": "updated",
                "type": "date",
                "alias": "attachmentUpdatedDate"
              }
            ],
            "propertyKey": "attachment"
          }
        ],
        "entityType": "issue",
        "name": {
          "value": "Attachment Index Document"
        },
        "key": "attachment-entity-property"
      }
    ]
  }
}

Properties

key
Type
Max length
100
Required
Yes
Pattern
^[a-zA-Z0-9-]+$
Description

A key to identify this module.

This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be globally unique.

Keys must only contain alphanumeric characters and dashes.

The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on key and module key. For example, an add-on which looks like:

1
2
3
4
5
6
7
8
9
{
    "key": "my-addon",
    "modules": {
        "configurePage": {
            "key": "configure-me",
        }
    }
}

Will have a configuration page module with a URL of /plugins/servlet/ac/my-addon/configure-me.


name
Type
Required
Yes
Description

A human readable name.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
3
4
{
  "value": "My text"
}

Properties

value
Type
Max length
1500
Required
Yes
Description

The human-readable default value. This will be used if no translation exists. Only the following HTML tags are supported: b, i, strong, em, and code.

i18n
Type
Max length
300
Description

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.


entityType
Type
Defaults to
issue
Allowed values
  • issue
  • ISSUE
  • user
  • USER
  • project
  • PROJECT
Description

The type of the entity. The default value is issue.


keyConfigurations
Type
Description

List of properties from which selected values are indexed.