Happy New Year! Now that we are a few days into 2022, I hope all of you are having a great start to your work week (assuming you aren’t still on vacation 😉). If you missed last week’s post because you were taking a well-deserved break, be sure to check it out! It’s a fantastic app to make your life in Jira easier as an Admin.
So, this week I sat down and took a look at what JQL functions I’ve covered already and what’s currently out there. And I came to the realization I’ve never talked about any of the JQL specifically designed to help you sort your Jira Service Management queues.
Now, after I went through these functions, I noticed two things. First, these functions tended to fall into groups – and as such, I’m going to group them up when talking about them. And second, there are a lot of functions here, so I’m going to have to rapid-fire these off. So I will only go into enough detail to tell you what each function does, how to use it, and what I see it useful for.
I am also only considering functions that are universal – that is, they are found both in Data Center and on Cloud. Cloud has a few more functions that I find interesting, but it’s super frustrating to find a new function and realize it’s not for your version of Jira. Seriously, it saddens me that Atlassian has altogether abandoned the concept of feature parity between Data Center and Cloud. Still, I don’t see this changing any time soon, so it is what it is.
Approval Flow Functions
My first set of functions has to do with Approval workflows. Whether sorting out approved functions or finding issues you or your team need to approve, these functions all center on the same theme. All of these will search against the approval field,
This function looks for issues that needed approval, then got it. This search helps find tickets ready to be worked. To use this, you need to search against the approval field so that it will look like this:
approval = approved()
I can easily see this being the driving function for a query on a Dashboard to show issues your team needs to work on actively.
This function looks for issues waiting on you specifically to approve or those you have already approved. Considering you are a blocking step, finding issues you need to approve or deny quickly is critical. So I’d consider adding a query containing this search term to your daily-driver dashboard.
As stated earlier, you will use this against the approval field so that the search would look like this:
approval = myApproval()
I chose to add this after myApproval() as it does something similar, but rather than searching for your approvals; it searches for approvals from a list of users you specify. This function takes in a comma-separated list of users as input and returns all issues waiting for approval from those users. In practice, it looks like this:
approval = approver(user1, user2)
So, anytime I see a list of users like this, I can’t help but experiment. I tried to use this with the “memberOf()” function to return a list of users from a group. Unfortunately, these functions don’t play well together, which means you are stuck writing out your group. Serious “Boo Atlassian” here – it would be crazy useful to specify a group instead of writing out a list of names – which is precisely what the membersOf function is supposed to do.
So Pending functions are very similar to the Approval functions, as they both work to show tickets that are waiting on approvals (or have had approvals completed). But approver and myApproval concern themselves with who has the action to approve the issue, the Pending functions only concern themselves with functions awaiting approval.
This shows all issues that are waiting on approval. The JQL is simple enough:
approval = pending()
But given how broad this particular search is, it is best to pair it with other JQL terms to narrow the scope. As a best practice, I find it best to specify which projects your JQL will search on at the start of any query.
No joke, this function is almost the same as the approver() function – it returns a list of issues waiting on approval by the list of users specified. The difference here is that pendingBy() will only return those that need approval still, whereas approver() will return those tickets that are either awaiting approval or approved by the list specified. Both are used in a similar function as well.
approvals = pendingBy(user1,user2)
Like approvers, this function also doesn’t work well with membersOf(). Which, yes, is still a disappointment.
The functions myPending() and myApproval are very similar functions. The only difference I can find is that myPending() will only return those awaiting your approval, whereas myApproval will also return tickets you have already approved. You use it similar to myApproval(), so the JQL would be:
approvals = myPending()
The following two functions help you find issues that are in trouble – that is, tickets that have breached your SLA Timers. The search will vary depending on which SLA you are checking for, but for the examples, I will be using the “Time to First Response” SLA, as that one is relatively common.
This function returns issues currently in breach of whatever SLA you specify. So, if your search term is:
“Time to First Response” = breached()
Your list will show all issues where your team has taken longer to respond than they are supposed to. I can hear you now – Management will use this function to micromanage everyone. And yes, managers can abuse it as such. But let’s be honest – any manager worth their salt will realize stuff happens. The real point of this function is to find when it starts to become a consistent problem. After all, the first step in fixing a problem is realizing you have one.
This function behaves similarly to its brother above, but it has more of a historical slant. Given that SLA’s reset, like time to respond, it might be hard to tell if a ticket has been breached in the past because it can look okay today. Instead, this function looks at past SLAs, and if an issue has ever been in a breached status, it will find those tickets and return them in a search.
This is also used against the SLA of your choice so that the JQL will look like this:
“Time to First Response” = everBreached()
SLA Timer functions
So, SLAs are important, so JSM lets you search on issues whose timers are running or paused. You can even search on issues whose timers are below a certain threshold. This allows you to build dashboards to prioritize tickets that might be close to violating their SLAs or just those that have active SLAs counting against you. These are the functions we will look at next.
This function runs against your SLA timers, and returns tickets whose SLA timers are paused, as would be logical. This means you can generate a list of tickets that you can put at a lower priority, as they are not actively counting against your SLAs.
To use this, you will query this plugin against the SLA of your choice. For example:
“Time to First Response” = paused()
The running() function does the exact opposite of paused(). That is to say, it returns the tickets whose SLAs are active counting down. This would be your priority hit-list as you want to clear those SLAs quickly. It’s also used in a very similar format:
“Time to First Response” = running()
The last function we’ll talk about today is the remaining() function. This is probably the most interesting function of today, as it lets you do the most against it. To start with, it takes in a time-value as a parameter. This parameter is formatted the same as you would time remaining on estimates, so “2h 30m” kind of format. Then it will take that time, and compare it using whatever operator you use. So a greater-than (“>”) will return all values where the SLA is more than the given time value, whereas a less-than (“<“) will return anything below that threshold. In practice, this will look something like this:
“Time to First Response” < remaining(“1h”)
So, what did you think?
I’m not going to lie; in my new role, I’m using JSM a lot more than I was previously used to – but it’s never a bad thing to expand your repertoire of skills. Did you know all of these functions? Are there any JQL tricks you want to share? Let me hear about it in the comments!
I’ve got some big plans for the new year – I’m still trying to figure out and finalize a few of them, though. Among them are I plan to be live on Youtube and Twitch a lot more. I hope you will join me to ask questions, contribute, or help me answer questions from the Atlassian Community page. I’ll be live today at 5:00 PM Eastern, so see you there!
Likewise, you can catch me on social media via my Linktree page. Another goal I have for this year is to be a lot more active on all the platforms, so definitely follow to see what’s happening with The Jira Guy and the Atlassian Community at large!
You can sign up below to get new blog posts delivered to your inbox. I still think this is the easiest and fastest way to get new content directly from the blog, and yes, I’ve even signed up myself.
But until next time, my name is Rodney, asking, “Have you updated your Jira issues today