JQL extension for custom fields

Owned by Rosen Marinkov
Last updated: Jul 26, 2023 by Julver Petrova (Deactivated)
4 min read

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

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:

Â