JQL Extension

Owned by Rosen Marinkov
Feb 17, 2023
5 min read

On this page:

Overview

Issue Matrix for Jira provides an extension to the JQL syntax, which can be used to configure what an issue matrix custom field should display. The extension allows comparing issue fields (custom and system) with their values stored in the currently viewed issue.

This extension can be used in the JQL mode and the JQL filter configuration option in the Sub-Tasks, Issue Links, and Epic modes.

Learn JQL syntax

Issue Matrix for Jira extended JQL syntax follows Jira's JQL syntax rules and guidelines. To check Jira's advanced searching and JQL syntax rules, visit the following Atlassian documents:

A simple query in JQL (also known as a "clause") consists of a field, followed by an operator, followed by one or more values or functions. For example:

Comparing issue fields with the currently viewed issue

To allow you to compare system and custom issue fields with the currently viewed issue, the JQL syntax extension introduces the following placeholders:

  • $currentIssue

  • ${currentIssue}

  • $currentIssueKey

  • ${currentIssueKey}

Continue reading to find specific examples of how to use these placeholders in your queries.

The currentIssue() function has been deprecated!

The currentIssue() function has been deprecated due to problematic and inconsistent behaviour of the matrices created with it. This means the JQL queries you created with the currentIssue() function will still work, but it will not always produce error-free results.

Our recommendation: use the $currentIssue, ${currentIssue}, $currentIssueKey and ${currentIssueKey} placeholders instead of the currentIssue() function to ensure that your queries give correct results.

Comparing system fields

Here are some examples of comparing system field values using the JQL Query mode in Issue Matrix for Jira.

To find all issues in the TSP project for which the reporter is the same as the assignee of the current issue:

project = TSP and reporter = ${currentIssue.assignee}

To find all issues which are linked to the current issue and are in the Open status:

issue in linkedIssues(${currentIssue.key}) and status = Open

A complete reference for all supported system fields can be found in JQL extension for system fields.

Comparing custom fields

To find all issues with the same Customer Request Type as the current issue:

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

Same as above but using the custom field ID:

Searching by custom field ID vs name
It is safer to search by custom field ID than by custom field name.
Listed below, are potential problems you may have when searching by the custom field's name.

  • If a custom field has the same name as a built-in Jira system field, Jira will search for the system field (not for the custom field).

  • If a Jira administrator changes the name of a custom field, the change will break any saved filters that rely on that name.

Custom field IDs are unique and cannot be changed.

A complete reference for all supported custom field types can be found in JQL extension for custom fields.

Empty fields

Sometimes an issue field might be empty i.e. it has no value. Then a comparison query using this empty field will return all issues for which the same field does not have a value as well. If this is undesired, you can use the “is not empty” clause. This way, the comparison query will be applied only if the field is not empty.

Let's see this in practice. For example, you can use the following JQL syntax to find all issues with the same assignee as the current issue:

In this case, if an issue doesn't have an assignee, its issue matrix will show all the other issues in the project that are unassigned.

However, if you want to see results only for issues that have an assignee, you need to use the "is not empty" "clause:

In this case, if an issue doesn't have an assignee, its issue matrix will not show any issues.

System fields

Below, you will find extended JQL syntax for configuring Issue Matrix (in JQL mode) that will display issues with the same value(s) as in the system custom field value(s) in the current issue. The issue matrix will also include issues with an empty value in the system custom field.

  • Fix Version/s

  • Affects Version/s

  • Labels

  • Component/s

Custom fields

You can also use the “EMPTY” clause to query custom fields created by the admin. The JQL syntax examples below use the labels/multi-version custom field type. The Issue Matrix will display issues with the same values in the labels/multi-version picker field value(s) as in the current issue. The matrix will also include all issues with an empty value in the labels/multi-version picker field.

Labels custom field type: "com.atlassian.jira.plugin.system.customfieldtypes:labels"

Multi version picker custom field  type:  "com.atlassian.jira.plugin.system.customfieldtypes:multiversion"

  • Query by custom field ID:

  • Query by custom field name:

Jira Service Management

In this section, you can find Jira Service Management use cases where the JQL extension is used to compare issue fields with the values stored in the current issue. The examples illustrate how you can use the JQL extension with the following Jira Service Management fields: Customer Request Type, Organizations, and Reporter. Visit the JQL mode documentation to check how to configure the Jira Service Management fields comparisons.

With this feature, Jira Service Management agents can quickly assess the situation with a particular customer and find out if there are other open issues or not.

Customer Request Type

You can use the following JQL syntax to find and list all issues with the same "Customer Request Type" as the customer request type of the current issue:

Same Organization

You can use the following JQL syntax to find and list all issues associated with the same organizations as in the current issue:

Same Reporter

You can use the following JQL syntax to find and list all issues with the same reporter as in the current issue: