Customizing email content (batched notifications)

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

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.

  1. Go to Administration () > Manage apps, and open the Manage apps page.

  2. From the drop-down, select All apps, and search for Jira inform - batchers.

  3. Expand the app, and check your version (in the example below, it’s 1.1.3). 

    Jira inform - batchers app.

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.

  1. Go to <jira-installation-directory>/atlassian-jira/WEB-INF/atlassian-bundled-plugins/.

  2. Find the batchers-<version>.jar file.

  3. 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/email

Step 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 fileDescription

IssueUpdateBatcher-subject.vm

Email subject for issue updates.

IssueUpdateBatcher-header.vm

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.

IssueUpdateBatcher-content.vm (for HTML format)

IssueUpdateBatcher.vm (for text format)

Main part of the email, containing the list of all changes, like details about the created issue, issue updates, and comments.

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.

Text format...
  1. Find the Velocity template of the email part you wish to modify. All templates are in this directory:

    /templates/email/batch/text/
  2. Bring the template up in your favorite text editor. Refer to the Velocity Users Guide to make the customizations you want.

HTML format...
  1. Find the Velocity template of the email part you wish to modify. All templates are in this directory:

    /templates/email/batch/html/
  2. Bring the template up in your favorite text editor. Refer to the Velocity Users Guide to make the customizations you want.

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.

  1. Insert the templates back into the JAR file. 

    jar uf batchers-1.1.3.jar templates/email
  2. Upload the app to Jira.

    1. Go to Administration (> Manage apps > Manage apps.

    2. 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.

Reverting the changes...

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 Administration () > Manage apps > Manage apps.

You can find the app’s JAR file in <jira-installation-directory>/atlassian-jira/WEB-INF/atlassian-bundled-plugins/.

Changes are not visible in emails...

This problem often occurs when you edit the templates from a different Jira inform - batchers app version than the one your Jira instance is using. See Step 1: Retrieve the Velocity templates for more information on how to get the version right.

Changes disappeared after upgrading Jira...

The Jira inform - batchers app, and the templates inside it, will get overwritten after every upgrade of your Jira instance. This means that you have to reapply the changes after an upgrade. It’s good to keep the copy of the templates somewhere, so you can reapply the changes more quickly.

Last modified on Aug 17, 2020

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.