JQL Functions

Enhanced Search features several advanced JQL functions not available as default in Jira, which are documented within this section. 

Almost all functions require a subquery as a first parameter. If you provide an empty string (e.g.,""), your query will be inefficient because it matches all issues in your Jira instance.

You should be aware if you use the statement below within your subqueries, means that other users will see your results, not their own results:

assignee = currentUser()

For example, issueFunction in linkedIssuesOf("assignee = currentUser()") saved as an Enhanced Search filter will always show the issues linked to the filter owner's tickets, regardless of who views the filter.

Operators

Enhanced Search uses the  in and not in operators for all JQL functions. You can also use some additional operators for the Date Function.

Agile Functions

The board parameter in the three functions below may be either the board name or the board ID. You can find the board ID in the page URL when viewing the board e.g. https://example.atlassian.net/secure/RapidBoard.jspa?rapidView=24&projectKey=EXAMPLE shows the board ID to be 24.

inSprint

inSprint(board, sprint)

Query the issues of a sprint of an agile board. Both board and sprint are required fields.

issueFunction in inSprint("EX Scrum Board", "Sprint 3")

nextSprint

nextSprint(board)

Query the issues of the next active sprint of an agile board. Board is a required field.

issueFunction in nextSprint(452) AND assignee = currentUser()

previousSprint

previousSprint(board)

Query the issues of the previous active sprint of an agile board. Board is a required field.

issueFunction in previousSprint("Kanban Board") AND fixVersion IS EMPTY

addedAfterSprintStart

addedAfterSprintStart(board, sprint)

Query the issues added after the sprint began for the active sprint of an agile board. Only the board name is required. If a sprint is not chosen, then the default is the current active sprint. However, if there is more than one current sprint (parallel sprints) enabled for the board, it is mandatory to add the sprint parameter, as the function can only return one sprint. 

issueFunction in addedAfterSprintStart("EX Scrum Board", "Sprint 3")

You can use the board ID or name as the first argument. If a board and sprint are used, but the sprint was not created from that particular board,then the function will not show any results. The sprint needs to have been created from the board used in the function. This is a limitation on the information we receive from Jira when an issue is moved into a sprint after the sprint has started.

Using IDs

You can use the board ID or name as the first argument. If a board and sprint are used, but the sprint was not created from that particular board, then the function will not show any results. The sprint needs to have been created from the board used in the function. This is a limitation on the information we receive from Jira when an issue is moved into a sprint after the sprint has started.

You can use the sprint ID as the second parameter, but you must not contain the ID within quotes. For example:

issueFunction in addedAfterSprintStart("EX Scrum Board", 30)

To find the sprint ID:

1. Go to the board's backlog.

2. Right click the elipsis icon just above the sprint.
   

3. Copy the link, or URL, that looks similar to https://your-jira-instance.atlassian.net/rest/greenhopper/1.0/xboard/plan/sprints/actions?sprintId=30.
4. Go to the end of the link where you can retrieve the ID. In this example, the ID is 30.

Differences with ScriptRunner for Jira Server Agile Functions

The following agile functions are available on ScriptRunner for Jira Server but are not available on ScriptRunner for Jira Cloud:

• removedAfterSprintStart

• incompleteInSprint

• completeInSprint

Date Functions

Using Date Functions

You can use Date functions, for instance now(), startOfDay() etc, anywhere you would use a date. Supported functions include:

• now()

• startOfDay()

• startOfMonth()

• startOfWeek()

• startOfYear()

• endOfDay()

• endOfMonth()

• endOfWeek()

• endOfYear()

Differences with ScriptRunner for Jira Server

Functions startOfWeek() and endOfWeek() return Monday as the first day of the week and they take time in UTC. If you use Sunday instead of Monday, you can use -1d period modificator, e.g. startOfWeek('-1d').

dateCompare

dateCompare(Subquery, date comparison expression)

This function lets you compare two dates on the same issue, for instance to find all issues that were updated later than created:

issueFunction in dateCompare("project = SRCLOUD", "created < updated")

Time Windows

You can use time windows on both side of the expression. Eg to find issues resolved before or up to six days after their due date:

issueFunction in dateCompare("project = SRCLOUD", "resolutiondate +1d < duedate +1w")

Created and Updated

You can also use created or updated.

To find issues that were resolved within two weeks of creation, use:

issueFunction in dateCompare("project = SRCLOUD", "created +2w > resolutiondate ")

Datetime Custom Fields

You can also use date and datetime custom fields. Example:

issueFunction in dateCompare("project = SRCLOUD", "resolutiondate > customfield_10500")

where customfield_10500 is the name of a 'date' custom field.

Operators

Equal to Operator

You can also use the equality operator = to find issues that have been resolved on the same date that’s in a custom field:

issueFunction in dateCompare("project = SRCLOUD", "resolutiondate = customfield_10500")

Greater than or Equal to Operator

You can also use the greater or equal operator >= to find issues that have been resolved on or after the same date that’s in a custom field:

issueFunction in dateCompare("project = SRCLOUD", "resolutiondate >= customfield_10500")

Smaller or Equal to Operator

You can also use the smaller or equal operator ⇐ to find issues that have been resolved on or before the same date that’s in a custom field:

issueFunction in dateCompare("project = SRCLOUD", "resolutiondate <= customfield_10500")

Not Equal to Operator

You can also use the not equal operator != to find issues that have been resolved on a different date than that’s in a custom field:

issueFunction in dateCompare("project = SRCLOUD", "resolutiondate != customfield_10500")

Clear Time Operator

You can use the .clearTime() method to get the date part of a date or datetime field. The date will be converted to the user’s timezone, before the date is extracted:

issueFunction in dateCompare("project = SRCLOUD", "customfield_10500.clearTime() = duedate.clearTime()")

Epic Functions

epicsOf

epicsOf(subquery)

Jira Software users can query on epic links. For example, find all Epics that have unresolved stories:

issueFunction in epicsOf("resolution = unresolved")

Jira Software users can also query on epic links to find all epics which do contain any issues.

project = <ProjectKeyHere> and issuetype = Epic and NOT (issueFunction in epicsOf("project = <ProjectKeyHere>")

This function will only return issues of the Epic type.

issuesInEpics

issuesInEpics(subquery)

This function allows you to find issues related to epics found by the subquery. For example, find all stories for open Epics in a project:

issueFunction in issuesInEpics("project = DEMO AND status = 'To Do'")

issueFunction in issuesInEpics("resolution IS NOT EMPTY") AND resolution IS EMPTY

Issue Link Functions

linkedIssuesOf

linkedIssuesOf(Subquery, [link name])

This is similar to parentsOf and subtasksOf, in that it will return the linked issues.

To find all the unresolved issues that are blocked by issues in the Open state you could use:

issueFunction in linkedIssuesOf("status = Open", "blocks") AND resolution IS EMPTY

With no link name argument, this function will search for the linked issues whatever the link type:

issueFunction in linkedIssuesOf("resolution = unresolved")

linkedIssuesOfRecursive

linkedIssuesOfRecursive(Subquery, [Link name])

This is similar to linkedIssuesOf, in that it will return the linked issues, however this function traverses issue links recursively to return all issues that are linked (directly and indirectly) to the results of the initial subquery.

We have protection mechanisms built in to deal with circular dependencies in your issue links. For example, if DEMO-1 links to DEMO-2, DEMO-2 links to DEMO-3 and DEMO-3 links to DEMO-1, then we will notice that we have already seen DEMO-1 and stop processing. 

To find all direct and indirectly linked issues of a particular issue you can use:

issueFunction in linkedIssuesOfRecursive("issue = DEMO-1")

So if we have the following setup:

Then our query would return: DEMO-1, DEMO-2, DEMO-3, DEMO-4 and DEMO-5.

You can limit the type (and direction) of links that are traversed using the second parameter.

issueFunction in linkedIssuesOfRecursive("issue = DEMO-1", "blocks")

In this instance, if we use the example already mentioned, only DEMO-2, DEMO-3 and DEMO-4 will be returned.

The Link type parameter behaves exactly the same as the Link description parameter for linkedIssuesOf.

linkedIssuesOfRecursiveLimited

linkedIssuesOfRecursiveLimited(Subquery, Traversal depth, [Link name])

This function is exactly the same as linkedIssuesOfRecursive but it allows us to limit the depth of traversals along issue links that the function will do.

The following query will follow all links, recursively, from all issues in the DEMO project until it has traversed a maximum of 2 links deep along any link path.

issueFunction in linkedIssuesOfRecursiveLimited("project = DEMO", 2)

Using the following setup:

Our query with the depth parameter would return: DEMO-1, DEMO-2, TEST-1, TEST-2, TEST-4 and TEST-5.

We could specify the link name as well, to get different results:

issueFunction in linkedIssuesOfRecursiveLimited("issue = TEST-2", 3, "is blocked by")

which would return: TEST-3, TEST-6 and TEST-5

Match Functions

issueFieldMatch

issueFieldMatch (jqlQuery, fieldname, regexp)

Query on any field by regular expression. Performance will be roughly proportional to the number of issues selected by the subquery, so use the query that selects the smallest set of issues you can, eg just your projects. Fieldname and regexp are required fields.

To find all issues where the description contains a ABC0000 where 0000 is any number, you could use:

issueFunction in issueFieldMatch("project = SRCLOUD", "description", "ABC\d{4}")

issueFieldExactMatch

issueFieldExactMatch (jqlQuery, fieldname, regexp)

Find issues by matching the text of a field exactly. Fieldname and regexp are required fields.

projectMatch

The following functions provide lists of projects that match the provided regular expression for the project key.

projectMatch(reg exp)

For example, you want to look for all projects that have keys starting with ABC:

project in projectMatch("^ABC")

componentMatch

The following functions provide lists of components that match the provided regular expression for the component name.

componentMatch(reg exp)

For example, you want to look for all issues that have a component beginning with Web:

component in componentMatch("^Web.*")

versionMatch

The following function provides lists of versions that match the provided regular expression.

versionMatch(reg exp, [project keys])

For example, you want to find issues with the fixVersion field value that starts with RC across all projects:

fixVersion in versionMatch("^RC.*")

And the same search but restricted to several projects:

fixVersion in versionMatch("^RC.*", "DEMO, EXAMPLE, TEST")

Subtask Functions

subtasksOf

subtasksOf(subquery)

Returns the subtasks of issues specified by the subquery, eg:

issueFunction in subtasksOf("project = SRCLOUD")

To find unresolved subtasks of resolved issues you might use:

issueFunction in subtasksOf("resolution IS NOT EMPTY") AND resolution IS EMPTY

To find subtasks that are Open, but their parent issue has a resolution of Fixed, you could use:

issueFunction in subtasksOf("resolution = Fixed") AND status = Open

subtasksOf is analogous to saying "subtasks which have a parent selected by the subquery".

childrenOf

This function allows users to find descendant issues of a given subquery, including children and grandchildren. For instance, it can be used to find children issues of initiatives and epics.

The syntax for it is:

childrenOf(subquery)

Examples:

• To get all children issues of an initiative or any issue type:
  

  issueFunction in childrenOf("issue = EXAMPLE-1")
  
  

• To find children issues of a project that aren’t subtasks:
  

  issueFunction in childrenOf("project = DEMO") and issueType != "Subtask"

parentsOf

This function allows users to find the ancestor issues of a given subquery, including parents and grandparents. For instance, it can be used to find parent issues of subtasks, stories and epics.

To find the parent issue of subtasks:

parentsOf(subquery)

To find the parents (and grandparents) of stories, epics and beyond:

parentsOf(subquery, "all")

Examples:

• To find parent issues of subtasks in a project:

  issueFunction in parentsOf("project = DEMO")
  
  

• To find all the epics and initiatives in a project with stories, epics and initiatives:

  issueFunction in parentsOf("project = DEMO", "all")
  
  

• To find just the initiatives in a project which has initiatives, epics and stories:
  

  issueFunction in parentsOf("project = DEMO", "all") and issueType!="Epic"

• To find parent issues that have at least one open sub-task:
  

  issueFunction in parentsOf("project = DEMO AND status = Open")
  
  

• To find closed parent issues with open sub-tasks:
  

  status = Closed AND issueFunction in parentsOf("project = DEMO AND status = open")