Use Template Sets (Custom Templates)

Scenario

You want to be able to customize email content that users receive, or JEMH generates.

Template Sets

Template Sets are groupings of TEXT, HTML and Subject templates that can be customized.  The templates are scripted using VTL (Velocity Template Language).  There are several varieties of TemplateSets:

Type

Description

Example

Type

Description

Example

Comment Header

Allows customized prefixes to be injected into created descriptions/comments, for example to list email headers, like to: from: cc:, there is a basic and a detailed version.

Issue Event

Allows per-even customized content. On creation, copies of the related JIRA template TEXT,HTML and Subjects are loaded. Custom events are also supported.

HintOgram Template

If enabled, JEMH can summarize processing problems to the remote user, or an override recipient, TEXT, HTML and Subject can be customized.

Forward

If for some reason an email is not selected for processing or fails processing, it will be forwarded to a nominated user (admin), the content of the email contains information about the email, describing why it wasn't processed.

todo

JEMH Template Sets expose the underlying Velocity template used in generating email through a web interface, changes do not require a JIRA restart. Template Sets can be copied and exported (1.3+) to allow migration over environments.

Creating an IssueEvent Template Set

Editing an IssueEvent Template Set

Exporting a Template Set

All TemplateSets can be copied within JEMH or exported/imported to allow migration between environments.

Export

Importing

Imported

Export

Importing

Imported

Selection of Templates

Forward, Hint-O-gram and Comment Header templates are selected via the profile.  Issue Event templates will be selected via either the profile or the Event Listener, depending on which is being used to generate notifications.

JEMH Profile

If using the JEMH Profile for notifications, it can allow the simple selection of Templates through the Profile > Email > Templates section, this allows per-profile variance if needed.

Event Listener/Notifications

The Event Listener allows JEMH to create per-project mappings that allow JIRA and non-JIRA user notifications to be sent.  Each Issue Event can be set to the DEFAULT template, or can refer to a specific custom template.  For more information on its configuration, please see How Do I Use Event Listener for Issue Events.

Removing Notifiation Scheme from Project at JIRA level

When a Notification Scheme is associated with a project, JIRA will automatically receive Issue Event's and generate email. JEMH's Event Listener is just another listener - if enabled, will produce appropriate emails, but JIRA will still do the same, creating a second notification for JIRA users.

If JIRA user notification needs customization, the JIRA-User section of the JEMH Event Listener project mapping needs to have the appropriate Notification Scheme selected. The same Notification Scheme also needs to be deselected from the actual Project (this is required because of JRA-19957 that prevents the disablement of the internal Mail Event Listener).

JEMH is then able to take over all notifications for JIRA users, using exactly the same Notification Scheme that you have configured.

In newer versions of JEMH, the Event Listener is now called Notifications

 

  1. Go to JEMH>Event Listener/Notifications

  2. Scroll down to the Transports>Email section and choose either the Non-JIRA notifications or JIRA notifications tab

  3. Click Edit

    on the project of your choice

  4. Scroll down to the Event Template Selection section

  5. Find the event type for which you have created a custom template, and open the drop down menu on the right.  You should see your custom template:

  6. Press Submit to save your changes

  7. When expanding the mapping, you should see that the custom template is now selected:

Ensuring Templates will be used

Some custom issue templates work automatically, such as Issue Created or Issue Commented. However for others, such as Issue Resolved or Issue Updated, the Jira Workflow Transitions must be edited in order to ensure that the correct issue event is fired which will tell JEMH to use your custom template. Once you have created your template and selected it in the Event Handler/Notifications section for the related event, you need to modify the Workflow for your project.

  1. In your project, go to Project Settings>Workflows and click edit

  2. Click on a transition that you want your template set to be used on (For example, for ‘Issue Resolved’ you might want the ‘In Progress → Done’ transition)

  3. Go to the ‘Post Functions’ tab

  4. If a ‘Generic Event’ is being fired (Or Event ID:13) then edit this and select ‘Issue Resolved’. If there is no Issue Event being fired, click ‘Add post function’ and choose ‘Fire Event’

  5. Repeat steps 2-4 for each transition that you want your custom issue event templates to be used on

  6. Save these changes to the workflow