Table of Contents | ||||
---|---|---|---|---|
|
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:
Static Addressees - static list of SMTP addresses to be set, of format:
user1@domain.com,user2@domain2.com
Custom Fields - text (single and multi line, containing email addresses as above), user pickers and group pickers also supported
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 '.'
Note |
---|
Attachments added during a transition won't be accessible until after the Update change history for an issue and store the issue in the database step. For safety, putting it after the Re-index an issue to keep indexes in sync with the database step of the transition is recommended. |
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:
Reference | Type |
---|---|
issue | com.atlassian.jira.issue.issueImpl |
comment | java.lang.String |
createdStep | com.opensymphony.workflow.spi.SimpleStep |
store | com.opensymphony.workflow.spi.ofbiz.OfbizWorkflowStore |
descriptor | com.atlassian.jira.worklfow.ImmutableWorkflowDescriptor |
entry | com.opensymphony.workflow.spi.SimpleWorkflowEntry |
context | com.opensymphony.workflow.basic.BasicWorkflowContext |
actionId | java.lang.Integer |
configuration | com.opensymphony.workflow.config.DefaultConfiguration |
currentSteps | List<com.opensymphony.workflow.spi.SimpleStep> |
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:
Code Block |
---|
$transientVars.jemhTransientVarList |
Example accessing the issue object
Code Block |
---|
#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.
...
Set up a check-box custom field
Add the custom field to a screen, and and set that screen to be the one shown during a transition
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
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
Code Block |
---|
addRecipientsFromRole(String recipientType, String issueKey, com.atlassian.jira.project.Project project, String roleName) |
...
Code Block |
---|
$jemhUtils.addRecipientsFromRole("to", $issue.getKey(), $issue.getProjectObject(),"Developers") |
Add a specific email address
Code Block |
---|
addRecipientAddress(String recipientType, String addressCsv) |
...
Code Block |
---|
$jemhUtils.addRecipientAddress("to", "address1@example.com,address2@example.com") |
Add members of a group
Code Block |
---|
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
Filter by label (Content by label) | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...