How do you currently store the URL and credentials of the services you want to connect to from your applications? For example, if you connect to your ERP digital core server how do you store the URL of your server in a secure and easy to reconfigure way?
We have shared recently several blogs talking about the importance of developing loosely coupled solutions connecting to your ERP digital core, you can find all them in our blog Loosely Coupled Solutions for SMBs Topics.
I suppose then by now you know how to develop loosely coupled solutions and I would like to cover here the usage of the SAP Cloud Platform Destination service from your Node.js applications.
The SAP Cloud Platform Destination service allows you to securely store settings such as credentials, the protocol, the URL of the ERP system, and the proxy type. Destinations are defined on the SAP Cloud Platform subaccount level of your Cloud Foundry environment and you can integrate them in your application on the space level and therefore access the details stored in the destinations from within your application. You can find all details in the Destinations documentation.
In this blog I would like to share with you the implementation of a Node.js sample application using the destination service to retrieve your SMB ERP connectivity details, for both SAP Business One and SAP Business ByDesign. You can get the source code of the cfDestinations application here.
The implementation of the destinations has also be applied to our SMBMkt application described in the blog Digital Transformation for SMBs – the Intelligent Enterprise connecting to SAP Business One and SAP Business ByDesign systems via the Destination service. You can get the full source code implementing destinations on top of the SMBMkt application at this branch.
Steps to deploy the sample destinations application in your account
Please follow the steps proposed in the next sections to deploy the sample destinations application in your SAP Cloud Platform account.
To be able to use the Destination service from our application we need to create an instance for each one of the services we will use:
Authorization & Trust Management
We are using Redis in the application to store session cookies, the redis instance needs then also to be created.
There are 2 different ways to create the service instances:
From the SAP Cloud Platform cockpit
Via the Cloud Foundry Command Line Interface (CLI)
In this document we will create the required service instances it via the CLI, you can see how to perform the same operations via the SAP Cloud Platform cockpit in this blog.
To proceed with next steps, you need to login to your SAP Cloud Platform subaccount via CLI. If you are new on the SAP Cloud Platform world or you haven’t worked yet with the CLI please follow the Getting started with Cloud Foundry great tutorial.
Creation of the destination instance
To access the details stored in the SAP Cloud Platform Destination service we need first to create a destination instance.
Run the following command on your CLI (after connecting, please check previous section for more details):
cf create-service destination lite destination-demo-lite
With this command you will create a service instance for the service “destination”, with the service plan “lite” and the name of your destination service instance will be “destination-demo-lite” (you can of course change the name of the service instance, just remember to change it also in the following steps).
You can check all the services offered as well as the plans and versions available by running the command
Creation of the connectivity instance
SAP Cloud Platform Connectivity provides a standard HTTP proxy for on-premise connectivity to be accessible by any application. Proxy host and port are available in the credentials of the bound connectivity service via the environment variable “VCAP_SERVICES”. More details on how to interpret VCAP_SERVICES can found in the official CF documentation.
To consume the data coming from the on-premise in the application via the HTTP proxy, we need to create an SAP Cloud Platform Connectivity instance and bind it to the application. When a binding is created the application gets connectivity credentials in its environment variables. More details about it here.
To create the connectivity service instance please run the following command on your CLI:
cf create-service connectivity lite connectivity-demo-lite
With this command you will create a service instance for the service “connectivity”, with the service plan “lite” and the name of your connectivity service instance will be “connectivity-demo-lite” (you can of course change the name of the service instance, just remember to change it also in the subsequent steps).
Creation of the Authorization & Trust Management instance (aka. XSUAA)
The central identity management service for the Cloud Foundry environment manages application authorizations and the trust to identity providers.
By calling the application, the user will be redirected to the XSUAA and will be prompt to give his credentials. It will then achieve certain checks like verifying the OAuth client, client’s scopes, user’s scopes (Scopes are permissions to access one or more resources). Assuming everything is fine, the user will be authenticated and the XSUAA will redirect the browser to the application.
In a second step the application will take the client Id and the client secret and will talk directly with the XSUAA to get an access token. Then the application will send both tokens as HTTP header so that it can consume the backend system via the SAP Cloud Platform Connectivity. For more details on this flow please check this detailed blog.
The next step is then to create an instance for the XSUAA.
To create the xsuaa service instance please run the following command on your CLI:
With this command you will create a service instance for the service “xsuaa”, with the service plan “application” and the name of your authorization & Trust Management service instance will be “xsuaa-demo” (you can of course change the name of the service instance, just remember to change it also in the following steps).
reation of the redis instance
The application is storing session cookies and tokens in Redis DB. Run the following command on your CLI:
cf create-service redis v3.0-dev cachedb
With this command you will create a service instance for the service "redis", with the service plan "v3.0-dev" and the name of your destination service instance will be "cachedb" (you can of course change the name of the service instance, just remember to change it also in the following steps).
Note: If you encounter errors while creating your instances due to missing entitlements, please go to the Entitlements menu on your account and assign the missing Entitlements to your account:
In a following step we will bind the application to the different service instances we have just created.
3. Get the sample application
As explained at the beginning of the blog we will use an application sample called cfDestinations. Download/clone the full application source code from this link.
This sample application is simply providing 2 services: GetB1Items and GetByDItems to retrieve Items either from SAP Business One or SAP Business ByDesign.
In the following sections I’ll detail how the destination service is accessed from the application and what are the files that make it work.
4. Bind your application to the service instances
The binding between the service instances we created in previous steps and your application can be done in three different ways:
Define all the services to be bound to your application in the manifest.yml file.
During the deployment of the app, the binding will be done in the SAP Cloud Platform automatically.
If you changed the names of the services instances during the create-instance operation, please change the names accordingly in the manifest.yml file.
Pay attention, every time you redeploy your application with cf push the manifest.yml defined services will be bound again.
The second option that would be most likely the one you will use when deploying applications in a productive environment is to use the CLI to do the binding.
The SAP Cloud Platform cockpit also allows you to do the binding between your application and the service instances and will be equivalent to the CLI operations.
Go to your Space, Services, Service Instances and press the “Bind Instance” icon of the service instance you want to bind. In the Bind Instance form select the application to be bound:
5. Deploy the application into your SAP Cloud Platform space
To deploy the sample application into your SAP Cloud Platform space we use the Cloud Foundry Command Line Interface (CLI) and run the following command:
cf push --random-route
We use the push command to deploy our application to the Cloud Foundry environment.
We use --random-route to get a random route not only based on the name of our application and avoid collisions from different applications running on the SAP Cloud Platform with the same name.
During the deployment all required Node.js modules will be installed and the specified bindings to the service instances will be also done.
6. Test your application
As a result of the cf push command you will get the status of your application as well as the url to your application:
To test your application, you can run a REST API testing tool like for example Postman can call the /ByDItems and /B1Items with the GET command.
Here we can see the /B1Items results:
In a similar way we can retrieve the Byd Items with /ByDItems request:
Source code explanation
Let’s have a look to the code we have implemented to get the destinations service access in our Node.js application.
1. “dest” folder inside “modules”
First, we have added a folder called “dest” inside “modules”.
This folder contains 4 files:
dest-app.json – this json file defines the routes that will used in our application. For each route it is provided:
the destination name pointing to the SAP Cloud Platform Destination service
the entryPath variable defining a specific entry path if required
js – utility script providing basic access to the required services to manage destinations as well as the token for xsuaa service.
js – xsuaa service management.
js – main script managing the destinations by reading the dest-app.json file and taking care of retrieving the destination service details when requested by the ERP modules.
2. Consumption of the destinations from the sample app
We are consuming the destination service mainly from 2 different scripts: byd.js and b1.js both located inside the erp module. Those low-level scripts connect to the ERPs to consume their specific oData services and therefore need to know the path and credentials to connect to the ERP systems.
In our b1 and byd scripts we reference the Destinations script that implements the connection to the Cloud Foundry Destinations service:
SAP Business One (b1.js)
We retrieve from the Destinations service all details saved in the Cloud Foundry for the B1 destination “b1Dest”.
We fill our B1 Server Service Layer URL (SLServer).
We retrieve the UserName, Password and CompanyDB required to login to B1 Service Layer from the B1 Destination (b1Dest):
SAP Business ByDesign (byd.js)
We retrieve from the Destinations service all details saved in the Cloud Foundry for the ByD destination and the ByD route from the dest-app.json: “bydDest”:
We get the ByD destination authorization token from the ByD Destination (bydDest):
We get the ByD server url combining the destination configuration and the route entryPath defined in the dest-app.json:
You can reuse this code in your Node.js Cloud Foundry applications to take advantage of the Destinations service by:
avoiding security issues while storing urls, users and passwords.
easily modifying destinations without having to redeploy your application.
I hope this blog is giving you all the required tricks for you to implement destinations on SAP Cloud Platform.
Special thanks to matthieu.pelatan, markus.richter4 and philipp.stehle for their valuable help on building this blog and sample exercise.