JIRA Service Desk is a great product. It provides all the essential features to set up a fully functional business and customer friendly service desk. It is, like the rest of JIRA, quite flexible.
But there is one area that I believe is seriously lacking in terms of flexibility. Email Handling!
Whilst many users will prefer to login to the portal and raise requests, others will prefer to email. The majority will prefer to receive change notifications for requests by email too.
The ‘Default’ Email Notifications feature is baked into JIRA Service Desk. This will send customers email notifications using Atlassian’s own built-in HTML email template.
But many JIRA Service Desk customers want to send these emails with their own branding, own look and feel, and customized data items in the body of the email.
The lack of ability to customize this essential function has been outstanding for a long time. Check out JSD-218 – As an Admin I want to be able to customize the Service Desk notifications’ subject, content and format
Read through the 330+ comments and you can see there is a lot of frustration in the community with Atlassian’s lack of progress on this issue. Only recently Atlassian announced a slow rollout of features related to Email customization in a beta program for JIRA Cloud customers.
The comments do provide some workarounds using ScriptRunner and velocity template modifications but I wanted to see if I could come up with an alternative that didn’t involve add-ons.
Without further ado, let’s define the requirements. We would like to be able to do the following:
Send emails in response to events on issues in JSD.
We want to be able to completely customize the look and feel of those emails.
We want to be able to insert data from the issue into those emails.
The emails should come from an email domain that the customer recognises and won’t be blocked or treated as spam.
Customers should be able to reply to these emails.
In this article I will show you how you can do all of this in JIRA Service Desk (for both cloud and server versions). We will use a combination of JIRA’s webhooks, Zapier, and SparkPost.
JIRA Email Notifications
So what are these email notifications that JSD / JIRA sends? They are emails, triggered by JIRA issue events that are sent to a defined set of recipients. The content of the email is defined in a template.
When we are dealing with JIRA Service Desk there are actually two flavours of email notifications.
JSD Customer Notifications. These are the notifications that are baked into the JIRA Service Desk project. There is very little we can do to change the behaviour of these notifications, or customize the content. We cannot change the layout or content without cracking open the source code, and on Cloud this is not even an option.
JIRA User Notifications. This is the traditional means of sending email notifications. Using notification schemes, we have the ability to define who receives the notifications for each type of event. But these email notifications are only sent to licensed JIRA users and not to JIRA Service Desk customers (free, and unlicensed). For the server instance we can also modify the Velocity templates used to control the layout and appearance of the emails.
Here are some examples of the out-of-the-box notifications; one is a standard JIRA Service Desk notification a customer would receive and the other is the type of notification received by licensed JIRA users.
The challenge for many Atlassian customers, and the challenge we set out to tackle in this article, is to provide a mechanism to change the content and branding of the emails, preferably without additional plugins.
An Alternative Approach
We want to send customized emails in response to events in our primary system. When you think about it this sounds a lot like the function of transactional email systems like Mandrill and SparkPost.
These are normally used in e-commerce systems to send receipts and other automated replies. They provide users with the ability to trigger emails and define templates for the content of those emails.
So I thought – could we disable JIRA’s native notifications and instead use one of these transactional email systems.
To do that we need a means of sending a message to our transactional email system when an event of interest occurs in JIRA. JIRA has webhooks which can do exactly that. But we need something that would catch the webhook, parse the content, and trigger the sending of the email.
Zapier has the capability to do this and is quite easy to set up.
Finally, we need to have something to actually send the email. There’s a bunch of candidates, but the new kid on the block is
SparkPost and I’ve decided for the purposes of this post to give it a try.
So the next step is to set up our accounts with Zapier and SparkPost.
Zap It
Firstly lets set up the Zapier account we need and create the webhook we are going to use.
Create your account on the Zapier site here, and sign up for a free plan.
Click Make a Zap and then select Choose App under trigger. Type Webhook and select the result.
Select the Catch Hook option and then click the Save + Continue button.
On the next screen select Continue. A custom webhook URL is generated. This is the webhook that JIRA will use to trigger the Zap. Click the Copy to Clipboard button.
Click OK, I did this button and keep this window open. Zapier is waiting to intercept this webhook. So we need to open another window and set up the webhook in JIRA.
Go to JIRA->Admin->System->Webhooks and configure the webhook.
Give the Webhook a name.
Paste the URL copied to the clipboard in step 4 into the URL field.
Select the events that will trigger this webhook. We will select the Issue Created and the Issue Updated event.
Note: In part 2 of this article we will further customize this to fire events from our workflow, restrict the issues we are interested in using JQL, and create webhooks for other events.
Click the Save button.
Now create an issue in any project and switch back to your Zapier browser window. Zapier should detect the webhook. You can click the view your hook link to see the actual data sent.
Here’s a screencast showing you what to do.
So we have JIRA talking to Zapier and sending the details of events as JSON.
But this is only half the story. We can’t complete the full Zapier definition yet as we need to also configure SparkPost.
Spark It
Now we are going to set up our email system using SparkPost. We just want to test a very basic scenario and ensure that we can send an email with some data from our JIRA issue created/updated event.
So first we need an account and then an email template.
Setting Up A SparkPost Account And Linking It To Zapier
First things first, set up a SparkPost account here. When you first set up an account, SparkPost will ask you about your sending domain. I advise skipping this for now. Click the Skip For Now button.
Click the Get A Key button under ‘Send with REST’. Copy the Key to notepad.
Switch back to Zapier. The next step is to set up the Action which will be called when the Zap is triggered by the webhook.
In Choose App, type SparkPost and select it. The next step is to Choose the Action. There is only one – Send Email.
Click the Connect a New Account button. Paste the key you just copied and click Yes, Continue.
Click the Test button next to the new account. If this is successful, click Save + Continue.
Here’s another short screencast to demonstrate these steps, although in this case I already had a SparkPost account.
So we’ve connected Zapier and SparkPost. Next we need to trigger an email in SparkPost. We need a template for the email.
Setting Up The SparkPost Email Template
On the next screen we can select the Template for the email that SparkPost will send. Right now we don’t have any template, but there is a draft template called “My First Email” set up for you in SparkPost.
Switch to the SparkPost browser window.
Click Templates. Then click My First Email. This will bring you into the editor. We are just going to use the default template as this is really a proof of concept.
Our Zap is going to take some data from the webhook body and construct a subject line that contains the Issue Key and Summary. In the Subject field in the template editor enter the text “{{mysubject}}” (without the quotes).
Click the button to Save & Publish.
Double-check your work with this screencast.
Complete The Zap
Switch back to Zapier to complete the configuration.
Select My First Email in the Template ID field.
In the Inline Recipients field choose Issue Fields Reporter EmailAddress.
In Substitution Data we provide key value pairs. The first field box is the key and here we can enter the key namemysubject. The second box is the value and here we can select Issue Key from the dropdown. After Issue Key, type a ” – ” (space, hyphen space) and then select Issue Fields Summary from the dropdown. This builds up a string of text for the subject line which will be injected into our email template.
Click Continue and a test email should be sent to you.
This screencast shows the setting up of the key value pairs in Zapier.
Now let’s see if it was all worth it. Create an Issue in JIRA using your own account. You should receive a notification from sandbox@sparkpost.com and the email subject line should contain your new issue key and summary. Then update any field, such as the description field. You should very quickly receive another email from SparkPost.
Hopefully it worked. If not, get in touch with me on the comments and I’ll try to help you diagnose it.
In Conclusion…
OK so there are quite a few steps involved but they are reasonably simple and give you a good sense of the power of Webhooks and Zapier. Let’s review where we are at and what we can do next.
At the beginning of this post we set a number of requirements.
Send emails in response to events on issues in JSD. We are using webhooks, triggered by JIRA events, to trigger emails using Zapier and SparkPost.
We want to be able to completely customize the look and feel of those emails. Although we didn’t show it here we have full access to the email template in SparkPost and we can completely customize the emails. Check out the SparkPost docs for more information.
We want to be able to insert data from the issue into those emails. We can inject substitution data (issue data from webhook body JSON content) into the templates. In this example we only injected data into the Subject but we can also do this in the body of the email. You can read up on the substitution data and its capabilities here.
The emails should come from an email domain that the customer recognises and won’t be blocked or treated as spam. We used the *.sparkpost.com domain as the sender domain for our proof-of-concept. You can set up your own sending domain and then verify it with SPF and DKIM to allow SparkPost send emails from your own domain. See docs here.
Customers should be able to reply to these emails. We have not yet addressed this requirement. But I believe it is possible and this worked in my initial tests. You would first need to set up sending from your company mail domain so that notifications arrive in recipients inboxes coming from support@company.com. When customers reply, the replies will go to this address. If you have JIRA set up to poll this account then JIRA should be able to process those emails and add the replies to the original issue. Alternatively you could auto-forward the emails to whatever email address is configured in JIRA.
To be honest I have not had time to completely test all scenarios and this is merely a proof-of-concept. I hope it inspires others to try this out and if you feel like it please add comments below and share your results. In the next post (assuming there is interest), I will look into how you can send the emails from your own domain, how to filter the events using JQL, and how we can customize the email templates. I’ll also look at triggering the emails from workflow transitions and by using the JIRA Automation Plugin. We won’t be able to create an email notification system as flexible as Notification Schemes but I think we can solve the problem of customizing email content for JIRA Service Desk customers.