Last updated Dec 9, 2024

Entity properties

You can build this in Forge

Jira entity properties are available in Forge, our next-generation developer platform.

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

Entity properties enable apps to add key-value stores to Jira entities, such as issues or projects. You can also add app properties to the Connect app itself. This page provides an overview and examples of how entity properties and app properties work:

Users can access entity and app properties using the REST APIs. For this reason, never store user personal data, any sensitive data or configuration information using entity properties or app properties. Your app has to handle storage and permissions for security-sensitive information.

Jira entity properties

Entity properties let you store data on the following entities:

Jira Cloud platform

You can use app properties to store data on your Connect app.

Jira Software

Limitations of entity properties

Remember these limitations when using entity properties:

Make sure users have the right permission level to interact with your entity properties. For example, any user who can edit an issue can also edit an issue property, but you may only want admins to edit that property. You can check a user's permission or group using the permissions APIs: Get all permissions and Get user groups.

Storing data against an entity with REST

The cURL examples below show you how to store data against and retrieve data from an issue using REST. For information how to manipulate properties of other Jira entities, such as projects, please see the Jira REST API documentation.

To modify, add, or remove the properties, the user executing the request must have permission to edit the entity. For example, to add new property to issue ENPR-4, the user needs permission to edit the issue. To retrieve a property, the user must have read permissions for the issue.

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.

1
2
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}'

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.

1
2
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.

1
2
{"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.

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

Making searchable entity properties

Atlassian Connect can provide a module descriptor, making the issue properties searchable using JQL. For example, to index the data from the first example, apps provide the following module descriptors:

1
2
"jiraEntityProperties": [{
    "key": "jira-issue-tasklist-indexing",
    "name": {
        "value" :"Tasks index",
        "i18n": "tasks.index"
    },
    "entityType": "issue",
    "keyConfigurations": [{
        "propertyKey" : "tasks",
        "extractions" : [{
            "objectName" : "content",
            "type" : "text"
        }]
    }]
}]

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

The indexed data is available for a JQL search. The JQL query...

1
2
issue.property[tasks].completed = 1 AND 
issue.property[tasks].content ~ "works" 

...result is shown in this screenshot.

Alt text

The Forge module jira:entityProperty can also be used to index entity property values and make them available to search using JQL.

1
2
modules:
  jira:entityProperty:
    - key: "jira-issue-tasklist-indexing"
      entityType: "issue"
      propertyKey: tasks
      values:
        - path: content
          type: text
        - path: completed
          type: number

See the Jira entity property module documentation for more information.

Conditions on entity properties

Entity properties can be referenced in the following conditions to decide whether or not to show a web fragment:

  • entity_property_exists
  • entity_property_equal_to
  • entity_property_equal_to_context
  • entity_property_contains_any
  • entity_property_contains_all
  • entity_property_contains_context
  • entity_property_contains_any_user_group
  • entity_property_contains_any_user_role

You can use the entity_property_equal_to condition to decide whether or not to show a web fragment based on the data in an entity property. For example, if we had an issue entity property with the key myExtraProperties and a JSON value that has the field isSpecial set to true (JSON boolean) then we could write the following condition:

1
2
{
  "condition": "entity_property_equal_to",
  "params": {
      "entity": "issue",
      "propertyKey": "myExtraProperties",
      "objectName": "isSpecial",
      "value": "true"
  }
}

It is important to note that the params.value field currently expects a string. Therefore you will need to convert your JSON into a string before you can compare it for equality. For example, to check that the JSON string "special" was stored in myExtraProperties then the condition must be written like so:

1
2
{
  "condition": "entity_property_equal_to",
  "params": {
      "entity": "issue",
      "propertyKey": "myExtraProperties",
      "objectName": "isSpecial",
      "value": "\"special\""
  }
}

There is currently no way to get a nested value out of a JSON object stored in an entity property for the purposes of comparison in a condition.

App properties

App properties are entity properties stored against your app itself. In this case the app is considered to be the storage container. However, app properties are still unique to each host application: the same app installed on two different host applications will not share the same app properties.

Limitations of app properties

App properties have the following limitations:

App properties can be read or modified by any authenticated user through the REST APIs, regardless of conditions or scopes. For this reason:

  • Don't store user-specific data in app properties.
  • Be defensive when retrieving app properties, and don't assume data consistency (arbitrary keys may be modified or deleted by users).

Supported operations

The following operations may be performed to manipulate app properties:

Examples

App properties can be set using Create or update app property:

1
2
curl --request PUT \ 
--user 'email@example.com:<api_token>' \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{"string":"string-value","number":5}' \
 'https://your-domain.atlassian.net/rest/atlassian-connect/1/addons/{addonKey}/properties/{propertyKey}'

Use Get app property to get the value of the property we just set:

1
2
curl --request GET \ 
--user 'email@example.com:<api_token>' \
--header "Accept: application/json" \
 'https://your-domain.atlassian.net/rest/atlassian-connect/1/addons/{addonKey}/properties/{propertyKey}'

Here is an example that will show a pop-up with a JSON property named my-property-key for an app with the key my-app-key.

1
2
AP.request({
    url: '/rest/atlassian-connect/1/addons/my-app-key/properties/my-property-key?jsonValue=true',
    success: function(response) {
        // Convert the string response to JSON
        response = JSON.parse(response);
        alert(response);
    },
    error: function(response) {
        console.log("Error loading API (" + uri + ")");
        console.log(arguments);
    },
    contentType: "application/json"
});

Apart from using AP.request, the same resources are accessible via a request signed with JWT.

Conditions based on app properties

App properties can be referenced in the entity_property_equal_to, entity_property_contains_any, and entity_property_contains_all conditions to decide whether or not to show a web fragment. For example, the following is a valid condition on the app property activated:

1
2
{
  "condition": "entity_property_equal_to",
  "params": {
      "entity": "addon",
      "propertyKey": "activated",
      "objectName": "for-users"  
      "value": "true"
  }
}

The structure of the JSON value of the activated app property might look like this:

1
2
{
  "for-anonymous": false,
  "for-users": true,
  "for-admins": true,
}

As for-users is set to true, the condition allows the web fragment to show.

Using conditions with app properties only controls what users see in the product UI. Any authenticated user can access these properties using the REST APIs. For this reason, never use app properties to store private or personal information.

Here is an example of a condition that requires the browser user to be in at least one specified group:

1
2
{
  "condition": "addon_property_contains_any_user_group",
  "params": {
      "propertyKey": "myListOfGroups"
  }
}

addon_property_contains_any_user_role is very similar to addon_property_contains_any_user_group, but references project roles in Jira.

Reference

See Entity Property reference

Rate this page: