Use Ad hoc notifications
Send customized email notifications to recipients directly from the Jira issue view. Recipients can be specified from custom fields, issue participants or manually defined instead. Email contents can be pre-built using templates to allow quick use.
Granting users access to Ad hoc notifications
Enable feature
By default, the feature is disabled. To enable its use, navigate to JEMHC → Notifications → Ad Hoc Notifications → Configuration. Once enabled, you need to grant the Send JEMHC ad hoc Emails permission via the project’s permission scheme for users who should have access.
Grant users permission to use feature
To give access to your users, go to Jira Administration → Issue → Permission Schemes and edit the Permissions on your project's scheme.
Once in permissions, click on the Grant permission button. Select the Send JEMHC ad hoc Emails permission and the roles/groups/users etc. that you want to give access to the feature.
Accessing the Ad hoc Notification window
As an authorized user for ad hoc notifications, a new Send Email action will appear in the issue view:
Don't see the action?
It's possible that the logged user doesn't have the right permission. Use Jira’s permission helper tool to ensure that the user has the Send JEMHC ad hoc Emails permission.
Creating an Ad Hoc notification
Each of the sections of the pop-up will be described, later we'll show how these settings can be saved as defaults for the project, making subsequent use much more straight forward.
Content
Here, users enter their unique message contents. They can also select the message format, and the related 'theme' that combines CSS styling and macros used by templates. For more information on customizing pre-made templates, see create custom Theme and Template Sets.
Modified template
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0" />
<title>Message Title</title>
</head>
<body class="Jira" >
#jemhBodyDelimiter()
<table id="background-table" cellpadding="0" cellspacing="0" width="100%">
<!-- header here -->
#jemhIncludeSupportAdHocActionHeader()
<tr>
<td id="email-content-container">
<table id="email-content-table" cellspacing="0" cellpadding="0" border="0" width="100%" >
#jemhIncludeIssueHeader()
#jemhIncludeBody()
#jemhIncludeAddComment()
#jemhIncludeFooter()
</table>
</td>
</tr>
</table>
</body>
</html>
#inhibitSendingConditions()That renders as:
The definition of the header content is in the macro jemhIncludeSupportActionHeader, which can be modified within a writeable (non-system) Theme (i.e. you'd copy the system Theme you want to modify!), that macro looks like:
#macro ( jemhIncludeAdHocSupportActionHeader )
<tr>
<td id="header-pattern-container">
<table id="header-pattern">
<tr>
#if ($context.user)
<td valign="top" id="header-avatar-image-container">
#if ($jemhUtils.isCreatedByEmailUser())
<IMG height="32" width="32" border="0" style="border-radius: 3px; vertical-align: top" SRC='$jemhUtils.inlineImage($jemhUtils.getImageUrl("EmailUserIcon1"))' alt='$messageUtils.getMessage("velocity.macro.action.header.emailUser")'/>
#else
<IMG height="32" width="32" border="0" style="border-radius: 3px; vertical-align: top" SRC='$jemhUtils.inlineImage($jemhUtils.getImageUrl("SupportUserIcon4"))' alt='$messageUtils.getMessage("velocity.macro.action.header.support")'/>
#end
</td>
<td id="header-text-container" valign="middle">
#if ($jemhUtils.isCreatedByEmailUser())
<span>$messageUtils.getMessage('velocity.macro.action.header.emailUser')</span>
#else
<span>$messageUtils.getMessage('velocity.macro.action.header.support')</span>
#end
</td>
#else
<td valign="top" id="header-avatar-image-container">
<IMG height="32" width="32" border="0" style="border-radius: 3px; vertical-align: top" src="$jemhUtils.inlineImage($jemhUtils.getImageUrl('AnonymousUserIcon'))" alt='$messageUtils.getMessage("velocity.macro.action.header.anonymous")'/>
</td>
<td id="header-text-container" valign="middle">
$messageUtils.getMessage('velocity.macro.action.header.anonymous')
<strong>$messageUtils.getMessage("velocity.macro.action.header.$jemhUtils.webhookEvent")</strong> $messageUtils.getMessage('velocity.macro.action.header.anIssue')
</td>
#end
</tr>
</table>
</td>
</tr>
#end
When previewing the message before sending it's also possible to use a JEMHC Translation configuration (that could apply to a remote sender, by their domain - as defined in the Translation configuration).
The expandable Context section shows the representation of the event data involved:
Accessing this data is relatively straight forward. For example, the following will 'extract' the current issue key:
$context.issue.key.asText()Here is some further reading:
Manipulate Webhook data in a Template (this is specific to webhooks that are specific to event-driven notifications, but may be a further useful reference to accessing values)
Previewing the message
The preview icon switches between a rendered version of the content and the edit-time mark-up (and back), enabling expected outcome to be validated.
Subject
Edit Time | Preview |
|---|---|
Content
The same is available for content, but, with HTML content, its also possible to see the raw mark-up involved:
Edit Time | Preview (as HTML) | Preview (as TEXT) |
|---|---|---|
Help
The help icon opens up Manipulate Webhook data in a Template:
To, CC and BCC
Email address privacy
Sending a JEMHC ad hoc notification results in one email being sent with all recipient email addresses present. If email addresses are to be private, they should be set in BCC only.
The addressee tabs allow entry of addressee recipients to be defied as To/CC and BCC. Recipients can be defined in several ways:
manually entered email addresses in CSV format, e.g.
adam@example.com,sara@example.comselected “text” custom fields containing email addresses in CSV format
selected individual users/groups
selected issue participant users, e.g. Watchers, Reporter, Assignee
selected user and group custom fields present on the issue
Additional Recipients
See https://thepluginpeople.atlassian.net/wiki/spaces/JEMHC/pages/66355211 for more.
From
Optionally the sender address (From) can be manipulated and customized, allowing per-project email addresses and 'sender' personal part, for example "Personal Part" <ofthe@email.com>.
Attachments
Attachments may be selected for inclusion in the ad hoc notification:
Issue attachments
Uploaded files
Issue Update
To track what ad hoc notifications have been sent, it's possible to add the message content as a comment on the issue, with restricted visibility. Setting restricted visibility ensures that JEMHC doesn't broadcast the Ad Hoc message to all issue participants:
Comments that are successfully created are then shown, for example:
Settings
In this tab, the following settings are available:
KISS Mode
The Ad-Hoc pop-up has two modes; Simple and Full. Simple mode removes some of the more advanced tabs and settings in order to streamline the experience for end-users. Full mode displays all available settings, which can be useful for power users who want more control.
Example view of Simple mode | Example view of Full mode |
|---|---|
Message Outbound
Select a configured outbound mail server to be used for the sending of the Ad Hoc notification.
Remember Me
Allows saving of the Ad Hoc configuration on submission. Options are Global, Project or None.
If the current user is a system administrator, they can save as Global for all ad hoc notifications.
If the current user is a project administrator, they can save as the default for this Project.
It's possible to reload a previously defined Project or Global configuration which will update the current window session.
Use Next
Determines what configuration should be used for future sessions (Project or Global).
Create Preview Context
A Preview Context contains the current 'ad hoc' notification context (data) which can then be used when editing Ad Hoc Template Sets, enabling them to be previewed with real issue data.
Result
The Result shows the outcome of the messages delivery:
Before sending | During Sending | After Sending |
|---|---|---|
|
Sending the Message
When Send Message is clicked:
A confirmation window will appear, hit OK to proceed:
Troubleshooting
Adding a visibility restricted comment
Where the user has selected an Issue Update comment visibility level that the JEMHCloud add-on user (under which all issue updates occurs) is not part of, which means it cannot be done (in such cases, the comment wouldn't be added to the issue).
In this case, add the JEMHCloud Add-On user to the project role “Developers”.