Objectives

XavierPicquart · ‎2024 Jul 03

Objectives

You want to externalize SAP Cloud ALM requirement approval to external workflow management systems like SAP Build Process Automation.

Prerequisites

Any workflow management external system can be connected to SAP Cloud ALM using the provided External API Integration capabilities.
The external tool must:

Expose REST APIs to receive messages.
Expose an API endpoint accessible from your SAP Cloud ALM BTP sub-account.
Support one of the following authentication protocol described in the following documentation.
Support a compatible payload for REST operations. The list of supported mapping rules can be found in the help.sap.com.

If the external tools do not match the requirements for a simple integration, an integration can still be achieved by using SAP Integration Suite or a third-party API Integration HUB platform.

Procedure Overview

Configure a workflow system to manage the requirement approval.
Configure an SAP BTP destination to enable connectivity to your workflow system.
Configure an SAP Cloud ALM web-hook to enable communication between your external system and your SAP Cloud ALM tenant.
Use the built-in SAP Cloud ALM mapping “Workflow to SAP Build Process Automation Workflow” to define the transformation rules to apply to messages exchanges between SAP Cloud ALM and the external REST API.
Add a SAP Cloud ALM subscription to associate the external system with the event types raised by SAP Cloud ALM.
Configure your SAP Cloud ALM Project to associate SAP Cloud ALM subscriptions to the requirement workflow type.

Configure a workflow system

In this example, the workflow system used is SAP Build Process Automation.

A basic process is defined:

Following parameters can be sent by SAP Cloud ALM:

You can download this SAP build process example here: Approval Workflow 2 eyes_1.0.2.mtar and adjust it to your needs.

Check the help.sap.portal for more information.

Configure SAP BTP destination

In your SAP BTP Cockpit create a destination to your SAP BPA tenant by following this tutorial.

Configure SAP Cloud ALM Web-hook

In the SAP Cloud ALM External API Management application, create a web-hook for your destination with the following parameters:

External resource type: Task.
Destination type: Enter Other.

Check the help.sap.portal for more information.

Create a SAP Cloud ALM mapping

The mapping defines the transformation rule to apply before sending the request and after receiving the response from the external system.

Copy the built-in “Workflow to SAP Build Process Automation Workflow” mapping to adjust it to your needs. In below example, priority and scope are added to the original mapping.

The mapping content is:

{
  "_information": {
    "_version": "1",
    "_source": "SAP Cloud ALM Workflow",
    "_destination": "SAP Build",
    "_name": "SAP Cloud ALM Task to SAP Build",
    "_comment": ""
  },
  "switches": [
    {
      "name": "switchLink",
      "cases": [
        {
          "when": "CALMREQU",
          "then": "ptmRequirement-management?sap-app-origin-hint=&tile=PTMREQ&"
        },
        {
          "when": "CALMDEF",
          "then": "ptmDefect-management?sap-app-origin-hint=&tile=PTMDEF&"
        },
        {
          "when": "CALMUS",
          "then": "task-management?sap-ui-app-id-hint=com.sap.calm.imp.tkm.ui&"
        },
        {
          "when": "CALMTASK",
          "then": "task-management?sap-ui-app-id-hint=com.sap.calm.imp.tkm.ui&"
        }
      ],
      "default": "task-management?sap-ui-app-id-hint=com.sap.calm.imp.tkm.ui&"
    },
    {
      "name": "switchExternalStatus",
      "cases": [
        {
          "when": "RUNNING",
          "then": "STARTED"
        },
        {
          "when": "CANCELED",
          "then": "FAILED"
        },
        {
          "when": "ERRONEOUS",
          "then": "FAILED"
        },
        {
          "when": "COMPLETED",
          "then": "STARTED"
        },
        {
          "when": "SUSPENDED",
          "then": "STARTED"
        }
      ],
      "default": "FAILED"
    },
    {
      "name": "switchPriority",
      "cases": [
        {
          "when": 10,
          "then": "Highest"
        },
        {
          "when": 20,
          "then": "High"
        },
        {
          "when": 30,
          "then": "Medium"
        },
        {
          "when": 40,
          "then": "Low"
        },
        {
          "when": 40,
          "then": "Lowest"
        }
      ],
      "default": "Lowest"
    }
  ],
  "structure": {
    "request": {
      "definitionId": "#{@USER_VAR(workflowDefinitionId)}",
      "context": {
        "subject": "#{item.title}",
        "desc": "#{item.description}",
        "status": "#{item.status}",
        "id": "#{item.id}",
        "link": "#{@CLOUD_ALM_URL}/launchpad#${SWITCH(switchLink,item.type)}/taskDetail/#{item.id}",
        "triggeredBy": "#{triggeredBy}",
        "projectId": "#{item.projectId}",
        "reviewedBy": "#{@USER_VAR(reviewedBy)}",
        "priority": "${SWITCH(switchPriority,item.priorityId)}",
        "scope": "#{item.scopeName}",
        "timestamp": "#{item.createdTimestamp}"
      }
    },
    "response": {
      "externalResourceId": "#{id}",
      "externalResourceStatus": "${SWITCH(switchExternalStatus,status)}"
    }
  },
  "eventTypeMapping": {
    "_comment": "Specific event type mapping",
    "operationMappings": [
      {
        "eventType": "WORKFLOW.STARTED",
        "operation": "POST",
        "responseRoot": "",
        "externalIdProperty": "/id"
      },
      {
        "eventType": "WORKFLOW.CANCELED",
        "operation": "PATCH",
        "responseRoot": "",
        "path": "/#{@CLOUD_ALM_EXTERNAL_ID}",
        "structure": {
          "request": {
            "status": "CANCELED",
            "cascade": false
          },
          "response": {
            "sentCancelRequest": true,
            "externalResourceStatus": "FAILED"
          }
        }
      }
    ]
  }
}

In this example, we use the following mapping details:

Mapping	Description
"eventType":"WORKFLOW.STARTED", "operation":"POST", "responseRoot":"", "externalIdProperty":"/id"	The externalIdProperty property is defined in the response mapping of a creation event to store the ID of the workflow in the built-in variable @Cloud_ALM_EXTERNAL_ID. The value of the externalIdProperty should follow the JSON pointer syntax.
"eventType":"WORKFLOW.CANCELED", "operation":"PATCH", "responseRoot":"", "path":"/#{@CLOUD_ALM_EXTERNAL_ID}"	During a workflow cancelation, we pass the workflow ID as a path parameter with the built-in variable: @Cloud_ALM_EXTERNAL_ID.
"#{@USER_VAR(workflowDefinitionId)}"	The workflowDefinitionId property is defined in the subscription and is the ID to the SAP Build Process Automation workflow. You can find it in the SAP Build monitoring application.

Check the help.sap.portal for more information.

Add a SAP Cloud ALM subscription

Create a subscription based on your web-hook and your mapping with the following parameters:

Resource type: workflow to use this subscription for workflow events raised for resources managed by the project and task applications.
Type: Built-in to apply a transformation payload.

The workflowDefinitionId property is the ID to the SAP Build Process Automation workflow. You can find using this documentation: Determine the Workflow Definition ID.

Check the help.sap.portal for more information.

Configure your SAP Cloud ALM project

In the Subscriptions panel of the SAP Cloud ALM Project Management application, associate the subscription to the selected task types in the workflow column.

In this example, workflow events will be sent for Requirement. Other tasks types are not yet supported.
All workflow events (kick-off or cancelation) will be managed by the associated subscriptions.

Check the help.sap.portal for more information.