Macros

Owned by Ryan Clifton
Last updated: Jun 01, 2023
3 min read

Summary

JIRA email templates use Velocity markup, this can be cumbersome.  Macros can be used to centralise the rendering of some content, for example, headers/footers, or custom field extraction.

We have a historic issue with this feature that affects high mail volume environments, there is a concurrency bug in the version of Velocity shipped by Atlassian. It is fixed in Velocity 2.0.0 but Atlassian is still ‘gathering interest’ on updating ( https://jira.atlassian.com/browse/JRASERVER-64947 ).

The only workaround we have is for you to create a Jira customization, that will need to be redone every time Jira is upgraded.

a) Export your JEMH User Macro definitions to a text file and append them to the Jira macros.vm ./atlassian-jira/WEB-INF/classes/templates/email/macros.vm
b) remove from User Macros in JEMH
c) restart Jira

How Macros are used

JEMH will prefix all custom Templates with:

  • JEMH global macro definitions - These are non-editable internal macros that will include utility functions

  • JEMH user macro definitions - These are user editable macros, for whatever is needed

Macro Viewing and Editing

The JEMH TemplateSets screen allows the viewing of the internal JEMH and JIRA email macros.  This is useful for understanding structure and workings of existing macros. 

The User Macros tab allows the user to create and edit custom macros for use in templates.

User Macro Testing

When creating a User Macro you are able to test the Macro to see the values that it will show when used in a Template.

This is done by:

  1. Specifying a Preview Context Issue Key - An existing issue which you wish to preview the Template Set against.

  2. Specifying a Action User - User who triggers the Notification to be sent. e.g. The User who adds a Comment.

  3. Specifying a Actioner User - The recipient User who receives the Notification.

  4. Calling the Relevant Macro within the Velocity box

  5. Pressing the Preview button.

Once the Preview button is pressed you will then see the output of the Macro in a Text Format.

 

Example Use of User Macro

To customize html content , for example an ISSUE_CREATED HTML TemplateSet:

In the 'table' for example, say we want to modify how the issuetype is shown.  Editing the user Macro content, adding function, now just including COPY of text:

#macro ( exampleCopyOfIssueType ) <tr> <th>COPY of #text("issue.field.issuetype"):</th> <td class="has-icon"> #set ($issueType = $issue.getIssueTypeObject()) #renderIcon(${issueType.iconUrlHtml} ${issueType.getNameTranslation($i18n)}) $textutils.htmlEncode(${issueType.getNameTranslation($i18n)}, false) </td> </tr> #end

If Macros contain any visible macro not wrapped in #macro ...#end delimiters it will appear in all emails!

Editing the TemplateSet, the macro can be called with #exampleCopyOfIssueType() :

<table class="keyvalue-table"> #exampleCopyOfIssueType() #parse("templates/email/html/includes/fields/affectsversions.vm")

In this way content can be customized, or at least, when it needs to be customized, it can be done once, and included through macro calls.  An example ISSUE_CREATED can be previewed showing the updated "COPY of" text from the above:

Using Parameters

Parameters can be passed to macros by modifying the macro definition:

#macro ( exampleCopyOfIssueType $param1 )

To call, a static value can be used:

Or, even

More details on Velocity at: http://velocity.apache.org/engine/devel/user-guide.html