JIRA Entity Properties Overview

This page provides an overview of JIRA entity properties. Entity properties are available in JIRA 6.2 and above. 

What are entity properties?

Entity properties allow add-ons to add key/value stores to JIRA entities, such as issues or projects. These values can be indexed by JIRA and queried via a REST API or through JQL. 

How do I store data against an entity using REST?

The curl examples below show you how you can store data against an issue and retrieve the data from an issue, using REST. 

Please note, in order to modify, add or remove the properties, the user who is executing the request must have permission to edit the entity. For example, to add new property to issue ENPR-4, you need permission to edit the issue. In order to retrieve a property, the user must have read permissions for the entity.

Example 1: Storing data

The simple example below will store the JSON object {"content":"Test if works on JIRA Cloud", "completed" : 1} against issue ENPR-4 with the key tasks. 

curl -X PUT -H "Content-type: application/json" https://jira-instance1.net/rest/api/2/issue/ENPR-4/properties/tasks -d '{"content":"Test if works on JIRA Cloud", "completed" : 1}'

Note:

  • The key has a maximum length of 255 characters. 
  • The value must be a valid JSON Object and has a maximum size of 32 KB.

Example 2: Retrieving data

The example below shows how to get all of the properties stored against an issue.

curl -X GET https://jira-instance1.net/rest/api/2/issue/ENPR-4/properties/

The response from server will contain keys and URLs of all properties of the issue ENPR-4. 

{"keys":[{"self":"https://jira-instance1.net/rest/api/2/issue/ENPR-4/properties/tasks","key":"tasks"}]}

Example 3: Removing a property

The example below shows how to remove a property from an issue.

curl -X DELETE https://jira-instance1.net/rest/api/2/issue/ENPR-4/properties/tasks

How do I make the properties of an entity searchable?

Atlassian Connect and P2 plugins both can provide a module descriptor, which will make the issue properties searchable using JQL. For example, to index the data from the first example, P2 and Connect plugins can provide the following module descriptors:

P2 module descriptor
<index-document-configuration 
  entity-key="IssueProperty" 
  key="jira-issue-tasklist-indexing">
  <key property-key="tasks">
    <extract path="content" type="text" />
  </key>
</index-document-configuration>

 

 

Connect module
"jiraEntityProperties": [{
    "name": {
        "value" :"Tasks index",
        "i18n": "tasks.index"
    },
	"key": "com.example.myaddon",
    "entityType": "issue",
    "keyConfigurations": [{
        "propertyKey" : "tasks",
        "extractions" : [{
            "objectName" : "content",
            "type" : "text"
        }]
    }]
}]

The descriptors shown above will make JIRA index the object "content" of the issue property "tasks" as a text. The available index data types are:

  • number: indexed as a number and allows for range ordering and searching on this field.
  • text: tokenized before indexing and allows for searching for particular words.
  • string: indexed as-is and allows for searching for the exact phrase only.
  • date: indexed as a date and allows for date range searching and ordering. The expected date format is [YYYY]-[MM]-[DD]. The expected date time format is [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss] with optional offset from UTC: +/-[hh]:[mm] or Z for no offset. For reference, please see ISO_8601 standard.

The indexed data is available for a JQL search. The result of the JQL query: issue.property[tasks].completed = 1 AND issue.property[tasks].content ~ "works" is shown in the screenshot below. 

Please see the Connect documentation or P2 documentation for detailed explanations on how to use the module descriptors. 

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport