How to Upgrade to Version 4 of the SAP Cloud SDK for JavaScript

This document will guide you through the steps necessary to upgrade to version 4 of the SAP Cloud SDK. Depending on your project, some steps might not be applicable. The To-Do list is:

• Update Your Project Dependencies
• Update to Node 22 or Newer
• Set useCache explicitly to false to turn off destination caching
• Set iasToXsuaaTokenExchange to true to enable IAS to XSUAA token exchange
• Remove Deprecated Content

Update Your Project Dependencies

Search for occurrences of @sap-cloud-sdk/[some module] in your package.json files. Replace the version numbers with ^4. run npm install or similar to install the dependencies and update the lock file.

Running your tests or deploying your application might fail at this point if you need to adapt to any breaking changes. We recommend updating your applications in one commit or pull request and making sure everything still works using your existing test suite.

Update to Node 22 or Newer

All SAP Cloud SDK for JavaScript libraries now support node 22 (LTS) as the minimum node version. If you are using a node version older than 22, update your runtime environment to a newer version. On Cloud Foundry you can do this by setting the node engine in your package.json.

Set useCache explicitly to false to turn off destination caching

Destination caching while retrieving destinations via the destination service is now enabled by default.

This change affects the default behaviour of getDestination() method, getAllDestinationsFromDestinationService() method, generated client's execute() method and generic HTTP requests execution using executeHttpRequest().

To disable caching set useCache: false in the options, for example in execute() method:

.execute({ destinationName: 'DESTINATION', jwt: 'JWT', useCache: false })

Set iasToXsuaaTokenExchange to true to enable IAS to XSUAA token exchange

Token exchange from IAS to XSUAA is now disabled by default. Set iasToXsuaaTokenExchange to true explicitly if token exchange is expected.

This change affects the default behaviour of following functions

• getDestination()
• getAllDestinationsFromDestinationService()
• getDestinationFromDestinationService()
• useOrFetchDestination()
• toDestinationNameUrl()
• buildHttpRequest()
• executeHttpRequest()
• executeHttpRequestWithOrigin()

and following methods of request builder

• execute()
• executeRaw()
• url()

Remove Deprecated Content

• @sap-cloud-sdk/connectivity
  • The getAgentConfig() function is now asynchronous, the getAgentConfigAsync() function has been removed.
  • The destinationForServiceBinding() function has been removed, use getDestinationFromServiceBinding() instead.
  • The PartialDestinationFetchOptions type has been removed, use either ServiceBindingTransformOptions or getDestinationFromServiceBinding() function.
  • The serviceToken() function no longer takes xsuaaCredentials as part of the options parameter.
  • The parseDestination() function is no longer a public API.
  • The DestinationForServiceBindingOptions interface has been renamed to DestinationFromServiceBindingOptions.
• @sap-cloud-sdk/odata-common
  • The FunctionImportParameters type has been removed, use OperationParameters instead.
  • The ODataFunctionImportRequestConfig constant has been removed, use ODataFunctionRequestConfig instead.
  • The FunctionImportParameter constant has been removed, use OperationParameter instead.
  • The ActionFunctionImportRequestBuilderBase constant has been removed, use OperationRequestBuilderBase instead.
• @sap-cloud-sdk/odata-v2
  • The ODataFunctionImportRequestConfig constant has been removed, use ODataFunctionRequestConfig instead.
  • The FunctionImportRequestBuilder constant has been removed, use OperationRequestBuilder instead.
• @sap-cloud-sdk/odata-v4
  • The ODataFunctionImportRequestConfig constant has been removed, use ODataFunctionRequestConfig instead.
  • The ActionImportParameter class has been removed, use OperationParameter instead.
  • The ActionImportParameters type has been removed, use OperationParameters instead.
  • The FunctionImportRequestBuilder class has been removed, use OperationRequestBuilder instead.
  • The BoundFunctionImportRequestBuilder class has been removed, use OperationRequestBuilder instead.
  • The BoundActionImportRequestBuilder class has been removed, use OperationRequestBuilder instead.
  • The ODataActionImportRequestConfig constant has been removed, use ODataActionRequestConfig instead.
  • The ODataBoundActionImportRequestConfig class has been removed, use ODataBoundActionRequestConfig instead.
  • The OdataBoundFunctionImportRequestConfig constant has been removed, use ODataBoundFunctionRequestConfig instead.
  • The ActionImportRequestBuilder class has been removed, use OperationRequestBuilder instead.
• @sap-cloud-sdk/resilience
  • The circuitBreakerHttp constant has been removed, use circuitBreaker instead.
• @sap-cloud-sdk/util
  • The assoc constant has been removed, there is no replacement.
• @sap-cloud-sdk/mail-client package has been removed in v4.
  • As an alternative, implement your own mail client by checking the v3 implementation and the SAP BTP documentation for using the TCP protocol for cloud applications.