Page Comparison

Table of Contents

Summary

As a JIRA user, you want to send an email notification from within the JIRA UI 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

Granting users access to Ad hoc notifications

Enable feature

Feature enablement is done via JEMHC > Notifications > Ad Hoc Notifications ->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.

Access - Permissions

Assign users the permission

To give access to your users, go to Cog→ JIRA Administration → Issue → Permission Schemes and click in Permissions on your project's schema.

Once in permissions, click on Grant permission button.

Select Send JEMHC ad hoc Emails permission and the roles, group, etc of the people you want to give access to the feature.

Tip

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

pop-up window

As an authorized user for ad hoc notifications, a new icon will appear in the issue view:

Tip

title	Don't see envelope button in the issue?

It's possible that the logged user doesn't have the right permission. Use the permission helper tools to test the permission against the user in the project.

Due to the nature of Cloud add-ons, the ad hoc pop-up 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!

The Popup

Notification window sections

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 can pick the notification format for the message, and the related 'theme' defined in JEMHC that bundles up the CSS styling, and support macros used by the themes Templates. JEMHC Template Sets include Subject, HTML and Text variants. Selecting a pre-existing Template can only be done through selecting the Theme that they are defined within them. Only System Admins can create/modify Themes and related templates.

Create custom Theme and Template Sets

Currently we haven't defined a styled HTML adhoc ad hoc 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

No Format

<!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 (ie you'd copy the system Theme you want to modify!), that macro looks like:

No Format

#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 prior to sending its 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 Context is the representation of the issue involved, the section is expandable:

Accessing this data is relatively straight forward, e.g., the following will 'extract' the current issue key:

No Format
$context.issue.key.asText()

There are some further reading guides:

Customize Email Content
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

The preview icon switches between a rendered version of the content and the edit-time markup mark-up (and back), enabling expected outcome to be validated, here that that issue key shows:

Subject

Edit Time	Preview

Content

The same is available for content, but, with HTML content, its also possible to see the raw markup invovledmark-up involved:

Edit Time	Preview (as HTML)	Preview (as TEXT)

Help

The help icon opens up Manipulate Webhook data in a Template:

Maximize

In normal state	On Maximize

To, CC and BCC

The addressee tabs allow entry of addressee recipients to be defied as To/Cc CC and BccBCC. The recipients can be defined in several ways:

statically via a valid SMTP address, for example 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 ad hoc notifications, ALL recipient email addresses are visible. If email addresses are sensitive, they should be set in BCC only.

From

Optionally the from address can be manipulated and customized, allowing per-project email addresses and 'sender' persona part (the personal part is the "Personal Part" <ofthe@email.com> )

Attachments

If the issue contains attachments, the user will be shown an Attachment Tab where the available attachments may be selected for inclusion in the ad hoc notification:

Issue Update

To track ad hoc notifications, its possible to add the sent content as a comment on the issue, with restricted visibility. Setting the restricted visibility will ensure that JEMHC doesn't broadcast the comment to all email users who may be defined on the issue:

Comments that are successfully created are then shown ,e.g.:

Settings

In this tab, the following settings are available

Message Outbound

Pick the 'right' outbound mail server configuration (could be many, each with their own 'email' addresses)

Remember Me

On submission, this setting will cause the supplied values to be remembered as defaults. Options are Global, Project or None. If current user is a system admin, they can save as Global for all ad hoc notifications. If current user is a project admin, they can save only as the default for this project. Its possible to reload a previously defined Project or Global configuration which will update the current dialog.

Use Next

When the user saves the settings with 'Remember Me' this value drives the choice of what should be the default source of configuration settings in future for this project, it will be either Global or Project.

Create Preview Context

A Preview Context contains the current 'adhoc' notification context (data) which can then be used when editing AdHoc TemplateSets, enabling them to be previewed in 'this' issues context.

Result

The Result shows the outcome of the messages delivery:

Before sending	During Sending	After Sending

Sending the Message

When Send Message is selected:

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,

Adding 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 would not be added to the issue!)

Member of a Role

For this, add the JEMHCloud Add-On user to the role Developers.

When sent, the results are shown:

Versions Compared

Old Version 20

New Version 21

Key