- Kyma ✅
- Cloud Foundry ✅
In this part of the tutorial, you will learn about the different helper classes implemented in the business application service. These classes mainly support the automation of the Tenant subscription process. Furthermore, they contain the logic of the in-app user management.
- Deep Dive into Helper Classes
- 1. Overview
- 2. Automator (automator.js)
- 3. Cloud Management Helper (cis-central.js)
- 4. Service Manager Helper (service-manager.js)
- 5. Token Helper (token-utils.js)
- 6. Destination Helper (destination.js)
- 7. Credential Store Helper (credStore.js)
- 8. User Management Helper (user-management.js)
- 9. Alert Notification Helper (alertNotification.js)
- 10. Kyma Utils (kyma-utils.js)
- 11. Cloud Foundry Utils (cf-utils.js)
The table below shows all helper classes used by the Sustainable SaaS business application service:
| Util | Source Code | Description |
|---|---|---|
| Automator | automator.js | Runtime-specific helper classes for automatic creation and deletion of artifacts on Tenant (un-)subscription |
| Cloud-Management-Helper | cis-central.js | Helper class interacting with Cloud Management Service (central plan) |
| Service-Manager-Helper | service-manager.js | Helper class interacting with Service Manager Subaccount (admin plan) |
| Token-Helper | token-utils.js | Helper class retrieving tokens from relevant OAuth2 servers |
| Destination-Helper | destination.js | Helper module interacting with the SAP Destination Service |
| Credential-Store-Helper | credStore.js | Helper module interacting with the SAP Credential Store when using Cloud Foundry |
| User-Management-Helper | user-management.js | Helper class for User and Role management interacting with SAP Identity Authentication and XSUAA |
| Alert-Notification-Helper | alertNotification.js | Helper class for interacting with SAP Alert Notification service |
| Kyma-Utils | kyma-utils.js | Helper module interacting with the SAP Kyma Runtime API (e.g., to create Kyma API Rules) |
| Cloud-Foundry-Utils | cf-utils.js | Helper module interacting with the Cloud Foundry API (e.g., to create Cloud Foundry Routes) |
For effortless Tenant on-offboarding in the SaaS context, it is essential to automate the process of onboarding as much as it can be automated. Therefore, the sample application automates as many steps as possible during the subscription of the SaaS Tenant instance. The Automator module helps to provide a fully automated, self-service (un-) subscription experience.
As a few steps of the automation process are runtime dependent, the respective module is returning different Java Script Classes, which are overwriting and extending a TenantAutomator Base Class. While most automation steps are congruent for the Kyma and Cloud Foundry Runtime and can be handled by the Base Class implementation, the runtime-specific Classes take care of specific configurations like setting up API Rules (in Kyma) or Routes (in Cloud Foundry).
// Shared logic
class TenantAutomator
// Runtime-specific extensions and overwrites
class CloudFoundry extends TenantAutomator
class Kyma extends TenantAutomator
...
// Module returns runtime-specific Class
export default (process.env.VCAP_APPLICATION ? CloudFoundry : Kyma)The Automator is responsible for the following tasks:
-
Creation of destinations in a Consumer Subaccount on subscription with the help of destination.js.
-
Deletion of destinations from Consumer Subaccount on unsubscription with the help of destination.js.
-
Creation of a Cloud Management service instance & binding within the Provider Subaccount cis-central.js
-
Deletion of a Cloud Management service instance & binding from the Provider Subaccount cis-central.js
-
Creation of a service manager service instance & binding within a Consumer Subaccount with the help of cis-central.js.
-
Deletion of a service manager service instance & binding from a Consumer Subaccount with the help of cis-central.js.
-
Registering of a service broker in a Consumer Subaccount on subscription with the help of service-manager.js.
-
Unregistering of a service broker from a Consumer Subaccount on unsubscription with the help of service-manager.js.
Kyma
- Creation of new API Rules for the respective Consumer Subaccount during subscription with the help of kyma-utils.js.
- Deletion of existing API Rules for the respective Subaccount during unsubscription with the help of kyma-utils.js.
Cloud Foundry
- Creation of new Routes for the respective Consumer Subaccount during subscription with the help of cf-utils.js.
- Deletion of existing Routes for the respective Subaccount during unsubscription with the help of cf-utils.js.
When a Tenant subscribes to the Sustainable SaaS app,
-
A new Cloud Management Service instance (central plan) will be created in the Provider Subaccount.
-
A new Service Manager instance will be created in the Consumer Subaccount using the Cloud Management Service instance.
-
The API Service Broker will be registered in the Consumer Subaccount by the Service Manager instance created in step 2.
-
A sample destination called *_S4HANA_CLOUD will be created in the Consumer Subaccount.
-
The Service Manager instance created in step 2 will be deleted from the Consumer Subaccount again.
-
The Cloud Management Service instance created in step 1 will be deleted from the Provider Subaccount again.
Kyma
- A new API Rule will be created for the new Consumer Subaccount.
Cloud Foundry
- A new Cloud Foundry Route will be created for the new Consumer Subaccount (not required when using a custom domain).
When a Tenant unsubscribes from the Sustainable SaaS app,
-
A new Cloud Management Service instance (central plan) will be created in the Provider Subaccount.
-
A new Service Manager instance will be created in the Consumer Subaccount using the Cloud Management Service instance.
-
The API Service Broker will be unregistered from the Consumer Subaccount by the Service Manager instance created in Step 2.
-
The *_S4HANA_CLOUD destination will be deleted from the Consumer Subaccount.
-
The Service Manager instance created in Step 2 will be deleted from the Consumer Subaccount.
-
The Cloud Management Service instance created in step 1 will be deleted again from the Provider Subaccount.
Kyma
- The API Rule of the Consumer Subaccount triggering the Unsubscription will be removed.
Cloud Foundry
- The Cloud Foundry Route of the Consumer Subaccount triggering the Unsubscription will be removed (not required when using a custom domain).
SAP BTP Cloud Management Service enables SAP BTP administrators to handle administrative tasks via APIs.
In the Sustainable SaaS application context, we are using SAP BTP Cloud Management Service to create and delete Service Manager instances in Consumer Subaccounts. To be able to do this, the Cloud Management helper class contains functions to create and to delete a new Cloud Management Service instance (central plan) on runtime within the Provider Subaccount. The usage of the central plan is essential, as this plan allows management operations across subaccounts.
Only a Cloud Management Service instance of plan "central" and grant type clientCredentials can be used to create service instances in other subaccounts (like in this case a Service Manager instance). This special type of Cloud Management Service instance (with grant type clientCredentials) cannot be created upon deployment, but has to be created and deleted during runtime, using a dedicated Service Manager instance of plan subaccount-admin.
Flow
Service Manager (subaccount admin plan) in Provider Subaccount creates Cloud Management Service (central plan) in Provider Subaccount creates Service Manager (subaccount admin plan) in Consumer Subaccount registers API Service Broker (in Consumer Subaccount)
Hint - The default Service Manager instance used by the SAP BTP Service Operator in Kyma (plan service-operator-access) cannot be used to create such an instance!
The Service Manager is a central registry for service brokers and platforms. It tracks service instances creation and allows sharing of services and service instances between different platform instances. The Service Manager allows an application to use services and service instances of multiple platforms.
The Service Manager helper module is used for (un-)registering the custom API Service Broker in the Sustainable SaaS App context by interacting with the Service Manager service instance, created in the Consumer Subaccount by the Cloud Management Service (central plan).
The Token helper module is used for retrieving tokens from OAuth2 servers using the client credentials flow.
The Destination helper is used for retrieving, creating, and deleting destinations in any given subaccount.
The Credential Store helper module is used to interact with the SAP Credential Store service in the provider subaccount and is being used as part of the Cloud Foundry based scenario. In the Kyma scenario, Kubernetes Secrets are used instead.
The User Management helper module is used for handling users and role assignments in both SAP IAS and XSUAA. For this use-case, it is required to allow in-app user management for SaaS Consumers.
Requirements
- A Tenant administrator should be able to create users without accessing the SAP BTP Consumer Subaccount.
- A Tenant administrator should be able to assign role collections to users without accessing the SAP BTP Consumer Subaccount.
- A Tenant administrator should be able to delete users without accessing the SAP BTP Consumer Subaccount.
How does the creation of a user work?
- A User is created in SAP IAS (Only if IAS usage is enabled!).
- An XSUAA shadow user is created in the SAP BTP Consumer Subaccount.
- The chosen role is assigned to the Shadow User for authorization purposes.
How does the deletion of a user work?
- The user is deleted from the Tenant Subaccount.
- The User is deleted from SAP IAS (Only if IAS usage is enabled!).
To be able to provide this functionality, the User-Management-Helper interacts with SAP IAS APIs as well as XSUAA APIs.
The Alert Notification helper helper is used to interact with the SAP BTP Alert Notification Service. In this sample, the provided functions allow you to send a generic notification to recipients of the event.
The Kyma utilities are used during subscription, to create new API Rules in the Kyma Cluster. These API rules expose a dedicated host for each Subscriber like customer.c-a1b2c3.kyma.ondemand.com if a custom value is provided during the subscription process. If the subscription does not require a custom domain, the default host pattern incl. the Consumer subaccount subdomain will be used like customer-379a13f-susaas-router-susaas.c-a1b2c3.kyma.ondemand.com.
Hint - If you are using a custom domain, the result will include your custom domain instead of c-a1b2c3.kyma.ondemand.com.
The Cloud Foundry utilities are used during subscription, to create new Cloud Foundry routes. These routes expose a dedicated host for each Subscriber like like customer-379a13f-susaas-router-susaas.cfapps.eu10.hana.ondemand.com. Using a custom domain or dedicated hostname defined during the subscription process is (as of today) not possible. To fulfill this requirement, the usage of the SAP Custom Domain Service is essential. To learn more, please check the respective expert features.
Hint - If you are using a custom domain, the result will include your custom domain instead of cfapps.eu10.hana.ondemand.com*.