Customizing email content in Jira Server
Jira generates emails in reaction to events using a templating engine—Apache’s Velocity. This relatively easy-to-use templating language can pull apart java objects in useful ways. Whether 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.
Customizations to Velocity templates or other Jira files are not included in the scope of Atlassian Support.
Jump to...
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
Your choice of the location to retrieve depends on what kind of notifications you want to customize. If you’re not sure what notifications you’re using, see Different types of email notifications in Jira.
This article is for Jira Server. If you’re using Jira Data Center, you will retrieve the templates in a different way. Learn more about it in Customizing email content.
Retrieving templates for batched issue notifications
Retrieve these templates to customize batched issue notifications.
Good to know
- You don't need to restart Jira after modifying these templates.
- The app that contains the templates will be overwritten with every Jira upgrade, and you'll need to reapply your changes. We recommend keeping the copy of the templates somewhere, so you can reapply the changes more quickly. But we don't recommend copying the whole app, because its version may change.
Step 1: Retrieve Velocity templates
Velocity templates used for batched issue notifications are in the Jira inform - batchers app. You should extract them.
1. Find out the app's version
Your Jira installation directory might have more versions of this app. Check your current version to know which file to edit later.
In the upper-right corner of the screen, select Administration
> Manage apps. Go to Manage apps. From the dropdown list, select All apps. Search for Jira inform - batchers.
Expand the app and check the version. In the screenshot, 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. We also recommend keeping the original .jar file in case you need to revert the changes.
Go to
<jira-installation-directory>/atlassian-jira/WEB-INF/atlassian-bundled-plugins/.Find the
batchers-<version>.jarfile.Copy the file to a separate directory.
3. Extract the template files from the app’s JAR file
Use the following command to extract the templates. Note that you’ll need a JDK installed for it to work.
jar xf batchers-1.1.3.jar templates/emailStep 2: Edit Velocity templates
Once you’ve extracted Velocity templates, you can edit them directly. For more information about the templates and what you can do with them, see: Templates: Batched issue notifications.
Step 3: Upload 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 with this command:
jar uf batchers-1.1.3.jar templates/emailUpload the app to Jira. In the upper-right corner of the screen, select Administration
> Manage apps. Go to Manage apps. Select Upload app and upload the .jar file. The changes will be visible once the app is reinstalled. You don’t need 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 and JSPs (JavaServer Pages) will be overwritten after a Jira upgrade. In this case, you should manually copy the modified files to the new Jira version.
If Velocity templates or JSPs have changed in a later version, you should manually port your customizations into them, but not copy these files directly over from the old Jira installation to the upgraded one.
Step 1: Retrieve Velocity templates
To retrieve the templates:
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.- Under this directory, you should see three subdirectories:
htmlcontains templates used to create emails in HTML.textcontains templates used to create plain text mailouts.subjectcontains templates used to generate the subject of emails.
Creating new email templates
- Create new
mytemplate.vmfiles in thehtml,text, andsubjectdirectories, based on the existing files in those directories - Add the templates to
atlassian-jira/WEB-INF/classes/email-template-id-mappings.xmlto make them valid choices for when you are adding a new event.
Step 2: Edit the Velocity templates
Once you’ve extracted Velocity templates, you can edit them directly. For more information about the templates and what you can do with them, see Templates: Separate issue notifications and other events.
Step 3: Restart Jira
After modifying Velocity templates, you should restart your Jira instance to apply the changes.
Optional: Deploying Velocity templates without restarting Jira
On a development instance, you pick up velocity file changes without restarting Jira.
From <jira-install>/atlassian-jira/WEB-INF/classes/velocity.properties:
- Change
class.resource.loader.cachefromtruetofalse - Remove the comment sign (
#) from#velocimacro.library.autoreload=true
On a production instance, this change allows you to go back to default Velocity templates and make changes in them without restarting Jira.