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.
Please follow the steps proposed in the next sections to deploy the sample destinations application in your SAP Cloud Platform account.
If you don’t have yet a SAP Cloud Platform account please follow the Getting started with Cloud Foundry great blog.
Please note we are working with the SAP Cloud Platform in a Cloud Foundry environment, and not a Neo environment.
First of all, we need to create the destinations in your SAP Cloud Platform subaccount so we can access them from our application.
To create a destination, go the SAP Cloud Platform cockpit and navigate to your Subaccount. Then go to “Destinations” menu under “Connectivity” and press “New Destination” link.
For more details on how to access the Destinations Editor you can check this documentation.
In the blog From SAP API Business Hub to your SAP Business One system we give some more details on how to create a Destination pointing to your SAP Business One server.
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:
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:
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.
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):
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
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:
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).
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).
The application is storing session cookies and tokens in Redis DB. Run the following command on your CLI:
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.
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.
You can use any JavaScript editor to familiarize yourself with the source code of the sample application. In my case I’m opening the folder containing the source code with Visual Code editor, but any other editor will also do the trick.
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.
The binding between the service instances we created in previous steps and your application can be done in three different ways:
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.
For doing the binding the command is as follows:
And in our specific sample it will be:
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:
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:
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.
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:
Let’s have a look to the code we have implemented to get the destinations service access in our Node.js application.
First, we have added a folder called “dest” inside “modules”.
This folder contains 4 files:
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:
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):
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:
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.
Please share with us any feedback.
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.
If you don’t have yet a SAP Cloud Platform account please follow the Getting started with Cloud Foundry great blog.
Please note we are working with the SAP Cloud Platform in a Cloud Foundry environment, and not a Neo environment.
1. Create your destinations in SCP CF
First of all, we need to create the destinations in your SAP Cloud Platform subaccount so we can access them from our application.
To create a destination, go the SAP Cloud Platform cockpit and navigate to your Subaccount. Then go to “Destinations” menu under “Connectivity” and press “New Destination” link.
For more details on how to access the Destinations Editor you can check this documentation.
Create a destination for SAP Business One:
In the blog From SAP API Business Hub to your SAP Business One system we give some more details on how to create a Destination pointing to your SAP Business One server.
Create a destination for SAP Business ByDesign:
2. Create the required services instances
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:
- Destination
- Connectivity
- 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-liteWith 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
cf marketplace
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-liteWith 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:
cf create-service xsuaa application xsuaa-demo -c '{\"xsappname\": \"connectivity-app-demo\", \"tenant-mode\": \"dedicated\"}'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 cachedbWith 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.
You can use any JavaScript editor to familiarize yourself with the source code of the sample application. In my case I’m opening the folder containing the source code with Visual Code editor, but any other editor will also do the trick.
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.
For doing the binding the command is as follows:
cf bind-service APP_NAME SERVICE_INSTANCEAnd in our specific sample it will be:
cf bind-service cfdestinations18 destination-demo-lite
cf bind-service cfdestinations18 xsuaa-demo
cf bind-service cfdestinations18 connectivity-demo-lite
cf bind-service cfdestinations18 cachedb- 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-routeWe 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.
Please share with us any feedback.
- SAP Managed Tags:
13 Comments
