Summary

Post-Functions are used as part of a Jira project workflow.  When transitioning from one workflow step to another (e.g. "Open" to "In Progress"), Post Functions can be added to execute within the transition.

• Attachment support since 1.5.37

• Entities support (reporter etc) since 1.6.5

• Attachment filters since 1.6.5

Setting up a Template

Custom Templates configured through the Event Listener are used only in the context of Issue and User Events.  For events occurring during a workflow transition, a new variety of Template Sets has been introduced: the AdHoc Template Set.

...

Editing AdHoc Templates

All existing Template Set features are available (export/import/copy).  Here is a list of some pre-existing templates:

...

Clicking the edit operation will open the Template editor screen, where you can write your custom template.

Adding the Post Function to your workflow

Firstly, the workflow editor needs to be accessed, which is done through the Issues administration section:

...

Once the ordering has been done, edit the JEMH Post Function to go to the configuration screen.

JEMH Post Function configuration screen

...

Transport

Here you select the Transport type that should be used for the notification. Current Options are:

...

Note: For Slack and SMS you will also need to select the Transport Config to use for this Post Function

Content

Default is custom content, where any content provided is sent.  For simplicity text is recommended.  Pre-created Adhoc Template Sets can be selected, to save typing and create consistent notifications.

Velocity Context

When creating custom velocity templates, sometimes helper code is needed to access some part of the issue.  The velocity references available are listed, with links to supporting Javadoc pages wherever possible.

...

To / Cc / Bcc

...

Each section allows addressees to be identified, in several ways:

1. Static Addressees - static list of SMTP addresses to be set, of format: user1@domain.com,user2@domain2.com

2. Custom Fields - text (single and multi line, containing email addresses as above), user pickers and group pickers also supported

3. Entities (since JEMH 1.6.5), allows selection of:

   • reporter

   • currentAssignee

   • allWatchers

   • currentUser

   • projectLead

   • componentLeads

   • requestParticipants 

     Status
     colour Yellow title Since 3.1.3

From/Reply-to

...

It is possible to override default Jira behaviour of using the 'action user' display name as the personal part of the notification, e.g. 'Support' could be used.  Additionally, it is sometimes desirable to change the from: address that the email uses, this value sets the from and reply to addresses.

Just setting the from address is not sufficient to make it work, your mail server and infrastructure must allow this - talk to your mail admin!

Attachments / Issue Update

...

Here, the inclusion of attachments can be managed, the scope can be all issue attachments or recent issue attachments (within a certain time).  Within that scope, it is (since 1.6.5) possible to filter what attachments should be included, through a comma separated list of expressions.  The filters are case insensitive, can be exact match, or a regular expression.  With regular expressions be sure to know that to match all PDF types, you MUST use  .*\.pdf , the first . means any character, the * means any number of the last (which was '.' meaning any character), the \. is an escape of the special . character so it matches the literal '.'

Testing

Hitting the TEST button with an issue in context adds a success/fail indicator at the of of the screen:

...

After hitting the Add button at the bottom of the form, the Transition View is shown again, this time, with the configuration.

Publishing workflow changes

Until activated, workflow changes are only made against a draft version of the workflow.

...

Selecting Publish will cause Jira to ask if a backup of the old workflow should made. Selecting Publish makes the new workflow active.

...

All Done, now about the Templates, how to get Transition data?

JEMH merges the transition data (a map of keys to values) in the velocityContext of the template:

Whats in the TransientVars?  Depends.  For the Example, the fields I have available are:

So, $issue will give the issue, which can then further manipulated in the template as needed.

Logging 

If DEBUG logging is enabled for package com.javahollic.jira.emh.postfunction, transient keys and types will be logged, as well as being made available in the following variable, allowing some 'live' debugging:

$transientVars.jemhTransientVarList

Example accessing the issue object

#set ($issue = $transientVars.get("issue"))
<h1>default html</h1>
<h2>$issue.getKey() : $issue.getSummary()</h2>

Sending a notification with attachments during a transition (e.g. Start Progress)

Example Email

...

Post Function Configuration

Part1:

...

Part2:

...

Part3:

...

The Configuration shows that the content of the Email Users custom field will be used, that currently contains 3 addresses as CSV.  Attachments are included with a window of 30S between when they were added and when the user triggered the Start Progress transition.

A comment will be added to the issue on sending, restricted to the Developer role.

Start Progress Flow

The expectation is that the To: list will contain jemhtesting2@gmail.com, the CC: list will just contain static addressees jemhtesting3@gmail.com and jemhtesting4@gmail.com.

...

And the message content was rendered with access to $issue in both subject and content.

...

Sending a notification with attachments during a transition with a screen, including attachments (e.g. Resolve Issue)

The Workflow for the Resolve Issue transition has a JEMH Post-function present.  Note the use of $comment in the custom comment, and the ordering:

...

Received emails look like:

...

Conditionally sending Post-function notifications

From versions 1.8.31 and 1.9.4 onwards, logic can be applied to determine if post-function notifications should be sent or not.

...

1. Set up a check-box custom field

2. Add the custom field to a screen, and and set that screen to be the one shown during a transition

3. In either a custom template or in the custom velocity content settings of the post-function, use the following:

   Code Block
   #if (!$issue.getCustomFieldValue("customfield_13200")) $jemhUtils.setInhibitSending(true) $jemhUtils.setInhibitSendingReason("JEMH Postfunction checkbox not ticked") #else START OF CONTENT HERE $issue.getKey() $comment ${baseurl}/browse/${issue.getKey()} END OF CONTENT HERE #end

4. The above script will need changing to match the custom field ID of your check-box field, and also addition of your own notification content.

Conditionally adding Additional Recipients (project role, specific address, groups)

From within the template its possible to add more recipients:

Add all project role members

addRecipientsFromRole(String recipientType, String issueKey, com.atlassian.jira.project.Project project, String roleName)

...

$jemhUtils.addRecipientsFromRole("to", $issue.getKey(), $issue.getProjectObject(),"Developers")

Add a specific email address

addRecipientAddress(String recipientType, String addressCsv)

...

$jemhUtils.addRecipientAddress("to", "address1@example.com,address2@example.com")

Add members of a group

addRecipientGroup(String recipientType, String groupName)

...

• Once you have modified the script to your requirements, save the template changes

• Ensure that your template is selected for the desired target audience (Jira or Non-Jira) and issue event types in the Event Listener

• Test using a test case (make sure outbound mail is enabled and that you know who is getting your test notifications!)

Related articles

...