JQL Functions
Custom field name duplicates
If you have custom fields with the same name as Jira default fields, Enhanced Search will prioritise Jira’s default fields during searches. We recommend renaming your custom fields before using them in search queries, as Jira’s default fields will be used instead of custom fields with the same name.
Enhanced Search features several advanced JQL functions not available as default in Jira, which are documented within this section.
Almost all of the 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:
Go to the board's backlog.
Right click the elipsis icon just above the sprint.
- 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.
- 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
You can read about the differences between ScriptRunner for Jira Server and Jira Cloud advanced JQL functions in the side-by-side comparison here. There is also a Feature Parity table which outlines feature differences that includes JQL 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:
Some arguments will need to be quoted. For example, if you want to say one week before the start of the month, you would write startOfMonth('-1w').
Differences with ScriptRunner for Jira Server
You can read about the differences between ScriptRunner for Jira Server and Jira Cloud advanced JQL functions in the side-by-side comparison here. There is also a Feature Parity table which outlines feature differences that includes JQL functions.
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")
<, >, <=, >=, and =. The use of the "!=" operator when using the dateCompare function is only supported on ScriptRunner for Jira Cloud. However, you can achieve the same result by using "=" and negating the JQL clause itself in ScriptRunner for Jira Server/DC.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")
If your date contains time, equality operator won’t be useful. Use the clearTime() method described below.
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")
The issues returned when using link names such as 'blocks' and 'is Blocked by', or 'clones' and 'is Cloned by', in the linkedIssues of function may provide different results when using the same link names for the issueLinkType alias.
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.
DEMO-1 is returned by the query above as it has "is blocked by" links from DEMO-2 and DEMO-3.
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.
If you have 1000s of indirectly linked issues, traversal of all of the links will take a long time or may time out. A 30 second limit is imposed on queries to avoid a) overwhelming Jira with search requests and b) search results taking a long time to keep up-to-date.
When using a negative search, you can use the not keyword before or after issueFunction as shown in the following examples:
project = "KEY" and not issueFunction in linkedIssuesOfRecursive("component='componentName'", "depends on")
project = "KEY" and issueFunction not in linkedIssuesOfRecursive("component='componentName'", "depends on")
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}")
Note - the function searches for the regular expression anywhere within the field. To match the entirety of the field, use ^ and $, e.g. ^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")