Support for Server products ends Feb. 15, 2024. Learn what this means for you.

Index document configuration

Available:

The Index Document Configuration plugin module is available in JIRA 6.2 and later.

Purpose of this Module Type

The Index Document Configuration plugin module allows add-ons to add key/value stores to JIRA entities, such as issues or projects. These values are indexed by JIRA and can be queried via a REST API or through JQL. For more information, please see the JIRA documentation on entity properties.

Configuration

The root element for the index document configuration plugin module is index-document-configuration. It allows the following attributes and child elements for configuration:

Attributes

Name*	Description
entity-key	The type of the property. Currently, the only available value is `IssueProperty`
key	The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources. 1 2 `<component-import key="appProps" interface="com.atlassian.sal.api.ApplicationProperties"/>` In the example, `appProps` is the key for this particular module declaration, for `component-import`, in this case. That is, the identifier of the index document configuration module.

Name*

Description

entity-key

The type of the property. Currently, the only available value is IssueProperty

key

The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources.

1
2
<component-import
key="appProps"
interface="com.atlassian.sal.api.ApplicationProperties"/>

In the example, appProps is the key for this particular module declaration, for component-import, in this case. That is, the identifier of the index document configuration module.

*all the attributes above are required.

Elements

Name*	Description
key	References to the values of the JSON object which will be indexed, and the types of the referenced values (Key elements).

*key element is required.

Key elements

Keys of the entity properties can be added to index-document-configuration as elements. Each element defines the key of the property from which the data is indexed (property-key) and a list that has references to values of the JSON object which will be indexed (extract).

Attributes

Name	Description
property-key	The key of the property from which the data is indexed.

*property-key attribute is required.

Elements

Name	Description
extract	References to values of the JSON object which will be indexed, and the type of referenced value (Extract elements ).

*name element is required.

Extract elements

Attributes

Name	Description
path	The path of the JSON data that will be indexed. The path will be the key of a flattened JSON object that is delimited by '.' For instance, for JSON shown below, the valid path referencing the `color` is `label.color`. 1 2 `{"label": {"color": "red", "name":"jira-6.2"}}` Currently, specifying indexes for JSON arrays is not supported.
type	The type of the referenced value. The type can be one of the following values: number, which is indexed as a number and allows range ordering and searching on this field. text, which is tokenized before indexing and allows searching for particular words. string, which is indexed as is and allows searching for the exact phase only. date, which is indexed as a date and allows 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]` with optional offset from UTC: `+/-[hh]:[mm]` or ``Z`` for no offset. For reference, please see [ISO_8601 standard](http://www.w3.org/TR/NOTE-datetime).
alias	The name under which the property will appear in JQL search. Since: JIRA 6.4

Name

Description

path

The path of the JSON data that will be indexed. The path will be the key of a flattened JSON object that is delimited by '.'

For instance, for JSON shown below, the valid path referencing the color is label.color.

1
2
{"label": {"color": "red", "name":"jira-6.2"}}

Currently, specifying indexes for JSON arrays is not supported.

type

The type of the referenced value. The type can be one of the following values:

number, which is indexed as a number and allows range ordering and searching on this field.
text, which is tokenized before indexing and allows searching for particular words.
string, which is indexed as is and allows searching for the exact phase only.
date, which is indexed as a date and allows 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] with optional offset from UTC: +/-[hh]:[mm] or `Z` for no offset. For reference, please see [ISO_8601 standard](http://www.w3.org/TR/NOTE-datetime).

alias

The name under which the property will appear in JQL search.

Since: JIRA 6.4

*path and type attributes are required.

Index Document Configuration example

An index configuration that indexes labels by the exact label text:

1
2
<index-document-configuration entity-key="IssueProperty" key="jira-issue-label-indexing">
  <key property-key="label">
    <extract path="name" type="text" alias="labelName"/>
  </key>
</index-document-configuration>

This code should be placed in atlassian-plugin.xml.

A configuration like this makes issues searchable by their label names (assuming that the property label is stored against the issue).

For a property with the value:

1
2
{"color": "red", "name":"jira-6.2"}

stored under the label key, the JQL to search for the issues are:

**issue.property[label].name = "jira-6.2". **This is a fully qualified name of the issue.property. Fully qualified names do not appear in autocompletion.
**labelName = "jira-6.2". **This is the alias of this issue.property. Aliases appear in JQL autocompletion.