Use Ad hoc notifications

1 Granting users access to Ad hoc notifications
- 1.1 Enable feature
- 1.2 Grant users permission to use feature
2 Accessing the Ad hoc Notification window
- 2.1 Don't see the action?
3 Creating an Ad Hoc notification
- 3.1 Content
- 3.2 Troubleshooting
4 Related articles

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.

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:

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)

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

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)

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.com
selected “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" <ofthe@email.com>.

Attachments

Attachments may be selected for inclusion in the ad hoc notification:

Issue attachments
Uploaded files
Static Resources

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

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

Before sending	During Sending	After Sending

Sending the Message

When Send Message is clicked:

A confirmation window will appear, hit OK to proceed:

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.

In order to save a project config; you will need to have the project administrator role.
In order to save the global config you will need to be a Jira administrator.

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).

In this case, add the JEMHCloud Add-On user to the project role “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

Use Ad hoc notifications

Granting users access to Ad hoc notifications

Enable feature

Grant users permission to use feature

Accessing the Ad hoc Notification window

Don't see the action?

Creating an Ad Hoc notification

Content

Previewing the message

Help

To, CC and BCC

Additional Recipients

From

Attachments

Issue Update

Settings

KISS Mode

Message Outbound

Remember Me

Use Next

Create Preview Context

Result

Sending the Message

Admin Only

Save as

Use Global Configuration

Create Preview Context

Troubleshooting

Adding a visibility restricted comment

Adding JEMHCloud addon user to Role

Related articles