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 (Preview)

This module can also be declared as a dynamic module. However, this capability is currently available as a Forge preview feature.

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 = {
  "type": "jira:entityProperty",
  "data": {
    "entityType": "issue",
    "propertyKey": "dynamic_property",
    "values": [
      {
        "type": "number",
        "path": "comments",
        "searchAlias": "commentCount"
      }
    ]
  }
}
const response = await asApp().requestAtlassian(`/forge/installation/v2/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 = {
  "type": "jira:entityProperty",
  "data": {
    "entityType": "issue",
    "propertyKey": "dynamic_property",
    "values": [
      {
        "type": "number",
        "path": "comments",
        "searchAlias": "commentCount"
      }
    ]
  }
}
const response = await asApp().requestAtlassian(`/forge/installation/v2/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"],
   "summary": "Performance improvements for the dashboard",
   "category": "optimization",
   "lastUpdated": "2025-06-15T10:30:00Z"
}

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
        - path: summary
          type: text
          searchAlias: statsSummary
        - path: category
          type: string
          searchAlias: statsCategory
        - path: lastUpdated
          type: date
          searchAlias: statsLastUpdated

JQL syntax

Once indexed, you can query entity property data in JQL using two syntax forms:

• Search alias — Use the searchAlias value directly as the JQL field name. This is the recommended approach.
• Full property path — Use the format issue.property['<propertyKey>'].<path>. This works without a searchAlias.

1
2
commentCount = 5
issue.property['stats'].comments = 5

Both queries above return the same results. The search alias form is shorter and easier to read.

JQL examples by type

The JQL operators available for a field depend on the type you specified in the module definition.

number type

The number type supports exact match (=, !=), comparison (>, >=, <, <=), and ordering.

1
2
commentCount = 5
commentCount > 3
commentCount >= 1 AND commentCount <= 10
transitionCount != 0
ORDER BY commentCount ASC

text type

The text type tokenizes the value before indexing, which means you can search for individual words using the ~ (contains) and !~ (does not contain) operators.

1
2
statsSummary ~ "dashboard"
statsSummary ~ "performance improvements"
statsSummary !~ "bug"

string type

The string type indexes the value as-is and supports exact match (=, !=) only.

1
2
statsCategory = "optimization"
statsCategory != "bug"
blockedIssues[0] = "10000"

date type

The date type supports exact match, comparison, and ordering. Use the format YYYY-MM-DD or an ISO 8601 date-time with timezone offset.

1
2
statsLastUpdated > "2025-01-01"
statsLastUpdated >= "2025-06-01" AND statsLastUpdated < "2025-07-01"
statsLastUpdated > "2025-06-15T00:00:00Z"
ORDER BY statsLastUpdated DESC

user type

The user type accepts an Atlassian account ID and supports the currentUser() function.

1
2
lastCommenter = currentUser()
lastCommenter = "<account-id>"
lastCommenter != currentUser()

User and project entity types

You can also request indexing for user and project entity types.

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 user and project properties using a prefix that corresponds to a JQL user or project field.

For project properties, use the project prefix:

1
2
project.pagesCount = 5
project.property['project-stats'].pages = 5

For user properties, use a user-based field as the prefix (for example, assignee, reporter, or creator):

1
2
assignee.commentCount = 10
reporter.property['user-stats'].comments = 10