Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
4,360,714
Community Members
 
Community Events
168
Community Groups

An unofficial way to monitor a JSM mail handler for errors

Howdy, everyone!

This post is intended to help people monitor their Service Projects for mail handler errors that may not be noticed until a manual check of the Processing log page is performed.

image-20220909-061357.png

This is also very requested by many of you and after playing with Jira Automation and API for a while now, I finally found a way to make this happen within Jira.

How does this work?

Jira Service Management has an internal endpoint that programmatically returns the same information we see on the Processing log page. The idea here will be to create a scheduled automation rule that will check this endpoint for error logs, format them and forward this to the email address you specify.

But before we proceed, there are a few things that are important to mention:

  • It will be necessary to have an Atlassian account with a Jira Service Management license and Project Administrator permission in the Service Projects you want to monitor the mail handlers;

  • It is highly recommended for this account to be a service account because its API Key will be exposed in one of the rule’s components.

How can we build this rule?

To ease this guide, we will split it into four parts.

Step 1 - Discovering the endpoint

Each Jira Service Management mail handler has its unique Channel Identifier, which can difficult things a bit, but stick with me as we make this into a piece of cake.

  1. Go to your Service Project mail handlers settings:

    1. For company-managed: Project Settings > Email Requests

    2. For team-managed: Service Project settings > Channels > Email

  2. Open your Browser’s Developer Tools and switch to the Network Tab

  3. Click on View logs for the mail handler you want to get the channel identifier

  4. This should record a few endpoint requests, but we need to find one similar to:

    https://instance.atlassian.net/rest/jira-email-processor-plugin/1.0/mail/audit/process/CHANNELXXXXXXXXXXXX?limit=50&page-1
  5. When you find it, copy the CHANNELXXXXXXXXXXXX to somewhere you can easily get it later like a text editor

To be sure you found the correct endpoint, you can simply copy the endpoint and open a new tab, the result should be a JSON structure similar to this:

image-20220909-061027.png

Here is a quick recording showing how to achieve this:

Step 2 - Generating an API Key

Even though we have found the endpoint to retrieve the logs, we still need to be authenticated to access this information and to achieve that we will need an Atlassian account with Project Administrator permission, a Jira Service Management license, and its API Key. After deciding which account to use, follow this guide to create its API Key.

Step 3 - Encoding credentials

You can encode the credentials yourself by opening your Browser's Developer Tools. In the Console tab, type in the following and click enter:

encodedData = "Basic " + window.btoa('ATLASSIAN_ACCOUNT_EMAIL:API_KEY')

You'll need to substitute both the ATLASSIAN_ACCOUNT_EMAIL and API_KEY with the chosen account credentials, like this:

image-20220909-060900.png

Copy this value (without quotation marks) to somewhere you can easily get it later like a text editor.

Step 4 - Build the automation rule

The final piece in this puzzle… the automation rule. Go to your Project Settings > Automation and start a new rule in the following components:

Scheduled Trigger: The frequency will be up to you, but for the sake of the example, let’s set it to run every hour.

image-20220911-221231.png

Create variable: This variable will be used in the endpoint we saved earlier as an epoch time. This is necessary to limit the logs by date, otherwise, you would keep retrieving the same errors every day.

  • Variable name: epochtimestamp (suggestion)

  • Smart value: {{#now}}func=minusHours(1), format="toMillis"{{/}}

    • The minusHours(n) is related to the frequency selected for the trigger, which is why we are using minus one hour. Replace Hours with Days/Weeks and n with the number of the selected unit you want to look back at.

image-20220911-221239.png

Send Web Request: The component where all things come together. Here we will programmatically simulate the action to open the Processing log page.

  • Web request URL: {{BaseURL}}/rest/jira-email-processor-plugin/1.0/mail/audit/process/CHANNELXXXXXXXXXXX?from={{epochtimestamp}}&statuses=FAILED

    • Replace CHANNELXXXXXXXXXXX with Channel Identifier we got at the end of Step 1.

    • ?from={{epochtimestamp}} is being used as a time window to avoid retrieving old errors

    • &statuses=FAILED was added so we only retrieve email logs with the FAILED tag.

  • Headers:

    • Key: Authorization

    • Value: Basic c2VydmljZWFjY291bnRhdGxhc3NpYW4uY29tOmNUVnlNbEJxTWtSNWNXaGhiVzFtWkZWeg== (Same credentials saved at the end of Step 3)

  • HTTP Method: GET

  • Wait for response: Flagged

image-20220911-221425.png

Advanced Compare Condition: A simple verification to avoid sending notifications without errors.

  • First value: {{exists(webResponse.body.data.first)}}

    • The smartvalue function exists() returns true if any content is returned for the webResponse.body.data.first smartvalue

  • Condition: equals

  • Second value: true

image-20220911-221217.png

Send Email: The last component of our rule, responsible to notify the administrators about the errors in your Jira Service Management mail handlers.

  • To: Here you can select Jira groups or add email addresses manually

  • Subject: {{webResponse.body.data.first.mailChannelName}} - Mail logs (suggestion)

    • The smartvalue is getting the mail handler address retrieved in the Send Web Request action and appending it to the subject of our notification

  • Content:

    {{#webResponse.body.data}}
    <b>Error Message</b>: {{message}}
    <b>Sender</b>: {{fromAddress}}
    <b>Subject</b>: {{subject}}
    <b>Event Time</b>: {{createdDateTime}}
    ---
    
    {{/}}
    • I will not dive into these smartvalues in this article, but I can tell we are using list expressions and HTML here to format our notification based on the Send Web Request response. If you want to learn more about it, you can check Smart Values - Example with lists.

image-20220911-221017.png

Finish your rule by giving it a name, and be sure you leave it enabled.

Example

After that, the result should be similar to the image below which matches perfectly with what we saw at the beginning of this page:

image-20220909-070403.png

Additional Resources

It isn't as good as a native solution, but I hope it will be useful for many of you until Jira Service Management makes it natively available.

Here are some additional links for anyone interested in learning more about Jira Automation, as well as two rules that you can easily import into your Atlassian site based on what we reviewed:

Automation Rules

  • Rule #1 - Alert Admins: This is exactly what we saw here, ready to be imported. ( Download Link)

  • Rule #2 - Alert Sender: Following the previous rule, this one will notify the senders if their emails were not processed. (Download Link)

Info icon Both rules require you to replace the Credentials and Channel Id.

Related Feature Request

Official Documentation

External Documentation

 

3 comments

Wagner Filho Atlassian Team Sep 12, 2022

Great article, Yuri!! 

Hi,

Can some one will help me out with How to configure Email Notifications in Jira.

How to trigger notification to Manager if it is approval is there.

Thanks,

Comment

Log in or Sign up to comment
TAGS

Atlassian Community Events