Skip to main content

Steps to update to Version 5 of the SAP Cloud SDK

Version 5 of the SAP Cloud SDK is here and we highly recommend updating to it as soon as possible. It brings various improvements, it is now Open Source and the Destination API has been unified.

Release Blog Post

For more information also check out our version 5 release blog post

Minimum Java Version

Starting with version 5.0.0 the SAP Cloud SDK requires a Java version of at least 17.

Minimum CAP version

If you are using the Cloud Application Programming model (CAP) to build your application, please note that the SAP Cloud SDK version 5 requires a minimum CAP/CDS version of at least 2.4.0. If you are on an older CAP stack, please follow the CAP migration guide first.

Before You Update​

Before you increase the SAP Cloud SDK version to 5, it is recommended to first update to the latest available version of the SAP Cloud SDK 4 and migrate any usage of deprecated API. Follow the deprecation notes in the Javadocs to find recommended replacements. All deprecated APIs are removed with version 5.

Also, make sure that you are using Java 17 or higher. To setup your build to use Java 17 you can use this guide. As Java EE modules have been removed from Java 11, you might also need to update your application to use the Jakarta EE modules instead. This JEP provides a good overview of the changes: JEP 320: Remove the Java EE and CORBA Modules.

If you are consuming SOAP APIs and are relying on the axis2-wsdl2code-maven-plugin to generate classes, please also additionally include javax.activation:activation artifact to your dependencies to avoid compilation errors.

tip

We recommend to update your application in the following order:

  1. Make sure you use the latest SAP Cloud SDK v4 version available.
  2. Update your application to use Java 17.
  3. Update your application to use the latest SAP Cloud SDK v5 and Spring Boot/Spring version available.

Change Version of Your sdk-bom or sdk-modules-bom​

The first step is to change the version of the SAP Cloud SDK dependency in your pom.xml file. Depending on your project setup you might use one of our BOMs or the individual modules.

To find our BOMs, search for the following entries in your maven dependencyManagement section: com.sap.cloud.sdk:sdk-bom and com.sap.cloud.sdk:sdk-modules-bom. Update them directly to version 5.0.0 or the latest version.

If you are building on Spring or Spring Boot you should also update to the latest version of the respective BOMs, so 6.1.0 (Spring) or 3.1.6 (Spring Boot) as of the time of writing. These BOMs should be listed after any SAP Cloud SDK related BOM, so for Spring Boot your dependencyManagement section should look something like this:

pom.xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.sap.cloud.sdk</groupId>
            <artifactId>sdk-bom</artifactId>
            <version>5.0.0</version> <!-- TODO: replace this with the most recent version -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.1.6</version> <!-- TODO: replace this with the most recent version -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

At the same time you should also replace usages of javax dependencies with the respective jakarta dependency. As we only provide a managed version for jakarta.servlet-api in our BOM, you will need to add the formerly managed version for the jakarta.inject-api dependency manually:

-<dependency>
-    <groupId>javax.inject</groupId>
-    <artifactId>javax.inject</artifactId>
-</dependency>
+<dependency>
+    <groupId>jakarta.inject</groupId>
+    <artifactId>jakarta.inject-api</artifactId>
+    <version>2.0.1</version>
+</dependency>

Also remember to migrate all your dependencies to their respective jakarta versions if applicable.

For example, if you were using com.sap.hcp.cf.logging:cf-java-logging-support-servlet for application logging you must instead switch to using com.sap.hcp.cf.logging:cf-java-logging-support-servlet-jakarta.

-<dependency>
-    <groupId>com.sap.hcp.cf.logging</groupId>
-    <artifactId>cf-java-logging-support-servlet</artifactId>
-</dependency>
+<dependency>
+    <groupId>com.sap.hcp.cf.logging</groupId>
+    <artifactId>cf-java-logging-support-servlet-jakarta</artifactId>
+    <version>latest-lib-version</version>
+</dependency>
For projects that were already upgraded to Java 17 and Spring Boot 3 in SAP Cloud SDK 4

Please remove any workarounds that were needed to make Java 17 and Spring Boot 3 work with SAP Cloud SDK 4:

  • When using the scp-cf module or its replacement sdk-core, please remove the servlet-jakarta module.
  • When using the @ServletComponentScan annotation, please update the namespace back to:
- @ServletComponentScan({"com.sap.cloud.sdk.cloudplatform.servletjakarta", ...
+ @ServletComponentScan({"com.sap.cloud.sdk", ...

Remove or Replace Modified SAP Cloud SDK Dependencies​

The lists below contains all modules that have been renamed or removed from the SAP Cloud SDK. Therefore, you should also rename respectively remove those from your project setup.

Full list of renamed or replaced modules
  • Module com.sap.cloud.sdk.frameworks:resilience4j has been moved to com.sap.cloud.sdk.cloudplatform:resilience4j
  • Module com.sap.cloud.sdk.frameworks:apache-httpclient5 has been moved to com.sap.cloud.sdk.cloudplatform:connectivity-apache-httpclient5
  • Module com.sap.cloud.sdk.cloudplatform:servlet has been removed and functionally replaced by com.sap.cloud.sdk.cloudplatform:servlet-jakarta (replacing usage of javax.servlet with jakarta.servlet)
  • Module com.sap.cloud.sdk.cloudplatform:scp-cf has been deprecated and functionally replaced by com.sap.cloud.sdk:sdk-core
Full list of removed modules
  • Bill of Materials
    • com.sap.cloud.sdk:sdk-sjb-bom Please use the cf-tomee7-bom and the sdk-bom instead.
  • Archetypes (Replaced by single archetype: com.sap.cloud.sdk.archetypes:spring-boot3)
    • com.sap.cloud.sdk.archetypes:scp-cf-tomee
    • com.sap.cloud.sdk.archetypes:scp-neo-javaee7
  • Neo related modules, please migrate to the Cloud Foundry environment.
    • com.sap.cloud.sdk.cloudplatform:auditlog-scp-neo
    • com.sap.cloud.sdk.cloudplatform:cloudplatform-connectivity-scp-neo
    • com.sap.cloud.sdk.cloudplatform:cloudplatform-core-scp-neo
    • com.sap.cloud.sdk.cloudplatform:concurrency-scp-neo
    • com.sap.cloud.sdk.cloudplatform:scp-neo
    • com.sap.cloud.sdk.cloudplatform:security-scp-neo
    • com.sap.cloud.sdk.cloudplatform:tenant-scp-neo
    • com.sap.cloud.sdk.plugins:scp-neo-maven-plugin
  • Generator CLIs
    • com.sap.cloud.sdk.datamodel:odata-generator-cli
      • Call the generator directly as a maven plugin:
      • mvn com.sap.cloud.sdk.datamodel:odata-generator-maven-plugin:5.0.0:generate
    • com.sap.cloud.sdk.datamodel:odata-v4-generator-cli
      • Call the generator directly as a maven plugin:
      • mvn com.sap.cloud.sdk.datamodel:odata-v4-generator-maven-plugin:5.0.0:generate
    • com.sap.cloud.sdk.datamodel:openapi-generator-cli
      • Call the generator directly as a maven plugin:
      • mvn com.sap.cloud.sdk.datamodel:openapi-generator-maven-plugin:5.0.0:generate
  • Pregenerated Clients, generate and use your own OData clients instead.
    • com.sap.cloud.sdk.s4hana:s4hana-all
    • com.sap.cloud.sdk.s4hana:s4hana-api-odata
    • com.sap.cloud.sdk.s4hana:s4hana-api-odata-onpremise
    • com.sap.cloud.sdk.s4hana:s4hana-api-odata-v4
    • com.sap.cloud.sdk.s4hana:s4hana-api-odata-v4-onpremise
  • Services (Dropped without replacement)
    • com.sap.cloud.sdk.services:blockchain-business-services-sdk
    • com.sap.cloud.sdk.services:blockchain-business-services-visibility
    • com.sap.cloud.sdk.services:blockchain-client-fabric
    • com.sap.cloud.sdk.services:blockchain-client-multichain
    • com.sap.cloud.sdk.services:btp-business-rules
    • com.sap.cloud.sdk.services:btp-shared-ledger-client
    • com.sap.cloud.sdk.services:scp-blockchain
    • com.sap.cloud.sdk.services:scp-business-logging-all
    • com.sap.cloud.sdk.services:scp-business-logging-core
    • com.sap.cloud.sdk.services:scp-business-logging-odata
    • com.sap.cloud.sdk.services:scp-business-logging-rest
    • com.sap.cloud.sdk.services:scp-workflow-cf
  • Others
    • com.sap.cloud.sdk.cloudplatform:auditlog (See Audit Log usage section below)
    • com.sap.cloud.sdk.cloudplatform:auditlog-scp-cf (See Audit Log usage section below)
    • com.sap.cloud.sdk.cloudplatform:cloudplatform-connectivity-scp (No replacement necessary)
    • com.sap.cloud.sdk.cloudplatform:cloudplatform-core-scp-cf (No replacement necessary)
    • com.sap.cloud.sdk.cloudplatform:security-scp-cf (Functionally integrated into the com.sap.cloud.sdk.cloudplatform:security module)
    • com.sap.cloud.sdk.cloudplatform:security-servlet (See the ServletFilter section below)
    • com.sap.cloud.sdk.cloudplatform:tenant-scp-cf (Functionally integrated into the com.sap.cloud.sdk.cloudplatform:tenant module)

If you are using our BOMs to provide the module versions, a fast way to do identify those is to run any mvn command. This will now lead to error messages like this:

'dependencies.dependency.version' for com.sap.cloud.sdk.cloudplatform:auditlog-scp-cf:jar is missing

This helps you to identify which modules you need to remove or replace in your project setup.

Steps to migrate Destination usages​

Version 5 of the SAP Cloud SDK comes with a major cleanup of the APIs around the Destination concept. This cleanup comes without a lot of breaking changes so that existing applications require only a minimum of adjustments. To make the process of adjusting existing applications as easy as possible, please follow the below steps:

  1. Remove any invocation of Destination#decorate. This method was only used in conjunction with the DefaultErpHttpDestination, which has been removed in this major version update. The functionality has been moved internally, so that decorating existing Destination instances is no longer needed.

  2. (Optional) Remove any invocations of Destination#asHttp or Destination#asRfc. A big part of the Destination cleanup was to straighten our public APIs that expected specific sub-types of Destination or DestinationProperties (e.g. HttpClientAccessor#getHttpClient(HttpDestinationProperties)). These APIs now all rely on Destination, which makes casting via #asHttp or #asRfc unnecessary.

  3. Replace any of the removed classes related to the Destination API as mentioned in the list of removed APIs.

Updated guidance on DestinationAccessException

An earlier version of the upgrade guide contained an additional instruction to move handling of DestinationAccessException from DestinationAccessor.getDestination() to destination.getHeaders(). This instruction was incorrect and has been removed. In case you have followed this instruction, please revert the change.

Remove or Replace Modified SAP Cloud SDK APIs​

Once the build doesn't complain about missing dependency versions anymore, you can start to fix the compilation errors.

Full list of removed API
APIReplacementComment
DefaultErpHttpDestinationHttpDestination

HttpDestination now automatically adds sap-client and sap-language headers defined on the destination

ErpHttpDestinationDefaultHttpDestination-
ErpHttpDestinationPropertiesDefaultHttpDestination-
ErpHttpDestinationUtils-No replacement necessary
AbstractHttpDestination-No direct replacement.
Most use cases, however, should be able to leverage the DefaultHttpDestination instead.
WrappedDestination-No replacement necessary
AbstractScpDestination-No replacement necessary
AbstractScpDestinationBuilder-No replacement necessary
ScpCfAuthTokenFacadeDefaultAuthTokenFacade-
ScpCfDestination-No replacement necessary
ScpCfDestinationLoaderDestinationService-
ScpCfDestinationOptionsAugmenterDestinationServiceOptionsAugmenter-
ScpCfDestinationServiceResponseProvider-No replacement necessary
ScpCfHttpDestinationDefaultHttpDestination-
ScpCfRfcDestinationDefaultRfcDestination-
ScpCfServiceDestinationLoader

ServiceBindingDestinationLoader

-
WithDestinationName-No replacement
StringConverterJava Standard Library

The Java Standard Library offers the same features, e.g. SimpleDateFormat or DateTimeFormatter, with the pattern yyyy-MM-dd or yyyy-MM-dd HH:mm:ss

StringValidator

Apache Commons Codec

 Use libraries like Apache Commons Codec , which offers a Base64 class.
ClientCredentialsValidatorJava Standard Library For validation client secrets see StringValidator above. To validate the client id, try to match the regular expression [a-zA-Z0-9\-!|]+.
OAuth2ServiceProviderSAP BTP Java Token Client Please directly use the SAP BTP Java Token Client library instead.
AuthTokenBuilderJava JWT implementation For creating an AuthToken from scratch, please manually define the claims and optional audience field. For example: 
String jwt = JWT.create()

  .withClaim("zid", "tenant-id")

  .withClaim("iss", "http://subscriber.domain")

  .withAudience("my-app!t123")

  .sign(Algorithm.none());

AuthToken token = new AuthToken(JWT.decode(jwt));
Alternatively for creating extended unit tests based on token handling, please find the SAP BTP Java Security Test library instead.
AccessToken-Use the results returned by the Token Client library instead
AuditLogger- You can use version 4 of the Audit Log artifact with version 5 of the SAP Cloud SDK. Please refer the Audit Log usage section below for more details. Please approach the SAP Cloud SDK development team if you face issues by creating a GitHub support issue .
This change also affects the Audit Log integration with the S/4HANA Connectivity module. You will have to explicitly use AuditLogger to log events.
ScpCfPrincipalDefaultPrincipal -
ScpCfPrincipalFacadeDefaultPrincipalFacade -
LocalScopePrefixProvider-No replacement.
DefaultLocalScopePrefixProvider-No replacement.
LocalScopePrefixExtractor-No replacement.
Audience

SAP BTP Security Libraries

Use the SAP BTP Security Libraries to retrieve token information from the token stored in the SecurityContext. For example: 

Token token = SecurityContext.getToken(); 

String audience = token.getClaimAsString(TokenClaims.AUDIENCE); 

List<String> scopes = token.getClaimAsStringList(TokenClaims.XSUAA.SCOPES); 

...

See the TokenClaims class for additional claims.

Authorization

SAP BTP Security Libraries

See comment on retrieving token information.
Role

SAP BTP Security Libraries

See comment on retrieving token information.
Scope

SAP BTP Security Libraries

See comment on retrieving token information.
TenantSpecificAuthorization

SAP BTP Security Libraries

See comment on retrieving token information.
UserSpecificAuthorization

SAP BTP Security Libraries

See comment on retrieving token information.
PrincipalAttribute

SAP BTP Security Libraries

See comment on retrieving token information.
CollectionPrincipalAttribute

SAP BTP Security Libraries

See comment on retrieving token information.
SimplePrincipalAttribute

SAP BTP Security Libraries

See comment on retrieving token information.
StringCollectionPrincipalAttribute

SAP BTP Security Libraries

See comment on retrieving token information.
StringPrincipalAttribute

SAP BTP Security Libraries

See comment on retrieving token information.

ScpCfDestinationRetrievalStrategy

.CURRENT_TENANT_THEN_PROVIDER

-Please query subscriber and provider tenants individually instead using ONLY_SUBSCRIBER and ALWAYS_PROVIDER

PrincipalPropagationStrategy

.setDefaultStrategy(...)

PrincipalPropagationModeUse via destination custom property:
DestinationProperty.PRINCIPAL_PROPAGATION_MODE = (TOKEN_FORWARDING|TOKEN_EXCHANGE)Default: TOKEN_FORWARDING, for reduced token exchanges. See more.
ScpCfTenantDefaultTenant -
DwcTenantDefaultTenant -
ScpCfTenantFacadeDefaultTenantFacade -
ThreadContextDecoratorInternal-Neo related classes are not supported anymore.
JndiLookupAccessor-Neo related classes are not supported anymore.
JndiLookupFacade-Neo related classes are not supported anymore.
DefaultJndiLookupFacade-Neo related classes are not supported anymore.
WithRuntimeDependencies-Neo related classes are not supported anymore.
ScpCfSecretStore-No SAP Cloud SDK replacement. A similar functionality can be achieved by using the java.security.KeyStore feature.
ScpCfSecretStoreFacade-No SAP Cloud SDK replacement. A similar functionality can be achieved by using the java.security.KeyStore feature.
SecretStore-No SAP Cloud SDK replacement. A similar functionality can be achieved by using the java.security.KeyStore feature.
SecretStoreAccessor-No SAP Cloud SDK replacement. A similar functionality can be achieved by using the java.security.KeyStore feature.
SecretStoreFacade-No SAP Cloud SDK replacement. A similar functionality can be achieved by using the java.security.KeyStore feature.

CloudPlatform

No SAP Cloud SDK replacement.
Handling bound applications (i.e. VCAP_SERVICES) is done via the Service Binding library .
Handling application information (i.e. VCAP_APPLICATION) can be done manually: 

new Gson().fromJson(System.getenv("VCAP_APPLICATION"), JsonObject.class).asMap();
ScpCfCloudPlatform-No replacement. See note on CloudPlatform (above).
CloudPlatformFacade-No replacement. See note on CloudPlatform (above).
ScpCfCloudPlatformFacade-No replacement. See note on CloudPlatform (above).
CloudPlatformAccessor-No replacement. See note on CloudPlatform (above).
ThreadContextInvocationInterceptor-No replacement.
ThrowableAssertionUtil-No replacement.

Generate and Use Your Own OData Clients​

Generate Your Own OData Clients​

The SAP Cloud SDK no longer provides pre-generated OData Virtual Data Models. We made this decision to reduce the maintenance effort and to allow you to generate your own OData clients with the exact version of the OData service you are using. That way there is no need to wait for the next SAP Cloud SDK release to get the latest changes of an OData service you are consuming.

To generate your own OData VDM, you can use the OData Generator Maven Plugin directly. You can use the following configuration to generate an OData client that is compatible with the OData VDM the SAP Cloud SDK provided in version 4:

<inputDirectory>${project.basedir}/src/main/resources/odata/edmx</inputDirectory>
<outputDirectory>${project.build.directory}/vdm</outputDirectory>
<serviceNameMappingFile>${project.basedir}/src/main/resources/odata/serviceNameMappings.properties</serviceNameMappingFile>
<deleteOutputDirectory>true</deleteOutputDirectory>
<packageName>com.sap.cloud.sdk.s4hana.datamodel.odatav4</packageName>
<compileScope>COMPILE</compileScope>

The file specified under serviceNameMappingFile will be created and populated, if it doesn't exist yet. If you want to create an OData client that is compatible with the OData VDM the SAP Cloud SDK provided in version 4, you can use this serviceNameMappings.properties.

If you want to generate an OData client that is compatible with the On-Premise OData VDM the SAP Cloud SDK provided in version 4, take special care of the packageName and the contents of the serviceNameMappingFile to reflect what you are expecting.

Handle OData Virtual Data Model Instantiation​

Depending on your project setup, you might have relied on the @Inject annotation in your OData VDM services. As the OData generators don't generate the javax.inject.Named annotations anymore, you will need to instantiate your own services instead. For that you can either use your own dependency injection framework, or instantiate the services manually.

The manual approach would look something like this:

- @Inject
- private BusinessPartnerService businessPartnerService;
+ private BusinessPartnerService businessPartnerService = new DefaultBusinessPartnerService();

Remove Discontinued ServletFilter from Your web.xml​

We decided to remove all security related Filter implementations from the SAP Cloud SDK, to have a clearer separation between the SAP Security Libraries and the SAP Cloud SDK.

This means you need to remove all mentions of the following filters from your web.xml (mind the security in the package): com.sap.cloud.sdk.cloudplatform.security.servlet.*Filter

The com.sap.cloud.sdk.cloudplatform.servlet.RequestAccessorFilter is functionally replaced by com.sap.cloud.sdk.cloudplatform.servletjakarta.RequestAccessorFilter found in com.sap.cloud.sdk.cloudplatform:servlet-jakarta.

Audit Log usage​

The Audit Log feature is no longer released with version 5 of the SAP Cloud SDK. If you want to continue using audit logging, you could still use version 4 of the audit logging artifact along with version 5 of the SAP Cloud SDK.

You would have to manually add all the following artifacts(only available internally) to your project:

      <dependency>
         <groupId>com.sap.cloud.sdk.cloudplatform</groupId>
         <artifactId>auditlog-scp-cf</artifactId>
         <version>4.28.0</version> <!-- Pay attention that this the old v4 artifact -->
      </dependency>
      <dependency>
         <groupId>com.sap.xs.auditlog</groupId>
         <artifactId>audit-java-client-api</artifactId>
         <version>latest-available-version-in-artifactory</version>
      </dependency>
      <dependency>
         <groupId>com.sap.xs.auditlog</groupId>
         <artifactId>audit-java-client-impl</artifactId>
         <version>latest-available-version-in-artifactory</version>
      </dependency>
      <dependency>
         <groupId>com.sap.xs.java</groupId>
         <artifactId>xs-env</artifactId>
         <version>latest-available-version-in-artifactory</version>
      </dependency>

You will then be able to log events using the AuditLogger API.