The SAP Cloud Platform (SCP) Workflow service is available on the Cloud Foundry environment since April 2019. It helps you build, run and manage workflows to model processes that span from simple approval steps to complex business scenarios with several involved parties.
Imagine a business scenario involving multiple parties, complex validation logic, and parallel execution flows. SCP Workflow service solves exactly this problem. To benefit from features offered by REST API of the SCP Workflow service you can leverage type-safe client library provided by SAP Cloud SDK and discover it via your IDE or manually integrate it into your application.
Refer to this blog post for an overview of all resources about the SCP Workflow Service.
This library is released for productive usage as of November 19, 2020.
We need to model a business workflow involving multiple parties, complex validation logic, and parallel flows execution together with other business logic in your App hosted on the SAP Cloud Platform.
Use SAP Cloud Platform Workflow service and its REST API. You can do workflows modeling using a convenient visual editor and call SCP Workflow REST API via type-safe client library module provided by SAP Cloud SDK for Java. Additionally, you'll get other benefits off SAP Cloud SDK like destinations and authentication handling, complete type-safety, multi-tenancy, easy resilience, and caching configuration.
Add the latest version of SAP Cloud SDK to your Java application dependencies or generate a new one from archetypes that we provide.
After we have an SAP Cloud SDK-based Java App, we can invoke the SCP Workflow REST API in our business logic. More specifically, we are interested in retrieving a list of all workflow definitions that exist in the connected SCP Workflow service instance which corresponds to the API endpoint
/v1/workflow-definitions. You can find it under the section
Workflow Definitions on the left-hand side of your CF cockpit.
Let's look in detail at all necessary steps of Cloud Foundry configuration to run this scenario.
Refer to the documentation on help.sap.com for the full picture. We'll outline essentials with the assumption that you understand or have all of the following:
- Which Cloud Foundry subaccount and space you want to use
- You have access to the SCP Workflow Service feature
- You possess all necessary authorizations on Cloud Foundry
- You have installed the Cloud Foundry Command Line Interface (CLI) on your machine.
The SCP Workflow REST API is protected and requires authenticating with an OAuth 2.0 access token. Each particular API endpoint requires the client to provide an access token valid for the respective endpoint. The token must be issued for the respective OAuth scope that corresponds to the desired API endpoint.
Let's figure out which OAuth scope is relevant for our application. For that, we have to check SCP Workflow API documentation to find out that the endpoint
/v1/workflow-definitions is assigned to the scope
Open a text editor and create a JSON file with the following content:
Remember where you've saved the file, you'll need it later.
Open the command line and authenticate at your Cloud Foundry organization by invoking
Consider specifying the respective subaccount, organization, and space with
cf target if necessary.
cd to navigate to the directory that contains
JSON configuration file we created before and run the following to create the service instance:
This command creates an instance of the SCP Workflow Service in the CF space that your CLI points to. More specifically, it uses the service plan "standard" and takes the
JSON configuration into account. Note that we named the service instance
my-workflow. If you have chosen a different name, please, remember the name as you'll need it for your deployment descriptor
manifest.yml later on.
Once the service instance creation is finished, you can see the service instance in your CF space under
Service Instances in the left-hand side menu.
Open the file
manifest.yml in your project and mention your service instance under
services as follows:
Now, redeploy your app with
After app deployment has finished, go to your CF space and navigate to
Services\Service Instances. You should see the service instance you created along with the information that is bound to your application.
Click on the service instance name, for instance
my-workflow, in the upcoming screen you should see the headline
Service Instance: my-workflow - Referencing Apps. Make sure that the entry belongs to your app is selected in the table below, given that multiple apps are bound to the same service instance.
JSON content below the table. For your convenience, we recommend copying that
JSON to a text editor. Here is a quick example:
Next look carefully at the
JSON content and collect the values for the following
You'll need these values in the next step.
Go to your CF subaccount, navigate to
Connectivity\Destinations in the left-hand side menu, and create a new HTTP destination with the following properties:
- Name: Workflow-Api
- Type: HTTP
- URL: The value of
- Proxy Type: Internet
- Authentication: OAuth2ClientCredentials
- Client ID: The value of
- Client Secret: The value of
- Token Service URL: The value of
Click save. Restart your app by navigating to
Spaces\<you-space-name>\Applications. Chose your App from the list by clicking on the link with its name and find restart button on the page that loads.
We assume that you have a Java project using the SAP Cloud SDK. If not, we recommend going ahead and creating one from one of the Maven archetypes. You should also have Apache Maven installed and be able to successfully run
mvn clean install from the root of your project.
Make sure that you have the SAP Cloud SDK Bill-of-Material (BOM) in your
dependencyManagement section of your
pom.xml structure like on the example below.
You can refer to the Java client library for the SCP Workflow service with the following Maven dependency:
After adding the dependency to your
pom.xml file run
mvn clean install to let
Maven install it.
The name of the HTTP destination that we configured in the SCP cockpit is
Workflow-API. Let's create a Java representation of this destination.
Now we can make the first call to SCP Workflow API by invoking the method to get the list of all existing workflow definitions. For that, we pass the HTTP destination as an argument to the constructor of the API class.
This is how we call the SCP Workflow REST API in a type-safe manner and benefit from type-safe access to the resulting response objects. For instance, we can read particular details about each workflow definition. We'll log them for demonstration purposes.
Another benefit is that the SCP Workflow API library allows us to inspect all jobs related to a particular workflow definition together with many other properties. You can check the SCP Workflow API's model definition on the SAP API Hub or simply use your IDE to discover available properties via its auto-complete function.
The Java client library for SCP Workflow enables the developer to:
- invoke the REST API in a type-safe and convenient manner
- provides Java abstractions for all REST API endpoints along with the respective model classes
- relieves the developer from all the
HTTP-relateddevelopment work like interpreting
JSON de-/serialization, etc
- it lets the developer focus on the business logic instead of coding low-level API calls
- we keep the library up to date with the latest Workflow API specification which simplifies maintainability of your App's code
- we integrate the SCP Workflow library with other valuable SAP Cloud SDK capabilities, such as the tenant-aware destination retrieval and many more
- We support SCP Workflow API only on SCP Cloud Foundry. The SCP Neo landscape in Not supported!
- In the current state, it is required to create a destination manually instead of letting the library resolve it for you via VCAP_SERVICES binding available on SCP Cloud Foundry.
This video tutorial by the developer advocate team of SAP Cloud Platform will help you get up to speed with SAP Cloud SDK for Java and Workflow API in 60 minutes.