Technical Articles
Posting alerts to JIRA and other issue tracking systems with SAP Cloud Platform Alert Notification
Introduction
This blog post is part of a series of blog posts related to SAP Cloud Platform Alert Notification service.
You can relate to the parent blog post for more detailed information about the service itself.
In this blog post you will learn how to use SAP Cloud Platform Alert Notification for creating issues in Jira. Thus, you will enhance your issue tracking processes and help you team even more. It will be demonstrated how an alert, warning about a mission critical failure within your landscape, could result in an automatically created issue in a concrete Jira project, ready to be handled by your operations team immediately after the outage. You might be wondering how this will happen? The answer – using Webhooks
SAP Cloud Platform Alert Notification has launched a new feature which allows the usage of templates to customize a Webhook payload. While configuring an action, you can enter free text or structured json that includes parameter placeholders. Furthermore, define a URL address which is going to be called and plays the role of a Webhook. By executing a POST HTTP request to the respective URL address, Alert Notification is going to replace dynamically each placeholder with the value of the corresponding alert property, before the payload is actually sent.
Prerequisites:
- An active subscription to SAP Cloud Platform Alert Notification
- Existing Jira project
- User credentials with sufficient level of permissions for creating issues in the Jira project
- Jira API token. It is used for the basic authentication. For more details, refer to the following link
Let’s have a look at this implementation in the context of Jira Cloud platform.
Configure your Alert Notification
Logon to your SAP Cloud Platform account and select the sub-account where SAP Cloud Platform Alert Notification service is available. Navigate to the Alert Notification UI. If you are not familiar with the Alert Notification’s terminology, you can glance through the official documentation. We are going to start by creating a subscription.
Define a name for you subscription. Optionally, you can enter a description and labels to help you distinguish it. Insert your labels and click Enter.
Next step is to select conditions for the subscription. As some of the conditions already exist, we would just pick them up from the available list.
Besides, we can narrow the scope of the incoming alerts further by defining a condition which matches only events triggered from a specific resource, our java application for an instance. Let’s create it now.
Note: the labels are independent for each category. In our case we have one label “online-shop-app” for our Subscriptions and another with similar name for our Conditions. Summary of the selected conditions looks like:
Having done the configurations above, we should expect the Alert Notification to forward to us only alerts with severity ERROR or FATAL, related to our java application, called “online-shop”. It would be great if these alerts are reflected in our Jira project without having created the issues manually, wouldn’t it? Thus, we could free some capacity and focus on more demanding tasks, as analyzing the disruptive event and finding a solution.
Well, what’s next? For having a complete subscription, we should assign an action. To create a new action click on “Create Action” button. In our case Basic Authentication would be the relevant authentication type. From the displayed list select “Webhook with Basic Authentication” and click “Next”
After selecting the action type, we should define the required details.
Scroll down to move forward. Enter a URL address which is going to be called by Alert Notification, during the Webhook execution. In this blog post we would like to interact with Jira programmatically, so we are going to consume the Jira REST API. For Jira Cloud Platform, the URL for resources has the following structure:
https://<site-url>/rest/api/3/<resource-name>
Note: the number “3” specifies the version of the Jira Cloud platform REST API. At the time of writing this blog post, version 3 is in beta, therefore the example here represents the usage of version 2. For more details, check the Jira Cloud platform’s documentation.
Enter a username for Jira, in order to ensure access of Alert Notification to your project.
Note: the user should be authorized for tasks like generating items in the respective Jira project. For password use the API token, which can be generated here. Write down the provided token, as it could not be retrieved at a later point.
Scroll down to continue with the configuration. In the field “Payload Template” you can insert your custom payload which might include placeholders. They will be dynamically replaced by Alert Notification with the value of the corresponding alert property, before the payload is sent to the Jira REST API.
In this blog post, we are going to create an issue in Jira project with key “TRAP”, by using the following json which complies with the Jira’s requirements:
{
"fields": {
"project": {
"key": "TRAP"
},
"summary": "{subject}",
"description": "{body}",
"issuetype": {
"id": "10115"
},
"labels" : ["{resource.resourceName}"]
}
}
Of course, you can omit the label specification or instead you can use
"labels" : ["{eventType}"], "labels" : ["{severity}"]
or whatsoever, in order to adapt to your issue tracking needs. The usage of labels will help you to sort out the variety of tickets which might appear in your queue.
Note: it is very important to avoid the usage of white spaces in the labels’ value. Otherwise, Jira is not going to accept your request.
Click “Create“.
Now, the new action is ready to be assigned to subscription “Manage-Jira-Issues”.
Finally, our subscription is ready to be used. Do not miss the opportunity to go once again through the past configurations in the subscription summary overview, displayed as a last step.
Let me show you what the Alert Notification does once an alert regarding our java application “online-shop” is generated:
On the left-hand side it’s shown the raw format of the alert sent to Alert Notification from the events producer. On the right-hand side is the custom payload that Alert Notification is going to send to Jira.
It’s time to check our queue in Jira.
Issue with key “TRAP-35” has been created based on the alert above. If we go into the issue details, we will find the same description, as stated in the alert’s body.
The label “online-shop” could help us to list easily all open issues related with resource name “online-shop”.
That’s all!
Try out the service, play around, give us feedback. Subscribe your productive accounts to get an advantage of its full power. Cloud Platform Alert Notification is available for both CPEA accounts and for a subscription via SAP Store.