Sending emails from a Java application is not rocket science! But why bother if JIRA has its own APIs to do the job foryou?

I am talking about taking advantage of the issue event management in JIRA.

We all know about the notification schemes in JIRA and how JIRA sends email to the various subscribers when an event is fired. All we need to do is to make use of this feature.

Following are the simple configuration steps needed.

Define a template which renders the subject and body of the email message - both html and text version. I have discussed about this in detail in my book. In case if you missed it, check out the email-template-id-mappings. xml file under WEB-INF/classes folder. I have created the following entry:<templatemapping id="99"> <name>Mail Servlet</name> <template>mailservlet.vm</template> <templatetype>issueevent</templatetype></templatemapping>Note that you can do this programmatically when the plugin is enabled but I am not going into those details here.

Write the templates defined above. You need 3 templates, all with the same name mailservlet.vm (name defined above).Subject : The subject file goes into WEB-INF/classes/templates/email/subject folderSubject will be something simple. We are going to keep it very simple!Test Mail from Servlethtml : The html file goes into WEB-INF/classes/templates/email/html folderThis can be as fancy as you want. Let us keep it simple, using just 2 velocity params.Hello there!<br><br>#set ($baseUrl = $params.get("baseurl")) Are you having fun reading the <a href="http://www.j-tricks.com">j-tricks</a> tutorial? Take a look at <a href="$baseUrl/browse/$issue.key">$issue.key</a>.<br><br>$params.get("sender").getDisplayName()As you can see, there are 2 velocity variables, $params and $issue, that we have used in this template. We will see soon where those comes from.text : The text file goes into WEB-INF/classes/templates/email/text folderAgain, let us keep it simple as shown:Hello there!Are you having fun reading the j-tricks (http://www.j-tricks.com) tutorial? Take a look at $issue.key.$params.get("sender").getDisplayName()

Restart your JIRA so that the template mapping is effective. No need to do this if you are handling it programmatically when the plugin is enabled.

Add the new event to the notification scheme and add subscribers to this event notification.

Now that the template is defined and the event added, we can write the code that feeds the relevant context for the template and then fires the event. In your plugin, all you needed is a few lines of code.

That's it! The event is fired and mail will now be sent to all the subscribers as defined in the notification scheme.How about sending it only to selected people and not depending on the notification schemes? Like the share feature inJIRA5? i.e. send only to selected users? Replace the dispatchEvent with the following.

Create the map of params as in the above case.

For each user, create a notification recipient and add it into a Set of recipients.

Note that you will have to enable to jira-core dependency in the pom.xml for IssueMailQueueItemFactory.

Add the item to the mail queue.

ComponentAccessor.getMailQueue().addItem(item);

And that's all. The mail queue will take care of dispatching our message.

I have attached the code of a simple servlet plugin which does both the approaches at the end of this page. After installing the plugin, it can be tested by accessing the servlet. Use a valid issue key and a receiver attribute if you are not using notification scheme.

A handy article, as ever. It looks like the email is sent by the mail queue, which has a 60s interval, right?

Also, a useful trick I found for adding more variables to the standard Velocity context for regular email templates is to define a calculated custom field type that always returns the same thing - a Map of the objects you want in the context. Then in the email velocity template
retrieve the value of the custom field with $customFieldManager.getCustomFieldObjectByName()

~Matt

Reply

J-Tricks

7/10/2012 07:07:06 am

Matt, yes. It will be sent by the mail queue every N minutes as defined in the MailQueueService.

Nice trick about adding the objects to velocity context. Never thought about that before :)

It is quite interesting to know this kind of emails sending process and will try the plugins you mention in the post .

Reply

Bastien

11/23/2012 03:06:42 am

Hi !

I've tried this code, and i have this exeception :

ERROR ServiceRunner Mail Queue Service [atlassian.jira.mail.IssueMailQueueItem] This code or velocity template expects a GenericValue, but received an Issue. We need to recode
java.lang.UnsupportedOperationException: This code or velocity template expects a GenericValue, but received an Issue. We need to recode
at com.atlassian.jira.issue.DocumentIssueImpl.getLong(DocumentIssueImpl.java:446)
at com.atlassian.jira.mail.IssueMailQueueItem.send(IssueMailQueueItem.java:143)
at com.atlassian.mail.queue.MailQueueImpl.sendBuffer(MailQueueImpl.java:66)
at com.atlassian.jira.service.services.mail.MailQueueService.run(MailQueueService.java:28)
at com.atlassian.jira.service.JiraServiceContainerImpl.run(JiraServiceContainerImpl.java:61)
at com.atlassian.jira.service.ServiceRunner.execute(ServiceRunner.java:47)
at org.quartz.core.JobRunShell.run(JobRunShell.java:195)
at com.atlassian.multitenant.quartz.MultiTenantThreadPool$MultiTenantRunnable.run(MultiTenantThreadPool.java:72)
at org.quartz.simpl.SimpleThreadPool$WorkerThread.run(SimpleThreadPool.java:520)

also is there a way to do all the process of creating a template, notification scheme and add subscribers in the plugin?
like just install the plugin and you are ready to send email like:
http://localhost:8080/plugins/servlet/mailservlet?issue=DEMO-1

Reply

J-Tricks

12/14/2012 12:47:57 am

You can do most of it when the plugin is enabled. See http://www.j-tricks.com/1/post/2012/03/plugin-lifecycle-events.html for details.

You will have to manually add the template though!

Reply

Shabbir K

2/12/2013 12:50:25 am

HI

I am trying to create a screen where user can select 'groups' from group picker and have an option to send email notification (containing the ISSUE details) to the selected groups only. Is it possible with this plugin, please advise

Reply

J-Tricks

2/12/2013 01:53:23 am

You can try the method where you add recipients and add the mail item.

Reply

Matt Doar

2/14/2013 11:24:46 am

Shabbir, why not just define a notification scheme that uses a Custom Group Picker field. Then have the user populate the custom field and email will be sent to the groups in that field.

Reply

roark

3/25/2013 02:29:14 am

How do i include the package com.atlassian. jira in my project

Reply

J-Tricks

3/25/2013 03:47:25 am

Do you have the jira-api dependancy in the pom.xml? That will bring in most classes. Some of them are still part of core API and so you will have to add jira-core dependancy.