Ultimate Guide

The main purpose of this article is to present the possibility of the Epic Finder app and to show how to solve problems that often appear as a question of Jira users. In this article we show you how to use Epic Finder with JQL (Jira Query Language) advanced searching.

In Jira we have three possibility of searching:

  • Quick Search
  • Basic Search
  • Advanced Search

Each of them has its purpose, possibilities and limitations.

Quick Search - the main purpose is quick issue search. In Quick Search you can jump to an issue, find free-text or use smart JQL query.

Basic Search (Issues → Search for issues) is used when you want to build query without using JQL. It is user friendly mechanism where you choose each elements of search query. If you have never used JQL before and you want in a simple way to find issues by criteria, this mechanism is for you. But this search has some limitations - in criteria definition you can choose only those that are predefined by JIRA. For more advanced search you must switch to Advanced mode.

Advanced Search is a search mode which allows you to search issues using JQL Query mechanism. This type of search is intended for advanced Jira users who know the JQL Query language. But this mechanism is most powerful when you want to search by advanced criteria. You can use in this mode logical operators, Jira fields and functions (predefined or extended by other apps). The last possibility is significant from the point of view of using Epic Finder app. What is the JQL function? It is an extension of the JQL language, which allows you to extend the Jira search engine for more advanced capabilities. For example, you can search for data that can not be found using JQL query.


Epic Finder

It is an app which is extension of Jira Query Language. It provides specialized JQL functions which allows you to realize more advanced query and finds data which you can not find using pure JQL Query. Epic Finder focuses on Agile type projects. Allows you to search for data such as epics, user stories, issues, subtasks.

Each Epic Finder function consists of prefix ef and next has name of element which are returned and next element which is the query parameter. For example, function efEpicsIssues returns the list of epics and takes issues as parameter. Issues meaning list of issues in this case is a query or filter for issues selection.

Below we present the possibilities of this app with examples.


Epic Queries


How to search for epics using JQL Query?

Create a request for issuetype as it is shown below.

If you want to add additional condition, for example status, you can do that in this way.

This query will return all Epics that have To do status. The same result you can get using function efEpics.

Or for example if you want to find epics for the Audit software project that have To do status.

The same functionality you can get using this query.

Or if you define filter AS_TODO = "project = \'Audit software\' and status = \'TO DO\'" you can use this function with filter name.

Or more advanced example, you can use filter and add additional condition, for example, assignee.

Function efEpics returns epics for specified query or filter and as you have noticed it has its equivalent in the query JQL.


How to create a JQL query that returns a list of empty epics (without user stories, issues)?

It is very hard to do that by JQL query. We can not find acceptable response for that question. Each answer involved using some specific apps from the Atlassian Marketplace. One example of such app is Epic Finder. If you want to find epics without user stories or issues you can use efEmptyEpics. This function returns empty epics which meet the given criteria. This criteria are defined as query or filter. Below is example how to find empty epics for project Audit software.

Or if you want return all epics for Audit software and status Done

Or if you want to find epics for project Audit software and assignee is Unassigned

In summary, the efEmptyEpics function searches for all empty epics that satisfy the query or filter condition.


How to find epics that have all issues completed?

We have generalized the question of how to find the epics that all issues have a particular status? As epics issues we think about issues in user stories which are joined with given epic. We have created a function efEpicsAllIssuesInStatus. Below is example of query which returns epics for project Audit software with all issues in status Done.

Or if you want to get epics for project Audit software and assignee Potty with all issues in status Done

Function efEpicsAllIssuesInStatus returns epics that meet the criteria defined in the query or filter and that all their issues have given status. It is very important to memorize that these are issues that are found in user stories (subtasks) and issues without user stories but added to given epics (e.g. as a bug). Please note that if we add the issue directly to epic (without user stories) and in this issue you define subtask then both issue and substask must have the given status (e.g. both must be done).


How to find epics that have issues and user stories in done status?

If you want to find epics for issues (user stories, bugs e.t.c) which meet given query or filter use function efEpicsIssues. This function returns epics which have issues that satisfy the condition specified in the query. 

This query returns epics which issues (all types) are in project Audit software and they have a status Done.  


How to find epics that have issues (all types) without assignee?

In this case you can also use the function efEpicsIssues. Below is example how to do that.

The efEpicIssues function has a great ability to search for epics based on issues that meet the condition given as a query or filter parameter. For example, you can search epics by issue version.

Or if you want you can filter epics by additional JQL query criteria

The above example returns epics for issues in project Audit software where epics are Unassigned.


How to find epics that have user stories with unassigned issues or assigned to given user?

The answer for this question is use efEpicsIssuesAssignee. This function returns the epics where issues or subtasks (without user stories) are assigned to the specified user. 

The above query returns epics for all issues and subtasks (without user stories) where assignee is user Potty.

Or if you want find epics with unassigned issues/subtasks 

How to find epics that have more than 3 issues in status done?

Use Epic Finder function efEpicsIssuesInStatusCondition. This function has two parameters, query or filter and condition. Condition has syntax: [status][=,<, <=,>=, >][number] 

Below is example which returns epics for more than 3 issues with status Done.

How to find epics that have user stories in given sprint?

To find epics which have user stories or issues in given sprint, use function efEpicsSprint. This function returns epics and takes as parameter a name of sprint or index.

The above example returns all epics which have issues realized in CRM sprint 2.


Issues Queries


How to search for issues in epic using JQL Query?

If you want to find issues for given epic, use efIssuesEpic. This functions takes one parameter epic key and returns list of issues (user stories/issues). Example below shows how to get issues for epic CRM-7.

This is simple function, which you can use as a part of a bigger query, for example to find issues from epics CRM-7 which assignee is user Potty.


How to find issues in epics labeled as Production?

If you need to find issues for epics which meet a given condition, use efIssuesEpics. This function takes as a paremeter query or filter and returns issues  (user stories/issues) for these epics which meet condition in query or filter.

In example above we want to find all issues for epics in project CRM which are labeled as Production.

Function efIssuesEpics is useful when you want to find issues for epics that meet certain criteria. Below you see example when this function behaves similar like efIssuesEpic.

This query return issues for epic key CRM-7. This example shows how flexible are the functions that have the query and filter as a parameter.


How to find issues for user stories in status Done?

Function efIssuesStories returns issues for stories which meet the condition as query or filter. And this function you can use for example to find issues in user stories in given state.

By using query or filter as a parameter, you can create any query that will return user stories and then add it as a parameter to the efIssuesStories function and get issues for these user stories.


I would like to find issues in the user stories for the given epic?

If you want to find issues (subtasks) for user stories in given epic you must use function efIssuesStoriesEpic. This function takes epic key as a parameter.


User stories Queries


How to search for user stories using JQL Query?

Use function efStories. This function is similar to efEpics but it returns user stories for given query or filter. Below example shows how to use this function to find user stories in status Done.

Or for example if you want to find user stories for the Audit software project that have To do status.

The same functionality you can get using query below.

Or if you define filter AS_TODO = "project = \'Audit software\' and status = \'TO DO\'" you can use this function with filter name.

Or more advanced example, you can use filter and add additional condition, for example, assignee.


How to find user stories which all issues has status done?

In Epic Finder you find function efStoriesAllIssuesStatus. This function find user stories for all issues with particular status. Below example shows how to use this function to return user stories for issues with status Done.

Or if you want to get user stories for project Audit software and assignee Potty with all issues in status Done.

Function efStoriesAllIssuesStatus returns user stories that meet the criteria defined in the query or filter and that all their issues have given status. It is very important to memorize that these are issues that are found in user stories (subtasks). 

How to create a JQL query that returns a list of empty user stories (without sub-tasks)?

If you want to find user stories without issues you can use efEmptyStories. This function returns empty user stories which meet the given criteria. This criteria are defined as query or filter. Below is example how to find empty user stories for project Audit software.

Or if you want to return all user stories for Audit software and status Done.

Or if you want to find user stories for project Audit software and assignee is Unassigned.


In summary, the efEmptyStories function searches for all empty stories that satisfy the query or filter condition.


How to create a JQL query that returns a list of user stories with sub-tasks?

If you want to find user stories with issues (excluding empty user stories) you can also use efEmptyStories as per below:


How to find user stories for given epic using JQL Query?

If you want to find user stories for given epic use efIssuesEpic. This functions takes one parameter epic key and return list of user stories . Example below shows how to get user stories for epic CRM-7.

This is simple function, which you can use as a part of a bigger query, for example to find user stories from epics CRM-7 which assignee is user Potty.


How to find user stories that have issues for fixVersion?

In this case you can also use the function efStoriesIssues. Below is example how to do that.

The efStoriesIssues function has a great ability to search for epics based on issues that meet the condition given as a query or filter parameter. For example, you can search user stories without assignee.

Or if you want you can filter user stories by additional JQL query criteria.

The above example returns user stories for issues in project Audit software where user stories are unassigned.


How to find user stories that have unassigned issues?

The answer for this question is use efStoriesIssuesAssignee. This function returns the user stories where issues (subtask) are assigned to the specified user. 

The above query returns user stories for all issues (sub-tasks) where assignee is user Potty.

Or if you want find user stories with unassigned issues/sub-tasks .


How to find user stories that have more than 1 issue in status in progress?

Use Epic Finder function efStoriesIssuesInStatusCondition. This function has two params, query or filter and condition. The query or filter is JQL query for issues (sub-tasks) and second parameter is condition which has syntax: [status][=,<, <=,>=, >][number] 

Below is example which returns user stories for more than 1 issue (subtasks) with status In progress.


Subtasks Queries


How to find all issues and subtasks for given epic?

Function efSubtasksEpic returns all issues (user stories, issues) and subtasks that have been added to given epic. As parameter function takes epic key. Below is example how to use this function to find all issues and sub-tasks in epic CRM-24.

The method is applicable as part of a larger query. For example, when we want to find all subtasks from epic which have status In Progress.

Or if you want to find in epic all Bugs that do not have an assignee.


How to find subtasks for epics that have a High priority?

Use function efSubtasksForEpics which takes as paremeter query or filter. This function returns all issues and subtasks for epics which meet query or filter condition. Below is example which is the response for this question.

Or if you want to find subtask for current user which are assigned to epics in project CRM with High priority without assignee