---
title: "JQL extension for custom fields"
canonical: "https://support.appfire.com/space/ILV/198086197/JQL%20extension%20for%20custom%20fields"
format: markdown
---
> Macro (aura-html)

# 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
  
- Retrieving the custom field value using the name of the custom field
  
- 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:

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

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](https://docs.atlassian.com/jira/server/com/atlassian/jira/issue/fields/CustomField.html#getValue-com.atlassian.jira.issue.Issue-). 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 

|  |
| --- |
| ```
customField = ${currentIssue.cf[10006].number}
``` |

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

|  |
| --- |
| ```
customField = 333
``` |

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

## URL field

| **Return value description** | The URL field value surrounded by double quotes. |
| --- | --- |
| **Return value example** | "[http://sample.url](http://sample.url)" |
| **Examples** | - Find all issues with the same "Documentation link" custom field value as the current issue's "Documentation link":<br>```
  "Documentation link" = ${currentIssue.cf["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:<br>```
  "Reviewers" IN (${currentIssue.cf["Reviewers"]})
``` |

## 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:<br>```
  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:<br>```
   fixVersions IN (${currentIssue.cf["Release Versions"]})
``` |