JQL Functions Tutorial

To power searches, dashboards, Software boards (etc.) using advanced queries, Jira uses its own Jira Query Language, known as JQL. JQL searches have a field, an operator and a function. The first two are relatively straight forward, but let’s focus on the third for a moment.

A function defines a variable with a word, such as approver, and a set of parenthesis after the word. This set of parenthesis can include a qualifier(s) inside to help further define the set of values the function uses, but they aren’t required. So as an example, for an approver function, you could write approval=approver(kparker) in standard JQL.

A script JQL function takes a basic JQL function and powers it up with ScriptRunner, allowing you to extend your capabilities in areas where you can use JQL such as searches and Jira Software boards.

While you use JQL functions in several different places within Jira, let’s start with the administration side to see what script JQL functions you have available in your instance. To get here, you access the JQL Functions page of the Jira administration console (Administration>Manage Apps>JQL Functions).

What are Script JQL Functions?

Script JQL functions allow you to extend your JQL capabilities with functions like addedAfterSprintStart, fileAttached, and hasComments. Basically, taking JQL functions deeper by looking further into your Jira instance and digging up more specific information. For example, the ScriptRunner JQL function, hasLinkType() can find all issues with a particular link type by entering it, for example Blocks, in the parenthesis of the function to define that qualifier.

On the JQL Functions page, you can view the enabled script JQL functions available on your instance. To manage these functions, you access the Universal Plugin Manager (UPM) on the Manage Apps page on the Jira administration console.

Script JQL functions allow you to be more granular in your searches and obtain more detailed information about what is happening in your Jira instance and in your projects. For example, if you needed to find issues in a project that are blockers, you can run the hasLinkType script JQL function to find those issues. Likewise, you can find information on issues added after a sprint starts with the addedAfterSprintStart and so on. There are several built-in JQL functions that you can use with ScriptRunner installed, which you can review here. You can also write your own custom script JQL functions, but we don’t cover that here.

If you can use JQL in your Jira instance, you can run script JQL functions in Jira as well. Your limitations will fall within general limitations of application and project permissions. You only need to be an administrator to work with the custom script JQL functions or manage the script JQL functions in the UPM. Otherwise, you can use script JQL functions in your searches. However, there are some areas where you need to be careful with script JQL.

Examples of Script JQL Functions

Script JQL Function: hasLinkType()

For this example, we look for issues that are blockers in the Jira instance.

1. From the top ribbon, choose Issues>Search for Issues.

   

2. If you see the basic search with drop-down menus, click Advanced. (If you see a text bar, you are already in Advanced search.)

   

3. Type the name of the field you want to search against. In our example, the field is issueFunction*.

4. Type the operator in.

   1. Remember that the in operator allows you to search for issues within a range of values, so, you are looking for issues that are in the category of a certain link type (blocks). If you think about standard JQL, you may look for something like project in ("project Sun", "project Stars") to look at issues in either the Sun project or the Stars project.

5. Enter the JQL function you are using, along with any values that apply. So in the example, the function is: hasLinkType("Blocks"). If your JQL is a viable search you see the green checkmark.

   

6. Add additional JQL clauses as needed. For example, you can narrow your search to a specific project. For Great Adventure, we want to look in the Virtual Tours project.

7. When you are ready, press Search to see the results. In the example we see all issues with the link type of Blocks in the Virtual Tours project. There are two issues that block other issues in this Jira instance.

   

Once you run your search, you can save the search if you want to create a filter, just like standard JQL. You can also use this search query to power a Software board or even in a Service Management queue.

Script JQL Function: lastUpdated()

This function can search based on the user, role, or group who last updated the set of issues. So, if you want to see all issues updated by administrators, you would search using that specific role.

For a specific user: in lastUpdated('by username'). So to find Anna Jewells updated issues it would be: in lastUpdated('by ajewell').

For a role: in lastUpdated('inRole Role Name'). So to find those updated by admins, it would be: in lastUpdated('inRole Administrators').

For a group: in lastUpdated('inGroup Group Name'). In other words, to find issues updated by Software users you would need, in lastUpdated('inGroup Jira-software-users').

Therefore a full JQL query would be:

groovy
issueFunction in lastUpdated('inRole Administrators')

That search likely returns several examples from the entire instance. To narrow it down, you could use additional JQL to search for a specific project or issues in a specific status.

Script JQL functions allow you to extend the possibilities of JQL and provide you with more powerful search options. Take time exploring the library of script JQL functions and if you feel comfortable with Groovy, you can always try and write your own.