SAP Cloud ALM, the SAP Application Lifecycle Management platform in the cloud, comes with several services, especially in the Run area, that can trigger events.
These events are usually configurable either from the service's configuration page or from Intelligent Event Processing service.
In some cases, we need to forward important events or alerts to an external application. A typical example is the creation of a ServiceNow incident out of SAP Cloud ALM Event.
SAP Cloud ALM External API Management Service helps to forward Cloud ALM resources like events to third party products.
In the following we detail the steps to forward some selected SAP Cloud ALM events to Jira Cloud and create tasks out of them. No coding is needed, only configuration.
Note: the general principles and configuration steps described in this blog remain valid for other platforms than Jira Cloud like SAP ALM, Github, MS Teams...
Resource Mapping
To integrate SAP Cloud ALM with external applications you can either build this integration within SAP Cloud ALM itself, using a resource mapping file or, for more advanced scenarios, build such integration outside SAP Cloud ALM within SAP Integration Suite or your own external service.
In this example, we rely on a mapping file to convert an Cloud ALM event to a Jira Task.
Payload Mapping
Released in Q4 2022, Payload Mapping format completes the original Rule Based format. While the Rule Based format let you define one to one relationship between two flat json structures (not nested elements), the Payload Mapping format offers a different approach.
With Payload Mapping format, you build a json template which has the structure expected by the external application. Complex json structures with arrays an nested elements are supported. You can insert in this template file some placeholders that will be replaced at runtime. The value of the placeholders come from the SAP Cloud ALM ALM resource, in this case an event. It can be for example, the priority of the event, the name of the service...
Below are detailed the four main sections of a Payload Mapping file. The four sections contain the Payload Mapping to create a custom Jira task (named CALMTask) in the Jira Cloud project "CAD". To build the complete file, you just need to gather these four sections following the same order than this blog.
_information
The header information provides details regarding the content of the file. The values are just free text meant for documentation. In this section, we indicate for example that the source (internal resource) is an IEP (Intelligent Event Processing) event while the target (external resource) is a Jira task.
| { "_information": { "_version": "1", "_source": "IEP", "_destination": "Jira Cloud", "_name": "IEP to Jira Cloud", "_comment": "Jira Cloud ALM Task - Jira_CALMTask_Payload_Mapping_v1.json" }, |
switches
A switch is used to replace a placeholder by different constants depending on the value received from the Cloud ALM resource. In this example, SAP Cloud ALM and Jira Cloud don't use the same names for priorities, thus we use a switch to convert SAP Cloud ALM Event-Situation priorities to Jira Cloud Issue priorities.
The switch defined in this section can be referenced later in the next section ("structure") using their name. To reference the switch "switchPriority" we have defined (see after), we'll use this notation: ${SWITCH(switchPriority,rating)}
"switches": [ { "name": "switchPriority", "cases": [ { "when": "FATAL", "then": "Highest" }, { "when": "ERROR", "then": "High" }, { "when": "WARNING", "then": "Low" }, { "when": "INFO", "then": "Lowest" } ], "default": "Lowest" } ], |
structure
Section "structure" contains the template of the message sent to the external application (Jira Cloud). Here we use directly the Jira Cloud syntax. The place holders will be replaced at runtime with SAP Cloud ALM values. For example: #{subject}, #{rating}, #{eventName}...
To get the list of possible placeholders, you can check the SAP Help documentation of the corresponding SAP Cloud ALM resource, in our case, this is the Event-Situation.
Together with the placeholders, switches can be inserted when defined in the previous section "switches".
The section "structure" contains the "request" payload but also the "response" payload as it should be returned to SAP Cloud ALM. For instance, SAP Cloud ALM expects to receive the "externalId" of the external resource (id of the Jira task). The format of the response payload depends on the SAP Cloud ALM resource type (again here is the Event-Situation). This time, the placeholders used in the response (e.g. #{key}) are resolved from the external application response, Jira Cloud in this case.
Caution: You will notice that the target issue type is "CALMTask" which is a custom type not delivered in standard Jira Cloud. The name and identifier of custom fields (e.g. "customfield_10040") are relevant only for this specific custom issue "CALMTask". Thus, you should adapt this example to your own context. The project's id "CAD" also depends on your own context. Values that need to be adapted to your own environment are marked in red.
"structure": { "request": { "fields": { "summary": "[Cloud ALM for Operations] #{subject}", "issuetype": { "name": "CALMTask" }, "project": { "key": "CAD" }, "description": { "type": "doc", "version": 1, "content": [ { "type": "paragraph", "content": [ { "text": "#{rating} - #{eventName}: ", "type": "text" } ] } ] }, "labels": [ "CALM", "#{eventType}", "#{eventSubType}" ], "assignee": { "accountId": "6256cbbba872****" }, "customfield_10040": "#{eventName}", "customfield_10041": "#{eventType}", "customfield_10042": "#{eventSubType}", "customfield_10043": "#{serviceName}", "customfield_10044": "#{serviceType}", "customfield_10045": "https://www.sap.com", "priority": { "name": "${SWITCH(switchPriority,rating)}" }, "environment": { "type": "doc", "version": 1, "content": [ { "type": "paragraph", "content": [ { "text": "#{workNotes}", "type": "text" } ] }, { "type": "paragraph", "content": [ { "text": "serviceId: #{serviceId}", "type": "text" } ] } ] } } }, "response": { "externalStatus": "TO DO", "externalUrl": "#{self}", "externalNumber": "#{key}", "externalId": "#{id}" } }, |
eventTypeMapping
In this section, we indicate on which event type(s), the mapping should be applied. In this case, we want tp trigger the Jira task creation when the Event-Situation is created on SAP Cloud ALM side (event type "EVENT-SITUATION.CREATED").
"eventTypeMapping": { "_comment": "Specificeventtypemapping", "operationMappings": [ { "eventType": "EVENT-SITUATION.CREATED", "operation": "POST", "responseRoot": "" } ] } } |
Jira issue type "SAP Cloud ALM Task"
In this example we create a Jira issue type "CALMTask" out of SAP Cloud ALM Event-Situation. "CALMTask" is a custom Jira issue type that must be previously configured on the Jira side.
To build a working example, this is mandatory to reference the correct Jira issue type and adapt the Mapping Payload file consequently. It's out of scope of this blog to describe the step by step operations to configure a custom Jira issue type; However, the configuration of a custom Jira issue type is very simple an can be done from the UI mostly with drag and drop.
Confirm the Event-Situation (advanced integration)
It's ok to create a Jira task out of an Event-Situation but it might be interesting to close automatically the Event-Situation when the Jira task is completed.
To close a SAP Cloud ALM Event-Situation from the outside, we can use the dedicated public API SAP Cloud ALM Event Situations.
Although this is beyond the scope of this blog to details such integration on the Jira side, one way to implement the close Event-Situation is to rely on Jira Automation.
Below an example of simple manual automation to close the Event-Situation from a Jira Task.
Here the Jira automation is not triggered automatically but triggered manually from the Jira task.
Configuration details
In this section you'll find the configuration items; three different services must be configured:
- BTP Destination service
- SAP Cloud ALM External API Management service
- SAP Cloud ALM Monitoring service (in this case Business Process Monitoring)
SAP BTP Destination
In BTP Destination service we create a destination to reach Jira Cloud interface (REST api v3 in this example).
We connect to Jira Cloud with basic authentication and API token.
SAP Cloud ALM External API Management
In SAP Cloud ALM External API Management, we need to configure three objects:
- Webhook to reference the Jira Cloud destination
- Mapping which contain the transformation from SAP Cloud ALM Event-Situation to Jira Cloud "CALMTask"
- Subscription which can be consumed by IEP and the monitoring services
Webhook
In SAP Cloud ALM External API Management service, we create a webhook which references the BTP destination.
The webhook's path ("/rest/api/3/issues/") points to the correct api version.
We use external resource type "Incident" for the moment; in the future, a dedicated resource type "Task" might be introduced.
Mapping
We create the mapping file of type "Payload Based" (see above).
Subscription
We create the "Built-in" subscription which references the webhook as well as the mapping file we created above.
Type of subscription should is "Built-in" as we want to rely on the internal mapping mechanism of SAP Cloud ALM.
SAP Cloud ALM Business Process Monitoring
Most of SAP Cloud ALM monitoring use cases are integrated with Intelligent Event Processing and could be used as a Event-Situation producer. Please not that configuration steps might slightly differ depending on the use case chosen.
In this example we configure an Event-Situation in SAP Cloud ALM Business Process Monitoring service.
First we need to select on the right menu the KPI we want to configure. This must be a KPI collected by the infrastructure.
Then, we need to create an event out of this KPI to select specific filters (specific characteristics values) and thresholds that should produce an Event-Situation.
Once the event is created an activated, we should select the Jira Subscription we configured previously on External API Management service.
This is ready 👍, the next time this event will be created, it will trigger the creation of a Jira CALMTask.
Note: a Cloud ALM alert could be generated out of the same event in order to display it in the SAP Cloud ALM Business Monitoring user interface.
- SAP Managed Tags:
