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.comcf 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:   startedroutes:            <YOUR-APPLICATION-NAME>.cfapps.eu10.hana.ondemand.comlast uploaded:     Thu 21 Mar 14:05:32 CET 2019stack:             cflinuxfs3buildpacks:        nodejs
type:            webinstances:       1/1memory usage:    256Mstart 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