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 the free app, Expression Tester by Polymetis Apps. You can install the Expression Tester from the Atlassian Marketplace.
But first: What are Jira Expressions?
The short answer is: Jira Expressions are a domain-specific language that allows you to select and compare specific data from Jira Cloud in a single, concise expression.
Let’s break it down a bit more: A Jira Expression is nothing more than a short string that is evaluated within Jira Cloud to give you a result. Mostly, you will encounter Jira Expressions when building custom Conditions and Validators. But Jira Expressions can do quite a bit more: They allow app developers to add UI elements in certain conditions and they can be used in a REST API. Atlassian’s official documentation includes a few examples and a complete reference. Here at Jodocus, we are big fans of Jira Expressions and rely heavily on them.
Example 1
For our first example, let’s assume we want to read all the comments of an issue but nothing else. This can be done like this:
issue.comments
.map(c => c.body.plainText)
This expression returns the text of all comments for an issue, looking something like this:
[“Hello World “,”A small comment made by me”,”some comment”]
Pretty neat, isn’t it? Just the data we want, nothing else. So how does it work?
Whenever a Jira Expression is evaluated, there is some context. Context refers to the data that is available when evaluating the expression. In our example, that is the issue CTP-1, which is available as ‘issue’, which in itself is already a valid Jira Expression, albeit not a very useful one.
We want the issue’s comments, which are available as an attribute to the issue. Getting to an attribute is done like this:
issue.comments
Closer, but not quite what we are looking for. We get a list of all the comments, but there still is so much information for every comment. This is where the map()-function comes in. The map()-function allows us to execute a small piece of code for every element of a list and returns a new list of all the results. Since we really just want the comment as plain text, we can get away with a very easy piece of code: we just let it return the attribute we want, which is body.plainText of every comment. Here’s how map() allows us to do that.
Whenever there is a list in Jira Expression, we can use map(). We just need to provide map() with a function to execute on every element, which is this part:
c => c.body.plainText
In plain language this says: Hey Jira, for every element in my list, let’s call it c, I want you to return the attribute body.plainText. And that’s what Jira does, giving us a nice plain list of comments:
And there you have it – a nice, concise Jira Expression that you could use in a REST call to get all comments to an issue. Next week, we will use this expression as a basis for a “User has entered at least one comment”-condition to be used in a workflow.
