JQL extension for custom fields
On this page:
- 1 Extended JQL syntax
- 2 Supported custom field types
- 2.1 Checkboxes
- 2.2 Date Picker
- 2.3 Date Time Picker
- 2.4 Days since last comment
- 2.5 Group Picker (single group)
- 2.6 Group Picker (multiple groups)
- 2.7 Insight
- 2.8 Labels
- 2.9 Message Custom Field (for view)
- 2.10 Number Field
- 2.11 Organizations
- 2.12 Project picker
- 2.13 Radio Buttons
- 2.14 Request Type
- 2.15 Request Language
- 2.16 Satisfaction
- 2.17 SLAs
- 2.18 Select List (single)
- 2.19 Select List (multi)
- 2.20 Text field
- 2.21 Text field (read-only)
- 2.22 Text Field (multi-line)
- 2.23 URL field
- 2.24 User Picker
- 2.25 User Picker (multi)
- 2.26 User Property Field (< 255 characters)
- 2.27 Version Picker (single)
- 2.28 Version Picker (multi)
Extended JQL syntax
Issue Matrix for Jira Cloud offers you a custom JQL syntax that extends Jira’s JQL options and allows filtering based on the values of custom fields of the current issue.
You can see more information on the feature in our JQL extension document.
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
"Custom field name" = ${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".
Extended JQL syntax by custom field ID:
"Profession labels" IN (${currentIssue.cf[10005]}, EMPTY)
Extended JQL syntax by custom field name:
"Profession labels" IN (${currentIssue.cf["Profession labels"]}, EMPTY)
When should custom field names be surrounded by quotes?
When a custom field’s name is a single word, the name in the left side of the operand in the JQL syntax can be used without quotes:customFieldName = ${currentIssue.cf["customFieldName"]}
However, when the name consists of more than one word, you should surround its name in the left side of the JQL syntax in quotes:"Custom field name"= ${currentIssue.cf["Custom field name"]}
Jira allows having multiple custom fields with the same name but different types. In this case, the extended JQL will return the value of the first custom field found. 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 like a date picker or user multi-picker. Marketplace apps can also add their custom field types.
Below is a list of all the supported custom field types with examples of using them.
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 |
|
Date Picker
Return value description | String in the format "yyyy/MM/dd" surrounded by double quotes. |
---|---|
Return value example | "2017/12/30" |
Examples |
|
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 |
|
Days since last comment
Return value description | Date/time since last comment returned as a date "yyyy/MM/dd" surrounded by double quotes. |
---|---|
Return value example | "2021/09/09 15:30" |
Examples |
|
Group Picker (single group)
Return value description | The group name surrounded by double quotes. |
---|---|
Return value example | "jira-administrators" |
Examples |
|
Group Picker (multiple groups)
Return value description | Comma separated list of group names surrounded by double quotes |
---|---|
Return value example | "jira-administrators", "jira-developers" |
Examples |
|
Insight
Used in Jira Service Management Premium and Enterprise only
Return value description | Comma-separated list of object object IDs surrounded by double quotes |
---|---|
Return value example |
The return value has the following format: The workspaceId is the ID of the Insight workspace and objectId is the ID of the object referenced. |
Examples |
|
Labels
Return value description | Comma-separated list of label names surrounded by double quotes |
---|---|
Return value example | "Orange", "Green" |
Examples |
|
Message Custom Field (for view)
Return value description | Default message that will be displayed as HTML or as a wiki markup on demand on the View screen. |
---|---|
Return value example | "Option 1", "Option 2" |
Examples |
|
Number Field
Return value description | The value of the field. |
---|---|
Return value example | 20 |
Examples |
|
Organizations
Used in Jira Service Management only
Return value description | Comma-separated list of organization IDs surrounded by double quotes |
---|---|
Return value example | "3", "4", "7" |
Examples |
|
Project picker
Return value description | The key of the project |
---|---|
Return value example | Project ID (e.g. 1000) |
Examples |
|
Radio Buttons
Return value description | The value of the selected option surrounded by double quotes |
---|---|
Return value example | "Option 1" |
Examples |
|
Request Type
Used in Jira Service Management only
Return value description | Request type surrounded by double quotes |
---|---|
Return value example | "Request a change", “Investigate a problem“ |
Examples |
|
Request Language
Used in Jira Service Management only
Return value description | Request language surrounded by double quotes |
---|---|
Return value example | "de" |
Examples |
|
Satisfaction
Used in Jira Service Management only
Return value description | Rating number between 1 and 5 |
---|---|
Return value example | 5 |
Examples |
|
SLAs
Used in Jira Service Management only
Return value description | Time a string in the format "HH mm" surrounded by double quotes |
---|---|
Return value example | "24h 10m" |
Examples |
|
Select List (single)
Return value description | The value of the selected option surrounded by double quotes |
---|---|
Return value example | "Selection 1" |
Examples |
|
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 |
|
Text field
Return value description | The text field value surrounded by double quotes. |
---|---|
Return value example | "Sample text" |
Examples |
|
Text field (read-only)
Return value description | The text field value surrounded by double quotes. |
---|---|
Return value example | "Sample text" |
Examples |
|
Text Field (multi-line)
Return value description | Comma-separated list of the text field values surrounded by double quotes |
---|---|
Return value example | "Sample text1", "Sample text2" |
Examples |
|
URL field
Return value description | The URL field value surrounded by double quotes. |
---|---|
Return value example | |
Examples |
|
User Picker
Return value description | The account id of the selected user surrounded by double quotes. |
---|---|
Return value example |
|
Examples |
|
User Picker (multi)
Return value description | Comma-separated list of account ids of the selected users each surrounded by double quotes. |
---|---|
Return value example |
|
Examples |
|
User Property Field (< 255 characters)
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 |
|
Version Picker (single)
Return value description | The id of the selected version |
---|---|
Return value example | 10001 |
Examples |
|
Version Picker (multi)
Return value description | Comma-separated list of the ids of the selected versions |
---|---|
Return value example | 10001, 10002 |
Examples |
|