Customizing email content in Jira Server

Jira generates emails in reaction to events using a templating engine — Apache’s Velocity. This is a relatively easy to use templating language that can pull apart java objects in useful ways. Whether it’s adding some info to the header or footer, or shuffling around the contents of your emails, you can make a number of customizations and tailor the emails to your needs.

Before you begin

Email templates in Jira Server are stored in two locations:

• Jira installation directory: Batched issue notifications
• Jira inform - batchers app: Separate issue notifications and other events

Which ones you need to retrieve depends on what kind of notifications are you looking to customize. If you’re not sure which notifications you’re using, see Different types of email notifications in Jira.

Retrieving templates for batched issue notifications

Retrieve these templates to customize batched issue notifications. 

Good to know

• You don't have to restart Jira after modifying these 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). 

Step 1: Retrieve the Velocity templates

The Velocity templates used for batched issue 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). 

   

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. For more info about the templates and what you can do with them, see:

• Templates: Batched issue notifications

Step 3: Upload the updated templates to Jira

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.

Retrieving templates for separate issue notifications (and other events)

Retrieve these templates to customize separate issue notifications, or any other notifications, like User created, Forgot Password, Contact admin, etc.

Good to know

• Any changes to Velocity templates (as well as JSPs) will be overwritten following a Jira upgrade. In such a case, you will need to manually copy your modified files to the new Jira version. If the Velocity templates and/or JSPs have changed in the newer version, you will have to manually port your customizations into them (as opposed to copying these files directly over from your old Jira installation to your upgraded one).

Step 1: Retrieve the Velocity templates

1. Go to the following location in your Jira installation directory: 

   /atlassian-jira/WEB-INF/classes/templates/email/

   If you're using Jira sources files, go to jira/src/etc/java/templates/email/ instead.

2. Under this directory, there are three subdirectories:
   
   
   • html - contains the templates used to create emails in html
   • text - contains the templates used to create plain text mail outs
   • subject - contains the templates used to generate the subject of the emails

Creating new email templates

1. Create your new mytemplate.vm files in the html, text and subject directories, based on the existing files in those directories
2. Add the templates to atlassian-jira/WEB-INF/classes/email-template-id-mappings.xml to make them valid choices for when you are adding a new event.

Step 2: Edit the Velocity templates

Once you’ve extracted the Velocity templates, you can edit them directly. For more info about the templates and what you can do with them, see:

• Templates: Separate issue notifications and other events

Step 3: Restart Jira

After modifying these templates, you'll need to restart your Jira instance to apply the changes.

Optional: Deploying Velocity templates without restarting Jira

In a development instance, you can play with picking up velocity file changes without a restart.
From <jira-install>/atlassian-jira/WEB-INF/classes/velocity.properties:

1. Change class.resource.loader.cache from true to false
2. Remove the comment sign (#) from #velocimacro.library.autoreload=true

Making this change in production will eventually lead to Jira not serving pages along with the 'ran out of parsers' error in the log file.