JQL extension for custom fields

Owned by Rosen Marinkov
Mar 13, 2023
6 min read

On this page:

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:

  1. Retrieving the custom field value using the id of the custom field
    customField = ${currentIssue.cf[10006]}

  2. Retrieving the custom field value using the name of the custom field
    "Custom field name" = ${currentIssue.cf["Custom field name"]}

  3. 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".

    1. Extended JQL syntax by custom field ID:
      "Profession labels" IN (${currentIssue.cf[10005]}, EMPTY)

    2. 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

  • Find issues where the value of the "DoD" custom field is contained in the list of the values for the current Issue:

    "DoD" IN (${currentIssue.cf["Dod"]})

 

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:

    duedate = ${currentIssue.cf["Release Date"]}

  • Find issues where the value of "Start Date" custom field is before the currentIssue's "Start Date" by using the custom field ID:

    cf[10006] < ${currentIssue.cf[10006]}

 

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":

    "Custom Date" = ${currentIssue.cf["Custom Date"]}

 

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

  • Find all issues updated after the current issue’s “Days since last comment” custom field value:

    updated > ${currentIssue.cf["Days since last comment"]}

 

Group Picker (single group)

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:

    "Testing group" = ${currentIssue.cf["Testing group"]}

 

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

  • 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"]}) 

 

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

"ari:cloud:cmdb::object/152d60fb-dde9-48f7-afa6-d1643ae9f633/3", "ari:cloud:cmdb::object/152d60fb-dde9-48f7-afa6-d1643ae9f633/6"

The return value has the following format:
"ari:cloud:cmdb::object/${workspaceId}/${objectId}"

The workspaceId is the ID of the Insight workspace and objectId is the ID of the object referenced.

Examples

  • Find all issues having a common "Software products" value with the current issue's "Software products" values:

"Software products" IN (${currentIssue.cf["Software products"]})

 

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":

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

 

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

  • Find all issues with “Doc link” url field value contained in current issue’s “Default message” field value:

    "Doc link" IN (${currentIssue.cf["Default message"]})

 

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"] 

 

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

  • Find all issues associated with the same organizations as in the current issue:

    Organizations = ${currentIssue.cf["Organizations"]}

     

  • Find all issues associated to an organization of the current issue’s organizations:

Organizations IN (${currentIssue.cf["Organizations"]}

  • Find all issues associated with the same organizations as in the current issue (find by custom field ID):

Organizations = ${currentIssue.cf[10002]}

 

Project picker 

Return value description

The key of the project

Return value example

Project ID (e.g. 1000)

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"]}

 

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

  • Find all issues of the same request type as the request type of the current issue:

"Request Type" = ${currentIssue.cf["RequestType"]}

 

  • Find all issues with Request Type the same as the customer request type with a specific id in the current issue (find by custom field ID):

"Request Type" = ${currentIssue.cf[10010]}

 

Request Language

Used in Jira Service Management only

Return value description

Request language surrounded by double quotes

Return value example

"de"

Examples

  • Find all issues with the same "Request Language" as the request language of the current issue:
    "Request Language" = ${currentIssue.cf["Request Language"]}

 

  • Find all issues with "Request Language" the same as the request language with a specific id in the current issue (find by custom field ID):
    "Customer Request Type" = ${currentIssue.cf[10034]}

 

Satisfaction

Used in Jira Service Management only

Return value description

Rating number between 1 and 5

Return value example

5

Examples

  • Find all issues with the same rating number as of the current issue:
    "Satisfaction" = ${currentIssue.cf["Satisfaction"]}

 

  • Find all issues with the same satisfaction value as of the current issue (find by custom field ID):
    "Satisfaction" = ${currentIssue.cf[10032]}

 

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

  • Find all issues with time to close more than the time to close of the current issue:
    "Time to close" > ${currentIssue.cf["Time to close"]}

 

  • Find all issues with time to first response less than the time to response of the current issue:

    "Time to first response" < ${currentIssue.cf["Time to first response"]}

 

  • Find all issues with time to resolution less than the time to resolution of the current issue:
    "Time to resolution" > ${currentIssue.cf["Time to resolution"]}

 

  • Find all issues with time to review less than the time to review of the current issue:

    "Time to review" > ${currentIssue.cf["Time to review"]}

 

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:
    components IN (${currentIssue.cf["Parent components"]})

 

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: 
    summary !~ ${currentIssue.cf["Real Summary"]}

 

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: 
    description ~ ${currentIssue.cf["Short Description"]}

 

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

  • Find all issues whose URL field value is included in the current issue’s text field value:

    url IN (${currentIssue.cf["Text 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":
    "Doc link" = ${currentIssue.cf["Doc link"]}

 

User Picker 

Return value description

The account id of the selected user surrounded by double quotes.

Return value example

557058:5aedf933-2312-40bc-b328-0c21314167f0

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 account ids of the selected users each surrounded by double quotes.

Return value example

"557058:f14b7e17-b5c0-4a14-bbae-37296b8c50a0", "557058:5aedf933-2312-40bc-b328-0c21314167f0"

Examples

  • Find issues which contain common users in "Reviewers" custom field of the current Issue:
    "Reviewers" IN (${currentIssue.cf["Reviewers"]})

 

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

  • Find all issues where the value of the project field is contained in the values for the current issue’s “User Property Field”:

    project IN (${currentIssue.cf["User property"]})

 

Version Picker (single)

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:
    affectedVersion = ${currentIssue.cf["Release Version"]}

 

Version Picker (multi)

Return value description

Comma-separated list of the ids of the selected versions

Return value example

10001, 10002

Examples

  • Find issues which contain common fixVersion with the "Release Versions" custom field of the current Issue:
    fixVersions IN (${currentIssue.cf["Release Versions"]})