Skip to Content
Technical Articles
Author's profile photo Brian McDonnell

Defining Custom Subscription Parameters in Multitenant SAP BTP CF Applications

Customizing Subscription Parameters

For those that operate multitenant applications in the SAP BTP CF environment, the subscription process should be familiar. You have your application deployed in a CF-enabled provider subaccount and then you have many non-CF-enabled consumer subaccounts within the same region. These consumer subaccounts can then subscribe to the application through a familiar service creation interface. After triggering the service creation, the provider account receives a request for onboarding and handles all necessary onboarding steps thereby completing the consumer subscription. For a more detailed explanation of this process, I recommend the standard documentation here: Developing Multitenant Applications in the Cloud Foundry Environment

The contents of this post detail methods to customize a particular step in this subscription flow: adding custom subscription parameters.


The subscription process often involves onboarding steps which create particular services needed by a consumer subaccount. For applications backed by a HANA Database, this most often means a dedicated HDI container for the consumer. A key configuration parameter required for HDI container creation is the backing Database ID. If your provider account has a single HANA Database, you could perhaps read this ID from the environment and be on your way. But what if have you multiple databases for security or scaling reasons? Is there some mechanism to set the ID dynamically during subscription?

On first glance, there don’t appear to be any points to enter information dynamically during subscription:


Default subscription window

But if we inspect other SAP BTP services, we see that there is often a second step to the service creation process where we can define parameters.


Redis service creation

Our goal is to allow for the same sort of custom subscription parameter entry during onboarding.


The first place we need to look is at our SAAS Registry Configuration. Unfortunately, the standard documentation doesn’t allude to anything that fits our needs. If we look hard enough though, we can find a our exact scenario described here Use multiple SAP HANA Cloud instances. This neatly outlines how to define the necessary configuration within our MTA file directly:

    xsappname: 'my-app' 
                $schema: ''
                additionalProperties: false
                _show_form_view: true
                type: 'object'
                    type: 'string'
                    title: 'SAP HANA Cloud Database ID'
                    description: 'Enter SAP HANA Cloud Database ID'

But what if we want to define this information via json for a direct update via cf update-service? This is how it’d look in JSON:

  "appId": "my-app",
  "paramsSchema": {
    "schemas": {
      "subscription": {
        "create": {
          "parameters": {
            "$schema": "",
            "additionalProperties": false,
            "_show_form_view": true,
            "type": "object",
            "properties": {
              "databaseId": {
                "type": "string",
                "title": "SAP HANA Cloud Database ID",
                "description": "Enter SAP HANA Cloud Database ID"

After a quick cf update-service saas-registry -c ./my-saas-config.json we should now see our new parameter appear:


Adding a simple custom parameter

We can even apply constraints and suggested values to these parameters using patternenum and default:

  "properties": {
    "databaseId": {
      "type": "string",
      "title": "SAP HANA Cloud Database ID",
      "description": "Enter SAP HANA Cloud Database ID",
      "pattern": "^[A-Za-z0-9-]{36}$"
    "deployMode": {
      "type": "string",
      "enum": [
      "default": "legacy",
      "title": "Deployment Mode",
      "description": "Deploy using legacy or cloud mode"


Advanced subscription parameters


With the registry now configured to allow custom parameters, the next step is to handle them in the subscription callback. The subscription request body includes it in the subscriptionParams object, for example:

  "subscriptionAppId": "my-app",
  "subscriptionParams": {
    "databaseId": "",
    "deployMode": "legacy",
  "userInfo": {
  "additionalInformation": {
  "eventType": "CREATE"

From here, it’s just a matter of handling it in the logic. The project I work on has a bespoke onboarding handler but for those that use CAP and MTX I’d again like to refer you to this excellent tutorial which I believe will be made available as an SAP Discovery Center Mission in the near future: Use multiple SAP HANA Cloud instances


With the steps outlined in this post, you should now know the basics of configuring the SAAS Registry to allow for custom subscription parameters and how to access these when handling the subscription request. A natural application of this is targeting distinct HANA Databases but this general pattern can be extended to any general application.


Aside from the GitHub tutorial linked throughout this post, I couldn’t find any documentation on how to set these custom subscription parameters up. The tutorial of course made me aware that this was possible but the particulars were still opaque. One technique I found to be useful in this regard was to use my browser web tools to inspect how the these services are rendered as raw JSON. Indeed, this is what allowed me to finally discover an acceptable JSON format as well as the advanced formatting options. I’d encourage anyone that wants a deeper understanding to take this additional step.

For example, if I switch over to my CF-enabled provider account I can inspect the GET /GetMarketplace call to find details on how any service is presented. This is what the maintenance window config looks like for the Redis service that was used as an example above:


Using chrome devtools to inspect parameter definitions

Obviously, this isn’t an ideal way to work with things so if anyone knows of a dedicated resource for this sort of information I’ll gladly update my blog post.



Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Mustafa Bensan
      Mustafa Bensan

      Hi Brian,

      Thanks for sharing your experience in the BTP multi-tenant SaaS space.  Custom subscription parameters are certainly very relevant for implementing a self-service onboarding process.  As you've pointed out, Martin Frick and Alper Dedeoglu have published some very helpful resources related to building multi-tenant SaaS applications on BTP.  Perhaps they will chime in with their thoughts on custom subscription parameters.



      Author's profile photo Martin Frick
      Martin Frick

      Hi Brian McDonnell,

      thanks for highlighting this cool topic in a dedicated blog post! A hardly known but extremely important topic for anyone who is planning to develop a multitenant SaaS application on SAP BTP! A special thanks to Mustafa Bensan for highlighting our contribution in this field! As much as we would love to provide an official "documentation" of these custom subscription parameters, we don't have it at hand. Still, the logic is more or less straight forward once you understood the concept and the bonus provided by Brian should be very helpful closing the remaining gaps.

      Keep on coding folks,


      Author's profile photo Alper Dedeoglu
      Alper Dedeoglu

      Nicely done Brian McDonnell .

      I really like the content and structure, thanks for sharing your knowledge!

      Worth to mention: This would work also in SAP BTP Kyma runtime seamlessly. 

      Author's profile photo Gregor Wolf
      Gregor Wolf

      Hi Brian,

      thank you for closing the documentation gap. Very unfortunate that the saas-registry documentation doesn't provide this.

      I understand that this parameters get passed to the subscribe handler. But how do I get the parameters when I need to upgrade tenants? Can I retrieve the parameters from the saas-registry? Have you already tried that?

      My concrete scenario is that I need to consume user provided services (UPS) created in the provider subaccount for each subscriber linking to a specific SAP Datasphere (fka SAP Data Warehouse Cloud DWC) schema. This UPS needs to be provided during the subscription but also during update. For subscription I got it already working in my sample repo srv/server.js#L37. But I'm wondering how to do it during update.

      Best Regards