Jira Expression of the Week — Filtering Results

This week we will look into a Jira Expression which allows to make sure that a “user has entered at least one comment” as a condition (or validator) in a workflow.

Last week, we came up with an expression to give us the plaintext version of all comments of an issue. It looked like this:

issue.comments
 .map(c => c.body.plainText)

So, there were a few parts to this. The issue itself, these issue’s comments, the map()-function, and finally the plaintext of each comment. We will use these elements and a few more today to build this week’s expression. If you are unsure about all the elements above or haven’t read last week’s article, you can get up to speed here.

You do not need any extra apps to follow along — everything can be done via the Jira Expression REST API. However, the easiest way to work with Jira Expressions is to use our free app, Expression Tester. You can install the Expression Tester from the Atlassian Marketplace.

Now, Jira Cloud by itself does not offer Jira Expressions as workflow conditions or validators. However, there are apps that extend Jira Cloud to allow this feature, for example our own app Cloud Workflows. So, if you want to follow along and go ahead and give it a spin. Of course, you can also use the REST API to test all the expressions discussed in this series.

This week, we will create an expression that verifies that the current user has entered a comment. We already know how to select all comments of an issue using an expression that accesses the comments attribute:

issue.comments

This produces a lengthy list of all the issue’s comments with a lot of extra information, most of which we do not need. Since we are interested in who wrote each comment and using Atlassian’s reference documentation, we find that every comment has an author attribute, which in turn has a displayName attribute. So, let’s use the map()-function to see who wrote the comments:

issue.comments
 .map(c => c.author.displayName)

So, now we have a list of names, yeah! However, we are only interested in comments written by a specific user. If only there was a way to filter the list… Of course there is: it’s the filter()-function and it works very similar to the map()-function.

issue.comments
 .filter(c => c.author.displayName == “Oliver Siebenmarck”)
 .map(c => c.author.displayName)

The filter()-function returns a list with only those elements for which a condition returns true. In our example above that is true for those comments whose author’s displayName is “Oliver Siebenmarck”. Which of course works in my case, but hard-coding a name is hardly an ideal solution. Fortunately, Jira Expressions have us covered here: they have a user object in the context. This user object always contains some data on the current user and we can easily use it like this…

user.displayName

…and get the displayName of the current user. Using this, we can now build a general filter:

issue.comments
 .filter(c => c.author.displayName == user.displayName)
 .map(c => c.author.displayName)

Before we continue, a quick word on GDPR and data privacy. Atlassian takes data privacy quite seriously and has taken steps to ensure that the REST APIs of their products respect user data.
While the Jira Expressions API has not been affected, as a consequence of these measures, the reliable and future-proof way to work with user identities is to use the accountId attribute rather than displayName. Since we found displayName easier to grasp, we have used it in the examples up to this point, but we will use the accountId in the examples from now on.

We now have a general filter that returns a list of all comments of the current user has made on a given issue. If this list has at least one entry, we know the user commented on the issue, so this is what we are going to check using the length attribute every list in Jira Expression has.

issue.comments
 .filter(c => c.author.accountId == user.accountId)
 .length

Two comments! That’s definitely more than none, but to use this as a condition, we need our expression to return either true or false. Luckily, we can simply add > 0 and turn the whole expression into a boolean expression (i.e. it returns either true or false):

issue.comments
 .filter(c => c.author.accountId == user.accountId)
 .length > 0

And that’s it — if the current user has commented at least once on the issue, the whole expression will evaluate as true — it will returnfalse otherwise. If you are a user of Cloud Workflows you can now add that expression as a condition or validator to your workflow transitions and never again have a user close an issue without adding a comment first.

Join us again next week, when we have a look at how to build expressions that work with an issue’s parent issue.