Configure the integration with 3rd party automation engines

  • You want to initiate an operation flow (for example a job, workflow or automation) in a non-SAP automation engine from a monitoring event in SAP Cloud ALM. The operation flow will execute problem remediation activities.
  • You want to initiate an operation flow (for example a job, workflow or automation) in a non-SAP automation engine from a status event, for example a maintenance event in SAP Cloud ALM. The operation flow will automate standard operational tasks.

Prerequisites

The non-SAP automation engine provides the following REST APIs:

  • A REST API to initiate a new execution of an operation flow by passing an identifier for the operation flow definition or template. The REST API responds with an identifier for the triggered execution and optionally a runtime status.
  • A REST API to query the runtime status of the execution by passing the execution identifier. It returns the current runtime status of the execution.

The APIs are accessible over the Internet.

Ideally, the automation engine supports context sensitive navigation to the operation flow execution via a URL that accepts the execution identifier as URL parameter.

Configuration

Establish connectivity

  1. Log on to BTP Cockpit and enter your SAP Cloud ALM subaccount.
  2. Navigate to "Connectivity" --> "Destinations".
  3. Click "New Destination".
  4. Enter the following data:
    1. Name: Enter a destination name that identifies the API endpoint of the automation engine.
    2. Type: HTTP.
    3. Description: A description of the destination.
    4. URL: URL of the API endpoint of your automation engine.
    5. Proxy Type: Internet.
    6. Authentication: use the authentication method of the target API. Authentication method “NoAuthentication” is not recommended for SAP Cloud ALM integrations.
    7. Enter the required authentication information depending on the authentication method.
  5. Click the "Save" button

 

Define webhook
  1. Log on to SAP Cloud ALM.
  2. Select Administration à External API management  Webhook Management.
  3. Select Add new Webhook.
  4. Enter the following data:
    1. Enter a name that identifies the webhook.
    2. Select Destination Source BTP destination.
    3. Select the Destination you created before.
    4. If required enter the path to reach the APIs in the external ticket system.
    5. Select External Resource Type “Workflow”.
  5. Select Save

Define mapping

The mapping file needs to define the request and response for the supported events.
You can take the following generic mapping as a template and adapt it to your automation engine. Please note: This mapping serves only as a template, it will not work out of the box and need to be adapted.

"switches":[ {

        "name": "switchExternalStatus",

        "cases":

        [

          {

                "when": "Running”,

                 "then": "STARTED"

            },

            {

                "when": "Failed",

                "then": "FAILED"

            },

            {

                "when": "Cancelled",

                "then": "FAILED"

            },

        

            {

                "when": "Finished",

                "then": "COMPLETED"

            }

],

        "default": "FAILED"

    }],

    "structure": {

        "request": {

            "globalVariables":[{

                "variableKey" : "<EventName>",

                "variableValue": "#{eventName}"

            },

                {

                    "variableKey" : "<StartTime>",

                    "variableValue": "#{timestamp}"

                },

                    {

                    "variableKey" : "<EventData>",

                    "variableValue": "#{eventDetailsTable}"

                },

                {

                    "variableKey" : "<ServiceName>",

                    "variableValue": "#{serviceName}"

                }]},

                "response": {

                    "externalResourceId":"#{<executionId>}",

                    "externalResourceStatus":"${SWITCH(switchExternalStatus,<status>)}",

                    "displayUrl":"https://<prefix>/#{<executionId>}"

                }

},

    "eventTypeMapping": {

        "_comment":"Specific event type mapping",

        "operationMappings":[{

            "eventType":"OPERATIONFLOW.STARTED",

            "operation":"POST",

            "path":"/<prefix>/#{<automationId>}/<suffix>",

            "responseRoot":"",

                    },

            {

                "eventType":"OPERATIONFLOW.GETDEFINITIONS",

                "operation":"GET",

                "responseRoot":"",

                "structure": {

                    "response": {

                        "definitions": [{

                            "automationId": "<id>",

                            "name": "<name>"

                        },

                            {

                                "automationId": "002",

                                "name": "IDoc Re-Process"

                            },

                            {

                                "automationId": "003",

                                "name": "AIF Message Reprocess"

                            },

                            {

                                "automationId": "004",

                                "name": "Upscale CF APP"

                            },

                            {

                                "automationId": "005",

                                "name": "Restart failed jobs"

                            }]

                    }

                }

            },

            {

                "eventType": "OPERATIONFLOW.PING",

                "operation": "GET",

                "path": "/<prefix>/#{externalResourceId}/<suffix>",

                "responseRoot": "",

                "structure":

                {

                    "response":

                    {

                        "externalResourceId":"#{executiond}",

                        "externalResourceStatus":"${SWITCH(switchExternalStatus,status)}"

                    }

                }

            }]}}

Please note that the mapping example above is only a template and cannot work out of the box. It needs to be adapted as explained below

  • Block “switchExternalStatus”
    Map the execution status codes returned by the automation engine to the status codes supported by SAP Cloud ALM: STARTED,COMPLETED, FAILED.
  • Block "structure": { "request": {…
    Map the properties provided in the event payload to the input properties of the operation flow. In the example shown above, the following 5 properties are passed to the automation engine: eventname, starttime, eventdetailstable, servicename.
    For information about the available properties check here(opens in new tab) .
  • Block "structure": { "response": {…
    Map the response of the automation engine to expected values in SAP Cloud ALM.
    The response data received by the automation engine must return the execution id and the status of the execution id. 
    Example:
    The automation engine return as response
    {"executionId":459680,"status":"Running"}
    The expression "externalResourceId":"#{executionId}" in the mapping parses the workflow id as execution id and stores it in SAP Cloud ALM.
    The expression  "externalResourceStatus":"${SWITCH(switchExternalStatus,status)}" in the mapping parses the returned runtime status, converts it via the switchExternalStatus to values understood by SAP Cloud ALM and stores it in SAP Cloud ALM
    The expression  "displayUrl":"https://<URL</#{workflowId}/<...> " in the mapping calculates a context sensitive navigation link to the operation flow execution. This navigation link will be used in the alert details and in the IEP event log to jump to the execution.
  • Block eventTypeMapping "eventType":"OPERATIONFLOW.GETDEFINITIONS"
    Currently the event type OPERATIONFLOW.GETDEFINITIONS does not perform calls to the automation engine. Therefore, you need to maintain in the response section the list of available operation flow definitions that can be triggered from SAP Cloud ALM.
    Expected format: {  "automationId": "<id>", "name": "<name>“}. The id is the id of the operation flow definition or template required to trigger a new execution, and the name is the name of the operation flow definition or template which will be shown in SAP Cloud ALM.
  • Block eventTypeMapping "eventType":"OPERATIONFLOW.STARTED"
    Adapt the path so that a new execution of the given automation id can be triggered. The complete URL will be composed out of the API endpoint maintained in the destination + the path. The complete URL needs to contain the automationId which will be dynamically replaced. 
  • Block eventTypeMapping "eventType":"OPERATIONFLOW.PING"
    Adapt the path so that a status check of the given automation id can be triggered. The complete URL will be composed out of the API endpoint maintained in the destination + the path. The complete URL needs to contain the externalResourceId which will be dynamically replaced.

Once you have completed the mapping verify that it has a valid JSON structure.

Upload mapping

  1. Log on to SAP Cloud ALM.
  2. Select Administration --> External API management --> Mappings Management.
  3. Select Add new mapping.
  4. Enter the following data:
    1. Enter a description that identifies the mapping.
    2. Enter a version.
    3. Enter “Source” SAP Cloud ALM”.
    4. Enter “Destination” the name of the automation engine.
    5. Select Mapping Type Payload based.
    6. Paste the content of your mapping file into the mapping rules or Load rules from file.
  5. Select Save.

Define subscription

  1. Log on to SAP Cloud ALM
  2. Select Administration à External API management  Subscriptions Management
  3. Select Add new subscription
  4. Enter the following data:
  5. Enter a name and description.
  6. Select Type Built in
  7. Select the webhook you created earlier
  8. Select the mapping you created earlier
  9. Select critical if you want to get alerted on failed calls to the automation engine. In this case you need to configure the API call monitoring as explained here(opens in new tab).
  10. Select Save

Test the subscription

Prerequisites:

  • Enable debug mode
  1. Log on to SAP Cloud ALM.
  2. Select Administration --> External API Management --> Subscriptions Management.
  3. Select the subscription you created earlier.
  4. Select Start Debug.
  • Find an alert in SAP Cloud ALM against which you want to test the integration.

Testing the event OPERATIONFLOW.GETDEFINITIONS

  1. Select Operations --> Operations Automation.
  2. Select Register operation flow --> Automation Engine.
  3. Select the subscription you created earlier.
  4. Select the F4 help besides Automation ID.
    Check that the list of operation flow definitions you defined in block OPERATIONFLOW.GETDEFINITIONS appears.
  5. Select an Automation which is suitable for testing. Assign an use case which corresponds to the use cases of the alert.
  6. Select OK.

Testing the event OPERATIONFLOW.STARTED

  1. Open the alert.
  2. Select Actions --> Start Operation Flow.
  3. Select action "Start" for the automation you registered previously.
  4. Check that you get a success message.
  5. Open the Automation engine and select the execution you just triggered. Check that the input parameters (e.g. event name, event details ) were correctly filled with Event data from SAP Cloud ALM.

Testing the event OPERATIONFLOW.PING and the context sensitive navigation link.

  1. Open the alert.
  2. Select Tab Operation Flows.
  3. Select Automatic Refresh --> Refresh.
  4. Check that the operation flow execution you just triggered is listed and the status is displayed correctly.
  5. Select the Instance Id navigation link.
  6. Check that the jump-in to the execution in the automation engine works.

Troubleshooting

  1. Select Administration --> External API Management --> Console.
  2. Check that the events you just triggered have response code 200.
  3. Select the events and check the request details.