[Jira Service Management] How to customize customer notifications with Jira Automation

Short introduction of Jira Service Managment

I would assume that everyone who tries to search for this problem has already known about Jira Service Managment and what it can do. But in case you haven’t known about this beautiful tool yet, this is an introduction from Atlassian. Jira Service Managment basically allows you to create a help center to leverage communication between “those who needs help” — i.e “customers” and “those who can help” — i.e “agents”. Depending on your settings, the help center can be totally/ partially opened to the public, and your customers do not need access/ license to any Atlassian products to raise request to you.

There are two options to host your Jira Service Management solution, Cloud-based or Data Center. The article is based mostly on Data Center experience, but it is very similar in Cloud too.

Jira Service Management Customer Notifications

So, because Jira Service Management handles two different parties: the customers and the agents, it has two different notification systems, namely:

• Customer Notifications: The emails that will be sent to the customers to notify them that something has happen. This is managed in Project settings → Customer Notifications
• Notifications: The emails that will be sent to the agents — those who work inside the Jira tool. This is managed in Project settings → Notifications by a notification scheme (same as Notifications in Jira Software).

In this article, we are looking at how we can alternate the built-in Jira Service Management Customer Notifications with Jira Automation.

The built-in Jira Service Management Customer Notifications

Before we are going to customize the customer notifications in JSM, let’s look at how it is built-in in Jira first.

Below are the list of built-in events:

The built-in events in Jira Customer Notifications

and the original email template looks as simple as this:

The built-in Customer Notification works with the mechanism that all the events share the same templates of header and footer, and each event can have its customized message. The template is built by customizing HTML and CSS.

For each of the event, admin can configure who will receive the email. You can conveniently exclude the person who caused the action by checking the box below “To” field:

Jira Automation (also called Automation for Jira)

As quoted directly from Atlassian, Jira Automation is “a no-code rule builder that enables users to build if-this-then-that-rules based on events in Jira”. There are basically three important components to a Jira Automation rules:

• The trigger: when something happens
• The condition: if something matches some conditions
• The action: then do something

Jira Automation works by issue-based, meaning the rule is triggered for each issue. Among several actions that is built into Jira Automation, there is a Send Email action that you can use to send notification. The email can be built by using HTML and CSS.

We will go into this Send Email action in details later in the article.

Customizing the email Look and Feel

The first part of customizing the notifications involves customizing its look and feel. These tips can be applied to both the built-in solution and Jira Automation.

To customize the email Look and Feel, you basically need to adjust the HTML and CSS to make the Look and Feel as you want. This sounds very simple, yet pretty tricky. Some very important notes that you need to pay attention to:

• Write the HTML & CSS by using table markup so that the email client will respect it. Inline CSS is often respected compared with a separate <style> file. Many email clients, include the grumpy Outlook, do not really know how to treat HTML & CSS nicely. Check the email design tips for different email clients before you start, that will save you a lot of time.
• Always add a reply marker in your email, even if you think you don’t need them. With a reply marker, Jira knows where to stripe the comments when the email is sent to Jira, making the email looks a lot nicer and neater inside Jira. Without the reply marker, the whole email conversation will be added into the Jira ticket. With a reply marker, only the last reply will be added to the Jira ticket.

Without the correct reply marker

• To find the correct reply marker is little tricky. Jira basically respects what is stated in the atlassian-jira/WEB-INF/classes/outlook-email.translations file. That means:
  – It’s safest to use — - — - — - — as it is not language dependent
  – If you are using English, it is most likely that the reply marker will be either — - — - — - — or — — Original Message — — (Note that the Original Message one will not work if you have your email client in another language)
  – Even when you already add those marker at the beginning of the email body, the header of the old email is still copied to Jira (as when you click “Reply” the email header is added automatically)
  – To stripe the email header as well, add a new line to the translations file. For example “From:”. Note that this word is language-dependent, so you need to add the version of the language that you are using (for example “Fra:” in Norwegian).
• When deciding on the color of the email, remember that every email client also has the dark mode version, and that can mess up with your design completely. Remember to test the email in dark mode as well.
• Test the email with Outlook desktop app first, my experience shows that if the email looks nice in Outlook, it will look nice in other email clients too.

Below is an example of a working template

which will generate something that look like this:

The automation rules

With the HTML & CSS of the email ready, let’s look at how we should configured our rules. The rules can be configured under Project settings > Automation.

The trigger and condition

In the below table, you will find some of the main built-in events in the left hand side, and the equivalent Automation trigger and condition in the right hand side.

Some take-aways:

• Remember to add the condition Issue matches JQL: request-channel-type in (portal, email), otherwise the emails will be sent to the tickets that are created inside Jira too (which is ok if you want, but often the tickets that are created inside Jira have the Notifications settings to take care of it, so you are likely to receive double notifications).
• Try to add the condition that filter out the most issues first in the list to ensure good performance of the rules.
• These are the starting point for the conditions but does not necessary mean all the conditions that you should include. You might need to add more conditions later depending on your need.

The send email action

Now let’s look at the Send email action.

At the first glance the settings of Send email action is quite simple. You add the email receiver(s) to the “To” field, that can be the Initator, the Reporter, Assignee, or any user/group field in your instance. Then you specify the email subject, paste the HTML code that you have created above into the “Content” field and that’s it. But there some details that is quite tricky that you should pay attention to:

• As you can see, there is no easy option to just exclude the person who caused the action. It means that if you as the reporter make a public comment in the ticket and set the “reporter” as the receiver in the Send email option, you will receive notification for your own action. This is quite annoying, I hope Jira will integrate this possibility into Send Email action in the future. Meanwhile, we need to work around by adding conditions. For example: When Issue commented AND
  - if {{comment.author}} is not equal {{issue.reporter}} → Send email to reporter,
  - if {{comment.author}} equals {{issue.reporter}} → Send email to just Request Participants
• When Request Participants is added to the “To” field of the Send Email action, all the Request Partipants will received the notification email, even if he/she is the person who does the action. I have thought of using smart values to filter out the person who causes the action here, but unfortunately haven’t managed to find a solution for it yet.
• In the email Content, if you want to include specific field values in the notification, use smart values. Note that if you want to include the last comments into the email notification for example, use {{issue.last.comment.body.html}} as the smart value so that the formatting of the comment is preserved in the email, otherwise only plain text will be included.
• The “From” email address field in More options:
  The actual email handler of outcoming emails (emails that you will send to the customer) is the one that is set by default in the “From” field, which is the default email handler of the whole Jira instance. Now it will be quite easy if the default email handler of your Jira instance is a service email handler, but things got complicated when you also have Jira Software, and most of the time the Jira Software email handler is set as default. Jira Software email handler cannot handle pictures and attachments as well as the Jira Service Management email handler, so if you include a comment in the notification email, and that comment contains a picture, the picture will be broken as shown in the notification email. You will not have this problem if you use the built-in notification system, or if the default email handler of your instance is a JSM email.
  Very important! If you put a custom email address to this field, check that it doesn’t have trailing space! Otherwise Jira will not be able to send the email out, even though in the log the rule is said to send email successfully. This has caused me a lot of headache when we implemented to solution to our production.
• The “Reply to” email address field in More options:
  This field is very important, as it dertermines whether or not a new ticket or comments will be added to Jira when there is a reply email. If you use the default Jira Software email handler here, NO requests via email will be created. Make sure that you add a Jira Service Management email address, the one that you set up in Project settings > Email Requests.
  If you are applying these rules to multiple projects at once, the good news is that you can just use ONE Jira Service Management email address for all of them! When the customers reply to the notification email, as long as the correct Issue Key is added into the email title, Jira will add the reply to the correct ticket even if the reply email is not from the same project, how brilliant is that :D Thus, remember to ALWAYS include the issue key in your email title!
• Last but not least, UNCHECK the option to “Convert line breaks to HTML line breaks”, most of the time it would break your email design.

Testing

After implementing the rules, make sure to create a test case and test everything throughoutly. When testing there are two places that you need to watch out:

• The automation rule Audit log: This you can find inside the rule itself, make sure that all the rules are executed successfully. Note that if you include a log action early in the rules, it will always say “Success” in the audit log. So if you are finished with debugging, it’s a good idea to exclude the log action from the actual rules.
• The outgoing email queue: This you can find under Administration > System > Mail > Mail queue. Make sure that there is no error registered here, sometimes it’s possible that the rule Audit Log says “success” but the email was not actually sent out. This is the place where you can caught that problem!

Alternatives to customize Jira Service Management Customer Notifications

That’s it for my guide to use Automation rules in Jira to send out notifications, especially to the customers. There are several ways to customize the Jira Service Management Customer Notifications, especially if you are open to use third-party apps. Below I made a simple comparison between the built-in JSM Customer Notifications, Jira Automation and the well-known third-party app Email This Issue.

Using Jira Automation to send email notifications come with its good and bad. You can customize as much as you want, and can apply the same rules to multiple project at once, reduce the maintenance overhead in the future. At the same time, it has its own problem, there’s no convenient way to exclude the person who caused the action from the recipient list, and the outgoing email handler is most likely not be able to process pictures. Also, in Jira Cloud, you can only send maximum 100 emails per day, and there is a limit for rule execution, so having so notification rules might consume a lot of executions from bucket. If those disadvantages do not matter to you that much, and if you prefer to have a customization solution built in Jira, Jira Automation might be a good choice for you!