Use Postfunction notifications

This How To will take you through the configuration of the JEMHC Postfunction to drive notifications in response to workflow changes.

Create a simple Ad hoc TemplateSet

Template Sets are composed of a Subject, TEXT content and separate HTML content.  Its more work to edit in HTML, examples are always given in TEXT.

 A 'twist' to configuration is that in order to 'easily' edit an adhoc Template, you will need to capture a Postfunction Webhook, but in order to do that you need to configure a JEMHC postfunction first.  The template set will be trivial to start with to prove basic configuration, then later more details can be added.

Create the TemplateSet

Navigate to JEMHC > Notifications > Template Sets, and select All Event Groups.  Pick a theme that you want this notification to be styled/associated with, in the example below, we have a copy of the JEMHC system JIRA theme called JIRA Support.

Clicking Create will popup the TemplateSet creation dialog, set the name, select the theme and TemplateSet Type, which should be Adhoc Notifications, and submit.

Then, its also possible to copy from an existing template of that nominated type in the nominated theme, or blank:

On Submit you will be taken to the TemplateSet editor:

Edit the Template Set

Scroll down the editor to get to the content section, its also possible to preview the content (below).  To get back to edit, just hit the same icon.

Edit Time	Preview Time

Full details of the Velocity Context are also available in the UI, which are hyperlinked to external Javadoc sources:

Save the Template Set

Don't forget!

View the available Ad hoc Template Sets

Change the Event Group to 'Ad hoc Notifications'

Which then shows:

Create a JEMHC Postfunction

Navigate to JIRA Admin > Issues > Workflows.  Edit the workflow:

Drill in to a Transition, here we use Start Progress:

Click Add post function:

Select JEMHCloud, then Add.

After a short time, the JEMHC Postfunction editor will be shown.  Select an existing Ad hoc Template Set, the basic one created earlier will be in the drop down, remember to set TEXT as the format (as the example Template Set only provides that, and of course, the correct Ad hoc Template Set itself:

For testing I'm going to set a static addressee to start with in the TO: recipient tab:

Now review the From tab, set a Sender Personal for the Postfunction notification if needed

Check that the address is valid for the Configured Outbound Mailserver set in the Settings tab:

Saving the Postfunction

Due to how the layout currently works, the biggest 'page' of the configuration pushes the Submit button down, scroll down to find it:

Postfunction ordering

Initially the JEMHC Postfunction will be first in the list, this is not ideal because changes in the transition have not yet been applied.  Move the JEMHC postfunction down until after the Issue has been re-indexed.  Its a slow process as a page refresh is required each time, patience padawan!

Before:

After:

Make the workflow active

Changes made so far are in a Draft of the workflow, time to publish:

In testing I don't backup, you may want to:

Now its active:

Verify notification

verification should be as simple as transitioning an existing issue in the TO DO Status with the Start Progress Transition.  I'm going to just create one:

Transition the issue

Hit Start Progress to trigger the transition, well then get the related traffic from JEMHC auditing to see what happened:

In another window, navigate to JEMHC > Auditing > Events to see what happens, here, older events have been removed:

Before:

After:

Apart from the Timestamp variance all looks well

It is at this point that the 'data' that was sent from JIRA in relation to the Postfunction transition can be captured as a Preview Context that will allow fine tuning of TemplateSets content (where content from the event is to be included in the Template).

Create a Preview Context for the Postfunction

A preview context can be created from captured Postfunction Webhooks.  This is done in Auditing > Events > PostFunction Notification entries.  Once Created they can be selected in the Editor (show previously), which can then be used within the template:

The content of the Preview Context is JSON and looks like this:

 JEMHC has some editor autocomplete that allows you to drill into this structure:

 $context.<CTRL-SPACE>

With this, its possible to (later) build up an expression like $context.user.name, but thats the JSON object, to get the 'text' of the node, you also need to use .textValue(), so a subject could be:

$context.user.name.textValue() did something to $context.issue.key.textValue()

Verify emails were sent

JEMHC tracks recent sent email content, and allows preview of that content, in JEMHC > Auditing > Outbound Messages we see two notifications, one via Email to the statically defined recipient in the postfunction (notice the subject had the injected username set from the Postfunction Webhook data), and a second via the JEMHC HipChat integration:

HipChat notification (doesn't indicate source, just the content of the event)

Check the Mailbox, you should see something like this, highlighted are the values injected from the Postfunction Webhook:

Next Steps: Fine tuning

With a TemplateSet in place, and communication validated, further configuration can be made:

Postfunction Configuration

Content

This section allows you select the Format of the outbound mail, which translates to what part of the TemplateSet would be used.  Make sure what is selected exists in the selected TemplateSet!

To/Cc/Bcc

It is possible to define addressees for inclusion in specific addressee levels (To/Cc/Bcc).  JEMHC will include a given recipient only once!

 Supplied Addresses must only be of format user@domain.com

Email Addresses	This is a comma separated list of simpleemail adddresses
Address Custom Fields	These are TEXT type custom fields (single or multi-line) that contain comma separated simple email addresses
Notify Reporter	Yep, that.
Notify Assignee	Yep, that.
Notify Watchers	Yep, that.
Notify Current User	Includes the user who triggered the change.
Notify Project Lead	Yep, that.
Notify Component Leads	Yep, that.
Notify SD Request Participants	If enabled, and JSD is installed (we should probably hide this if JSD is not installed) then the users within this field will be notified
Notify Users	This is a comma separated list of usernames. Usernames require the 'workaround' user defined in the Workaround tab in order to lookup the users address
User Custom Fields	User picker type custom fields (single or multiple) to include users for notification

From

Sender Email Address can be defined, this is the literal from: address, varying it is useful in some situations but your outbound Mailserver must allow it, various outcomes will occur if it does not ranging from the default (connecting) account being used instead (Gmail), to no mail being sent at all (Exchange).

Sender Personal should not include quotes, just the text required.

Reply-To Email Address is optional, for example, could be set to noreply@blah.com

Attachments

Its possible to include attachments in Postfunction notifications, there are issues (https://jira.atlassian.com/browse/JRA-43448):

• All Attachments: which makes sense during 'create', and can be limited to a filename filter.  The Filename Filter is a comma separated list of regular expressions - a type of data used in JEMHC and JEMH a lot.
• Recent Attachments: can also be used, but due to the issue above, a 'time window' is required to look back from the issue event, to find attachments created within.  This works fine on create, ad fine for simple file uploads with a small comment (eg within 30s) but will fail for 'big' comments.

Issue Update

Settings

Here you can select the Message Outbound configuration that describes the outbound mail server.  It isn't possible to know the status of a given Message Outbound in the postfunction at this time(ie it could be offline or a deadletterbox configuration).

Template Set Enhancements

Any value present in the Webhook payload can be used in a notification, here are some examples:

(TODO)

How Many Emails Get Sent?

The behaviour of email-based postfunctions is that one email is sent that includes every recipient (To, CC, BCC).

Changes due to GDPR

Methods of access to personally identifiable data have been changed to comply with GDPR. Details about these changes can be found in this blog post.

Related articles

• Page:
  Use Ad hoc notifications
• Page:
  Scriptlets