Customizing email content

JIRA generates emails in reaction to events using a templating engine. The templating engine is Apache's Velocity. This is a relatively easy to use templating language that can pull apart java objects in useful ways. The mails are generated inside JIRA by invoking Velocity with a set of objects of relevance to the event.

(info) Please Note:

  • To change the columns in your filter subscriptions, you don't need to customize the mail templates.
  • There's a feature request to improve this at JRA-7266, which you can vote on to improve its chances of being implemented.
  • Bear in mind that the next time you upgrade JIRA – or need a new installation for any reason – you will have to manually copy any changes you have made to Velocity templates (as well as JSPs) into the new installation of JIRA. 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).

Customizations to Velocity templates or other JIRA files are not included in the scope of Atlassian Support.

Email template locations

  1. Open up your JIRA distribution, and navigate to the following paths:
    • The WEB-INF/classes/templates/email/ of the <jira-application-dir> in your JIRA installation directory.
    • The jira/src/etc/java/templates/email/ in your extracted JIRA source directory.
  2. Under this directory there are three directories: html, text and subject. The html subdirectory contains the templates used to create emails in html, while the text directory the plain text mail outs. The subject directory contains the templates used to generate the subject of the emails. The templates are named after the event that will trigger the email.
  3. Bring the template up in your favorite text editor. Referring to the JIRA template documentation (particularly Velocity Context for Email Templates) and Velocity Users Guide, make the customizations you want.
  4. Restart JIRA.

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

Note that since JIRA 4.1 each new template has to have a corresponding file in the subject directory.

Advanced customization

The Issue object is passed into the vm templates. Notice some of its implementation in /includes/summary-topleft.vm. As an example, calling $issue.getProject() would allow you to determine the project an issue comes from, and even create logic to show different information for emails from different projects.

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.

See also Adding Custom Fields to Email.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport