Customizing email content in Jira Server

Still need help?

The Atlassian Community is here for you.

Ask the community

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.

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.

tip/resting Created with Sketch.

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.

  1. In the upper-right corner of the screen, select  Administration  > Manage apps

  2. Go to Manage apps. From the dropdown list, select All apps. Search for Jira inform - batchers.

  3. Expand the app and check the version. In the screenshot, 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. We also recommend keeping the original .jar file in case you need 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

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

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

  1. Insert the templates back into the .jar file with this command:

    jar uf batchers-1.1.3.jar templates/email
  2. Upload the app to Jira. In the upper-right corner of the screen, select  Administration  > Manage apps

  3. 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:

  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, you should see three subdirectories:

    • html contains templates used to create emails in HTML.
    • text contains templates used to create plain text mailouts.
    • subject contains templates used to generate the subject of emails.

Creating new email templates

  1. Create new mytemplate.vm files in the htmltext , 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 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:

  1. Change class.resource.loader.cache from true to false
  2. 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.

Last modified on Aug 4, 2022

Was this helpful?

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