On this page:

Extended JQL syntax

The "Custom JQL" mode and the JQL filtering functionality of Issue Matrix for Jira support an extended JQL syntax which allows filtering based on the values of custom fields of the current issue.

There are several forms of the extended syntax you can use for custom fields:

Retrieving the custom field value using the id of the custom field
customField = ${currentIssue.cf[10006]}
Retrieving the custom field value using the name of the custom field
customField = ${currentIssue.cf["Custom field name"]}
Retrieving the issues with the same value(s) as in the labels/multi version picker field value(s) in the current issue as well as all issues with empty value for the custom field. Only applicable for custom fields of type Labels custom field type: "com.atlassian.jira.plugin.system.customfieldtypes:labels", Multi version picker custom field type: "com.atlassian.jira.plugin.system.customfieldtypes:multiversion".

by custom field ID:

"Profession labels" IN (${currentIssue.cf[10005]}, EMPTY)

by custom field name:

Jira allows multiple custom fields with the same name but different type. In this case, the fields that have applicable context for the specific issue will be preferred, but if there are multiple such fields or if none of them has context for the issue the result will be indeterminate. This is why when there are multiple custom fields with the same name it is preferable to use the custom field id.

Supported custom field types

Jira comes with a predefined set of custom field types - for example, date picker or user multi-picker. Marketplace apps can add their own custom field types.

Below is a list of all the supported custom field types with examples on how to use them.

For all other custom field types, the replaced value is the value returned by the Jira API. This means that if the custom field value is an object which has a getNumber() method which returns 333 for a specific issue, the syntax

is valid and the evaluated JQL for the specific issue will be

List of supported custom field types

1 Checkboxes
2 Date Picker
3 Date Time Picker
4 Group Picker
5 Multi-group Picker
6 Labels
7 Number Field
8 Project picker
9 Radio Buttons
10 Select List (single)
11 Select List (multi)
12 Text field
13 Text field (read-only)
14 URL field
15 User Picker
16 User Picker (multi)
17 Version Picker
18 Version Picker (multi)

Checkboxes

Return value description	Comma-separated list of the value of the selected options surrounded by double quotes
Return value example	"Option 1", "Option 2"
Examples	Find issues where the value of the "DoD" custom field is contained in the list of the values for the current Issue:

Date Picker

Return value description	String in the format "yyyy/MM/dd" surrounded by double quotes.
Return value example	"2017/12/30"
Examples	Find issues where the value of the Due Date is the same as the value of the "Release Date" custom field for the current Issue: Find issues where the value of "Start Date" custom field is before the currentIssue's "Start Date" by using the custom field ID:

Date Time Picker

Return value description	Time string in the format "yyyy/MM/dd HH:mm" surrounded by double quotes.
Return value example	"2017/12/30 09:30"
Examples	Find issues where the value of the "Custom Date" is same current Issue's "Custom Date":

Group Picker

Return value description	The group name surrounded by double quotes.
Return value example	"jira-administrators"
Examples	Find issues where the value of the "Testing group" custom field is the same as current Issue's:

Multi-group Picker

Return value description	Comma separated list of group names surrounded by double quotes
Return value example	"jira-administrators", "jira-developers"
Examples	Find issues where the value of the "Dev Teams" custom field is not in the values of current Issue's "Dev Teams": `"Dev Teams" NOT IN (${currentIssue.cf["Dev Teams"]})`

Labels

Return value description	Comma-separated list of label names surrounded by double quotes
Return value example	"Orange", "Green"
Examples	Find all issues having a common "Profession labels" value with the current issue's "Profession labels":

Number Field

Return value description	The value of the field.
Return value example	20
Examples	Find issues where the value of the "Prize" custom field is less than current Issue's "Prize": `"Prize" < ${currentIssue.cf["Prize"]`

Project picker

Return value description	The key of the project
Return value example	TSP
Examples	Find issues where the issue's project is the same as the "Parent project" custom field of the current Issue: `project = ${currentIssue.cf["Parent project"]}`

Radio Buttons

Return value description	The value of the selected option surrounded by double quotes
Return value example	"Option 1"
Examples	Find issues where the option of the custom field is the same as the "Option" custom field of the current Issue: `"Option" = ${currentIssue.cf["Option"]}`

Select List (single)

Return value description	The value of the selected option surrounded by double quotes
Return value example	"Selection 1"
Examples	Find issues where the value of the custom field is the same as the "Selection" custom field of the current Issue: `"Selection" = ${currentIssue.cf["Selection"]}`

Select List (multi)

Return value description	Comma-separated list of the value of the selected options surrounded by double quotes
Return value example	"Selection 1", "selection 2"
Examples	Find issues which contain common components with the value of "Parent component" custom field of the current Issue

Text field

Return value description	The text field value surrounded by double quotes.
Return value example	"Sample text"
Examples	Find all issues with a summary with a value different than the value of the current issue's "Real Summary" custom field:

Text field (read-only)

Return value description	The text field value surrounded by double quotes.
Return value example	"Sample text"
Examples	Find all issues with a summary like the value of the current issue's "Short Description" custom field:

URL field

Return value description	The URL field value surrounded by double quotes.
Return value example	"http://sample.url"
Examples	Find all issues with the same "Documentation link" custom field value as the current issue's "Documentation link":

User Picker

Return value description	The username of the selected user surrounded by double quotes
Return value example	"Admin Username"
Examples	Find issues where the issue's assignee is the same as the "`Partner`" custom field of the current Issue: `assignee = ${currentIssue.cf["Partner"]}`

User Picker (multi)

Return value description	Comma-separated list of usernames of the selected users each surrounded by double quotes
Return value example	"Admin Username", "Fred Normal"
Examples	Find issues which contain common users in "Reviewers" custom field of the current Issue:

Version Picker

Return value description	The id of the selected version
Return value example	10001
Examples	Find issues where the issue's affectedVersion is the same as the "`Release Version`" custom field of the current Issue:

Version Picker (multi)

Return value description	Comma-separated list of the ids of the selected versions
Return value example
Examples	Find issues which contain common fixVersion with the "Release Versions" custom field of the current Issue: