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:
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.
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
Go to JEMH>Event Listener/Notifications
Scroll down to the Transports>Email section and choose either the Non-JIRA notifications or JIRA notifications tab
Click Edit
on the project of your choice
Scroll down to the Event Template Selection section
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:
Press Submit to save your changes
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.
In your project, go to Project Settings>Workflows and click edit
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)
Go to the ‘Post Functions’ tab
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’
Repeat steps 2-4 for each transition that you want your custom issue event templates to be used on
Save these changes to the workflow