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

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

Deep Insert and Navigation Properties

The virtual data model (VDM) for S/4HANA OData services is the easiest and most convenient way to access S/4HANA from your Cloud Platform application. The VDM now supports navigation properties for all OData services. Navigation properties represent associations between entities. For example, they make it possible to navigate from a business partner to the address of the business partner. Entities provided by the VDM expose navigation properties via methods for accessing and modifying the associated entities.

With the VDM, simply use the get[NavigationProperty]OrFetch method to access the list of associated entities (or the single entity in case of a single-valued association). As the name of the method indicates, the VDM will automatically fetch the values from the S/4HANA system in case they have not been fetched yet. In case you do not want to lazily retrieve the associated entities, you can instead use the corresponding method get[NavigationProperty]OrNull, which will return an optional that only contains a value . As an example, take a look at the two methods for the addresses of a business partner for more details:

  • BusinessPartner.getBusinessPartnerAddressOrFetch and
  • BusinessPartner.getBusinessPartnerAddressOrNull.

You can replace the list of associated entities (or the single entity in case of a to-one association) with set[NavigationProperty]. In case you want to add an entity to the existing list of a navigation property, use add[NavigationProperty]. Again, take a look at the addresses of a business partner as an example:

  • BusinessPartner.setBusinessPartnerAddress and
  • BusinessPartner.addBusinessPartnerAddress.

Based on the support for navigation properties, you can use the create operations of VDM services to create an entity together with associated entities, an operation called deep insert in OData. For example, you can create a business partner entity with an associated address and a role association as demonstrated in the following minimal example. Here, we create a new business partner with a new address and a new association to the customer role.

BusinessPartner businessPartner = BusinessPartner.builder() .firstName("John") .lastName("Doe") .businessPartnerCategory("1") .correspondenceLanguage("EN") .build(); businessPartner.addBusinessPartnerAddress( BusinessPartnerAddress.builder().country("DE").build() ); businessPartner.addBusinessPartnerRole( BusinessPartnerRole.builder().businessPartnerRole("FLCU00").build() ); BusinessPartner result = service.createBusinessPartner(businessPartner).execute(); 

For a more detailed explanation of deep insert with the VDM, take a look at our new tutorial blog post Step 20 with S/4HANA Cloud SDK: Create and Deep Insert with the Virtual Data Model for OData.

Modifying Values of Custom Fields

Already since version 1.3.0, the VDM gives read access to custom fields – extensions fields added to OData services via in-app extensibility mechanisms of S/4HANA Cloud. Custom fields allow to adapt the pre-delivered OData services to specific needs.

Now you can also modify the values of custom fields on VDM entities. If you send an entity with modified values of custom fields to S/4HANA as part of update or create operations, the custom field values will be persisted accordingly in S/4HANA.

The corresponding method is called setCustomField and is available on all VDM entities. See the Javadoc for more details.

Further Improvements

The ODataVdmErrorResultHandler used by default in all VDM operations exposes more information about exceptions that occur during calls of the VDM, including the original stack trace. This makes debugging easier and allows you to react appropriately in your client code.

The previously existing methods to examine a single custom field have been renamed to getCustomField, hasCustomField, and getCustomFieldNames in order to clearly indicate that they deal with custom fields. An additional method getCustomFields returns a map of all custom fields of an entity and their values.

New blog posts such as Step 19: Mocking S/4HANA calls or how to develop an S/4HANA extension without an S/4HANA system and Deep Dive 5: Executing BAPIs inside S/4HANA On-Premise from your Cloud Application explain other recent highlights of the SDK in detail.

Continuous Delivery Pipeline: Release Highlights

Performance Tests with Gatling

For continuous delivery, verifying that software changes do not introduce any performance regressions is critical. To this end, our continuous delivery pipeline already offered support for JMeter performance tests.

Now we also support performance tests with Gatling. You can run performance tests based on a Maven project in folder performance-tests. You need to enable Gatling for your pipeline in your configuration as follows.

general: ... steps: ... checkGatling: enabled: True

The pipeline will deploy the application to the targets specified for performance tests. Afterwards, the pipeline will execute mvn test on the Maven project in folder performance-tests in your git repository. Define your performance tests in that project so that they run as part of the test phase. Check the documentation on how to run Gatling as part of Maven projects in general.

End-to-end Tests of Password Protected Applications

For password-protected applications, your end-to-end tests need access to the credentials of a user. The pipeline now provides these credentials based on Jenkins’ credentials mechanism.

Define a credentialsId property as part of the appUrls setting as outlined in the documentation. The pipeline will retrieve the username and password from the corresponding credentials in your Jenkins server and supply both to the end-to-end tests in environment variables e2e_username and e2e_password, respectively.

Further Improvements

The default Java Development Kit (JDK) used by the Docker image is now Java 8 instead of Java 7. You can overwrite the default via the configuration property “steps.executeMaven.dockerImage”, if necessary.

Deployment to Cloud Foundry can now be configured – see the configuration documentation for an example of available parameters.

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

With this, you are already done thanks to the “bill of material” (BOM) approach. Your dependency should look like this: sdk-bom 1.5.0 pom import    

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

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