The new version of the SAP S/4HANA Cloud SDK Java libraries is available since today. You can update your dependencies to version 2.2.0 and consume the new version from Maven Central. We have also released version v9 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

Improvements of the Java Virtual Data Model (VDM)

We have improved the Java VDM by allowing to transparently convert custom field values and overriding the path of OData services.

Custom Service Path

The Java VDM represents the OData services of an SAP S/4HANA Cloud system in a fluent and easy-to-use Java API. OData requests are sent to the URL expected by SAP S/4HANA Cloud. In case of on-premise SAP S/4HANA systems, the same OData services may reside at a different, custom service path. With version 2.2.0, we allow to manually specify the service path on an OData service in the VDM to override the default service path in case the OData service can be reached at a different path than the default path in SAP S/4HANA Cloud.

All VDM services provide a new method withServicePath(String) to specify a custom service path that will override the default service path. The returned new service instance will use the provided service path for all OData requests. The method leaves the original service instance unchanged. See, for example, the BusinessPartnerService and the following code snippet:

BusinessPartnerService service = new DefaultBusinessPartnerService()
    .withServicePath("/my/path/to/API_BUSINESS_PARTNER");
service.getAllBusinessPartner().execute();

If you need to know the default service path, all VDM service interfaces provide a new static field named DEFAULT_SERVICE_PATH (example) with the value of the default service path from SAP S/4HANA Cloud that is used if no custom service path has been specified.

Type Converters for Custom Fields

You can add custom fields to standard OData services using the in-app extensibility options of SAP S/4HANA. The Java VDM already in previous versions allowed retrieving and modifying custom fields of VDM entities. These methods always provided and expected the value of the custom field in the Java type that is by default returned from the Olingo library, which for example maps the OData type Edm.DateTime to Calendar. If you instead wanted to use the newer LocalDateTime in Java, you had to manually convert the value before and after supplying it to the Java VDM.

Now, you can use a type converter when defining a custom field in order to convert from and to a specific type instead of the default OData type. Create an instance of an appropriate EntityField subclass to represent the custom field and supply a type converter. Getters and setters using this EntityField representation will automatically use the converter.

See below for an example that uses the LocalDateTimeCalendarConverter to convert Calendar to LocalDateTime. Similar converters exist out-of-the-box for LocalTime and ZonedDateTime.

// Create representation of custom field with type converter
BusinessPartnerField<LocalDateTime> CUSTOM_FIELD = new BusinessPartnerField<>(
    "YY1_CUSTOM_FIELD", new LocalDateTimeCalendarConverter());
// Use representation to access custom field with type conversion
LocalDateTime customFieldValue = businessPartner.getCustomField(CUSTOM_FIELD);
businessPartner.setCustomField(CUSTOM_FIELD, LocalDateTime.now());

Asynchronous Execution with JWT-based Request Context

The SAP S/4HANA Cloud SDK automatically identifies and authenticates the current tenant and user in many situations. This automatic handling is helpful in many regards, because it frees developers from dealing with many low-level activities, and it is also the prerequisite for many helpful features of the SDK such as tenant-aware resilience and caching, destination handling and connectivity, and many more. In the Cloud Foundry environment, this is based on JSON Web Tokens (JWT). As a prerequisite, the code using the SAP S/4HANA Cloud SDK has to run within a RequestContext. Normally, this request context is 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.

The SAP S/4HANA Cloud SDK now provides an easy means to execute code in a request context constructed from a manually supplied JWT with the JwtBasedRequestContextExecutor. The new class allows specifying a JWT and executing code as if the JWT has been provided as part of a RequestContext. Note that the JWT token will be verified to make sure that it is valid, but not automatically refreshed in case it has expired. Dependent code would need to handle expired tokens (indicated by an AuthTokenAccessException with a cause of type com.auth0.jwt.exceptions.TokenExpiredException).

The following code snippet explains how to use the new executor, assuming that the variable encodedJwt holds the JWT token, which has, for example, been retrieved from the payload of an event.

new JwtBasedRequestContextExecutor()
        .withJwt(encodedJwt)
        .execute(() -> {
            // Code using the SAP S/4HANA Cloud SDK
        });

Further Improvements

We have upgraded the dependency to the SAP Cloud Platform SDK for service development from 1.17.1 to 1.18.0.

Version 2.2.0 updates several other dependencies to address known security vulnerabilities in those external libraries, although the vulnerabilities did not affect the SAP S/4HANA Cloud SDK directly.

You can now add parameters to queries that will be sent as HTTP headers if the query is sent via HTTP. The withCustomHttpHeader method of the base Query class provides a fluent API for adding single string-based key-value pairs, and the method withSameCustomHttpHeadersAs copies header parameters from another query. The headers will only be sent if the query is sent via HTTP and ignored otherwise. For example, BAPI queries sent via SOAP to SAP S/4HANA Cloud will include the header parameters, but not queries that use JCo transactions.

We have fixed an issue where audit log messages were tried to be sent without subject or object identifier, resulting in errors at runtime. Now, if no identifier is provided by the consumer, a randomly generated string will be forwarded to the Audit Log API. To log with a custom identifier, use the newly provided constructors of AuditedDataSubject and AuditedDataObject.

Two new deep dives explain the integration of state-of-the-art machine learning services on SAP Cloud Platform using the SAP S/4HANA Cloud SDK and how to build conversational UIs using the SDK and SAP Conversational Ai.

Several further improvements are listed in the full release notes.

Continuous Delivery Toolkit: Release Highlights

Updates and Improvements

We now use the SpotBugs Maven plugin for static code checks instead of FindBugs. FindBugs is not maintained anymore and SpotBugs is its “spiritual successor” and a drop-in replacement.

The cx-server command line tool for managing the server shows a warning when starting cx-server with less then 4 GB of memory. Due to the Docker containers running as part of cx-server, using less then 4 GB of memory will often result in build failures, since containers will shut down when no memory is left. Please consult the respective Docker documentation for Windows or Mac on how to increase the memory assigned to Docker.

We optimized the layers of our Docker images, which leads to smaller images and faster build times.

Maven logs do not show successful downloads anymore, which makes the log file considerably smaller. Failed downloads are still logged.

Steps using the tools for the Neo environment of SAP Cloud Platform will assert that passwords are following the guidelines by the neo tools and print an error otherwise. The neo tools cannot handle passwords that start with an @ character, due to special handling of this character by the command line parsing library used.

We have improved the documentation of the configuration options. The documentation now has a table of contents. For each property, it is documented if the property is mandatory. Also, the documentation contains more detailed examples for Neo and Cloud Foundry deployment configuration.

Fixes

The path of the cx-server script may now contain spaces. In older versions, the current working directory was not quoted correctly, which made the cx-server script fail when it contained spaces.

The proxy server defined in server.cfg will also be configured automatically for the bundled download cache.

runtime and runtimeVersion are now mandatory parameters for Neo deployments. The artifactDeployment stage will fail if the runtime is not configured properly. Before, the stage may not have deployed the application correctly due to a runtime mismatch, but still passed with only a warning.

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.2.0.

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.2.0</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.2.0.

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