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.

Open

Editing AdHoc Templates

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

Open

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:

Skipping straight to Edit:

You should see this:

Clicking on the diagrams Create issue transition (the line going from the grey circle to the To Do box) will bring up a little menu that features the edit button along with a brief summary of how many Properties, Validators and Post Functions the transition has, selecting either the Validators or Post Functions links will allow you to access/create/edit that transitions Validators and Post Functions.

This takes you to the following, the Post Functions tab is shown:

Clicking Add post function, shows the list of available Post Functions, allowing JEMH Post Function to be located and selected.  Scroll to the bottom of the form to find the Add button.

Once added you'll be taken back the Post Function list. The JEMH Post Function will be positioned at the top of the list. In order to ensure that the Post Function has access to all required data, the Post Function should be moved to fire after re-indexing of the issue as occurred.

Use the Move Down action (down arrow) shown when hovering over the item to do this:

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:

1. Email

2. ppl-jemh-slack: Slack

3. ppl-jemh-sms: SMS

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 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:

Checking my mailbox I find I have a notification!

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:

Example accessing the issue object

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.

If for example, just before the transition a file is added to the issue, after clicking Start Progress we see:

Looking at the Jira Mail Queue quickly we see the message is queued

The comment was added to the issue:

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:

Using the same issue above, with Attachments added as a field to the Resolve Issue Screen, When resolving the test issue, there is now an opportunity to add attachments during the transition:

After Resolving, the issue has a final comment, with restricted visibility, showing access to both $issue in subject and $comment in the comment.  Referred attachments are also linked.

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.

In this example, we will implement a check-box field on a workflow transition screen which, only if ticked will a post-function notification be sent.

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:

   #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

This method adds all users with the given project role to to the notification being rendered. For example:

Add a specific email address

This method appends a recipient address (or multiple if comma separated) to the notification being rendered. Recipients can only be SMTP addresses of format local-part@domain. For example:

Add members of a group

This method appends all members of the given group to the notification being rendered. No consideration is given to whether a user is otherwise listed as a recipient. For example:

• 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