Workflow Post Function Notifications
- Ryan Clifton
- Andy Brook [Plugin People]
- Denny Miller
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.
Content configuration options
Format
This is the Notification format that the Notification will use when sent to the recipients. Current options are:
HTML
Text
Template Set
Post function notifications use the ‘Ad Hoc Notifications’ template set type. Other template set types are not shown in the post function content form as they are not compatible with Post Function behaviour.
This is the Ad Hoc template set that will be used to render this notification. Custom Templates can be created within JEMHCloud > Notifications > Template Sets. For more info see: Template Sets | Creating a Template Set
Message
This is an optional message that you want to send to your users. This message embedded inside the rendered template will become the email body.
Removing the default message content provided will remove the custom embedded message.
Please note that the custom text content Message field should be used as an additional plain text message.
Recipients (To, Cc, Bcc)
The To, Cc and Bcc tabs allow you to specify exactly who the recipients of the notification are:
Recipients configuration options
Email Addresses
This is a static CSV list of email addresses that you want to notify when issues are transitioned.
Address Custom Fields
This is a list of Custom Fields that contain Non-Jira user email addresses.
Recipients
This is a list of recipient types that should be notified. e.g. Reporter and Assignee.
Notify Users
List of specific users that should be notified when issues are transitioned.
User Custom Fields
Users found within these User Custom Fields will be notified.
Group Custom Fields
Groups found within these Groups Custom Fields will be notified.
Groups
This is a static CSV list of groups that will be notified.
Recipients Script
This is a custom script that will add email addresses, users or groups based on specific conditions made within the Script.
From
This section allows you to specify the Sender email address and reply to address for these notifications.
From configuration options
Sender Email Address
This is the address used in the email notification’s From header. Varying it is useful in some situations but your outbound mail server must allow it.
Sender Personal
This is 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>
User User Display As Sender Personal
If selected, the full name of the user that performed the action will be used as the sender personal when possible, otherwise the above Sender Personal will be used.
Reply-To Email Address
This sets the Reply-To header of the notification. If not set, mail clients use the from address when a user replies to the email.
Attachments
This defines when attachments should be included within the notification.
Attachment configuration options
Attachment Selection Method
This defines what attachments should be included within the notification. Current options are:
None - No attachments will be included
All Attachments - All attachments found on the issue will be included.
Recent Attachments - This will show some additional options to configure how recent the attachments should be added to the issue.
Filename Filter
CSV list of filenames regexps. To match a given file, use the filename (if you know what it will be!), to match types, e.g. PDFs, use the following case-insensitive format: .*.pdf.
Recent Attachment Window
Attachments that were uploaded within this time frame and not already sent (within a different event) will be included within the notification.
Thumbnail Images
This is the strategy that is used when adding thumbnail images to emails. Current options are:
Show Fullscreen Image
Show Thumbnail Image
Show Thumbnail Image and Attach Fullscreen image.
Inline Image Strategy
This defines what images can be inlined within the notification. Current options are:
Inline All Images - All images are inlined in the email as inline attachments. This strategy uses more plan data.
Inline Secured Images Only - Only images that need authentication such as issue attachments are attached inline.
Don’t Inline Images - External images are not inlined in the email. Some images may be blocked by email clients.
Static Resources
This is a list of attachments that can be selected to be inlined within the notification.
Issue Update
This allows you to customise if the post function content should be added as a comment on the issue and who can see this comment.
Issue Update configuration options
Add Content as a Comment to issue
This will add the Post Function notification as a comment onto the issue.
Comment Visibilty
This defines the Project role that should be able to see this comment. Users without this role will not see the comment.
Send comment Notification
Use to control firing of an ISSUE_UPDATED event, resulting in notification of Jira users. Notification to non-Jira watchers is also possible, but comments with a Security Level are filtered.
Settings
This is where you define the Message Outbound to use to send the notification and whether these should contain the Email Thread within the notification.
Settings configuration options
Message Outbound
This is the outbound mail server that should be used when sending these notifications.
JQL Whitelist
Only issues matching the JQL expression given will receive notifications
Email Threading
Adds a References header to the message so that replies to this message processed by JEMH Cloud can be associated with this issue regardless of email subject header contents.
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 post function at this time(i.e. it could be offline or a dead-letterbox configuration).
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.
Post function preview contexts
When a post function is successfully triggered, the event will be available in JEMHC > Auditing > Events.
From here, you can select the ‘Post function event’ > 'Create preview context'.
The preview context will allow you to edit your using expected context values.
Example - retrieving issue metadata using a preview context
By default, the additional embedded message will contain the issue key. This can be removed, or replaced with additional plain-text content, or issue context data can be used:
Field retrieval | Template content |
|---|---|
Issue Key |
|
Issue (JSON object) |
You can refer to a post function preview context to see current issue context fields. |
Post function transition |
|
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.