Today, we kick off our blog with a series of Jira Expressions of the week to showcase how versatile and easy to use Jira Expressions are. Each week, we will look at a different Jira Expression and explain what it does and how it can be used to make your life as a Jira Admin easier. If you want to follow along and try Jira Expressions on your own instance of Jira Cloud, you can do so with Jira Cloud’s REST API or even simpler with the Expression Tester, which is included in our app Cloud Workflows.
Cloud Workflows brings new conditions and validators to Jira Cloud! Thanks to either our easy templates or your custom Jira Expressions, you gain more fine-grained control of your workflows. Our flexible post-functions further enhance your workflow’s productivity. https://marketplace.atlassian.com/apps/1220407/cloud-workflows
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.
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:
.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:
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.