- SAP Managed Tags:
In this series of blog post, we 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 in the SAP Business Accelerator Hub.
You want to forward SAP Cloud ALM tasks events to external task management systems like Jira.
Any task management external system can be connected to SAP Cloud ALM using the provided External API Integration capabilities.
The external tool must:
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.
In your SAP BTP Cockpit create a destination to your external Jira system.
In the SAP Cloud ALM External API Management application, create a web-hook for your destination with the following parameters:
Note: In this example, we reuse a web-hook configured for incident creation.
Check the help.sap.portal for more information.
The mapping defines the transformation rule to apply before sending the request and after receiving the response from the external system.
The following mapping can be used:
In this example, we use the following mapping details:
Check the help.sap.portal for more information.
Create a subscription based on your web-hook and your mapping with the following parameters:
Check the help.sap.portal for more information.
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 Requirements and User Story. Other tasks types events (Defects, Projects, and Roadmap Task)s 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.
In the SAP Cloud ALM External API Management application, you can monitor the events exchanged with your external system
After creating or changing a task in your SAP Cloud ALM tenant, you can check the result in your Jira account.
By creating an automation rule in your Jira system, you can synchronise tasks in SAP Cloud ALM.
Automation rules are defined in the system section of the Jira settings. Here, you can use the SAP Cloud ALM Tasks API to create, update or delete your tasks entities in SAP Cloud ALM.
Thanks for reading
All Integration scenario of SAP Cloud ALM are based on the public APIs listed in the SAP Business Accelerator Hub.
Objectives
You want to forward SAP Cloud ALM tasks events to external task management systems like Jira.
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 Jira 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 JIRA.
Note: In this example, we reuse a web-hook configured for incident creation.
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.
The following mapping can be used:
{
"_information":
{
"_version": "1",
"_source": "SAP Cloud ALM Task",
"_destination": "Jira Task",
"_name": "SAP Cloud ALM Task to Jira Task",
"_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": "Highest"
},
{
"when": 20,
"then": "High"
},
{
"when": 30,
"then": "Medium"
},
{
"when": 40,
"then": "Low"
},
{
"when": 40,
"then": "Lowest"
}
],
"default": "Lowest"
}
],
"structure":
{
"request":
{
"fields":
{
"summary": "[SAP Cloud ALM ${SWITCH(switchType,type)}] #{title}",
"customfield_10049": "#{id}",
"issuetype":
{
"name": "Task"
},
"project":
{
"key": "RTP"
},
"description":
{
"type": "doc",
"version": 1,
"content":
[
{
"type": "paragraph",
"content":
[
{
"text": "Type: ${SWITCH(switchType,type)}\n\nProject ID: #{projectId}\n\nStatus: #{status} \n\nDescription: #{description}\n\nScope Name: #{scopeName}\n\nDue Date: #{dueDate}",
"type": "text"
}
]
},
{
"type": "paragraph",
"content":
[
{
"type": "text",
"text": "Direct Link",
"marks":
[
{
"type": "link",
"attrs":
{
"href": "#{@CLOUD_ALM_URL}/launchpad#${SWITCH(switchLink,type)}/taskDetail/#{id}"
}
}
]
}
]
}
]
},
"priority": {
"name": "${SWITCH(switchPriority,priorityId)}"
},
"labels":
[
"#{workstream}"
],
"assignee":
{
"accountId": "632adf49234d44d406cf77bb"
}
}
},
"response":
{
"displayUrl": "#{self}",
"externalNumber": "#{key}",
"externalId": "#{id}"
}
},
"eventTypeMapping":
{
"_comment": "Specific event type mapping",
"operationMappings":
[
{
"eventType": "TASK.CREATED",
"operation": "POST",
"responseRoot": "",
"externalIdProperty": "/id"
},
{
"eventType": "TASK.UPDATED",
"operation": "PUT",
"responseRoot": "",
"path": "/#{@CLOUD_ALM_EXTERNAL_ID}",
"structure":
{
"request":
{
"fields":
{
"description":
{
"type": "doc",
"version": 1,
"content":
[
{
"type": "paragraph",
"content":
[
{
"text": "Type: ${SWITCH(switchType,type)}\n\nProject ID: #{projectId}\n\nStatus: #{status} \n\nDescription: #{description}\n\nScope Name: #{scopeName}\n\nDue Date: #{dueDate}",
"type": "text"
}
]
},
{
"type": "paragraph",
"content":
[
{
"type": "text",
"text": "Direct Link",
"marks":
[
{
"type": "link",
"attrs":
{
"href": "#{@CLOUD_ALM_URL}/launchpad#${SWITCH(switchLink,type)}/taskDetail/#{id}"
}
}
]
}
]
}
]
},
"priority": {
"name": "${SWITCH(switchPriority,priorityId)}"
}
}
},
"response":
{
"ticketUpdated": true
}
}
},
{
"eventType": "TASK.DELETED",
"operation": "DELETE",
"responseRoot": "",
"path": "/#{@CLOUD_ALM_EXTERNAL_ID}"
}
]
}
}In this example, we use the following mapping details:
| Mapping | Description |
| "customfield_10049": "#{id}", | A custom field has been in Jira to store the SAP Cloud ALM Task ID. |
| " { "eventType": "TASK.CREATED", "operation": "POST", "responseRoot": "", "externalIdProperty": "/id" }, | The externalIdProperty property is defined in the response mapping of a creation event to store the ID of the Jira task in the built-in variable @CLOUD_ALM_EXTERNAL_ID. The value of the externalIdProperty should follow the JSON pointer syntax. |
| "eventType": "TASK.UPDATED", "operation": "PUT", "responseRoot": "", "path": "/#{@CLOUD_ALM_EXTERNAL_ID}", | During a task update, we pass the Jira task ID as a path parameter with the built-in variable: @CLOUD_ALM_EXTERNAL_ID. |
| "href": "#{@CLOUD_ALM_URL} | The parameter @CLOUD_ALM_URL is used to link the SAP Cloud ALM tenant from Jira. |
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 Requirements and User Story. Other tasks types events (Defects, Projects, and Roadmap Task)s 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
Check results in Jira
After creating or changing a task in your SAP Cloud ALM tenant, you can check the result in your Jira account.
Synchronise SAP Cloud ALM tasks
By creating an automation rule in your Jira system, you can synchronise tasks in SAP Cloud ALM.
Automation rules are defined in the system section of the Jira settings. Here, you can use the SAP Cloud ALM Tasks API to create, update or delete your tasks entities in SAP Cloud ALM.
More Information
Thanks for reading
8 Comments
