PU - Using JQL functions

Owned by Iryna Ihnatiuk
Last updated: Sept 06, 2021
5 min read

The following custom JQL functions enable you to expand your search in Jira:

JQL Functions

Be careful with JQL functions as they might be too powerful for some Jira instances. We recommend that you configure these functions so that your Jira performance is not affected.


JQL functionsDescriptionExamples

commentedIssues(timeframe)

Returns issues that have been commented by a currently logged in user within the specified time frame. To perform such search, you must have the "browse issues" rights.
  • issue in commentedIssues("5h")
  • issue in commentedIssues("startOfWeek")
  • issue in commentedIssues("startOfDay")

issuesParents(JQLquery)

Returns a list of issues that are parents of all issues inside the specified JQL query.

18416993

issue in issuesParents("Project = PRDT")

issuesSubtasks(JQLquery)

The issuesSubtasks function returns a list of issues that are subtasks of all issues in the specified JQL query.

issue in issuesSubtasks("Project = PRDT")

linkedIssuesHasStatuses(Status, linkingType)

Returns tickets that have linked issues which are in the specified status and that are linked with the specified linking type.

For example, you have a ticket A, and it's cloned by ticket B which is in progress. The following:

issue in linkedIssuesHasStatuses("In Progress", "clones")

will search for the tickets that

  • are in the In progress status - it will find many tickets, and ticket B among those.
    and 
  • then among those found search those that have the linking type clones - it will find ticket B

...and then it will display the tickets that this ticket B clones, in our case this is ticket A.

  • issue in linkedIssuesHasStatuses("In Progress")
  • issue in linkedIssuesHasStatuses("In Progress", "To Do", "clones")
  • Special JQL: areNotBlocked() = linkedIssuesHasStatuses("Open", "Reopened", "In Progress", "is blocked by")






membersOfProjectRole(Group)

Returns the users who are the members of a certain role inside the Jira project.
  • assignee in membersOfProjectRole("AAA", "Administrators")
  • assignee in membersOfProjectRole("IOS", "iOS Developers")
  • assignee in membersOfProjectRole("HELP", "Support team members")

transitionCount(Project, Status, Count, Operation)

This JQL function enables you to get a list of tickets in the specified project (first parameter) that were in a certain status (second parameter), X amount of times (third parameter) with a certain operation (fourth parameter - possible options">", "<", "=", ">=", "<=", "<>").
  • issue in transitionCount(SP, "Done", 4, "<") 
    It means that we search for the issues that were in 'Done' status less than 4 times

transitionDate(Duration, Status)

This function returns a list of tickets for which the status was changed within the specified time frame (first parameter) to the specified status (second parameter). For example, "2h" would mean within the last 2 hours.
  • transitionDate(2d, Closed)

transitionReporter(User, Status, Project)

Returns a list of issues where the status was changed by the specified user (first parameter) to the specified status (second parameter) within the specified project (third parameter, optional).
  • transitionReporter (Admin, Resolved, PROD)

transitionReporterGroup(Group, Status, Project)

Returns a list of issues that were transitioned by anyone from the specified group (first parameter) to the specified status (second parameter) within the specified project (third parameter, optional).
  • transitionReporterGroup(Administrators, Resolved, PROD)

userCommentedIssues(User, Duration)

Returns the issues that have been commented by a particular user within the specified time frame, for example, within the last 5 hours. To perform such search, you must have "browse issues" rights.

18416993
  • issue in userCommentedIssues("admin", "5h")
  • issue in userCommentedIssues("user", "startOfWeek")
  • issue in userCommentedIssues("fakeuser", "startOfDay")
  • issue in userCommentedIssues("admin", "startOfYear")
  • issue in userCommentedIssues("admin", "startOfMonth")
  • issue in userCommentedIssues("admin", "week")
  • issue in userCommentedIssues("admin", "month") / userCommentedIssues("admin", "5months")
  • issue in userCommentedIssues("admin", "year") / ("admin", "y")

groupCommentedIssues(User, Duration)

Returns the issues that have been commented by a particular group within the specified time frame, for example, within the last 5 hours. To perform such search, you must have "browse issues" rights.
  • issue in groupCommentedIssues("admin", "startOfYear")
  • issue in groupCommentedIssues("admin", "startOfMonth")
  • issue in groupCommentedIssues("admin", "week")

relatedIssuesByField(query, customFieldId)

Returns issues that contain issue keys of other issues in the specified field.
  • issue in relatedIssuesByField("project = Products and status != Resolved","customfield_10909")

relatedIssuesByQuery (query1, query2)

Allows to apply Query2 for the Query1 results.

It returns issues according to the following algorithm:

  1. Query1 starts running and the list of results appears.
  2. The function reads the results and applies Query2 to each of the Query1 results.
  3. The function substitutes the SELF_VALUE word from the Query2 with the Issue key of the Query1.
  4. Returns the results to the function.

JQL 1 = "project = TEST and assignee = test"
JQL 2 = "key = SELF_VALUE and AND \"Start Date\" > startOfDay()"

relatedIssuesByQuery("project = TEST and assignee = test", "key = SELF_VALUE and AND \"Start Date\" > startOfDay()")

JQL 1 starts running inside the function and, for instance, will find the following tasks:
TEST-1, TEST-2, TEST-3 ...

Then, it will perform the following calls and accumulate the results.
"key = TEST-1 and AND \"Start Date\" > startOfDay()"
"key = TEST-2 and AND \"Start Date\" > startOfDay()"
"key = TEST-3 and AND \"Start Date\" > startOfDay()"

Examples

Finding user's commented tickets

The following example will help you find tickets where the Tester6 user commented anything within the last 5 hours.

  1. Go to Issues > Search for issues.
    • If there are existing search criteria, click the New filter button to reset the search criteria.

    • If the basic search is shown instead of the advanced search, click Advanced.

  2. Enter your JQL query. As you type, Jira will offer a list of "auto-complete" suggestions based on the context of your query. Note that the auto-complete suggestions only include the first 15 matches, displayed alphabetically, so you might want to enter more text if you can't find a match.

    For example:

     project = PRDT and issue in userCommentedIssues("Tester6", "5h")

  3. Press Enter or click  to run your query. Your search results will display in the issue navigator.




Configuring a JQL function to prevent Jira performance issues

The following example will help you set the parameter in JQL function to prevent Jira performance issues.

  1. Go to Issues > Search for issues.
  2. Enter your JQL query. 
    For example: issuekey in issuesParents("project=TP").

  3. Your search results should be displayed in the issue navigator but it returned an error because the amount of results could be too large and could affect Jira performance.



  4. To prevent the error, ask your Jira Administrator to configure JQL functions in a way that allows more results.
  5. Enter your JQL query again.


Note that due to server specifics increasing the limit might not be an option. In that case you need to re-run the JQL query in a way that you don't get too many results.