Skip to main content
Rate this page

Getting Started

build License

Introduction

What Is the SAP Cloud 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.

Using the SAP Cloud SDK, you can reduce your effort when developing an application on SAP Business Technology Platform (SAP BTP) by building on best practices delivered by the SAP Cloud SDK. The SAP Cloud SDK can provide JavaScript libraries and project templates.

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 SAP Cloud SDK.

What Is the Command-Line Interface?

The command-line interface (CLI) can initialize a Nest-based project or (the more common case) add everything you need to develop for SAP Business Technology Platform to an existing project no matter what backend framework you use. If there are any incompatibilities, please let us know in the issues!

Installation

To install the CLI globally, run:

$ npm install -g @sap-cloud-sdk/cli

Update

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 per the semver spec.

$ npm install -g @sap-cloud-sdk/cli@latest

Usage

sap-cloud-sdk [COMMAND]

To get the CLI's version, run:

sap-cloud-sdk (-v|--version|version)

To get a list of all commands, run:

$ sap-cloud-sdk --help

Create a New Project

To create a new project run the CLI's init command in the project folder.

$ sap-cloud-sdk init

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:

+---------------------------------------------------------------+
| βœ… Init finished successfully. |
| |
| πŸš€ Next steps: |
| - Run the application locally (`npm run start:dev`) |
| - Deploy your application (`npm run deploy`) |
| |
| πŸ”¨ Consider setting up Jenkins to continuously build your app |
| Use `sap-cloud-sdk add-cx-server` to create the setup script |
+---------------------------------------------------------------+

Project Files and Folders

The project contains the following files and folders, among others, to get you started with the SAP Cloud SDK for JavaScript:

npm / Project

  • package.json: Specifies dependencies, metadata, and user-defined scripts. The application comes with some predefined scripts and dependencies.
  • .npmrc: The npm configuration file. The SAP Cloud SDK consists of some generic libraries, that are available as Open Source Software and service libraries for allowlisted SAP S/4HANA APIs, referred to as the Virtual Data Model (VDM). In the scaffolding, we specify the registry for the @sap scope, where the VDM libraries are published.

TypeScript

  • tsconfig.json: Configuration file for TypeScript. This is not needed in the plain JavaScript version.
  • tslint.json: Configuration file for tslint.

Continuous Delivery

Cloud Foundry

  • manifest.yml: The deployment descriptor file for SAP BTP, Cloud Foundry environment.

Local Development

  • src/: Source code for the initial application.

SAP Cloud SDK Specific

  • systems.json+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, execute the following command:

npm run start:dev

This will start a local server in watch mode so that subsequent changes will automatically trigger a restart of the server. Go to http://localhost:3000 and you should get a Hello, World! in response.

Deploy the Project on SAP BTP Cloud Foundry

Prerequisites

The Cloud Foundry CLI comes in handy when you want to deploy your application to the SAP Business Technology Platform. You can find installation instructions for all common platforms in the Cloud Foundry documentation. We recommend using a package manager for that. If you are using chocolatey on Windows, please find the instructions here.

Login

note

If you don't have an SAP Business Technology Platform account you need to create one.

To deploy our application, we first need to log in to Cloud Foundry in the SAP BTP 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 BTP 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:

cf api https://api.cf.<region>.hana.ondemand.com
cf login

Before Deploying

Build your app if necessary.

Deployment

To deploy your app, run:

npm run deploy

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 Cloud Foundry.

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):

applications:
- name: <YOUR-APPLICATION-NAME>
path: deployment/
buildpacks:
- nodejs_buildpack
memory: 256M
command: npm run start:prod
random-route: true
  • The specified path instructs Cloud Foundry to upload all the files from the deployment/ folder.
  • The command specified under the command attribute tells the buildpack what command to issue to start the application.

When everything works as expected, you should get output that looks something like this:

Waiting for app to start...

name: <YOUR-APPLICATION-NAME>
requested state: started
routes: <YOUR-APPLICATION-NAME>.cfapps.eu10.hana.ondemand.com
last uploaded: Thu 21 Mar 14:05:32 CET 2019
stack: cflinuxfs3
buildpacks: nodejs

type: web
instances: 1/1
memory usage: 256M
start command: node index.js
state since cpu memory disk details
#0 running 2019-03-21T13:05:47Z 0.0% 16M of 256M 126.8M of 1G

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:

cf logs <YOUR-APPLICATION-NAME> --recent

Additional Features

For productive use, your app should be linked to one or more databases and implement user authentication and authorization.

Configure Destination

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. Click Destinations. On the page that opens, click New Destination and fill in the details below.

For Name, choose a name that describes your system. For example, we will go with S4_SYSTEM.

If you use the Business Partner mock server, enter for URL the URL that you have saved from the previous step and use NoAuthentication for Authentication. If you use an SAP S/4HANA Cloud system, enter the systems URL in the URL field and choose BasicAuthentication as the authentication type. This will make the fields User and Password appear. Enter here the credentials of a technical user for your SAP S/4HANA Cloud system.

Bind Destination Service

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:

cf create-service destination lite my-destination

This tells Cloud Foundry to create an instance of the destination service with service plan lite and make it accessible under the name my-destination on the SAP BTP. 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.

The resulting manifest.yml should look like this:

applications:
- name: <YOUR-APPLICATION-NAME>
path: deployment/
buildpacks:
- nodejs_buildpack
memory: 256M
command: node index.js
random-route: true
services:
- my-destination

XSUAA Service

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:

{
"xsappname": "<YOUR-APPLICATION-NAME>",
"tenant-mode": "shared"
}

The value for xsappname again has to be unique across the whole of SAP BTP, so make sure to choose a unique name or prefix.

Now, execute the following command:

cf create-service xsuaa application my-xsuaa -c xs-security.json

And, as before, add the newly created services to the services section of your manifest.yml.

The final manifest.yml should look like this:

applications:
- name: <YOUR-APPLICATION-NAME>
path: deployment/
buildpacks:
- nodejs_buildpack
memory: 256M
command: node index.js
random-route: true
services:
- my-destination
- my-xsuaa

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:

.execute({
destinationName: 'Server'
});
Rate this page