If you are a Jira user or administrator, you’ve likely explored the search feature to find specific issues or lists of issues. While some searches are simple, others can be complex and require knowledge of JQL (Jira Query Language).
Introduction to JQL Search
JQL, or Jira Query Language, is a powerful tool for creating advanced search queries in Jira. One interesting aspect of JQL searches is that you can save them as filters for various purposes, including subscriptions, dashboards, Agile boards, and project portfolio plans, among others. Sometimes, you’ll need to craft a JQL query to create a filter that precisely groups the issues you want to display on your dashboard or board.
Before we delve into JQL tricks, let’s explore the different ways you can perform an issue search in Jira.
Jira Search Features: Unleashing the Power of JQL
1. Quick Search
The quick search is the most straightforward search feature accessible from the application header. It offers three methods of usage:
- Free-text searching: When you type a word that isn’t a Jira keyword, Jira will search in the Summary, Description, and Comments fields of the issue, redirecting you to the Issue Navigator with the matching issues.
- Jumping to an issue: Typing the issue key (e.g., TP-146) redirects you to that specific issue, provided you have the permission to view it. If you type only the number (e.g., 146), you’ll be taken to the issue with that number in the current project you are working on.
- Smart JQL querying: This search allows you to find specific issues using short queries, optimizing your search time. Some popular smart queries include “my” (returns issues assigned to the current user) and “r:me” (returns issues reported by the current user).
2. Basic JQL Search
Basic JQL search is recommended if you’re new to Jira Query Language and want a simple way to filter issues. Access it from the Issue Navigator by choosing “Issues” > “Search for Issues” in the application header. The basic search bar includes drop-down menus to narrow your search and allows adding more fields using the “More” menu.
3. Advanced JQL Search
The advanced search provides an autocomplete feature that allows you to craft queries using JQL. Any basic search can be translated into a JQL query by switching to the Advanced mode from the Basic mode. Reasons to use the advanced search mode include utilizing the OR logical operator, dealing with unsupported fields, or using JQL functions.
Commonly Requested Jira JQL Filters: Exploring Linked Issues and More
1. Linked Issues
A. All Linked Issues
To obtain the list of issues linked to a specific issue, use the built-in JQL function “linkedIssues(issueKey).”
Example: issue in linkedIssues(“TP-345”)
B. Linked Issues by Link Type
If you want to get the issues linked to a specific issue with a particular link type, use the function “linkedIssues(issueKey, linkType).”
Example: issue in linkedIssues(“TP-345”, “blocks”)
To find the link type, navigate to Administration > Issues > Issue Linking and use the “Name” column.
2. Issues with Links
To filter all issues that have ANY linked issues, use the function “hasLinks(linkType).”
Example: issueFunction in hasLinks()
3. Issues Linked to Filtered Issues
If you want to get the list of issues linked to a specific set of issues (filter of issues), use the function “linkedIssuesOf(Subquery).”
Example: issueFunction in linkedIssuesOf(“project=IDP”)
Jira JQL Issue Hierarchy: Navigating Epics, Stories, and Subtasks
1. Subtask Queries
To get the list of subtasks in Jira, use the object “Parent” and specify the parent issue key(s).
Example: parent = “IDP-4689”
For subtasks of a subset of issues, use the function “issueFunction in subtasksOf(Subquery).”
Example: issueFunction in subtasksOf(“project=IDP and issuetype=Incident”)
2. Parent Queries
To get parent issues of a subset of subtasks, use the function “issueFunction in parentsOf(Subquery).”
Example: issueFunction in parentsOf(“project=IDP and issuetype=Incident”)
3. Epics, Stories, and Subtasks
To get stories under epics, use the custom field “Epic Link.”
Example: “Epic Link” in (SCUR-24, SCUR-25)
To get epics for a subset of issues (stories), use the function “issueFunction in epicsOf(Subquery).”
Example: issueFunction in epicsOf(“project=IDP AND issuetype=Incident”)
To get the three levels of hierarchy in JQL, use the ScriptRunner app with the function “issueFunction in linkedIssuesOf(Subquery, linkType).”
Example: (project = IDP AND issuetype = Epic) OR issueFunction in linkedIssuesOf(“project = IDP AND issuetype = Epic”, “is epic of”) OR issueFunction in subtasksOf(“issueFunction in linkedIssuesOf(‘project = IDP AND issuetype = Epic’, ‘is epic of’)”)
Current User Context and User Membership Queries: Personalized Issue Searches using Jira JQL
The “Current User” context can be used with specific fields/custom fields like Reporter, Assignee, Watcher, Voter, and Any User Picker custom field.
Example: assignee = currentUser()
To get the list of issues where a user is part of a specific group in Jira, use the function “membersOf(GroupName).”
Example: assignee in membersOf(“jira-administrators”)
Portfolio for Jira and ScriptRunner: Enhancing Jira JQL with Portfolio Context
JQL queries based on Portfolio for Jira context can be performed using the Parent Link custom field and JQL functions provided by Portfolio for Jira and ScriptRunner.
Example: “Parent Link” in (“project=IDP”)
To use advanced JQL functions, such as “portfolioChildrenOf(Subquery)” and “portfolioParentsOf(Subquery),” make sure to have Portfolio for Jira installed along with ScriptRunner version 5.0.11 onwards.
Conclusion
JQL is a versatile tool that enables powerful searches in Jira. While the out-of-the-box features offer many possibilities, apps like ScriptRunner provide additional functionalities for more targeted queries. By combining the right functions and understanding the JQL syntax, you can efficiently manage and navigate your Jira instance to get the most out of it.
For more tips and assistance with Atlassian tools, feel free to get in touch with our team.
