In this post we show you how to use Jira's advanced JQL language to search for related issues. Often in Jira you'll want to search and find issues that are related to another issue. Perhaps you have Child issues or Linked issues for a particular issue you're working on. You just need to list, in the search results, all these related issues.
In Jira there are two ways to relate issues to each other…
Two Ways to Relate Issues
1. parent / child – created with the 'Add a child issue' feature
2. linked issues – created with the 'Link Issue' feature
In our example above we have an Epic (issue key SCR-26) that has both child issues AND linked issues. We're going to see how to search for that Epic and display those related issues, either child issues or linked issues or both.
First, when searching for children (User Stories and Tasks) of a parent (the Epic) we have ….
– Epic SCR-26 that has some User Stories and Tasks created as child issues
– Child issues, which when viewed you see the parent which is the Epic SCR-26
To find Child issues of a parent we can simply use the JQL …
parent = SCR-10
Or to find all the child issues for many parent issues…
parent in (SCR-26, SCR-10)
In our example task SCR-27 (a child Story of the Epic) has sub tasks.
Jira JQL for Related Issues
Our search will NOT list sub tasks related to the child issues. In our example above if Story SCR-28 had sub tasks these would not be shown in the results. Jira and JQL does NOT support this capability out of the box. You'll need a plugin like Script Runner for that.
Second then, let’s look at, 'linked issues. Our “parent in" JQL statement with our Epic (SCR-26) will not pick up linked issues. In our example Bug SCR-26 is linked to Epic SCR-10 … but doesn't show with the ‘parent in’ JQL!
We need a different JQL search for this. For this we can use the ‘linkedIssues()’ function. This JQL will pick up linked issues
issue in linkedIssues("SCR-26")
The ‘linkedIssues()’ function searches for issues linked to an issue.
Jira Linked Issues
When we use this in conjunction with the ‘issues in’ statement it’s saying “get me all issues – from the list returned when using the linkedIssues() function”.
This function also gives us the ability to filter by link type…
issue in linkedIssues(SCR-26, "is blocked by")
The limitation with this query is that it only returns results for one issue. If you want to find linked issues for more than one issue, then again we have to turn to the ScriptRunner app from the Atlassian marketplace.
Anyway, back to what you can do with core JQL. If you want to find ALL related issues … both 'child issues' and 'linked issues', then you'll need to use a query that combines both…
issue in linkedIssues("SCR-26") or parent = SCR-26
This JQL will pick up all issues that are related to the parent Epic.
Jira Linked Issues or Parent Issues
In summary you can search for related issues using the 'parent' keyword and the 'linkedIssues()' function. There are a few limitations though. Firstly 'parent' will only identify issues one level down (it will not find child issues of the parents child issues ). Secondly the 'linkedIssues()' function only allows you to search for issues linked to ONE issue.
In the next post and video we'll take a look at searching for issues in Sprints.
