With the
latest release of the SAP Cloud SDK, we have introduced a beta version of the Java client library for the SCP Workflow REST API.
Goal of this Blog Post
We are happy to announce that
SAP Cloud SDK for Java 3.19.1 introduces beta support for the SAP Cloud Platform (SCP) Workflow REST API. This blog will guide you through the way to start using it and highlight main use cases where the combination of SAP Cloud SDK and Workflow API brings the most value.
How SCP Workflow and Cloud SDK play together
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.
The SCP Workflow service provides a web editor for visual workflow modeling as well as an
REST API. For example, the REST API allows for interaction with your workflow definitions and task definitions from a loosely-coupled REST client. On its
section within the SAP API Business Hub we can discover all API endpoints along with their payloads and status codes.
Imagine a business scenario with multiple involved parties, complex validation logic, and parallel execution flows. SCP Workflow service solves exactly this problem. By integrating this service into your application via its REST API you get a seamless solution for this problem.
The
SAP Cloud SDK is a development toolkit that supports you end-to-end with the cloud application development for SAP Cloud Platform (SCP). As a developer you greatly benefit from an easy integration of your app with other SAP solutions, like SAP S/4HANA or SAP SuccessFactors. The SDK provides Java libraries, JavaScript libraries as well as predefined project templates and an out-of-the-box continuous delivery toolkit.
Let's see how newly released functionality helps to simplify developing of a Java app using both SAP Cloud SDK for Java and Workflow service via its REST API.
Consume the SCP Workflow REST API
Application Use Case
As described earlier, we have an existing SAP Cloud SDK-based Java app and we want to 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. That requirement corresponds to the API endpoint
/v1/workflow-definitions which you find under the section
Workflow Definitions on the left-hand side.
Configuration Steps
There are some configuration steps on Cloud Foundry necessary to run this scenario. Here is a brief overview:
- Bind app to SCP Workflow service instance
- Maintain HTTP destination
Refer to the
detailed technical documentation on how to achieve the configuration.
Add Maven Dependency
You can refer to the Java client library for the SCP Workflow service with the following Maven dependency:
<dependency>
<groupId>com.sap.cloud.sdk.services</groupId>
<artifactId>scp-workflow-cf</artifactId>
<!-- omit version identifier if SDK BOM is used -->
<!-- use at least version 3.19.1 -->
<version>3.19.1</version>
</dependency>
Invoke the Java Client Library
We know the name of the HTTP destination that we configured in the SCP cockpit. Let's obtain a Java representation of it:
final String destinationName = "workflow-rest-api";
final HttpDestination httpDestination = DestinationAccessor.getDestination(destinationName).asHttp();
Then we go ahead and invoke the Java API class for the workflow definitions. More specifically, we invoke the method to obtain the list of all existing workflow definitions. We pass the HTTP destination as an argument to the constructor of the API class.
final List<WorkflowDefinition> workflowDefinitions = new WorkflowDefinitionsApi(httpDestination).queryDefinitions();
We have now invoked the REST API in a type-safe manner and furthermore gain type-safe access to the resulting objects. For instance, we can read particular details about each workflow definition. We printed it to the log here for demonstration purposes.
workflowDefinitions.forEach(workflowDefinition -> {
log.info(workflowDefinition.getName());
log.info(workflowDefinition.getVersion());
log.info(workflowDefinition.getCreatedAt().toString());
});
Going even further, the library allows us to inspect all jobs related to a particular workflow definitions. Check out the model definition on the API Hub for this model relationship.
final WorkflowDefinition workflowDefinition = workflowDefinitions.get(0);
workflowDefinition.getJobs().forEach(job -> {
log.info(job.getId());
log.info(job.getPurpose().toString());
});
After this brief demo of the client library we'll touch upon its general capabilities and limitations.
Client Library Capabilities
The Java client library for SCP Workflow enables the developer to invoke the REST API in a type-safe and convenient manner. It provides Java abstractions for all REST API endpoints along with the respective model classes. Essentially, the library relieves the developer from all the HTTP-related development work (e.g., interpreting status codes, JSON de-/serialization) and lets them focus on the real business logic.
Moreover, we integrated the library with the SAP Cloud SDK capabilities, such as the tenant-aware destination retrieval.
Client Library Limitations
We have published the client library as beta version. We verified its functional correctness to the best of our knowledge. We do not yet recommend using it in a production environment. Follow our
release notes to see when it reaches release status.
Henceforth, the library supports the SCP Workflow service on Cloud Foundry, while it does not cover the SCP Workflow service on the Neo landscape on SCP.
Related to Cloud Foundry, you might know that environment variable VCAP_SERVICES contains information about your bound service instances. In the current state, it is required to create a destination manually instead of letting the library consume VCAP_SERVICES directly.
Call to Action: Give us feedback
If you had a chance to try the new library out, we look forward to your feedback to help us improve it quickly. You can do it by posting comments to this blog.
