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 `!=` is the NOT EQUALS operator, `=` is the EQUALS operator, and `in` is the IN operator. 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: Joins clauses together (for example `AND`) Alters the logic of clauses or operators (for example `NOT`) Has an explicit definition in a JQL query (for example EMPTY) Performs a specific function that alters the results of a JQL query (for example `ORDER BY`) 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.

Field Operator Value Keyword Field Function Operator Keyword Field Operator ScriptRunner JQL function Keyword Field Operator ScriptRunner JQL function Value

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.

JQL Functions Tutorial

What ScriptRunner JQL functions are available?