What is the SDK
The SAP Cloud SDK supports you end-to-end when developing applications that communicate with SAP solutions and services such as SAP S/4HANA Cloud, SAP SuccessFactors, and many others.
To create such an application we provide a command line interface, that allows you to scaffold or enhance an application with the missing parts to use the SDK.
What is the CLI.
The CLI (command line interface) can initialize a nest-based project or (the more common case) add everything you need to develop for SAP Cloud Platform to an existing project no matter what backend framework you use. If there are any incompatibilities, please let us know in the issues!
To install the CLI globally, run:
As long as the CLI version is less than
1.0.0, run the following to update to the latest version. Please keep in mind, that these updates can have breaking changes as per the semver spec.
To get the CLI's version, run:
To get a list of all commands, run:
Create a new project
To create a new project run the CLI's
init command in the project folder.
It will guide you through the initialization, create the necessary files and add necessary dependencies. If you run it in an empty folder, it will ask if you want to initialize a project using @nest/cli.
The CLI will already install all the necessary dependencies for the project, so this might take a minute. If everything worked correctly, you should see the following output:
Project files and folders
NPM / Project
package.json: Specifies dependencies, metadata and user-defined scripts. The application comes with some predefined scripts and dependencies.
npmconfiguration file. The SAP Cloud SDK consists of some generic libraries, that are available as Open Source Software and service libraries for the whitelisted SAP S/4HANA APIs, referred to as the Virtual Data Model (VDM). In the scaffolding we specify the registry for the
@sapscope, where the VDM libraries are published.
tsconfig.json: Configuration file for
TypeScript. This is not needed in the plain
tslint.json: Configuration file for
Jenkinsfile: Jenkins pipeline definition file for quality assurance. It uses the SAP Cloud SDK's Continuous Delivery Toolkit.
pipeline_config.yml: Pipeline configuration file for the Jenkins pipeline.
manifest.yml: The deployment descriptor file for
Cloud Foundry in SAP Cloud Platform.
src/: Source code for the initial application.
credentials.json: Allows you to maintain destinations for testing purposes.
sap-cloud-sdk-analytics.json: Only if you have agreed to usage analytics during the initialization of your project. You can find more information about anonymous usage analytics in the CLI's repository.
Run the project
To run the application locally, simply run the following command:
This will start a local server in watch mode, so that subsequent changes will automatically trigger a restart of the server.
http://localhost:3000 and you should get a
Hello, World! in response.
Deploy the project on Cloud Foundry
The Cloud Foundry CLI comes in handy when you want to deploy your application to SAP Cloud Platform. You can find installation instructions for all common platforms in the
Cloud Foundry documentation. We recommend to use a package manager for that. If you are using
chocolatey on Windows, please find the instructions here.
If you don't have an SAP Cloud Platform account you need to create one.
In order to deploy our application, we first need to login to Cloud Foundry in SAP Cloud Platform using the
cf CLI. First we need to set an
API endpoint. The exact URL of this API endpoint depends on the region your subaccount is in. Open the SAP Cloud Platform Cockpit and navigate to the subaccount you are planning to deploy your application to. Click on “Overview” on the left and you can see the URL of the API endpoint.
Copy the URL and paste it into the following command in your command line:
Build your app if necessary.
To deploy your app, run:
This command will use your local sources for transpiling, packaging and deployment, but will omit packaging your local
node_modules as those can be system dependent. Dependencies will instead be installed automatically when deploying to
The Cloud Foundry CLI will automatically pick up the
manifest.yml of the project when deploying your application. The file should look like this (where
<YOUR-APPLICATION-NAME> is replaced by the name you specified when initializing the project):
- The specified
pathinstructs Cloud Foundry to upload all the files from the
- The command specified under the
commandattribute tells the
buildpackwhat command to issue to start the application.
When everything works as expected, you should get output that looks something like this:
The application will be running at the
routes URL, you can also make sure that the application works correctly by running the start command, this command can be different than the one shown above.
Should the application not work for whatever reason, you can call the following command to access the logs:
For productive use, your app should be linked to one or more databases and implement user authentication and authorization.
Login the Cloud Cockpit, navigate to your respective subaccount (in case of a trial account it should be called
trial). In the menu bar on the left, there should be a section
Connectivity with an entry called
Destinations. On the page that opens, click
New Destination and fill in the details below.
Name, choose a name that describes your system. For the exemple, we will go with
If you use the Business Partner mock server, enter for
URL the URL that you have saved from the previous step and use
Authentication. If you use an SAP S/4HANA Cloud system, enter the systems URL in the
URL field and choose
BasicAuthentication as authentication type. This will make the fields
Password appear. Enter here the credentials of a technical user for your SAP S/4HANA Cloud system.
Bind destination service
In order to allow the application to use the destination you have just configured, you will need to bind an instance of the destination service and an instance of the
XSUAA service to your application.
To create an instance of the destination service, execute the following command in your terminal:
Cloud Foundry in SAP Cloud Platform to create an instance of the destination service with service plan
lite and make it accessible under the name
my-destination. We can now use the name to bind this service to our application. To do this, open your
manifest.yml and add a section called
services, under which you can then add the name of the just created service.
manifest.yml should look like this:
Secondly, we need an instance of the
XSUAA service. The
XSUAA service is responsible for issuing access tokens that are necessary to talk to other services, like the destination service. For this service, we will need a bit of extra configuration in the form of a configuration file. Create a file called
xs-security.json with the following content:
The value for
xsappname again has to be unique across the whole of
Cloud Foundry in SAP Cloud Platform, so make sure to choose a unique name or prefix.
Now, execute the following command:
And, as before, add the newly created services to the services section of your
manifest.yml should look like this:
Finally, we can replace the parameter of
execute with an object whose key
destinationName refers to the name of the destination we defined earlier. If you chose a different name than
S4_SYSTEM, make sure to use it here accordingly.
The new function now looks like this: