ScriptRunner Enhanced Search
Before you start
View the Enhanced Search training module outlining JQL functions and keywords.
What is the ScriptRunner Enhanced Search feature?
The ScriptRunner Enhanced Search feature provides advanced JQL function search capabilities, or queries, in Jira Cloud which you can modify or extend. Also available for use within those JQL queries are JQL keywords.
In essence, the terms ScriptRunner Enhanced Search and JQL queries (which are advanced searches that are made up of JQL functions and keywords) mean the same thing.
What are ScriptRunner JQL Functions?
The ScriptRunner Enhanced Search feature provides advanced JQL function search capabilities, or queries, in Jira Cloud. These extend Jira's built-in capabilities and enable you to conduct searches with greater granularity, including much more detailed information about what is happening in your instance and projects. For example, the linkedIssuesOf function will return issues of a certain type based on a subquery you give it.
ScriptRunner for Jira Cloud's out-of-the-box JQL functions are available to all users but can only be used on the Enhanced Search screen under Apps > Enhanced Search.
Below are just some examples of how you can use ScriptRunner JQL functions:
- Use epicsOf to query on epic links, such as finding all epics that have unresolved stories.
Use issuesInEpics to find all stories for open epics in a project, and then look specifically at the status of issues, such as ‘in progress.’
- Use linkedIssuesOf to return linked issues, such as all unresolved issues that are blocked by open issues.
What are ScriptRunner JQL Keywords?
Alongside JQL Functions are the JQL Keywords that can be used within those advanced JQL searches. ScriptRunner Enhanced Search looks at each issue in your Jira instance and adds metadata to them for easier and faster searching. We call this metadata JQL Keywords. These keywords can be used within JQL queries to access this metadata and allow users to search for previously unavailable variables, such as the number of sub-tasks (numberOfSubtasks).
JQL Keywords can be used in both the Enhanced Search screen under Apps > Enhanced Search or within Jira's issue navigator.
Below are just some examples of how you can use ScriptRunner JQL Keywords:
- Use numberOfAttachments to find issues that have a specified number of file attachments.
- Use numberOfSubtasks to search for issues that have a specified number of subtasks.
- Use commentedOn to find issues that have had a comment made on them on a specified date.
Technical Background
Add-on developers do not have access to the underlying database, therefore, the only way we can make a search to retrieve data is by using the Search API. Enhanced Search works by making simple queries to available APIs and then processing the results using pattern matching, comparing, aggregation and so on.
Let’s have a look at this example query:
assignee = currentUser() AND issueFunction in dateCompare("project = SRCLOUD", "created +1w < firstCommented") AND status = "In progress"
This contains a nested query. As you can see, the date compare function in the middle of the expression is not natively supported by Jira Cloud. We parse this query and process the dateCompare subquery as a first step. We make a standard search using the subquery "project = SRCLOUD" and then we apply the comparison expression on the results. At the end we make a final search to Jira Cloud with structure:
assignee = currentUser() AND issue in ("10012", "10013", "10055") AND status = "In progress"
As you can observe, the dateCompare query was replaced by another query: issue in (..). It contains issue ids/keys that were evaluated from the subquery. If you specify more than one advanced subquery, all of them will be evaluated and replaced in the final search.