JQL Functions Tutorial
You can use ScriptRunner JQL functions to extend Jira's built-in capabilities, allowing you to conduct more granular searches, and obtain more detailed information about what is happening in your instance and projects. For example, if you need to find blocker issues in a project, you can use the hasLinkType ScriptRunner JQL function with the Blocker value. To understand how our functions work you must know how to search for issues in Jira and how to construct a JQL query.
Permissions
If a user does not have permission to see a given project/issue, then the result of a JQL search does not include the restricted projects/issues. See the Permissions page for full details on ScriptRunner permissions.
In this tutorial we assume you already have knowledge of Advanced and Basic search in Jira. If you're relatively new to JQL, the following table will help you understand some key terms used for constructing an Advanced search JQL query:
| Term | Description |
|---|---|
Clause | A clause is a simple JQL query consisting of a field, an operator, and a value or a function. |
Function | A function appears as a word followed by parentheses, for example currentUser(). The parentheses may contain one or more explicit values. You can check out the Atlassian JQL function documentation for more details on functions. |
| Operator | An operator can be a symbol, a set of symbols, or words that compare the value of a field on its left with one or more values or functions on its right. For example You can check out the Atlassian JQL operator documentation for more details on operators. |
| Field | A field is a word that represents a Jira field (for example assignee) or is a custom field that has already been defined in your Jira applications. You can check out the Atlassian JQL field documentation for more details on fields. |
| Keyword | A keyword in JQL is a word or phrase that does the following:
You can check out the Atlassian JQL keyword documentation for more details on keywords. |
| Value | A value is a component of the named field in a query. For example, if the field is project then the value would be a project name (in the example below the value is Great Adventure Tours). A value can also be a number, for example if you're searching for comments with hasComments then you can use a number value. |
What ScriptRunner JQL functions are available?
You can view a complete list of ScriptRunner JQL functions on the Included JQL Functions page. If you're a Jira administrator, you can view the available ScriptRunner JQL functions in your instance by going to Administration > ScriptRunner > JQL Functions. Administrators can also write custom JQL functions, but we do not cover that on this page.
If a ScriptRunner function on the Included JQL Functions page isn't visible in your instance then it may have been disabled in your instance.
You can also find most ScriptRunner functions when typing a query and using the issueFunction field.
What is issueFunction?
The issueFunction field comes built-in with ScriptRunner and allows you to run most ScriptRunner JQL functions.
In cases where issueFunction isn't required then a Jira field is required. For example, the archivedVersions ScriptRunner JQL function (used to find issues with archived fix versions) must be preceded by the Jira fixVersion field.
issueFunction in Basic search
The issueFunction field can be found under More when running a basic search. After you select the issueFunction field, you can add a compatible ScriptRunner function.
issueFunction in Advanced search
You can use the issueFunction field in Advanced search like any other field. The issueFunction field can only be used with the in and not in operators. After you enter the issueFunction field, followed by an operator, the compatible ScriptRunner JQL functions display.
ScriptRunner JQL tips
Start in basic search then switch to advanced search
If you need to become more familiar with how JQL works you can build a search query in basic search and then switch to advanced search to view the entire query.
Keep it simple
To make sure your search doesn't slow down your instance, we recommend you do the following:
Provide a subquery in your search to help limit results.
A subquery is a query within a function. If you're using the issuesInEpics() function you could add a subquery within the parentheses, for example
issueFunction in issuesInEpics ("status = 'to do' AND priority = 'high'"). The subquery in the example provided searches for epics with the named status and priority.Keep your queries as simple as possible
Save your JQL queries
If you frequently run the same JQL query you can save your search as a filter.
Function name clashes
If you use multiple plugins to alter JQL functionality, you may encounter a case where function names are the same in each plugin. In this case, you need to disable a function because the two plugins essentially cancel each other out. For example, if two plugins use the function hasSubtasks you may need to disable one to be able to use the other. We recommend you check out the Troubleshooting JQL Functions page for information on how to deal with this issue.
Test yourself on key JQL terms
Have a look at the JQL query below and see if you can identify the following:
- Fields
- Operators
- Keywords
- Values
- ScriptRunner JQL functions
Once you're happy with your decisions, hover over each part of the query to see if you are correct.
Examples of search using ScriptRunner JQL functions
We recommend you set up and use a sample project for the following examples. See the tutorial Before You Start page for more information on creating a sample project.
The following are simple examples for you to follow so you understand how ScriptRunner JQL functions work. Check out our Included JQL Functions documentation for all available ScriptRunner JQL functions and examples.
Find all blocker issues in a project
Before you start this tutorial make sure you have some blocker issues in your sample project. Blocker issues are issues that are given the "Blocks" issue link type.
Great Adventure wants to find all high priority blocker issues in their Great Adventure Tours project. By using the hasLinkType ScriptRunner JQL, the project manager can see what issues they need to assign for completion.
- Select Issues > Search for Issues.
- If you see the basic search with drop-down menus, select Advanced. (If you see a text bar, you are already in Advanced search.)
Enter the following onto the search bar, replacing the project name with your project:
project = GAT AND priority in (Highest, High) AND issueFunction in hasLinkType('Blocks')- Select Search. All results that match the JQL query display.
Once you run your search, you can save the search if you want to create a filter. You can also use this search query to power a Software board or even in a Service Management queue.
Find how much effort remains on a set of stories
Before you start this tutorial make sure you have a few time entries / remaining estimates in issues in your project.
Great Adventure wants to audit their current workload to find out how many weeks of effort remain on a set of stories. By using the aggregateExpression ScriptRunner JQL, the project manager can see at an instant the data and make an informed decision about their next steps.
- Select Issues > Search for Issues.
- If you see the basic search with drop-down menus, select Advanced. (If you see a text bar, you are already in Advanced search.)
Enter the following onto the search bar, replacing the project name with your project:
project = GAT AND issuetype = Story AND issueFunction in aggregateExpression("Remaining work for all Issues", "remainingestimate.sum()")- Select Search. The remaining work for all stories displays.
Once you run your search, you can save the search if you want to create a filter. You can also use this search query to power a Software board or even in a Service Management queue.
Find all epics with unresolved issues
Before you start this tutorial make sure you have some issues in an epic.
Great Adventure wants to find all epics in the Great Adventure Tours project with unresolved issues. Using the issuesInEpics ScriptRunner JQL, the project manager can see what epics have issues yet to be completed and make an informed decision about their next steps.
- Select Issues > Search for Issues.
- If you see the basic search with drop-down menus, select Advanced. (If you see a text bar, you are already in Advanced search.)
Enter the following onto the search bar, replacing the project name with your project:
You may also have to replace the status values with values that relate to your project.
project = "Great Adventure Tours" AND issueFunction in issuesInEpics("status in('to do', 'in progress')")- Select Search. All results that match the JQL query display.
Once you run your search, you can save the search if you want to create a filter. You can also use this search query to power a Software board or even in a Service Management queue.