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

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

With version 2.8.0, the SAP S/4HANA Cloud SDK updates the Java virtual data model (VDM) for OData services of SAP S/4HANA Cloud 1811 to support all newly released or updated OData services of an SAP S/4HANA Cloud 1811 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.

As part of the update, there have been a few breaking changes because some OData operations have been delisted on the SAP API Business Hub, because they are no longer or have never been supported by SAP S/4HANA Cloud. Please take a look at the compatibility notes for more details.

Talk to your application with SAP Conversational AI

With SAP Conversational AI (also known as Recast.AI), you can quickly build a chat bot for your application. In a deep dive, we have already explained how to implement web hooks for the chat bot, leveraging the SAP S/4HANA Cloud SDK. This required implementing several boilerplate classes for communicating with the chat bot.

In version 2.8.0, we release an experimental module com.sap.cloud.s4hana.services:recast-ai which simplifies exactly this part of the development of a chat bot with SAP Conversational AI. In detail, this module provides classes that make interacting with the Recast.ai API in general easy. Furthermore, it contains Java classes to represent user requests sent by Recast.ai. Bot responses to be sent by Recast.ai can be created as instances of Java classes.

Please note that this module is experimental and might therefore be subject to breaking changes or discontinuation in the future.

Filter entities by single-valued navigation properties

With version 2.8.0, the Java VDM for accessing OData services allows to filter entities by properties of associated entities where the cardinality of the association is at most one. For example, a business partner has a one-to-one relationship to a customer object, which contains additional properties about the customer relationship of this business partner. Now, you can for example create an OData request for the list of business partners with a filter on the property “customer classification”. See the code snippet below for an example that only retrieves business partners that are classified as A-customers.

new DefaultBusinessPartnerService().getAllBusinessPartner()
    .filter(BusinessPartner.TO_CUSTOMER.filter(Customer.CUSTOMER_CLASSIFICATION.eq("A")))
    .execute();

As you can see in the above code snippet, the Java representation for such properties (such as CustomerOneToOneLink) provides a filter method.

Usage analytics

At the SAP S/4HANA Cloud SDK team, we are always highly interested in your feedback, for which we have a number of feedback channels such as Stack Overflow or answers.sap.com. In addition to this explicit feedback, actual usage data is another important source of information for improving any product. When deciding which features to develop, where to improve, and where to focus our efforts, it helps knowing how users are using our SDK for Java. That is why we now start analyzing the usage of the Java libraries of the SDK by collecting anonymous, non-sensitive telemetry data at compile time. The data collection only happens during the Maven build process and does not affect your running application in any way. We do not collect any data while the application is running nor do we inspect or transmit your source code.

Technically, the data is being collected by the Maven plugin com.sap.cloud.s4hana.plugins:s4sdk-maven-plugin. From version 2.8.0 onwards, this Maven plugin is included by default in projects newly created with our archetypes (see below for opt-out information). We would appreciate if you supported us in our efforts to improve the SDK and also included the plugin into your existing projects as follows:

1. Open the file application/pom.xml in your project.
2. Locate the build > plugins section (usually towards the end of the file).
3. Add the following snippet as an additional plugin within this section, in front of the closing </plugins> (with a plural “s”).

<plugin>
    <groupId>com.sap.cloud.s4hana.plugins</groupId>
    <artifactId>s4sdk-maven-plugin</artifactId>
    <version>2.8.0</version>
    <executions>
        <execution>
            <goals>
                <goal>usage-analytics</goal>
            </goals>
            <configuration>
                <skip>false</skip>
                <generateSalt>true</generateSalt>
                <salt />
            </configuration>
        </execution>
    </executions>
</plugin>

As an additional benefit, this will allow you to quickly generate a diagnosis report with mvn -pl .\application s4sdk:diagnosis-report. You can attach this report to any question or bug report for the SDK.

We want to be as transparent as possible about what is being transmitted and analyzed. As part of the log of your Maven build, you can see exactly what information is being sent. You can always find the up-to-date explanation in this blog post and an overview of collected data in the documentation of the Continuous Delivery Toolkit..

Collecting this data helps us to understand better how we can improve our offering. For example, we will be able to understand which modules are most often used in which versions or which parts of the pipeline usually take longest, allowing us to improve where it is most needed. Of course, the knowledge gained from this data is always combined with qualitative feedback and requirements we learn of through the other channels. We hope for your support for this endeavour, and also offer an opt-out, as described here.

Further improvements

There have been a few breaking changes in the Java VDM that may affect you if you are referencing entity helper classes of the Java VDM such as any selectable, field, or link directly in your code. The reason for these changes is that we expand the set of OData services for which the Java VDM generator can be used. To this end, we have fixed a few issues where name clashes between types or properties defined in the OData metadata and generated helper classes and methods led to compilation failures.
As part of this, the generator now generates some auxiliary classes in their own subpackages. In detail, you may need to adjust your import statements as follows:

• All …Selectable interfaces have been moved into a corresponding subpackage named selectable. For example, the interface BusinessPartnerSelectable can now be found in package com.sap.cloud.sdk.s4hana.datamodel.odata.namespaces.businesspartner.selectable. Adjust your import statements for selectables by inserting .selectable in front of the type name.
• All …Field classes (like BusinessPartnerField) have similarly been moved into a subpackage named field.
• All …Link (like BusinessPartnerLink) classes have similarly been moved into a subpackage named link.

If you are using the Java VDM generator, make sure to also delete the previously generated files via the –delete-output-dir (command line) or the <deleteOutputDirectory>true</deleteOutputDirectory> (Maven Plugin) options.

version 2.8.0 makes it possible to change the behavior for determining the local scope prefix of OAuth scopes when instantiating a user facade on Cloud Foundry. You can provide your own behavior by implementing the LocalScopePrefixProvider interface and supplying an instance to the ScpCfUserFacace. By default, the SDK will use the DefaultLocalScopePrefixProvider, which retrieves and uses the xsappname as before.

We have fixed a bug that had been introduced in version 2.4.1 where the list returned by the getAll* methods of the Java VDM was immutable. Now, the returned list can be modified again.

Several further improvements are listed in the full release notes.

Continuous Delivery Toolkit: Release Highlights

Parallelize end-to-end tests

End-to-end tests are an important part of the testing pyramid that automatically verify the behavior of a few selected end-to-end stories within your application. They typically involve a script that simulates a user clicking through the application. As a consequence, end-to-end tests tend to take longer.

With this release of the continuous delivery pipeline we make it possible to parallelize end-to-end tests. You can split your end-to-end tests into multiple sub-scenarios, for example, using tags, and run those scenarios in parallel. To this end, we provide a new configuration option parameters for use in end-to-end tests:

endToEndTests:
    cfTargets:
    - ...
    appUrls:
    - url: <app url 1>
      parameters: '--tag scenario1'
    - url: <app url 2>
      parameters: '--tag scenario2 --tag scenario3'

Parameters are assigned per appUrls entry. The pipeline will in parallel launch end-to-end tests for each specified entry and append the given parameters value to the npm command used to launch the tests. In the example above, tests annotated with tag scenario1 will be executed on “app url 1”, and scenario2 and scenario3 on “app url 2”.
The best parallelization effect is achieved when those URLs are different, pointing to different deployments of the application, but using multiple deployments is not mandatory. The parameters option is quite powerful and not limited to using tags – you can also leverage it for passing other information to the end-to-end tests that is different per test scenario.

Further improvements

Starting from v13, the pipeline ahead of a productive deployment scans deployment descriptors such as manifest.yml or mta.yaml for usage of security violating variables such as ALLOW_MOCKED_AUTH_HEADER. These options shall never be used in production. If you deliberately want to use these variables in demo scenarios, consult the documentation for an option to continue deployment. The pipeline will still issue a warning.

If you commit several code changes to the productive branch of your application in quick succession, multiple builds will be triggered and may overtake each other in certain conditions. The pipeline now ensures that significant steps of parallel builds are executed in the correct order. In particular, earlier builds will be deployed before later builds.

The whitesource scan stage can now be configured with an additional optional user token credential. This is required if your Whitesource service leverages additional access level control with a user token. Configure this token as a credential in Jenkins and provide the credentials identifier as part of the configuration.

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.8.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.8.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.8.0.

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