Enabling External Workflows for Documents in SAP Cloud ALM

[michael_skiba]

Summary

Beside the already available approval procedure available for documents, we’re excited to introduce external workflow integration for Documents in SAP Cloud ALM, enabling organizations to seamlessly connect document management with powerful workflow and approval solutions such as SAP Build Process Automation (BPA).

From Document to Approval – Automatically

When working with documents in SAP Cloud ALM, approvals are often a critical step. With external workflow integration enabled, a custom workflow is automatically triggered as soon as a user selects “Start Approval” in the Documents app.

Behind the scenes, SAP Cloud ALM hands over the approval request to SAP Build Process Automation, where approvers receive their tasks directly in BPA My Inbox.

 The model below illustrates the operational flow and overall functionality.

Seamless approval state synchronization

The integration ensures that document approval states in SAP Cloud ALM always reflect the current approval situation:

• Approval Pending→ Document status is set to In Review, the document content and external file cannot be edited
• Approved → Document status is automatically updated to Released
• Rejected → Document remains In Progress, ready for rework

This tight synchronization removes manual updates, reduces errors, and ensures compliance across teams and projects.

Flexible, customizable workflows

The approval process is fully customizable in SAP Build Process Automation. Organizations can design workflows that include:

• One or multiple approvers
• Email notifications
• Parallel or sequential approvals
• Additional logic and conditions based on document type or document tagging

Once designed, the workflow is deployed and connected to SAP Cloud ALM using standard APIs and destinations—no custom coding required.

Configuration

Configuration prerequisites

SAP Build Process Automation subscription and the corresponding service instance (including service key) are available.

For more information, please see: Subscribe to SAP Build Process Automation

Shared environment has been configured and API key has been added to the environment in SAP Build Process Automation.

We recommend to deploy your BPA workflow project in a shared environment instead of the public environment, as public environment will be deprecated. Please see the following note for more information: 3522611 - Build Process Automation Public Environment Deprecation timeline

For more information about shared environments, please see: Environments

For more information about how to add an API key to a shared environment, please check: Add API Keys to an Environment

SAP Cloud ALM has been provisioned and a Cloud ALM API service instance has been created (including service key).

For more information on how to create a Cloud ALM API service instance, please see: Enabling SAP Cloud ALM API

Configuration Overview

1) Create destination from SAP Cloud ALM to SAP Build Process Automation and backwards

Log on to your SAP Business Technology Platform (BTP) subaccount where your SAP Cloud ALM tenant is provisioned. Navigate to Connectivity -> Destinations and create a destination with the following parameter:

Parameter Name	Value
Type	HTTP
URL	https://<url>/workflow/rest/v1/workflow-instances <url> = URL from the section endpoints -> api of the BPA instance service key
Proxy Type	Internet
Authentication	OAuth2ClientCredentials
Client ID	section uaa->clientid of the BPA instance service key
Client Secret	section uaa->clientsecret of the BPA instance service key
Token Service URL Type	dedicated
Token Service URL	https://<tenant>.authentication.<domain>.hana.ondemand.com/oauth/token for <tenant> and <domain>, please refer to the URL from the section uaa->url of the BPA instance service key

Create a second one with the following parameter:

Parameter Name	Value
Type	HTTP
URL	https://<your tenant>/api
Proxy Type	Internet
Authentication	OAuth2ClientCredentials
Client ID	section uaa->clientid of the Cloud ALM API instance service key
Client Secret	section uaa->clientsecret of the Cloud ALM API instance service key
Token Service URL Type	dedicated
Token Service URL	https://<tenant>.authentication.<domain>.hana.ondemand.com/oauth/token for <tenant> and <domain>, please refer to the URL from the section uaa->url of the Cloud ALM API instance service key

Add the following additional properties to the destination:

• sap.applicationdevelopment.actions.enabled = true
• sap.processautomation.enabled = true

You can find more information about using the Destination Editor in the Cockpit in Using the Destinations Editor in the Cockpit.

To use this destination in your project, you must add it to your SAP Business Process Automation tenant. Use the Destinations App in the Control Tower.

For further information about managing destinations, see Manage Destinations.

2) Define workflow in SAP Build Process Automation

The following is an example of an approval workflow with an email notification sent to the approver(s) and initiating user of the workflow:

You can download a default workflow as a sample from the link below and import it into your SAP Build Process Automation tenant.

Sample Document Approval Workflow (link)

By extending this default case, you can use a sample workflow with built-in multi-step approval logic. In this workflow, all reviewers are processed sequentially, and every reviewer must approve for the process to continue. You can find this sample here: Sample Document Approval Workflow - exp. multiple level approval

An example demonstrating how to use script tasks to route approvals to reviewers based on document type or tags is available here: Sample Document Approval Workflow - exp. document tag/type routing 

In the Project Properties (available on the project Overview page) create an environment variable. Assign a name and set the type to Destination.

After completing your workflow edits, release the workflow. To make it usable, switch to the released version and choose Deploy.

You will be asked to select an environment. Use the Public Environment.

For more information about environments, see following link.

In the final step, map the Cloud ALM API destination (from SAP Build Process Automation to Cloud ALM) to the environment variable. Use the Destination created in Step 2.

3) Create workflow subscription in SAP Cloud ALM

Create a webhook in External API Management

Log on to your SAP Cloud ALM tenant and navigate to External API Management.

Go to Webhooks Management and choose Add new webhook.

Enter the following data:

Parameter Name	Value
Name	<any name> (identifier to map to the subscription)
Ext Resource Type	Workflow
Destination Source	BTP Destination
Destination Id	<destinationName> (of the destination from SAP Cloud ALM to BPA tenant)
Destination Type	Other

You can find the <destinationName> in the BTP Cockpit where the destination was created in Step 1.

Create a Mapping

Navigate to Mappings Management and choose Add New Mapping.

Enter the following data:

Parameter Name	Value
Description	<any description> (identifier to map to the subscription)
Version	REST API v1
Source	SAP Cloud ALM
Destination	SAP Build Process Automation
Mapping Type	Payload Based

Download the example mapping HERE and copy it into your mapping rules. Adjust the mapping as required. Ensure that the request context matches the input parameters of your workflow. Otherwise, conflicts may occur.

The following document attributes are available:

Parameter Name	Value
id	uuid of the document
title	title of the document
displayId	human readable id of the document
triggeredBy	id of the user that initiated the workflow (started the approval)
ownerId	id of the owner of the document
responsibleId	id of the responsible of the document (if assigned)
typeName	name of the type of the document
statusName	name of the current status the document is in
prorityName	priority of the document
tags	list of tags assigned to the document
projectId	id of the project the document is related to
projectName	name of the project the document is related to

Add a subscription in External API Management

Go to Subscriptions Management and choose Add new subscription.

 Enter the following data:

Parameter Name	Value
Name	<any name>
Description	<any description>
Type	Built-in
Resource Type	Workflow
Webhook	<name of the webhook you created before>
Mapping	<name of the mapping you created before>

Create a User Variable.     

Enter the following data:

Parameter Name	Value
workflowDefinitionId	<workflowId>
reviewedBy	any (optional recipient of the approval task, which is used in the mapping)

To obtain the <workflowId>, log on to your SAP Build Process Automation tenant,navigate to Control Tower -> Environments, select the environment where the workflow is deployed, then go to Processes and Workflows, select your workflow and copy the ID.

To obtain the <environmentId>, log on to your SAP Build Process Automation tenant, navigate to Control Tower -> Environments, select the environment where the workflow is deployed and copy the ID.

4) Assign the Workflow Subscription to a Project

Navigate to a project where you want to use the Document workflow. Open the Subscriptions tab and assign the created workflow subscription to the Document entity:

You are now able to execute test approvals for Documents in SAP Cloud ALM using SAP Build Process Automation.