Mail templates are physical files that you create and edit directly via a text editor; you cannot edit mail templates in the browser. Each mail template is made up of three files:

• Subject template: This file contains the template that's used to generate the email's subject
• Text template: This file contains the template that's used by Jira when the email is sent as plain text
• HTML template: This file contains the template that's used by Jira when the email is sent as HTML

Mail templates are stored in the <JIRA_INSTALL>/atlassian-jira/WEB-INF/classes/templates/email directory. Each of the three files that we listed is placed in its respective directory—subject, text, and html.

While creating new mail templates, it is a good practice to name your template files after the issue event. This will help future users understand the purpose of those templates.

Mail templates use Apache's Velocity template language (http://velocity.apache.org). For this reason, creating new mail templates will require some understanding of HTML and template programming.

If your templates only contain static text, you can simply use standard HTML tags for your template. However, if you need to have dynamic data rendered as part of your templates, such as the issue key or summary, you will need to use the Velocity syntax. A full explanation of Velocity is beyond the scope of this book. The following section provides a quick introduction to creating simple mail templates for Jira. You can find more information on Velocity and its usage in Jira mail templates at https://confluence.atlassian.com/x/dQISCw.

In a Velocity template, all the text will be treated as normal. Anything that starts with a dollar sign ($), such as $issue, is a Velocity statement. The $ sign tells Velocity to reference the item after the sign, and, when combined with the period (.), you are able to retrieve the value specified. For example, the following code in a template will get the issue key and summary from the current issue, separated by a - character:

    $issue.key - $issue.summary

This would produce content similar to DEMO-1 - This is a demo issue.

Jira provides a range of Velocity references that you can use for creating mail templates. These references allow you to access data such as the issue being updated and the user triggering the event. You can find a comprehensive list at https://developer.atlassian.com/server/jira/platform/jira-templates-and-jsps/#email-templates.

Now that you have a basic understanding of how Velocity works, you need to create a template for the mail subject. The following code shows a typical subject template:

    $eventTypeName: ($issue.key) $issue.summary

When the template is processed, Jira will substitute the actual values for the event type (for example, issue created), issue key, and issue summary. Therefore, the preceding example would produce content similar to Issue Escalated: HD-11: Database server is running very slow.

You then need to create a template for the actual email content. You need to create a text and HTML version. The following code shows a simple example of a text-based template, which displays the key for the escalated issue:

Hello, 
 
The ticket $issue.key has been escalated and is currently being worked on.  We will contact you if we require more information. 
 
Regards 
Support team. 

Before Jira sends out the email, the preceding text will be processed, where all Velocity references, such as $issue.key, will be converted into proper values, for example, DEMO-1.

After creating your mail templates, you need to register them with Jira. To register your new templates, locate and open the email-templates-id-mappings.xml file in the <JIRA_INSTALL>/atlassian-jira/WEB-INF/classes directory in a text editor. Add a new entry to the end of the file before closing the </templatemappings> tag, as follows:

<templatemapping id="10001"> 
  <name>Example Custom Event</name> 
  <template>examplecustomevent.vm</template> 
  <templatetype>issueevent</templatetype> 
</templatemapping> 

Here, we register a new custom mail template entry. The details of this are given in the following table:

After creating your templates and registering them in the mapping file, you will have to restart Jira for the changes to be picked up. The new templates will be available when we create new events, which we will talk about in the following section.