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

[HenningH]

The new version of the SAP S/4HANA Cloud SDK Java libraries is available. You can update your dependencies to version 1.6.0 and consume the new version from Maven Central. We have also released version v3 of our out-of-the-box continuous delivery offering consisting of a ready-made Jenkins server and a complete delivery pipeline.
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 pipeline. 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

Type-safe Expand

The virtual data model (VDM) for S/4HANA OData as the easiest and most convenient way to access S/4HANA now supports the expand query option. In OData queries, expand is used to specify which associated entities to retrieve eagerly in addition to the main entities. Associated entities are represented via navigation properties of an OData entity type. Expand thus allows to retrieve the necessary data set in a single query and access it in a type-safe manner.

In the VDM of the SAP S/4HANA Cloud SDK, expand is supported via the select method of fluent helpers. There is no separate expand method, instead you define in one place which fields to retrieve, both from the main entity and from entities of navigation properties - also on several levels.

Take a look at the following sample code excerpt:

new DefaultBusinessPartnerService().getAllBusinessPartner()

    .select(

        BusinessPartner.BUSINESS_PARTNER_NAME, // (1)

        BusinessPartner.TO_BUSINESS_PARTNER_ROLE, // (2)

        BusinessPartner.TO_BUSINESS_PARTNER_ADDRESS.select(BusinessPartnerAddress.COUNTRY) // (3)

    ).execute()

You supply all fields that shall be retrieved as parameters to the select method. In this example, the call will retrieve the business partner name of the business partner itself (1), the associated entities of the navigation property business partner role (2) with all fields (since we didn't specify any specific field), and the country field of the associated entities of the navigation property business partner address (3). Transparently, we thus specified both expand and select options of the query in a consistent manner. The entities returned by the call to the service then already contain the entities of the expanded navigation properties, which can be accessed using the corresponding getters for navigation properties, for example, businessPartner.getBusinessPartnerAddressOrNull().

For more details about the type-safe expand, as well as other recent new features of the VDM, please refer to our new tutorial blog post Step 22: Extensibility, Type-safe Expand, and Dependency Injection with the Virtual Data Model for O....

Destinations on Cloud Foundry

If you have studied our tutorials about integrating with SAP S/4HANA or the deep dive about our Cloud Platform abstractions, you may know that the SAP S/4HANA Cloud SDK provides easy access to destinations on SAP Cloud Platform. Destinations are used to configure the access to downstream systems that your application on SAP Cloud Platform interacts with - for example, SAP S/4HANA systems. The SDK allows a transparent consumption of those destinations and handles the authentication flow for you, so that you can focus on the business logic. This was already available for SAP Cloud Platform Neo.

Now, the SAP S/4HANA Cloud SDK supports consumption of the destinations also on Cloud Foundry. The corresponding SAP Cloud Platform destination service is available on Cloud Foundry in beta. You no longer need to manually specify an environment variable destinations (although you can still use this to override or for local deployments). Instead you can use the destination service (beta) to define destinations such as the default ErpQueryEndpoint. Please refer to the help pages to learn how to use the destination service. You do not need to change anything in your code, as this is handled transparently by the SAP S/4HANA Cloud SDK.

We have updated the corresponding tutorial step with more detailed instructions. In short: you need to create service instances for the destination service and for the Authorization & Trust Management (xsuaa) service and bind them to your application.

Further Improvements

The methods for modifying navigation properties, set[NavigationProperty] and add[NavigationProperty], no longer attempt to fetch the associated entities first. This makes working with these methods easier at design time, since you don't need to catch an ODataException, and quicker at runtime. If necessary, you can explicitly fetch using the get[NavigationProperty]OrFetch methods.

The new version makes it simpler to use builders of VDM entities for navigation properties. Use, for example, BusinessPartner.builder().businessPartnerAddress(address1, address2) to fluently add addresses while constructing an entity.

We have also fixed several issues with calling BAPIs and Remote Function Modules (RFM). Javadoc in this area has also been improved significantly (see packages com.sap.cloud.sdk.s4hana.connectivity.rfc and com.sap.cloud.sdk.result).

There are even more improvements that are not covered by the above - make sure to check the complete release notes.

We have revised our tutorial series with a new example based on the business partner API. Also, we now introduce the Virtual Data Model already in step 4 as the preferred way to integrate with OData services of SAP S/4HANA. Even if you have done at least some steps of the tutorials before, this may be a good opportunity to take a fresh look.

There are also these new blog posts available:

• Step 22: Extensibility, Type-safe Expand, and Dependency Injection with the Virtual Data Model for O...


• Deep Dive 6: Extend your Cloud Foundry Application with Tenant-Aware Persistency

Continuous Delivery Pipeline: Release Highlights

Mail Notifications

It is now possible to configure the pipeline to send a notification via mail in case of an unsuccessful build. By default, the pipeline sends an email to the users who committed a change since the last non-broken build. You can additionally define a set of recipients that should always receive notifications.

Read more about the available configuration options in the corresponding documentation.

Improvements to Nexus Deployments

The deployment of artifacts to a Nexus instance can now be configured to also deploy artifacts with additional classifiers. To this end, you can configure the corresponding step of the pipeline with a list of additional classifiers and the packaging type of the artifacts.

Furthermore, deployment to Nexus now happens only on the productive branch and both the parent POM file and the application module are being deployed.

Some of these changes have been triggered by members of our community via our GitHub channel. Please continue to raise your requirements and issues you have found via that channel. We will consider all issues and pull requests on GitHub.

Further Improvements

Frontend tests can be run on multiple browsers - our docker image already provides Firefox and Chromium out of the box.

You can configure the default Jenkins node on which the pipeline is executed. To do so, set the defaultNode property in the general section of your pipeline_config.yml.

Also, the pipeline will use any available Jenkins agents for execution to support master/slave setups.

The property surefire.forkCount is now configurable in the integrationTests section of pipeline_config.yml to control how many processes are forked during tests to parallelize testing.

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 1.6.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>1.6.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 1.6.0.

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

Continuous Delivery Pipeline

If you are using the pipeline as offered out-of-the-box and did not specify any specific version, you will automatically use the latest version.

To update the Jenkins image as used by the cx-server script, run the following commands on the server hosting the cx-server:

./cx-server stop

./cx-server remove

./cx-server start