Documentation for JIRA 4.4. Documentation for other versions of JIRA is available too.
Customisations to Velocity templates or other JIRA files are not included in the scope of Atlassian Support.
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
:
Keep 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 the JSPs or tempates into the new installation of JIRA. If the JSPs or templates have changed in the newer version, you will have to port your customization into them.
To change the columns in your filter subscriptions, you don't need to customise the mail templates. See Customising your Issue Navigator.
There's a feature request to improve this at JRA-7266. Please vote.
JIRA generates emails in reaction to events using a templating engine. The templating engine is Apache Jakarta'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.
To customise email content, please follow this procedure.
atlassian-jira/WEB-INF/classes/templates/email/
jira/src/etc/java/templates/email/
webapp/WEB-INF/classes/templates/email/
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.For new email templates:
mytemplate.vm
files in the html
, text
and subject
directories, based on the existing files in those directoriesatlassian-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.
The Issue object is passed into the vm templates. Notice some of it's 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.
See also Adding Custom Fields to Email.