Use Adhoc Notifications
- 1 Summary
- 2 Enabling ad hoc notifications
- 3 Using the AdHoc Notification Pop-up
- 3.1 Message Types
- 3.2 Spell Checking
- 3.3 Setting message recipients
- 3.4 Attachments
- 3.5 Sending a message
- 3.6 Settings
- 3.7 Full mode only tabs
- 4 Pre-defining custom notification content
- 4.1 Ad Hoc Template Sets
- 4.2 Scriptlets
- 5 Auto Updating Recipients on the Issue
- 6 Related articles
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.
Quick start
As a system administrator go to an issue view and use the keyboard shortcut g + @
The JEMH Ad-Hoc Notification dialogue should now be displayed
On the Comment tab, enter the default notification subject and comment content
Go to the Settings tab and under Save Settings select Remember As Global
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.
Go to JEMH by pressing full stop on the keyboard to open Jira's Operations box, and typing "jemh" and pressing Enter.
JEMH will appear. Open the Features tab and click the edit icon. Enable the feature and then press submit.
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:
Clearing all Global Settings will create a 'locked' down configuration by default.
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:
Custom Content, which is straight forward text
Template Sets - pre-defined messages or "canned responses". When Template Sets are selected, the resulting content can be edited before sending.
Changes made to custom Template Sets while in the Ad Hoc Notification window are not saved back to the database. The changes only apply to the current open session of the Ad Hoc Notification window.
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:
userx@example.com,usery@example.com,userz@example.com
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.
Example view of Simple Mode | Example view of Full Mode |
---|---|
|
|
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:
Set the desired From address
Set the ‘Config source (future)’ to ‘Project’ and save the Settings as ‘Project’
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;
Setting | Description |
---|---|
Add Content As a comment to issue | If checked, adds a 'quoted' comment to the issue indicating who it was sent to. |
Comment Security Level | So as to avoid unnecessary notifications, visibility of the comment can be set to retain the information but hide for clarity / privacy. |
Send Comment Event | When the comment is added, an event can be fired (causing email notifications) or not. |
Immediate Delivery | Whilst possible, pushing the mail queue is synchronous with the user interaction, i.e. checking this will result in the send operation hanging until the mail queue has been flushed. Not recommended to be defaulted. |
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