Work with Issue and Entity Properties

Entity properties allow you to add key/value stores to issues, projects, users, and comments. Your scripts can use these properties for automations, for example, to store a user's department name on the user object.

There are two different mechanisms you can use to create these data stores. Check out the table below to compare the two mechanisms:

Entity properties

Setting and getting issue properties

The following is a simple example of setting and getting an issue property:

            def issue = Issues.getByKey('ABC-1')
            
            // setting the property 
            issue.entityProperties.setString('my first property', 'Hello World!')
            
            // retrieving the property value 
            issue.entityProperties.getString('my first property') // returns 'Hello World!'

You can also set and get several other property types:

            import groovy.json.JsonOutput
            import java.time.LocalDate
            
            def entityProperties = Issues.getByKey('ABC-1').entityProperties
            
            entityProperties.setString('foo', 'bar')
            entityProperties.setBoolean('onboarded', true)
            entityProperties.setInteger('meaning of life', 42)
            entityProperties.setLong('birth year', 1972L)
            entityProperties.setLocalDate('my date', LocalDate.now())

In addition to the property types listed above, you can store maps, lists, or your own classes. For example, to store a map you could use the following:

            entityProperties.setAsActualType('tasks', [
                content: 'complete design work',
                estimateInDays: 2, 
            ])
            
            // retrieve the properties as a Map
            entityProperties.getAsActualType('tasks', Map)

You can store instances of your own classes. Check out the Searchable entity properties section to find out how.

Overwriting security restrictions

To read and write properties overriding the security restrictions, use getEntityPropertiesOverrideSecurity() :

                def entityProperties = Projects.getByKey('ABC').entityPropertiesOverrideSecurity
                entityProperties.setString('foo', 'bar')

Searchable entity properties

You can store your own instances of your own class and have it as a searchable entity property.

            entityProperties.setJson('my json', JsonOutput.toJson([foo: 'bar', qux: 3]))

Creating a searchable entity property

It is possible to have Jira index the property data of your own class, and then you can query on it with JQL. To do this, you can register a new plugin module, specifying which properties to extract. 

1. Register a plugin module using code similar to the following:

   Plugin modules registered as follows will be removed when Jira restarts. Use the code in a script inside the startup directory, to ensure it executes on every restart.

               import com.onresolve.licensing.DynamicModulesComponent
               import com.onresolve.scriptrunner.runner.ScriptRunnerImpl
       
               def dynamicModulesComponent = ScriptRunnerImpl.getPluginComponent(DynamicModulesComponent)
               def pluginXml = """
                   <index-document-configuration
                           entity-key="IssueProperty"
                           key="jira-issue-tasklist-indexing">
                       <key property-key="task">
                           <extract path="content" type="text"/>
                           <extract path="estimateInDays" type="number"/>
                       </key>
                   </index-document-configuration>
               """
               def writer = new StringWriter()
               writer.write(pluginXml)
               dynamicModulesComponent.register(writer)

2. Add the issue property as follows:
   

               class IssueTask {
                   String content
                   Integer estimateInDays
               }
               
               entityProperties.setAsActualType('task', new IssueTask(content: 'complete design', estimateInDays: 3))
               
               // if you need to retrieve the property programmatically:
               entityProperties.getAsActualType('task', IssueTask)

3. Execute the JQL as follows:
   

               'issue.property[task].content ~ "design" AND issue.property[task].estimateInDays = 3'

Consult Atlassian documentation on making entity properties searchable for more information.

Property sets

Reading and writing user properties

As discussed in the table above, property sets are an older form of storing key/value pairs. Use the following to read and write user properties:

                def user = Users.loggedInUser
                def propertySet = user.propertySet
                
                propertySet.setString('foo', 'bar')
                propertySet.getString('foo')

Related content

• Javadocs link
• Work with Users
• Work with Permission Schemes