How to use macros in JCWE

Jira Custom Workflow Extension (JCWE) introduces many new post functions that can be added to Jira workflows. Some of them allow you to define text content like the Summary or Description fields in case of Create issue post function or comment text in case of Comment current issue and Comment related issues post functions. In both cases, you can define static text, but sometimes it’s not enough and dynamic data would be highly appreciated to make the content more meaningful.

What are macros?

Macros are short expressions that add different data based on the issue being transitioned or the current user executing the transition. This makes the content of the comment or created issues more flexible as it will be issue- or user-specific.

The important about macros is that they are not related to coding in any way. You don’t have to create any scripts to customize the data. Simply add the predefined expressions to the text and that’s all. JCWE will substitute the macro with appropriate value from the field on the issue or user data.

How to use macros?

As mentioned previously, using macros for adding the dynamic data is really simple and doesn’t require any specific knowledge. Just define the text content adding macros where the issue- or user-specific data should be included.\

Let’s say that I want to add a comment on the Close transition with the information about who executed the transition and what was set in the Resolution field. In this case will use the macro for the display name (or full name) of the current user and the macro for the field on the issue. My comment text in the post function might look like this: {source.currentUser.displayName} closed the issue with resolution {source.resolution}. This would be translated in the actual comment to e.g. Marcin Żurawiecki closed the issue with resolution Won’t Do. It’s that simple.

Types of macros

JCWE provides lots of different macros to help you out with creating more meaningful content for automatically created comments and issues. Basically we can divide them into two categories – user and issue specific.

User-specific macros contain three expressions for the current user to fetch his full name with {source.currentUser.displayName}, username with {source.currentUser.username} and email address with {source.currentUser.email}. These three types of user data also apply to any user we might fetch from the issue.

The issue-related data is our second category with many more to offer. Similarly to the current user we can get the full name, username and email address of the assignee, reporter, project lead, watchers and even user picker custom fields. Other custom fields, like text, number, date or select fields are also supported, but you need to provide the id of the custom field e.g. a macro for the date custom fields would be {source.date.customfield_10200} where 10200 is the id of the field.

Key takeaway

Automatically added comments or issues created through a workflow post function are a great way to make your processes faster or more transparent. JCWE introduces these post functions with a little more flavor called macros – short expressions used to add dynamic data to text content such as comment text or fields on the issue created. Macros allow you to fetch the current user or issue-specific data (fields) and add them to your text. No coding is needed. The predefined macros will do the job for you.