JIRA is an event driven system. This means that usually when an action occurs (for example, when an issue is created), JIRA fires off a corresponding event. This event is then picked up by components that are designed to listen to the event. Not surprisingly, they are called listeners. When a listener picks up an event, it will perform its duty such as keeping issues up to date with changes or send an e-mail to users watching the issue.
This mechanism allows JIRA to process operations asynchronously. The advantage of this model is operations, such as sending e-mails, are separated from JIRA's core functions like issue creation. If there is a problem with the mail server, for example, then you will not want this problem to prevent your users from creating issues.
There are two types of events in JIRA:
The following table lists all the system events in JIRA and what they are used for:
Event |
Description |
---|---|
An issue has been created in JIRA. | |
An issue has been updated (for example, changes to its fields). | |
An issue has been assigned to a user. | |
An issue has been resolved (usually applied to the resolve workflow transition). | |
An issue has been closed (usually applied to the closed workflow transition). | |
A comment has been added to an issue. | |
A comment has been updated. | |
An issue has been reopened (usually applied to the reopen workflow transition). | |
An issue has been deleted from JIRA. | |
An issue has been moved (to a different or the same project). | |
Time has been logged on this issue (if time tracking has been enabled). | |
The assignee has started working on this issue (usually applied to the start progress workflow transition). | |
The assignee has stopped working on this issue (usually applied to the stop progress workflow transition). | |
Worklog has been updated (if time tracking has been enabled). | |
Worklog has been deleted (if time tracking has been enabled). | |
A generic event that can be used by any workflow post function. | |
Events created by user to represent arbitrary events generated by business processes. |
As an administrator, you will be able to get a one-page view of all the events in JIRA. You just need to do the following:
Like most other entities in JIRA, such as screens, events can be either active or inactive. New events are inactive by default, and they need to be associated with a notification scheme or workflow post function to become active. While you cannot edit or delete system events, you can deactivate them by removing their association with notification schemes and workflow post functions.
Each event is associated with a template, often referred to as mail template. These templates contain the base e-mail contents when notifications are sent. For system events, you cannot change their templates (you can change the template files, however). For custom events, you can choose to use one of the existing templates or create your own mail template.
Mail templates are physical files that you create and edit directly via a text editor. Each mail template is made up of three files:
Mail templates are stored in the <JIRA_INSTALL>/atlassian-jira/WEB-INF/classes/templates/email
directory. Each of the three files listed are placed in their respective directories called 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 the 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 command will get the issue key and summary from the current issue, separated by a –
character:
$issue.key - $issue.summary
JIRA provides a range of Velocity references that you can use for creating mail templates. You can find a comprehensive list at https://developer.atlassian.com/display/JIRADEV/Velocity_Context_for_Email_Templates.
Now that you have a brief understanding of how Velocity works, you first need to create a template for the mail subject. The following command shows a typical subject template:
$eventTypeName: ($issue.key) $issue.summary
When the template is processed, JIRA will substitute in the actual values for event type (for example, Issue Created), issue key, and issue summary (for example, Issue Escalated: HD-11 – Database server is running at very slow).
You then need to create a template for the actual e-mail 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 e-mail, 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, 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 the closing the </templatemappings>
tag, as follows:
<templatemapping id="10001"> <name>Example Custom Event</name> <template>examplecustomevent.vm</template> <templatetype>issueevent</templatetype> </templatemapping>
Here, we have registered a new custom mail template entry:
Parameter |
Description |
---|---|
The unique ID for the template. | |
A human-readable name for JIRA to display. | |
The mail template file names for | |
Template type. For events generated from an issue, the value will be |
After creating your templates and registering them in the mapping file, you will have to restart JIRA for the changes to be picked up.
JIRA comes with a comprehensive list of system events focused around issue-related operations. However, there will be times when you will need to create custom-designed events representing specialized business operations, or you simply need to use a custom e-mail template.
Perform the following steps to add a new custom event:
New events are inactive by default. Associating them with a notification scheme or workflow post function will activate them.
Unlike system events, with custom events, you need to tell JIRA when it should fire a custom event.
Custom events are mostly fired by workflow transitions. If you recall from Chapter 6, Workflows and Business Processes, you can add post functions to workflow transitions. Almost all JIRA's transitions will have a post function that fires an appropriate event. It is important to understand that just because an event is fired, it does not mean that there needs to be something to listen to it.
If you have skipped Chapter 6, Workflows and Business Processes, or still do not have a good understanding on workflows, now will be a good time to go back and revisit the chapter.
Perform the following steps to fire a custom event from a workflow post function:
Now, whenever the workflow transition is executed, the post
function will run and fire the selected event. Each transition can fire only one event, so you cannot have both Issue Created and Issue Updated events being fired from the one transition.