We have released new versions of the SAP S/4HANA Cloud SDK. In detail, the following components are now available in new versions:

• Java libraries in version 2.15.0
• JavaScript libraries in version 1.1.0

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 JavaScript libraries. 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.

SAPPHIRE NOW 2019 is drawing closer and will start in less than two weeks from now. You can meet us there from May 7 to 9 at the topic station SAP S/4HANA Cloud Integration and Extension.
Already one day earlier, Monday, May 6, the SAP Global Partner Summit 2019 takes place. There, we will have dedicated sessions at the booth Deploy and extend SAP S/4HANA Cloud. For more details on our presence at the summit, refer to this blog post.

Java Libraries: Release Highlights 2.15.0

You can update your dependencies of the SAP S/4HANA Cloud SDK for Java to version 2.15.0 and consume the new version from Maven Central.

Support for batch requests

The OData VDM now supports batch processing of update, create, and delete operations. With this, you can group several OData operations as a single request to a system to improve performance and achieve transactional behavior. For now, only change sets are supported as part of the batch request, no reading operations.

Use the batch method available on each service representation to begin constructing a batch request. The returned fluent helper (for example, BusinessPartnerServiceBatch) allows to begin a new change set, add operations to this change set, and end the change set. After adding the desired change sets, execute the batch request as usual.

BatchResponse batchResponse = new DefaultBusinessPartnerService()
    .batch()
    .beginChangeSet()
        .createBusinessPartner(customer1)
        .createBusinessPartner(customer2)
    .endChangeSet()
    .beginChangeSet()
        .updateBusinessPartnerAddress(addressToUpdate)
        .deleteBusinessPartnerAddress(addressToDelete)
    .endChangeSet()
    .execute();

The returned BatchResponse gives access to the results of individual change sets accessible by their index. As batch requests only have a meaningful return value (beyond success / error) for create operations, created entities returned from the server are accessible via getCreatedEntities.

if( batchResponse.get(0).isSuccess() ) {
    // Process created entities
    List createdBusinessPartners = batchResponse.get(0).get()
        .getCreatedEntities().stream()
        .map(entity -> (BusinessPartner) entity)
        .collect(Collectors.toList());
}

Count number of tuples

When constructing queries with the OData VDM, you can now issue a count request to count the number tuples that match the criteria specified in the query.
Use the count method available on all fluent helpers for queries. Calling execute on the fluent helper for count then returns the number of tuples. You can apply other query modifiers such as filter beforehand. Query options top and skip have no effect on the result.

long doeCount = new DefaultBusinessPartnerService()
    .getAllBusinessPartner()
    .filter(BusinessPartner.LAST_NAME.eq("Doe"))
    .count()
    .execute();

In the background, this executes a query with the $inlinecount query option and does not retrieve any actual tuples, just the count.

Further improvements

Version 2.15.0 support destinations on Cloud Foundry with authentication type OAuth2UserTokenExchange. This authentication type is similar to the OAuth2SAMLBearerAssertion, as the user exchange token flow is conducted with the XSUAA which issues a JWT encompassing the user principal. It targets use cases where apps/reuse services on Cloud Foundry are invoked on behalf of the user, opposed to the usage of technical user via client credentials flow.

With version 2.15.0, the OData VDM allows appending non-standard query parameters to reading OData requests via the method withCustomQueryParameter, which is also available for by-key requests.

The OData VDM Generator has an additional flag failOnWarning (introduced both in the CLI and in the Maven plugin) to force the generator to exit with failure in case a warning occurs. Furthermore, all generated code files are now annotated with a comment in the beginning of each file that references the used generator version.

The Message VDM no longer relies on the message topic (as defined in JMS) to determine the type of message received. Instead, we use the eventType property found in message payloads that follow the cloudevents specification, like SAP S/4HANA Cloud.

Several further improvements are listed in the full release notes.

JavaScript Libraries: Release Highlights 1.1.0

The JavaScript libraries of the SAP S/4HANA Cloud SDK are now available in version 1.1.0.

Function imports

Version 1.1.0 introduces support of function imports for services of SAP S/4HANA Cloud that expose function imports to trigger actions in SAP S/4HANA Cloud.

Each VDM module, where applicable, contains request builders for function imports. Modules export individual function imports as functions, like cancel in the material document service. Exports that group all function imports of one module are also available, for example, in the material document service.

import { cancel } from '@sap/cloud-sdk-vdm-material-document-service';
cancel({materialDocument: '1010212', materialDocumentYear: '2019'})
    .execute({destinationName: 'S4HANA'})
    .then(header => ...)
    .catch(...);

// alternatively, access via grouped function imports
import { functionImports } from '@sap/cloud-sdk-vdm-material-document-service';
functionImports.cancel({materialDocument: '1010212', materialDocumentYear: '2019'})
...

Complex types

Wherever SAP S/4HANA Cloud services use complex types, these are now supported. The value of complex type properties will be contained in entities returned from services. Corresponding fields are part of entities such as TimeSheetEntry. We have added representations for complex type fields (example in timesheet service) to be used for filtering, ordering, and selecting in queries and by-key requests. We export interfaces and builder functions for complex types, for example, in the workforce timesheet service.

import { TimeSheetEntry } from '@sap/cloud-sdk-vdm-workforce-timesheet-service';
var entry = await TimeSheetEntry.requestBuilder()
    .getAll().top(10)
    .select(TimeSheetEntry.TIME_SHEET_DATA_FIELDS)
    // For illustration only, filtering on complex type is not supported by this service
    .filter(TimeSheetEntry.TIME_SHEET_DATA_FIELDS.senderCostCenter.equals('109821'))
    .execute({destinationName: 'S4HANA'});
var hours = entry[0].timeSheetDataFields.recordedHours;

Optimistic concurrency control

The OData VDM now supports optimistic concurrency control for update requests. The OData v2 specification uses ETags for optimistic concurrency control. The VDM transparently retrieves the ETag version identifier during queries and by-key requests and supplies it as If-Match header during update requests. The OData service will only execute the update request if the version identifier is still the same as given in the header.

You can force overwrites (if the OData service supports it) by telling the update request to ignore the version identifier. This will send a header If-Match: *. You can manually set ETags to custom values by using the explicit method setVersionIdentifier (example). In delete requests, explicitly set the version identifier using setVersionIdentifier on the request builder.

Further improvements

Version 1.1.0 makes the error message when no destination could be found for a given name more explicit.

We support trusting all certificates for testing purposes, which effectively ignores all SSL certificates.

Furthermore, we fixed an issue where the EntityBuilder did not handle non-primitive types (e. g. moment, BigNumber) correctly.

As usual, the full release notes contain a list of all improvements in this release.

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.15.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.15.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
    <!-- possibly further managed dependencies ... -->
</dependencyManagement>

If you are using the SAP S/4HANA Cloud SDK in a project of the SAP Cloud Application Programming Model, replace sdk-bom with sdk-modules-bom to only update the version of SDK modules, not further dependencies.
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.15.0.

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

JavaScript libraries

To update the version of the SAP S/4HANA Cloud SDK JavaScript libraries used in an existing project, use the command npm update in the root folder of your module. Note that this will also update other modules, unless you explicitly specify which packages to update. If you want to check beforehand what will change, use npm outdated.