Customizing email content (batched notifications)
When using batched notifications, issue updates that occur close together are grouped and sent in a single summary email. Templates that control how batched notifications look are in the Jira inform - batchers app. You need to find this app in your Jira installation and extract the templates before you can edit them.
Customizations to Velocity templates or other Jira files are not included in the scope of Atlassian Support.
Good to know
- You don't have to restart Jira after modifying the templates.
- The app that contains the templates will get overwritten with every Jira upgrade, and you'll need to reapply your changes. It’s good to keep the copy of the templates somewhere, so you can reapply the changes more quickly (don't just copy the whole app as its version may change).
- Apart from modifying how your emails look, you can also add extra custom fields to describe the issues you're being notified about more precisely. For more info, see Adding custom fields to emails.
Step 1: Retrieve the Velocity templates
The Velocity templates used for batched email notifications are in the Jira inform - batchers app. You’ll need to extract them.
1. Find out the app version
Your Jira installation directory might have more versions of this app. Check your current version to know which file to edit later.
Go to
> Manage apps, and open the Manage apps page.From the drop-down, select All apps, and search for Jira inform - batchers.
Expand the app, and check your version (in the example below, it’s 1.1.3).
2. Copy the app from the Jira installation directory
Copy the app to a separate directory. You should never edit the .jar files inside the Jira installation directory. It’s also good to keep the original JAR file in case you needed to revert the changes.
Go to <jira-installation-directory>/atlassian-jira/WEB-INF/atlassian-bundled-plugins/.
Find the batchers-<version>.jar file.
Copy the file to a separate directory.
3. Extract the template files from the app’s JAR file
The easiest way to extract the templates is to use the following command. Note that you’ll need JDK installed for it to work.
jar xf batchers-1.1.3.jar templates/emailStep 2: Edit the Velocity templates
Once you’ve extracted the Velocity templates, you can edit them directly.
1. Choose a template to update
Batched email notifications are using several templates. Here are the most important ones:
| Template file | Description |
|---|---|
| Email subject for issue updates. |
| Email header. This includes everything above the first separator visible in the email, that is project name, issue name, issue key, and introduction text summarizing the updates. This file is also used for mentions. |
| Main part of the email, containing the list of all changes, like details about the created issue, issue updates, and comments. This file is also used for mentions. |
| Email subject for mentions. |
footer.vm | Email footer. |
2. Edit the template
Jira supports HTML and text email formats. You should choose instructions according to format set in your Jira.
Step 3: Upload the updated templates to Jira
Testing your changes
We recommend that you test your changes in a staging environment before applying them in production. If you break the Velocity syntax, emails won’t be sent at all.
Insert the templates back into the JAR file.
jar uf batchers-1.1.3.jar templates/emailUpload the app to Jira.
Go to
> Manage apps > Manage apps.Click Upload app, and upload the JAR file. The changes will be visible once the app is reinstalled. You don’t have to restart your Jira instance.
Troubleshooting
Here are some common issues we’ve encountered when editing the templates.
Your Jira installation directory contains the original version of the Jira inform - batchers app. To revert the changes, find the app’s JAR file and upload it manually to Jira by going to > Manage apps > Manage apps.
You can find the app’s JAR file in <jira-installation-directory>/atlassian-jira/WEB-INF/atlassian-bundled-plugins/.