Attila, S/4HANA, BTP Fullstack Developer (EN, DE, HU)
Hybrid Testing in CAP using environment variables
Introduction
Hybrid testing in CAP contect means You want to execute your application code inside Your development environment like BAS or VSCode but using and connected to BTP Cloud Foundry resources. This is a very common activity as CAP developer. You develop a feature making a code change what You want to test before deploying it to the corresponding BTP subaccount or pushing to the git repository. This is useful at the stage the MultiTarget application is deployed to CF already including xsuaa service responsible authentication to CF.
This approach can be used to connect to a quality subaccounts as well for troubleshooting, when only specific dataset makes possible to reproduce an issue. Just ensure the same version is checked out in your workspace which is deployed to quality
This documentation is for plain CAP HANA Fiori apps. Hybrid testing of S/4HANA side-by-side apps is described in the new SAP Help:
https://help.sap.com/docs/SUPPORT_CONTENT/fioritech/5765507966.html?locale=en-US&version=LATEST
Classic environment variables vs. cds bind
The official documentation now explains hybrid testing using the cds bind command which places service credentials into the .cdsrc-private.json file.
The old way of using classic environment variables still work however. For fetching service information and credentials into environment variable files like default-env.json You can use this plugin for the Cloud Foundry CLI. The tool is not available anymore, so You need to manually copy the VCAP services part from your Application and place it into a default-env.json file. You add the file to the project root folder next to the package.json, or into the approuter folder.
Note the VCAP_APPLICATION part is not needed !
We do not suggest to combine cds bind with environment variables for the same purpose for clarity, and to avoid conflicts and unexpected behaviour.
In further we’ll talk about:
- Extending
xs-security.jsonto enable hybrid testing from BAS and VSCode - Adding simple and stupid unmanaged approuter for testing applications within the
appfolder - adding credentials with basic authentication for remote services in
package.json, alternatively in default-env.json: https://cap.cloud.sap/docs/node.js/cds-connect#cds-requires-srv-credentials-1 - a valid example
Extending xs-security.json
By default login is restricted to BTP, but You can enable to authenticate using BAS and VSCode. Add the following snippet at the end of the xs-security.json file controlling the behaviour of the xsuaa service on BTP. This requires either to (re)deploy the application or manual update of the xsuaa service using the CF command line utility, so that the service running on BTP allows login from your development environment.
{
...
"oauth2-configuration": {
"redirect-uris": [
"https://*.applicationstudio.cloud.sap/**",
"http://localhost:5000/login/callback"
]
}
}Cloud foundry command line utility command to be executed in the folder where the xs-security.json resides.
cf update-service <xsuaa_service_name> -p <application_name> -c xs-security.jsonNow you can execute cds watch in the project root folder, so that the CAP CDS test page is available at http://localhost:4004 in VSCode or at a custom URL in BAS (a notification window offers You).
Adding an approuter
Remember we purged the VCAP_APPLICATION from the default-env.json file, to run the application inside the development environment instead of BTP, but still consuming BTP resources/services.
So far so good, but this means the app running in BAS/VSCode or simply using a terminal :) can access BTP services, but it does not mean that You’re authenticated/routed to those services.
To overcome this limitation, we need an application router instance defined and configured by ourself for testing purpose. The application router is a node module delivered by SAP, designed for SAP Cloud Foundry environment, taking care of user authentication via xsuaa services and routing of requests to the corresponding BTP resources. It is a reverse proxy. With the help of approuter we automatically authenticate to BTP instead of authenticating manually along the authentication flow. Fiori Tools users could use alternatively Fiori Tools Proxy, but this is not part of this article.
We need to add an approuter folder, please create it under the root. Copy the default-env.json from the project root into the approuter folder. Add both to the ignore list into the mta.yaml, thus they never gets packed into the mtar file which is deployed to Cloud Foundry.
_schema-version: "3.1"
ID: MyApp
version: 0.0.1
modules:
- name: MyApp-srv
type: nodejs
path: .
requires:
- name: MyApp-db
- name: uaa_MyApp
parameters:
service-key:
name: uaa_MyApp-key
- name: jobs
- name: MyApp-destination-service
- name: connectivity
provides:
- name: srv-api
properties:
srv-url: ${default-url}
parameters:
buildpack: nodejs_buildpack
disk-quota: 2048M
memory: 1024M
build-parameters:
builder: npm-ci
ignore:
- default-env.json
- /approuterLet’s add the approuter module itself, so create first a package.json file with this simple content within the approuter folder:
{
"dependencies": {
"@sap/approuter": "^14.3.0"
},
"scripts": {
"start": "node node_modules/@sap/approuter/approuter.js"
}
}
Then issue command in the same folder in the terminal so that the module gets installed.
npm iTo tell the approuter what to do, we need a configuration file xs-app.json.
{
"authenticationMethod": "route",
"routes": [
{
"source": "/(.*)$",
"target": "$1",
"destination": "custom_router_dest",
"csrfProtection": false,
"authenticationType": "xsuaa"
}
]
}The variable part in this configuration file is the destination name custom_router_dest, which comes from your mta.yaml configuration file. This is actually your applications endpoint root where the incoming requests have to be routed. You can find it under resources/MyApp-destination-service in this example. This is to present the approach with a sample, Your app structure might look different.
resources:
- name: MyApp-db
type: com.sap.xs.hdi-container
parameters:
service: hana
service-plan: hdi-shared
properties:
hdi-service-name: ${service-name}
- name: cross-container-service-1
type: org.cloudfoundry.existing-service
parameters:
service-name: sdi_service
properties:
the-service-name: ${service-name}
- name: MyApp-destination-service
type: org.cloudfoundry.managed-service
parameters:
config:
HTML5Runtime_enabled: true
init_data:
instance:
destinations:
- Authentication: NoAuthentication
HTML5.DynamicDestination: true
HTML5.ForwardAuthToken: true
HTML5.Timeout: 60000
Name: custom_router_dest
ProxyType: Internet
Type: HTTP
URL: ~{srv-api/srv-url}
- Authentication: NoAuthentication
Name: ui5
ProxyType: Internet
Type: HTTP
URL: https://ui5.sap.com
existing_destinations_policy: update
version: 1.0.0
service: destination
service-name: MyApp-destination-service
service-plan: lite
requires:
- name: srv-apiNow you can execute npm start in the approuter root folder, so that the CAP CDS test page is available at http://localhost:5000 in VSCode or at a custom URL in BAS (a notification window offers You). The authentication and routing now works. Look for posts and SAP Help to understand more about the approuter and the corresponding software architecture.
Tips
In case the You close the CDS server test page, there is a way to reopen it despite the notification is gone in the bottom left corner. To do this issue the Ports Preview command and select port 5000 to reopen it.
😉
