Summary

This feature allows Jira users to create and send custom emails directly from the issue view.  Notification recipients can be added from several sources; static email addresses, issue custom fields and standard issue entities (e.g. reporter, assignee).

This feature should not be confused with Ad hoc Post-function notifications fired in an issue workflow, or Issue Event notifications fired in response to an issue event.

Enabling ad hoc notifications

The feature is disabled by default. In order to use the feature, it needs to be enabled and access granted to users.  A Jira system admin can do this via JEMH > Features.

1. Go to JEMH by pressing full stop on the keyboard to open Jira's Operations box, and typing "jemh" and pressing Enter.

   Open

   

   
   
   
   

2. JEMH will appear. Open the Features tab and click the edit icon. Enable the feature and then press submit.

Open

Granting users permission to use Ad Hoc Notifications

The ability to use Ad Hoc notifications is configurable through default global settings, or can be granted on a per-project basis.  The ability to modify Global settings requires a Jira administrator, the ability to modify Project settings requires either a Project Admin or a JIRA administrator.  Access to the JEMH Permissions section is found through the JIRA Project Administration section:

The JEMH Permissions screen has two sections, the Project Settings and the Global Settings.  Editing ability is through the pen icon in each case, which is only possible with the Project Administrator privilege (for Project Settings) and JIRA Administrator (for Global Settings).  By default, all projects defer to the Global Settings for security.  To switch to Project Specific settings, just click the Use Project Settings button.

Once the Use Project Settings button has been selected, its activation is indicated:

Editing Project Settings

Editing the Project Settings, allows entry of the Roles, Groups and Users.  Entry of Groups and Users is by comma separated values.  For Users, their login 'names' should be provided (when saving this data, JEMH will store the user keys to be compatible with future user renames).  The 'Config Source' is another way to update the Project v Global setting for a project (i.e. to deselect the projects settings).

Upon saving, you will see the current authorisation settings:

Editing Global Settings

Editing the global settings is the same process as above, except a config source is not selected:

Using the AdHoc Notification Pop-up

Once a user is authorized to use AdHoc Notifications for a project, an additional icon will be shown on the Issue view screen (and search results):

Clicking the icon will open the Ad Hoc Notifications Pop-up:

Message Types

Through the comment screen, two kinds of notification can be sent:

1. Custom Content, which is straight forward text

2. Template Sets - pre-defined messages or "canned responses".  When Template Sets are selected, the resulting content can be edited before sending.

Spell Checking

The rich text email editor has browser based spell check support. To access this use CTRL-right click on the word in question.

Setting message recipients

Recipients can be be included from several sources for each recipient address field (To, Cc, Bcc).  Duplicate recipient addresses are filtered to account for cases where a recipient is defined in several places.  A recipient included in To: takes precedence over Cc: and that takes precedence over Bcc.

Recipient sources

Recipients can be defined in three different ways:

Static Email Address

These can be added in a comma separated list.  Note that this should only be the local and domain parts of an address, no "personal names" are permitted:

Custom Fields

Text, User and Group Picker custom fields can be selected, in order to find email addresses/users.

User Entities

A range of common user entities can be selected:

• reporter

• currentAssignee

• allWatchers

• currentUser

• projectLead

• componentLeads

• requestParticipants (works in JSD projects)

Recipients view

SINCE 3.1.15

Once the recipient list has been constructed from all the sources, you can review the final list of users to determine any recipient/s who should not be on the list of receiving the mail. This is ideal in cases when selecting Custom Fields and/or Entities.

From this view, you have the ability to be to Exclude or Include recipients from/to the notification.

The source column is the way to determine where the email address was obtained from - was it an Entity, CustomField or Manual insertion? Key reason behind this column is to provide the ability to be able to control the order of the list based on the source.

Useful information:

• This implementation has been applied for all the Recipient Types (To, Cc and Bcc)

• Excluding recipients from the list and select another custom field/entity or manually inputting new recipient WILL refresh the list again. Therefore, first construct the list of recipients and then begin the exclusion phase

Attachments

Attach Static Resources

JEMH 2.1.15 adds support for Static Resources. These are files which can be uploaded to JEMH to be used as attachments within notifications. Images can be attached as embedded images within notification content. Static Resources can also be statically attached to an email notification as a standard email attachment. Example uses include adding an embedded signature image within an email template, or adding a document to a notification (e.g. a terms of service document in PDF format).

In-line images in notification content

The new Rich Text editor added in version 2.1.1 allows the addition of inlined images.  This can be done in 3 ways:

• drag and drop an image onto the comment editor window

• go to Insert>Image, click the browse icon under Source and select the image file to inline

• click the Insert/edit Image icon on controls banner

Existing attachments from issue

Attachments found on the current issue will be listed under the Issue Attachments section.  Select one or more attachments from the list to include them in the notification when it is sent.  For versions 2.1.17 and older, select multiple items in the list by using the CTRL key (2.1.18+ uses a new selector to make this easy).

Upload attachments

From version 2.1.1, attachments can also be uploaded for inclusion in the Ad Hoc Notification.  To manually upload an attachment, simply drag and drop the target file into the designated drag and drop area.  Once they are successfully uploaded, they will be listed under the Manual Uploads section.

Manually uploaded files are temporarily stored in the JIRA home/import/attachments/jemh-adhoc folder for up to an hour in order to ensure that the files are present when JIRA gets round to sending the queued notification.

Sending a message

Sending an Ad Hoc notification is a simple one-click process.  At the bottom-right of the Ad Hoc Notification window there is a Send button.  Clicking this will queue the notification for the recipients JEMH has determined.

If the notification was successfully queued the following message should appear:

If the message cannot be sent for some reason, then a warning message will be shown.  In this example, the cause is that no recipient addressees were found:

If you are a JIRA administrator and you have made configuration changes, clicking Send will also save those changes as per the Remember As setting under Settings.

Settings

Here you will find several settings that change how the Ad Hoc Notification system looks and operates.

Content Editor

As of JEMH 2.1.1, there are now two different editors that can be used for editing the notification body content on the comment tab.

Rich Text

By default, the new Rich Text editor will be used. This editor allows editing of both text and images as you would expect with a standard text editor application.  It also features real-time image insertion, use of scriptlets and on-demand spell-checking.

Advanced

The Advanced editor was previously the only editor available. Whilst it lacks the controls found in a text editor, it is a good choice for velocity-heavy templates as it allows a rendering of a preview by pressing the blue button below it.

Configuration Source (now)

Ad Hoc Notification settings can be set at a global level or per-project. This shows where the current settings are being taken from.

Configuration Source (future)

This setting allows the modification of where this project gets its configuration from.  Note that if you are changing from a global source to a project-based source you will want to make sure that you set Remember As to Project.

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.

Show All Custom Fields

Sets whether custom fields of all types are listed as choices under the To, Cc and Bcc tabs.  When this setting is enabled, custom fields of all types are listed - note that no guarantees can be made that a type of custom field is compatible with the Ad Hoc Notification feature.  When this setting is disabled, only the known compatible custom field types are listed (text, user and group).  Default for this setting is disabled.

Remember As

When configuration changes have been made to the Ad Hoc Notification, they can be saved to be either specific to the current project, or global.  Once a selection has been made, clicking the Send button will send your notification and save the settings to the target location for the next opening of the Ad Hoc Notification feature.

Full mode only tabs

From

Setting the From Address for a Project

Setting a From address and saving the configuration using the ‘Settings’ tab will save the address as part of the Ad-hoc configuration. To use this to set a Project specific From address please:

1. Set the desired From address
   
   

2. Set the ‘Config source (future)’ to ‘Project’ and save the Settings as ‘Project’
   
   

3. When the popup is re-opened, the From address field will already be set to the Project Specific address.

Issue Update

This tab controls if/how the outgoing message is appended to the issue, and other event related items;

Pre-defining custom notification content

Ad Hoc Template Sets

Template Sets allow customisation of notification content and are used throughout JEMH.  The Ad Hoc Notification feature can also make use of notification templates.  To manage Ad Hoc templates, first click on the Template Sets tab in JEMH:

Under the Template Sets section of the page, there is a tab called Ad Hoc.  Opening this tab will list any existing Ad Hoc templates that are found.  Clicking the add icon  creates a new Template, clicking the edit icon opens the template for editing.  Learn more on using Template Sets here.

Scriptlets

From version 2.1.1 onwards, scriptlets can be inserted into the content of ad-hoc notifications.  A scriptlet is a pre-defined section of content, that is rendered in the context of the current issue.  See here for more information on creating template scriptlets.

Once you have created your scriptlets, they can be inserted by users into the Rich Text editor window by clicking Insert>Template and selecting the desired template:

Once the OK button has been clicked, the result of the render is inserted into the notification comment content:

Auto Updating Recipients on the Issue

SINCE 3.1.13

Auto Update Recipient allows you to add the recipients in the configured fields in the corresponding Jira issue. This way the recipients (if not involved/associated) are able to comment on the issue. The following screenshot indicates the configuration that needs to be configured:

Select Addressee Handling

In AdHoc Configuration edit Project Settings or Global Settings to determine Addressee Handling:

If toCustomField (Addressee handling) option is selected, you are then required to configure the corresponding custom fields needs to be selected to handle the Jira recipients and Non-Jira recipients as per screenshot:

Key points to note:

• Custom field -

  • Jira custom field - ONLY user picker field are configurable

  • Non-Jira custom field - ONLY text field are configurable (single line + multi line)

• If all Addressee Handling options are selected, users are submitted to the fields in the following order:

  • Watcher

  • Request Participants (if JSD)

  • Custom Fields

  • Do note that if Field criteria is not met, the user will be allocated to the next custom field in the order

Enabling Recipient Auto Update

During the sending of the AdHoc notification, you’ll need to ensure the Recipient Auto Update is enabled as per screenshot:

Issue commenting with Recipient Auto Update enabled

During the send, if Add Content As a comment to issue option selected (as per screenshot below), the users allocated to the configured field will be mentioned as part of the comment.

Example:

This functionality allows the user to review the end result of the processing of Recipient Auto Update feature. Do note that this is part of the Default AdHoc template and if you’d prefer not to see this information, you’ll have to create a template as per instructions on https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/2850840

If an expected user is not located either in the comment or anywhere on the issue, we’d recommend reviewing the JEMH log files and/or log a support ticket with us.

Related articles