SAP S/4HANA Cloud SDK: Version 2.6.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.6.1 and consume the new version from Maven Central. We have also released version v12 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

Refresh authentication token in asynchronous scenarios

The SAP S/4HANA Cloud SDK automatically identifies and authenticates the current tenant and user in many situations. In the Cloud Foundry environment, this is based on JSON Web Tokens (JWT). This automatic handling is the basis for tenant-aware resilience and caching, destination handling and connectivity, and many more features of the SDK. As a prerequisite, code using the SAP S/4HANA Cloud SDK has to run within a RequestContext, which is usually automatically initiated from an HttpServletRequest.
However, especially in asynchronous execution scenarios, an actual request may not be available. For example, in an event-based architecture, the system consuming an event no longer executes within the original request. Since version 2.2.0, the SAP S/4HANA Cloud SDK provides an easy means to execute code in a request context constructed from a manually supplied JWT with the JwtBasedRequestContextExecutor. This class allows specifying a JWT. It verifies the token and executes code as if the JWT had been provided as part of a RequestContext.

Previously, this class always threw an AuthTokenAccessException when the provided JWT token had expired, requiring you to manually initiate a refresh. Now, the class optionally triggers and handles the necessary refresh flow in a transparent manner, provided you call its method withJwt(String encodedJwt, String refreshToken) with a refresh token.

The following code snippet explains how to use the new option, assuming that the variable encodedJwt holds the JWT token and refreshToken holds a refresh token. Both could have been, for example, retrieved from the payload of an event.

new JwtBasedRequestContextExecutor()

        .withJwt(encodedJwt, refreshToken)

        .execute(() -> {

            // Code using the SAP S/4HANA Cloud SDK

        });

Please note that for this to work between multiple services, the services have to be bound to the same XSUAA instance. In order to retrieve a refresh token for a given JWT, the JWT must contain the scope uaa.user.

The SDK will then automatically refresh the JWT in case it has expired. Note that getting and possibly transferring the refresh token between services is the developer's responsibility.
A new method of the AuthTokenAcccessor facilitates this. You can simply retrieve a refresh token from AuthTokenAccessor.getRefreshToken() and store or transfer it together with the JWT.

Further improvements

We now support multiple bindings to Authorization & Trust Management (XSUAA) service instances. Previously, the SDK assumed that there exists only a single binding to a service instance of the XSUAA service for a given application. Now, the SDK transparently supports the case that an application has multiple bindings to instances of the XSUAA service. To this end, version 2.6.1 also introduces functions that explicitly return a list of credentials for relevant services, in addition to the existing methods that assume a single binding. In particular, these are getXsuaaServiceCredentialsList(), getConnectivityServiceCredentialsList(), getDestinationServiceCredentialsList(), all available from ScpCfCloudPlatform. They are implicitly used wherever the SDK previously assumed that there is just a single instance bound.

We have updated several dependencies, including Spring. If you are using Spring, you likely need to add an explicit dependency to org.skyscreamer:jsonassert along with an exclusion to com.vaadin.external.google:android-json into your integration-tests/pom.xml file in order to avoid runtime conflicts with org.json:json. Details on this issue can be found here. Add the following to the dependencies section of integration-tests/pom.xml:

<dependency>

    <groupId>org.skyscreamer</groupId>

    <artifactId>jsonassert</artifactId>

    <scope>test</scope>

    <exclusions>

        <exclusion>

            <groupId>com.vaadin.external.google</groupId>

            <artifactId>android-json</artifactId>

        </exclusion>

    </exclusions>

</dependency>

The classes TenantAccessor and TenantFacade now offer an additional method tryGetCurrentTenant which returns a Try for the current tenant. This object contains the current tenant (possibly null) or any possibly thrown exception. This allows writing idiomatic code without try-catch-blocks. For more details on this monadic container type, refer to the Vavr user guide.

Version 2.6.1 fixes an issue where SoapQuery did not properly respect the proxy configuration.

Several further improvements are listed in the full release notes.

Continuous Delivery Toolkit: Release Highlights

Flexibility for end-to-end tests

End-to-end tests are an important level of the testing pyramid. Especially as browser-based frontend tests, they give developers the necessary confidence to continuously deploy changes to production. At the same time, they often take a significant amount of time. For these reasons, we introduce additional flexibility when dealing with end-to-end tests during our out-of-the-box continuous delivery pipeline.

With this release v12, we added the possibility to use zero downtime deployment in the end-to-end tests. When this option is switched on, the deployment that is done for end-to-end tests uses the blue-green deployment mechanism (or rolling updates on Neo) that is also applied for deployment to production. This allows still using the application deployed to the end-to-end test space at all times, which is helpful in microservice architectures.

Additionally, we now provide the option to run end-to-end tests only for productive branches. This reduces the run time of the pipeline in pull requests, at the trade-off of only getting the feedback of end-to-end tests after merging to the productive branch (but, of course, before any deployment to production).

Both options are disabled by default. For details on how to use the new features around end-to-end tests, consult the documentation.

Further improvements

We now ensure that only one unique docker network will be used for the docker containers. This fixes issues where in the past the network may have been created multiple times, which led to further errors.

The pipeline now transparently handles different formats of the buildpacks parameter in Cloud Foundry manifest.yml deployment descriptors, both the new multi-valued buildpacks and the old single-valued buildpack.

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.6.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.6.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.6.1.

Of course, you can also generate a new project that uses version 2.6.1 from the start by running the Maven archetypes for Neo or Cloud Foundry with -DarchetypeVersion=2.6.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