In the previous recipe, Sending notifications for issue updates, we looked at how to set up notification schemes by mapping events to notification recipients.
In this recipe, we will expand on that, and look at how to create our custom events and templates to use for notifications. This has two advantages:
- We can customize the content and the look and feel of the notification e-mail
- We can specify exactly which event will be fired for each workflow transition, and set up notification rules accordingly
We will create a new event that will represent a request been approved by the management to proceed. This event will be triggered in an Approve workflow transition, and will have a custom template applied to it.
The first step is to create our custom e-mail templates. All mail templates are stored in the JIRA_INSTALL/atlassian-jira/WEB-INF/classes/templates/email directory, and generally, for each event in JIRA, there are three template files:
- The Subject template: This is the template file for the e-mail's subject line, which is stored in the
subjectsubdirectory - The Text template: This is the template file for e-mails sent in the text format, which is stored in the
textsubdirectory - The HTML template: This is the template file for e-mails sent in the HTML format, which is stored in the
htmlsubdirectory
To start creating our own e-mail templates, we first need to create the three files mentioned in the previous list of template files, and place them in their respective directories. Take special note that all three files need to have the same filename with a .vm extension.
We will start with the subject template as follows:
- Create a new file with the following code snippet:
#disable_html_escaping() $eventTypeName - ($issue.key) $issue.summary - We now need to create the body of the e-mail, keeping in mind that we have to create two versions: one for text and one for HTML. The following snippet shows the HTML version; for the text version, simply remove the HTML markups:
#disable_html_escaping() Hello $issue.reporterUser.displayName, <p> Your request <a href="">$issue.key</a> has been approved, with the comment below: </p> <blockquote> <p> $comment.body </p> </blockquote> <br/> Internal IT team - After we have created all three template files, we need to register them in JIRA so that they can be selected while creating custom events. To register new e-mail templates, open the
email-template-id-mappings.xmlfile in a text editor; you can find the file inside theJIRA_INSTALL/atlassian-jira/WEB-INF/classesdirectory. - The
email-template-id-mappings.xmlfile lists all the e-mail templates in JIRA, so we need to add a new entry at the end, as follows:<templatemapping id="10002"> <name>Issue Approved</name> <template>issueapproved.vm</template> <templatetype>issueevent</templatetype> </templatemapping>
There are a few points to note here:
- The
idvalue of<templatemapping>needs to be unique. - You can give any value to the
<name>element, but it is good practice to keep it consistent with your event in JIRA. - The
<template>element should have the name of the custom template files we have created. Since we can have only one<template>element, all three files need to have the same filename. - The
<templatetype>element needs to have the value set toissueevent.
Once you have added the entry and saved the file, you will need to restart JIRA for the changes to be applied.
Now that we have our custom e-mail templates in place, we can proceed to create custom events that will use our new templates. Follow the steps listed next to create custom events in JIRA:
- Navigate to Administration | System | Events.
- Enter
Issue Approvedfor the new event's name. - Select the Issue Approved template we just created.
- Click on the
Addbutton to create the new event.
Once you have created the events, they will be available in notification schemes, and we will be able to select who will receive e-mail notifications by configuring our notification schemes—as shown in the following screenshot, whenever an issue is approved, both the reporter and Christine will be notified:
The last step is to make sure that our custom events are fired when users trigger the action:
- Navigate to Administration | Issues | Workflows.
- Click on the Edit link for the workflow, which contains the transitions that will fire the custom event. In this case, we will be using a simple Approval Workflow that contains a transition called Approve:
- Click on the workflow transition, and select the Post Functions tab. Normally, you will see the last post function in the list firing Generic Event.
- Hover your mouse over the post function, and click on the edit icon (it looks like a pencil).
- Select the new
Issue Approvedevent, and click on Update, as shown in the following screenshot. This will make the transition to fire our event instead of the default Generic Event:
JIRA's e-mail templates use the Apache Velocity (http://velocity.apache.org) template language to display dynamic data. Each template is a mix of static text (with or without HTML markups) and some Velocity code. If you do not need to have dynamic contents, then you can have only static text in your templates.
In our previous examples, every time you see the dollar sign ($), such as $issue.key, it is a piece of Velocity code. The $ sign indicates getting a variable from the Velocity context, and the variable name is the word that comes directly after the $ sign; so, in this case, it is issue. The period (.) means getting the value specified from the variable. So, $issue.key can be read as get the value of key from the variable issue, or in other words, get me the issue's key.
JIRA exposes a number of variables in its Velocity context for e-mail templates; you can find the full list at https://confluence.atlassian.com/display/JIRA041/Velocity+Context+for+Email+Templates.
So, if we take a look at our templates, for the subject template, the ($issue.key) $issue.summary Velocity code will be turned into something like (TP-12) Request for JIRA administrator access, where TP-12 replaces $issue.key and Request for JIRA administrator access replaces $issue.summary.
The following screenshot shows a sample e-mail generated from the custom template that we have created, displayed in Gmail:
Now onto the custom Issue Approved event. Unlike system events, custom events can only be fired from workflow transitions, so we have to update our workflows. Every workflow transition fires an event, and by default, the Generic Event is fired. This means most workflow transitions will have the same notification recipient using the e-mail template.
By configuring the workflow to fire our own custom event, we have finer control over who receives notifications and which templates to use.