Jira entity property

The jira:entityProperty module requests that fields of an entity property are indexed by Jira to make the fields available to query in JQL.

See Entity properties in the Jira Cloud platform guides for more information about Jira entity properties.

Properties

Property values

Defines an entity property to be indexed by Jira. An entity property value is a reference to a JSON object, which also defines its type.

Dynamic module (EAP)

This module can also be declared as a dynamic module. However, this capability is currently only available as part of Forge’s Early Access Program (EAP).

For more details, see Dynamic Modules.

Code examples

The following examples show Dynamic Module implementations specific to this module. For more detailed information about the API used in these examples (including error handling information), see Dynamic Modules API.

Create a dynamic entity property module

1
2
import { asApp } from "@forge/api";
const payload = {
  "key": "dynamic-entity-property",
  "type": "jira:entityProperty",
  "data": {
    "entityType": "issue",
    "propertyKey": "dynamic_property",
    "values": [
      {
        "type": "number",
        "path": "comments",
        "searchAlias": "commentCount"
      }
    ]
  }
}
const response = await asApp().requestAtlassian(`/forge/installation/v1/dynamic/module/`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'POST',
  body: JSON.stringify(payload),
});
const body = await response.text(); 
console.log(`Response: ${response.status} ${body}`);

Update a dynamic entity property module

1
2
import { asApp } from "@forge/api";
const key = "dynamic-entity-property";
const payload = {
  "key": "dynamic-entity-property",
  "type": "jira:entityProperty",
  "data": {
    "entityType": "issue",
    "propertyKey": "dynamic_property",
    "values": [
      {
        "type": "number",
        "path": "comments",
        "searchAlias": "commentCount"
      }
    ]
  }
}
const response = await asApp().requestAtlassian(`/forge/installation/v1/dynamic/module/${key}`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'PUT',
  body: JSON.stringify(payload)
});
const body = await response.text(); 
console.log(`Response: ${response.status} ${body}`);

Example

This example uses an issue entity property with the key of stats, which is defined like this:

1
2
{
   "comments": 5,
   "statusTransitions": 6,
   "lastCommenter": "<account-id>",
   "blockedIssues": ["10000", "10001"]
}

Using the jira:entityProperty module you request that fields of an entity property are indexed.

1
2
modules:
  jira:entityProperty:
    - key: "stats-property"
      entityType: "issue"
      propertyKey: stats
      values:
        - path: comments
          type: number
          searchAlias: commentCount
        - path: statusTransitions
          type: number
          searchAlias: transitionCount
        - path: lastCommenter
          type: user
          searchAlias: lastCommenter
        - path: blockedIssues
          type: string
          searchAlias: blockedIssues

Now, indexed data is available to search in JQL, as in this example:

1
2
commentCount = 5
issue.property['stats'].comments = 5
lastCommenter = currentUser()
blockedIssues[0] = "10000"

Similarly, you can request indexing for other entity types, such as user and project.

1
2
modules:
  jira:entityProperty:
    - key: "user-property"
      entityType: "user"
      propertyKey: user-stats
      values:
        - path: comments
          type: number
          searchAlias: commentCount
    - key: "project-property"
      entityType: "project"
      propertyKey: project-stats
      values:
        - path: pages
          type: number
          searchAlias: pagesCount

In a JQL search, you access these properties using a prefix.

1
2
project.pagesCount = 5
project.property['project-stats'].pages = 5
assigne.commentCount = 10
reporter.property['user-stats'].comments = 10