SAP Cloud ALM, the SAP Application Lifecycle Management platform for cloud-centric customers was launched in May 2020. Since then, additional services and features are added regularly. In the area of APIs which interest us more specifically today, some public interfaces have already been released in the SAP API Business Hub and the list should continue to grow in the near future. In this blog I’d like to illustrate, with a simple example, the integration use case between SAP Cloud ALM and a Third-Party platform.
Let’s assume an SAP ALM implementation project is partly hosted in JIRA. While standard best practices and methodologies come from SAP Cloud ALM (i.e., project’s tasks are initially created there), one of the teams involved in the project maintains its project’s tasks status directly in JIRA. The project manager, however, consolidates all project tasks in SAP Cloud ALM for Implementation. We have then a typical integration scenario where task updates happening on JIRA side must be propagated into SAP Cloud ALM.
As depicted in the diagram below we want to import a subset of CALM tasks to JIRA. This “import” may not concern all tasks of the project but only the CALM tasks assigned to the team working with JIRA; it could happen one time at the creation of the project, or it could be scheduled regularly so that any update on CALM project is reflected on JIRA project.
On the other hand, we need also that any change on a CALM task happening on JIRA side is propagated on CALM side. This update should happen immediately.
To connect SAP Cloud ALM with JIRA, we rely on SAP Open Connectors, a component of SAP Integration Suite which helps to quickly interface various SAP and non-SAP products. SAP Open Connectors comes with a large catalog of pre-built connectors including JIRA.
The following diagram provides an overview of the technical setup. The proposed solution is composed of four main components running in SAP Open Connectors:
- JIRA connector
- SAP Cloud ALM connector
- Formula to import the CALM tasks into JIRA (to be scheduled)
- Formula to propagate JIRA task status updates (triggered by JIRA events)
About SAP Cloud ALM connector
While a JIRA connector is delivered in standard in SAP Open Connectors catalog, there is not such connector for SAP Cloud ALM yet. Thus, we need to build a custom one to access SAP Cloud ALM Task API from our formula.
About Import Formula
The import formula is scheduled regularly in SAP Open Connectors to import new CALM tasks created or propagate the task deletion on JIRA side. The table below summarises the actions of the import formula based on the status of a task on CALM side and on JIRA side.
Since we may not want to import all CALM tasks into JIRA but only the subset of tasks assigned to a specific team, we need to take into consideration the assignation of the task while doing the import. Only CALM tasks in status “Open” (CIPUSOPEN or CIPTKOPEN) and assigned to a specific team will be imported into JIRA. Furthermore, if a CALM task happens to be deleted on CALM or the team assignation of the task changed, the task is deleted on JIRA side.
About Update Formula
Update formula is triggered when the status of a task changes on JIRA side. This happens for example when we drag & drop a task from one column of a JIRA board to another column. Since task status are not necessarily the same on SAP Cloud ALM side and on JIRA side, we use the rules described in the table below to propagate the task status from JIRA to CALM.
To set up the technical solution, we perform the following steps:
- Build a custom connector for SAP Cloud ALM APIs
- Implement Import Formula
- Implement Update Formula
- Create an SAP Cloud ALM project
- Create a JIRA project
- Instantiate a JIRA connector
- Instantiate an SAP Cloud ALM connector
- Instantiate Import Formula
- Instantiate Update Formula
Build a custom connector for SAP Cloud ALM APIs
SAP CALM connector is not yet available in SAP Open Connectors, we need to create a basic custom one for SAP Cloud ALM Tasks API. This API let us access, update and create project tasks in SAP Cloud ALM if we have the proper authorisations.
In the following we present the main steps to create a custom connector for SAP Cloud ALM (APIs projects & tasks) in SAP Open Connectors.
We follow 3 steps: Information, Setup and Resources.
In the Information part, enter the connector’s name (“calm-API”) and the service type (“REST API ») ; Then in Setup, configure the Authentication (“oauth2ClientsCredentials“).
We add a parameter idProject to retrieve all tasks of an SAP Cloud ALM project.
Next, in Resources, add the necessary resources. Here, projects and tasks.
In the resource /tasks, we add the parameter idProject.
Implement Import Formula
The formula can be scheduled regularly to create or delete relevant CALM tasks on JIRA side; It operates in three stages:
- Collect all tasks from CALM and all tasks from JIRA using the connectors.
- Compare the two lists of tasks and compute the list of tasks to create and the list of tasks to delete on JIRA. See also table above to understand which kind of action is performed by the formula depending on CALM task status & corresponding JIRA task status.
- Based on the two lists computed on previous stage, create, and delete the tasks on JIRA using JIRA connector.
Implement Update Formula
Update formula is triggered from a JIRA event (webhook). After filtering for proper JIRA event (“issue_updated”), the formula updates the CALM task status based on JIRA task status. The conversion table described above is used to map the status.
To map JIRA tasks with the proper CALM task id and type in CALM, 2 labels are added to the JIRA task at import time. The first label contains the CALM id of the task which is necessary to call CALM task update interface, and the second label contains the type of the CALM task which is necessary to update the CALM task status, since the status of a CALM task depends on its type.
Create an SAP Cloud ALM project
There is nothing specific in this step, you can setup your SAP Cloud ALM project following the standard procedure. If you use a template, your project will come with a set of best practice tasks, but whether you use a template or not, you can always create additional custom tasks. The tasks will be replicated on the JIRA whatever their type.
Now it is time to identify the tasks relevant for the “JIRA team” and assign them properly in your CALM project.
Create a JIRA project
There is nothing specific in this step, you can create your JIRA project as usual. The JIRA must be accessible from the public cloud by SAP Open Connectors.
Instantiate a JIRA connector
We instantiate one JIRA connector pointing to our JIRA server. The event should be enabled on this connector instance since we want to intercept task updates.
It’s a good idea to restrict the JIRA webhook to only the events related to issues.
Instantiate an SAP Cloud ALM connector
We instantiate the custom connector for SAP Cloud ALM we built previously. We don’t need to receive events from this connector.
The OAuth authentication parameters (client id, client secret and token URL) come from your SAP Cloud ALM key you created on your tenant.
Make sure your key contains at least the following scopes:
The following screenshot is an example of json file you’ll need to pass at SAP Cloud ALM API service instance creation time (no json is needed at key creation time).
Instantiate Import Formula
The import formula needs the following input parameters:
- JIRA connector instance: to read, create and delete tasks
- CALM connector instance: to read tasks
- calmAssigneeId (optional): see after
- emailNotification (optional): to receive an email in case of successful import
calmAssigneeId parameter is used to restrict the set of CALM tasks to import on JIRA. This parameter should contain a CALM team as explained in the overview but since at this time the CALM Tasks API doesn’t return the assigned team in the payload, we cannot consider it as a filter. As a replacement, we use the task assignee instead (which should look like an email). calmAssigneeId is an optional parameter, if it is not set, the formula will import all the CALM tasks to JIRA without any filtering.
The formula is scheduled daily, so we need to wait the next scheduled execution to see the tasks created in JIRA or trigger the task execution manually. from SAP Opens Connectors
Instantiate Update Formula
The update formula needs the following input parameters:
- JIRA connector instance: to receive the events
- CALM connector instance: to update the task status
- emailNotification (optional): not used
All relevant CALM tasks are imported in the JIRA project.
We drag and drop a task in the JIRA project board to change is status.
The task status is immediately propagated in SAP Cloud ALM.
After initial synchronisation with SAP Cloud ALM project, a change to a JIRA task status (for example using drag & drop in the project board), is immediately propagated to SAP Cloud ALM corresponding task.
While SAP Cloud ALM is the recommended integrated application lifecycle platform to support your cloud centric implementation projects and operations, it’s also an open platform connectable to your own custom environment.