| Info |
|---|
Not Yet Released, will be available after 27/28 JUN upgrade |
This How To will take you through the configuration of the JEMHC Postfunction to drive notifications in response to workflow changes.
| Table of Contents |
|---|
| Info |
|---|
Velocity is a Template language used by JIRA, and JEMHC. It allows dynamic injection of 'values' into a template, a process called rendering. Velocity markup is not hard to learn, and the helper tools made available in JEMHC should make it very powerful and flexible. |
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:
| No Format |
|---|
$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:
| No Format |
|---|
$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 |
...
| Table of Contents |
|---|
A workflow post function provided by JEMH can be used to send notifications to specific recipients when an issue workflow transition occurs.
Adding a post function to an issue workflow
Start by editing the target Jira issue workflow. Select Settings > Issues and click Workflows. Click Edit on the relevant workflow.
Select the target workflow transition either in the diagram or text view
Select the Post Functions tab and click Add post function
Select the JEMHCloud post function that you would like to use, and click the Add button
Configuring a post function
Notification contents
The Content tab has settings that allow the contents of the post function notification to be set. An Ad hoc type notification template set can be selected, along with the format (HTML or text), along with custom text content specific to this particular notification.
Please note that the custom text content Message field should be used as an additional plain text message. Follow Create custom Theme and Template Sets to customize notifications using the provided $issue context
Recipients
The To, CC and BCC tabs allow you to specify exactly who the recipients of the notification are:
Sender Email Address can be defined, this is the literal from: address, varying address used in the email notification’s From header. Varying it is useful in some situations but situations but your outbound Mailserver mail server 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 .
Sender Personal defines the display name of the sender address for the notification (if the configured outbound connection allows this). This should not include quotes, just the text required (for example, setting NotificationBot for this setting could result in the From header looking like NotificationBot <from.address@example.com>
Reply-To Email Address is optional , for example, could be set to noreply@blah.comand sets the Reply-To header address of the email notification.
Attachments
Its possible to include attachments in Postfunction notifications, there are issues (https://jira.atlassian.com/browse/JRA-43448):post function notifications
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 (
...
e.g. within 30s) but will fail for 'big' comments.
Issue commenting
The settings on the Issue Update
...
tab allow you to choose whether the post function notification is recorded on the related issue as a comment.
Further 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 post function at this time(ie i.e. it could be offline or a deadletterbox dead-letterbox configuration).
Template Set Enhancements
Any value present in the Webhook payload can be used in a notification, here are some examples:
(TODO)
Related articles
...
Post function ordering
It is important to make sure that the post function you add to the workflow is positioned correctly in the post function execution order. Initially the added post function will be first in the list - this is not ideal as field changes in the issue transition have not yet been applied. Move the JEMHC post function down until after the Issue has been re-indexed. This will reduce the chance of issues occurring due to missing data.
Before:
...
After:
...
Make the workflow active
In order for your workflow changes to persist, you must commit them. To do this, click Publish Draft shown in the Jira warning at the top of the workflow configuration screen.
...
Frequently Asked Questions
How Many Emails Get Sent?
The behaviour of email-based post functions is that one email is sent that includes every recipient (To, CC, BCC).
What changes have been made 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
| Filter by label (Content by label) | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
...
...
|
| Page Properties | |||
|---|---|---|---|
| |||
|