SAP S/4HANA Cloud SDK: Version 2.11.1 is Available

[HenningH]

The new version of the SAP S/4HANA Cloud SDK Java libraries is available since today. You can update your dependencies to version 2.11.1 and consume the new version from Maven Central. We have also released version v16 of our out-of-the-box continuous delivery offering consisting of a ready-made Jenkins server and a complete delivery toolkit.
In this blog post, we will walk you through the highlights of these releases. For a complete overview, visit our release notes for the Java libraries and for the continuous delivery toolkit. The release notes also include the change log of all our releases so far.
At the end of the article, you will find a set of instructions on how to update to the new versions.

Java Libraries: Release Highlights

Update of Java VDM to SAP S/4HANA Cloud 1902

Recently, SAP released SAP S/4HANA Cloud 1902.

With version 2.11.1, the SAP S/4HANA Cloud SDK updates the virtual data model (VDM) for OData services of SAP S/4HANA Cloud 1902 to support all newly released or updated OData services of an SAP S/4HANA Cloud 1902 system. As explained in the blog post about the VDM itself, the VDM greatly simplifies reading and writing data from an SAP S/4HANA system in your Java code.

You can use the SDK to connect to all OData services listed in the SAP API Business Hub for SAP S/4HANA Cloud. As usual, the Java representations of all OData services are available from the package com.sap.cloud.sdk.s4hana.datamodel.odata.services.

Experimental release of Message VDM

Exchanging information about relevant events via asynchronous messages across applications is an important building block of a modern, Cloud-native architecture, because it allows for loose coupling, isolation, and elasticity. Patterns such as publish-subscribe can greatly improve Cloud-native applications. SAP S/4HANA systems emit business events for many occurrences that are interesting and relevant for side-by-side extensions on SAP Cloud Platform, for example, the creation of a new business partner or the change of a sales order.

While the OData VDM greatly simplifies the consumption of OData APIs, a similar ease of consumption was so far missing when handling business events emitted from an SAP S/4HANA system. Version 2.11.1 for the first time includes an experimental new component of the SAP S/4HANA Cloud SDK for Java: the virtual data model (VDM) for messages (message VDM).

With the message VDM, messages that transport business events from SAP S/4HANA Cloud can be represented in Java with similar qualities as known from the OData VDM. The experimental message VDM delivered with version 2.11.1 simplifies the consumption of events in a type-safe manner. It works together with existing services such as SAP Enterprise Messaging and existing frameworks such as Java Message Service (JMS). The usage of the message VDM starts where those generic services and frameworks have done their duty of delivering a generic message to your Java application. The message VDM allows you to discover available event types and their properties. It takes care of parsing the message, provides a Java representation of the message, and gives you a framework to easily implement type-safe event handlers.

The message VDM module messaging-api of the SDK contains Java classes representing each of the business event types that an SAP S/4HANA Cloud system (release 1902) may emit, as well as corresponding listener interfaces that you can implement to handle messages in a type-safe manner. The module messaging-jms provides a message delegator for dispatching messages received via JMS to registered listeners. This JmsMessageDelegator implements the standard JMS listener interface and can thus be plugged into any application using JMS for messaging. The underlying, more generic abstractions are part of the module messaging-core and may be useful for adaptation of the message VDM approach to other Java messaging libraries.

The beta release of the message VDM is meant to gather your feedback. We have published a blog post on using the message VDM with much more explanations and a detailed guide on how to use the new capabilities. Please note that, as an experimental module, breaking changes to the API are expected.

Using the SDK outside of HTTP requests

Version 2.11.1 brings several improvements that make it easier to use the SDK on Cloud Foundry outside of a typical HTTP request, for example, while handling a message, in background jobs, or during the launch of the application. In summary:

• We introduce a way to retrieve a JWT from XSUAA, which is useful when no JWT is available from a request.


• In the same situation, the current tenant now defaults to the provider tenant to ensure that functionality that relies on a tenant being available works as expected.


• Lastly, it got even easier to instantiate a JWT-based request context.

See the following for details about the individual improvements.

If you need a JWT, take a look at the new method getXsuaaServiceToken() of the AuthTokenAccessor class. It allows the caller to receive a JWT from the XSUAA service bound to the application.

TenantAccessor.getCurrentTenant() now has an adjusted behavior that falls back to the provider tenant on Cloud Foundry in case no tenant is available in the current request context as follows: The new behavior calls AuthTokenAccessor.getXsuaaServiceToken() in case AuthTokenAccessor.getCurrentToken() does not return a token.

The JwtBasedRequestContextExecutor now provides a method withXsuaaServiceJwt() that creates a request context using a JWT internally retrieved from the aforementioned AuthTokenAccessor.getXsuaaServiceToken method so that manually passing a JWT is not necessary.

Further improvements

With version 2.11.1, the SDK introduces support for destinations with the authentication type client certificate on Cloud Foundry.

We have fixed an issue (introduced in version 2.9.1) where navigation properties of VDM entities were not serialized when using Gson.

Before 2.11.1, TenantAccessor.tryGetCurrentTenant and UserAccessor.tryGetCurrentUser erroneously returned Success(null) in case no tenant was available, instead of propagating the TenantNotAvailableException. This has been fixed.

Several further improvements are listed in the full release notes.

Continuous Delivery Toolkit: Release Highlights

The pipeline now contains out-of-the-box a new lint stage that for now checks the code of your frontend for SAPUI5 best practices if it finds a component.js file indicating a SAPUI5 app. By default, the pipeline does not fail on lint findings. This can be changed via the pipeline configuration.

We have significantly simplifed the configuration of Checkmarx scans: it is now possible to specify the Checkmarx preset required by the configuration via its name. This name can simply be looked up in the Checkmarx Web UI, in contrast to the ID which was so far the only option and could only be retrieved by using the Checkmarx REST API. See the documentation for usage instructions.

The continuous delivery server now includes the Jenkins Warnings Next Generation Plugin (warnings-ng). The pipeline uses this plugin to consistently present code check results from SpotBugs, pmd, and others in the much improved layout and style of warnings-ng.

With version v16, the cx-server directory is now the single point of truth for the state of your Jenkins server. Please note that the directories for TLS configuration and for backup must be moved under the `cx-server` directory.

The cx-server will not fail to start in case of any misconfiguration of Nexus or Jenkins parameters such as proxy or JVM memory, instead of silently ignoring the errors.

You can find further fixes and improvements in the complete release notes.

How to Update

Java libraries

To update the version of the SAP S/4HANA Cloud SDK Java libraries used in an existing project, proceed as follows:

• Open the pom.xml file in the root folder of your project.


• Locate the dependency management section and therein the sdk-bom dependency.


• Update the version of that dependency to 2.11.1.

With this, you are already done thanks to the "bill of material" (BOM) approach. Your dependency should look like this:

<dependencyManagement>

    <dependencies>

        <dependency>

            <groupId>com.sap.cloud.s4hana</groupId>

            <artifactId>sdk-bom</artifactId>

            <version>2.11.1</version>

            <type>pom</type>

            <scope>import</scope>

        </dependency>

    </dependencies>

    <!-- possibly further managed dependencies ... -->

</dependencyManagement>

You can now recompile your project (be aware of the compatibility notes, though) and leverage the new features of the SAP S/4HANA Cloud SDK in version 2.11.1.

Of course, you can also generate a new project that uses version 2.11.1 from the start by running the Maven archetypes for Neo or Cloud Foundry with -DarchetypeVersion=2.11.1 (or RELEASE).

Continuous Delivery Toolkit

If you are using the pipeline with a fixed version (as recommended since v7), update the continuous delivery toolkit with the following command, that you run on the server hosting the cx-server:

./cx-server update image