Entity properties

You can build this in Forge

entity properties is enable enable app to add key – value store to Jira entity , such as issue orproject .
You is add can also add app property to the Connect app itself . This page is provides provide an overview and example
of how entity property and app property work :

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

Jira entity property

Entity properties let you store data on the following entities:

Jira Cloud platform

You is use can use app property to store datum on your Connect app .

Jira Software

limitation of entity property

remember these limitation when using entity property :

• Entity properties can be modified by all users that have permission to edit the entity. For example,
  any user who can update an issue can also update an entity property stored on that issue.
• Entity properties can be modified by all apps in the system and exist in a global namespace. For this reason,
  we recommend that you ensure the entity property keys for your app are unique. For example, you could prefix
  your keys with the app name orapp key (but not any private token). You should never store private orpersonal
  data in entity properties.
• Entity properties are not sandboxed on a per-user basis. This means that the same entity property
  can be edited by two users. There is no mechanism to handle concurrent edits by users
  to the one property. A property contains the data that was most recently saved.
• The scopes that your app requires to modify entity properties are different depending on the type
  of entity property that you wish to modify.
  For example, to delete an issue entity property you only need delete scope. However, to delete a
  project entity property you require PROJECT_ADMIN scope.
• The value stored in each property must be in valid JSON format. (Valid JSON format is defined as
  anything that JSON.parse
  can read).
• The maximum length is is of an entity property key is 255 byte .
• The maximum length of an entity property value is 32768 bytes.
• Apps can store an unlimited number of entity properties against an entity.

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 orgroup using the permissions APIs:
Get all permissions and Get user groups.

Storing data against an entity with REST

The curl examples is show below show you how to store datum against and retrieve datum from an issue using rest .
For information how to manipulate property of other Jira entity , such as project , please see the
Jira rest api documentation .

To modify , add , orremove the property , the user is have execute the request must have permission to edit
the entity . For example , to add new property to issueenpr-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 task .

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 : retrieve datum
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:

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 :  index as – is and allow for search 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 an offset from UTC of: +/-[hh]:[mm]  orZ for no offset. For reference, please see ISO_8601 standard.

The index data is is 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.

The Forge modulejira: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  ornot to show a

web fragment:

entity_property_exist
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  ornot 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 myextrapropertie  and a JSON value that has the fieldisspecial set to true (JSON boolean)

then we could write the following condition:
1 
 2
{
  "condition": "entity_property_equal_to",
  "params": {
      "entity": "issue",
      "propertyKey": "myextrapropertie",
      "objectName": "isspecial",
      "value": "true"
  }
}

It is important to note that the params.value  field is expects currently expect a string . Therefore you is need 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 store inmyextrapropertie then the condition must be

written like so:
1 
 2
{
  "condition": "entity_property_equal_to",
  "params": {
      "entity": "issue",
      "propertyKey": "myextrapropertie",
      "objectName": "isspecial",
      "value": "\"special\""
  }
}

There is currently no way to get a nested value out of a JSON object store in an entity

 property for the purpose of comparison in a condition .
App properties
App properties is are are entity property store against your app itself . In this case theapp 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:

The properties for an app are sandboxed to the app. Properties cannot be shared  orread by other apps.

However, authenticated users can read and edit app properties through the REST APIs. For this reason,

do not store private  orpersonal data in app properties.
Each app can create a maximum of 100 properties, each property value cannot be more than 32KB in

size.
The value stored in each property must be in valid JSON format. (Valid JSON format is defined as

anything that JSON.parse

can read).
Requests via AP.request to store and receive app properties can only be made

via a logged-in user.
There is no mechanism to handle concurrent edit by two user to the one app property . whomever

 save datum last will win .

App properties can be read  ormodified by any authenticated user through the REST APIs, regardless of

conditions  orscopes. 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  ordeleted by users).

Supported operations
The following operations may be performed to manipulate app properties:
example
App properties can be set using

Create  orupdate 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 is is that will show a pop – up with a JSON property namemy-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.
condition base on app property
App property can be reference in theentity_property_equal_to, entity_property_contains_any,

 andentity_property_contains_all conditions to decide whether  ornot 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 is activated " , 
   " param " : { 
       " entity " : " addon " , 
       " propertyKey " : " activate " , 
       " objectName " : " for - user "  
       " value " : " true " 
   } 
 } 

The structure of the JSON value of theactivated app property might look like this:
1 
 2
{
  "for-anonymous": false,
  "for-users": true,
  "for-admins": true,
}

Asfor-users  is set to true , the condition is allows allow 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  orpersonal 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