...
| Table of Contents |
|---|
Use Ad hoc notifications in JEMHC
As a JIRA account holder, you want to send an email notification from within JIRA relating to the issue in context. You may want to include email-only recipients, as well as JIRA users though groups, custom fields, you may want those users to be specifically addressed via To, Cc and Bcc. You may want to attach issue attachments to the outbound notification...
Step-by-step guide
Access - global
Feature enablement is done via JEMHC > Notifications > Ad Hoc Notifcations ->Configuration. By default the feature is disabled. Once you enable it, you need to grant Send JEMHC ad hoc Emails permissions in permission schemes so the right people can perform the action.
|
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, enable through JEMHC → Notifications → Global Configuration → Settings. 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.
...
| title | Don't see the permission? |
|---|
It's possible that your JEMHC Add-on descriptor is not up to date. Marketplace knows when the descriptor changes, and refreshes individual hosts over time when that happens (usually done within a few hours). If you do not see the section and see a JEMHC message as follows, you'll need to contact Atlassian Support to get them to refresh your descriptor:
Launching the ad hoc popup
...
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:
...
| Tip |
|---|
...
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 |
...
Due to the nature of Cloud addons, the ad hoc popup will appear in a window that is most of the current visible window. Resizing the browser window after launch doesn't change the popup window. Bigger is better!
...
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
...
Currently we haven't defined a styled HTML adhoc notification, this could be done with a modified issue event template taken from the Support Theme, the main difference is that the header is different
Modified IssueCreated template
...
templates. For more information on customizing pre-made templates, see create custom Theme and Template Sets.
Modified template
| Code Block |
|---|
<!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:
...
| Code Block |
|---|
#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:
...
| Code Block |
|---|
$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)
The Subject and Content Editors allow respective parts to be modified, there are some icons in each editor:
Preview
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:
Maximize
...
...
...
To, CC and BCC
| Note |
|---|
Email address privacy |
The addressee tabs allow entry of addressee recipients to be defied as To/
...
CC and
...
BCC.
...
Recipients can be defined in several ways:
- statically via a valid smtp address of format user@domain.com
- from a TEXT custom field populated by JEMHC storing CSV addresses of the same format as above
- JIRA users somehow involved in the issue may be included (e.g. Watchers) as well as nominated users. User Picker Custom fields on the issue can also be used.
ONE email is sent with JEMHC adhoc notifications, ALL recipient email addresses are visible. If email addresses are sensitive, they should be set in BCC only.
From
...
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 Add recipients by Velocity script 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"
...
Attachments
...
<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:
Errors during send
Its quite possible for several things to go wrong during mailing a notification, the outcome will all be shown in the report,
...
Admin Only
In this tab, the following settings are available:
...
Save as
Allows you to save the currently selected configuration as the default for the project, or as a global default.
| Info |
|---|
|
Use Global Configuration
Changes the configuration that is currently being used from project to global.
Create Preview Context
This creates an adhoc preview context, using the current issue as the context. This allows it to be selected when configuring adhoc templates.
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
...
).
Member of a Role
...
In this case, add the JEMHCloud Add-On user to the project role
...
When sent, the results are shown:
...
“Developers”.
Adding JEMHCloud addon user to Role
To add the JEMHCloud addon user to a role, you will need to:
Go to Jira Admin > System > Security > Project Roles
Press Manage Default Members on the relevant Role
Press Edit within the Default Users column
Then Add Enterprise Email Handler for Jira (JEMH) and press Add
Related articles
| Filter by label (Content by label) | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
|
...
|
...
| Page Properties | ||
|---|---|---|
| ||
|