- SAP Managed Tags:
Objectives
You want to forward SAP Cloud ALM tasks events to external task management systems like Azure DevOps Work Items.
Prerequisites
Any task 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 an SAP BTP destination to enable connectivity to your external system.
- Configure an SAP Cloud ALM web-hook to enable communication between your external system and your SAP Cloud ALM tenant.
- Create an SAP Cloud ALM mapping 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 different tasks types.
Configure SAP BTP destination
In your SAP BTP Cockpit create a destination to your external Azure Dev Ops system.
The SAP BTP destination enables the connectivity from your SAP BTP tenant to your external system
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.
Copy the built-in 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 mapping named "Task to Azure DevOps Work Item" and adjust it to your needs.
The mapping content is:
{
"_information": {
"_version":"1","_source":"SAP Cloud ALM Task","_destination":"Azure DevOps Work Item API","_name":"SAP Cloud ALM Task to Azure DevOps Work Item","_comment":""
},"switches":[{
"name":"switchType","cases":[{
"when":"CALMREQU","then":"Requirement"
}, {
"when":"CALMDEF","then":"Defect"
}, {
"when":"CALMUS","then":"User Story"
}, {
"when":"CALMTASK","then":"Project Task"
}, {
"when":"CALMTMPL","then":"Template"
}],"default":"Project Task"
}, {
"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":"switchPriority","cases":[{
"when":10,"then":1
}, {
"when":20,"then":2
}, {
"when":30,"then":3
}, {
"when":40,"then":4
}, {
"when":40,"then":4
}],"default":3
}, {
"name":"switchStatus","cases":[{
"when":"CIPREQUINP","then":"In Process"
}, {
"when":"CIPREQUNO","then":"Not Relevant"
}, {
"when":"CIPREQUBLK","then":"Blocked"
}, {
"when":"CIPTKINP","then":"In Process"
}, {
"when":"CIPTKNO","then":"Not Relevant"
}, {
"when":"CIPTKBLK","then":"Blocked"
}, {
"when":"CIPTKCLOSE","then":"Closed"
}, {
"when":"CIPDFCTINP","then":"In Process"
}, {
"when":"CIPDFCTBLK","then":"Blocked"
}, {
"when":"CIPDFCTDONE","then":"Done"
}, {
"when":"CIPUSINP","then":"In Process"
}, {
"when":"CIPUSNO","then":"Not Relevant"
}, {
"when":"CIPUSBLK","then":"Blocked"
}, {
"when":"CIPUSCLOSE","then":"Closed"
}],"default":"Open"
}, {
"name":"switchIssue","cases":[{
"when":"CALMUS","then":"$User Story"
}, {
"when":"CALMTASK","then":"$Task"
}, {
"when":"CALMDEF","then":"$Bug"
}],"default":"$Task"
}],"structure": {
"request":[{
"op":"add","path":"/fields/System.Title","from":null,"value":"#{title}"
}, {
"op":"add","path":"/fields/System.Description","from":null,"value":"<p>Type: ${SWITCH(switchType,type)}</p><p>Project ID: #{projectId}</p><p>Status: ${SWITCH(switchStatus,status)}</p><p>Description: #{description}</p><p>Scope Name: #{scopeName}</p><p>Due Date: #{dueDate}</p><p><a href=\"#{@CLOUD_ALM_URL}/launchpad#${SWITCH(switchLink,type)}/taskDetail/#{id}\">Direct link</a></p>"
}, {
"op":"add","path":"/fields/Microsoft.VSTS.Common.Priority","from":null,"value":"${SWITCH(switchPriority,priorityId)}"
}, {
"op":"add","path":"/fields/System.Tags","from":null,"value":"#{workstream}"
}],"response": {
"azureTaskCreated":true
}},"eventTypeMapping": {
"_comment":"Specific event type mapping","operationMappings":[{
"eventType":"TASK.CREATED","operation":"POST","responseRoot":"","path":"/${SWITCH(switchIssue,type)}?api-version=7.1-preview.3","externalIdProperty":"/id","headers": {
"mediaType":"application/json-patch+json"
}}, {
"eventType":"TASK.UPDATED","operation":"PATCH","responseRoot":"","path":"/#{@CLOUD_ALM_EXTERNAL_ID}?api-version=7.1-preview.3","headers": {
"mediaType":"application/json-patch+json"
},"structure": {
"request":[{
"op":"replace","path":"/fields/System.Title","from":null,"value":"#{title}"
}, {
"op":"replace","path":"/fields/System.Description","from":null,"value":"<p>Type: ${SWITCH(switchType,type)}</p><p>Project ID: #{projectId}</p><p>Status: ${SWITCH(switchStatus,status)}</p><p>Description: #{description}</p><p>Scope Name: #{scopeName}</p><p>Due Date: #{dueDate}</p><p><a href=\"#{@CLOUD_ALM_URL}/launchpad#${SWITCH(switchLink,type)}/taskDetail/#{id}\">Direct link</a></p>"
}, {
"op":"replace","path":"/fields/Microsoft.VSTS.Common.Priority","from":null,"value":"${SWITCH(switchPriority,priorityId)}"
}, {
"op":"replace","path":"/fields/System.Tags","from":null,"value":"#{workstream}"
}],"response": {
"azureTaskUpdated":true
}}}, {
"eventType":"TASK.DELETED","operation":"DELETE","responseRoot":"","path":"/#{@CLOUD_ALM_EXTERNAL_ID}?api-version=7.1-preview.3","structure": {
"request": {},"response": {
"azureTaskDeleted":true
}}}]}}
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: CALM Task to use this subscription for events raised for resources managed by the project and task applications.
- Type: Built-in to apply a transformation payload.
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 this example, tasks events will be sent for Project Task and User Story. Other tasks types events (Defects, Requirements, and Roadmap Tasks) are ignored.
All changes events for the selected tasks types (Creation, Update and Deletion) will be managed by the associated subscriptions.
Check the help.sap.portal for more information.
Monitor resources changes events
In the SAP Cloud ALM External API Management application, you can monitor the events exchanged with your external system.
More Information
Thanks for reading
2 Comments
