SAP Cloud ALM Integration: Event-Situations Transformation Mapping

[Xavier]

In this series of blog post, we will cover different use-cases of integration between SAP Cloud ALM and external ALM services. All Integration scenario of SAP Cloud ALM are based on the public APIs listed of the SAP API Business Hub.

Objectives

When events are created in SAP Cloud ALM, you would like to forward those events to an external ticketing system by applying specific transformation rules.

 

Approach

SAP Cloud ALM Resource Changes API

Events sent by SAP Cloud ALM are identified by REST resources of type Event-Situations managed by the SAP Cloud ALM RESOURCE_CHANGES API.

The SAP Cloud ALM Resource Changes API is the API implemented by the web-hooks destination declared in SAP Cloud ALM external management.

The Resource Changes API supports the following operation:

• POST
  
  
  
  • /resourceChangeCustomUrl
  
  
  
  


• Request Body

   {

      "subscriptionId": "string",

      "resourceType": "string",

      "eventType": "string",

      "resourceId": "string",

      "resource": {}

    }

The parameters resourceType and eventType in the change message indicate which event triggered the changemessage.

Event Situation

Events situation raised by SAP Cloud ALM SAP Cloud ALM support the following list of events:

1. Event-Situations
   
   
   
   • EVENT-SITUATION.CREATED
   
   
   • EVENT-SITUATION.UPDATED
   
   
   • EVENT-SITUATION.DELETED
   
   
   • EVENT-SITUATION.PING
   
   
   
   

The resource body of the EVENT SITUATION is the following:

    "resource": {

        "id": "cd0cb7ea-c4ed-43f5-aaf7-e12259483184",

        "startTime": "2022-05-16T18:25:43Z",

        "updateTime": "2022-05-16T18:25:43Z",

        "serviceId": "190c1314-efd9-44ce-8d2f-2f7dc24ddf04",

        "timestamp": "2022-05-16T18:25:43Z",

        "subject": "Ping failed to service S4H",

        "body": "System involved: S4H",

        "rating": "ERROR",

        "tags": {

            "type": "httpPing",

            "status": "DOWN"

        }

    }

 

Mapping Rules

A mapping rules transformation file contains 4 sections:

• _information: mapping information.


• request: general rules to be applied for all requests payload.


• response: general rules to be applied for all responses payload.


• eventTypeMapping: configuration and specific rules to apply for each event type.

 

Rules

4 mapping rules are supported and are applied when transforming a request message payload into a response payload.

Rules	Description	Examples
maps	Direct attribute mapping: Use the "source" value for the "destination" attribute.	"maps": [ { "destination": "subcategory", "source": "subEventType" }, { "destination": "description", "source": "body" } ]
expressions	Expression with placeholders to match the value defined in "format" for the "destination" attribute.	"expressions": [ { "destination": "short_description", "format": "#{eventType}_#{subEventType}" }, { "destination": "url", "format": "https://snow/id/#{value}" } ]
choices	Attributes and Values mapping. Select the "source" value for the "destination" attribute from the possible values.	"choices": [ { "destination": "impact", "source": "rating", "cases": [ { "when": "Fatal", "then": "4" }, { "when": "Error", "then": "3" }, { "when": "Warning", "then": "2" }, { "when": "All Correct", "then": "1" } ], "default": "3" } ]
constants	Constant mapping: Use constant specified in "value" for the value of the "destination" attribute.	"constants": [ { "destination": "comment", "value": "New error" }, { "destination": "endpoint", "value": "SNOW" } ]

 

Section

Information

This section contains informative information as version, source, and destination.

    "_information":

    {

        "_version": "1.0.0",

        "_source": "SAP Cloud ALM Event Situation",

        "_destination": "Service Now incidents",

        "_name": "SAP Cloud ALM Event Situation to Service Now incidents",

        "_comment": ""

    },

 

 

Request

This section contains a set of general mapping rules that will apply to requests.

 

Response

This section contains a set of general mapping rules that will apply to responses.

 

EventType Mapping

This section describes the URL attributes mapping for each event type. In addition, specific rules for request / response can be defined to override the general mapping rules.

For each event type, the following parameters can be applied:

• operation: REST operation to apply.


• responseRoot: root url. -> Root node from which the response should be read.


• path: url path parameters -> Specific path pattern (including URL parameters) to concatenate to the relative path.


• request: mapping rules to apply for the request.


• response: mapping rules to to apply for the response.


• displayURL: rules to apply when building the navigation URL to the external resource. This information is added to payload to the response and is used internally by SAP Cloud ALM applications.

 

Example:

   "operationMappings":

   [

     {

       "eventType": "EVENT-SITUATION.CREATED",

       "operation": "POST",

       "responseRoot": "/result",

       "displayURL": {

         "propertyName": "displayUrl",

         "relativePath":"/nav_to.do?uri=/incident.do?sys_id=#{sys_id}"

        }

      },

     {

      "eventType": "EVENT-SITUATION.UPDATED",

      "operation": "PATCH",

      "responseRoot": "/result",

      "path": "/#{externalId}?sysparm_exclude_ref_link=true"

     }

    ]