Defining Custom Subscription Parameters in Multitenant SAP BTP CF Applications

[bmcdonn2]

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.

Motivation

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.

Configuration

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:

...
config:
  xsappname: 'my-app'
  ...
  propagateParams: true
  paramsSchema: 
    schemas: 
      subscription:
        create:
          parameters:
            $schema: 'http://json-schema.org/draft-04/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'

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": "http://json-schema.org/draft-04/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 pattern, enum 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": [
        "legacy",
        "cloud"
      ],
      "default": "legacy",
      "title": "Deployment Mode",
      "description": "Deploy using legacy or cloud mode"
    }
  }
}

Advanced subscription parameters

Development

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

Conclusion

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.

Bonus

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.


Thanks!

[MustafaBensan]

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, martinfrick and alperdedeoglu 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.

Regards,

Mustafa.

[martinfrick]

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 mbensan 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,

Martin

[alperdedeoglu]

Nicely done bmcdonn2cf .

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. 

[gregorw]

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
Gregor

[sven-leonhardt]

Hi Brian,

thanks for this blog post. Unfortunately, it seems that defining the form view is no longer possible via the mentioned _show_form_view parameter. I copied your solution and only get the JSON view, which is of course missing the entered descriptions and enums, etc.

Are you aware of a new way for defining the form view?

Best Regards
Sven

[bmcdonn2]

Hey @sven-leonhardt ,

I recently ran into some issues while setting up a new saas registry and it was due to how I had formatted the yaml file. It should now be updated with a form that works. 

In terms of enums, it should be possible to delivery using the following yaml:

        propagateParams: true
        paramsSchema: 
          schemas: 
            subscription:
              create:
                parameters:
                  $schema: 'http://json-schema.org/draft-04/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'
                      enum:
                        - 'hana-service'
                        - 'hana-cloud'

One last note is the inclusion of the propagateParams flag. I'm not actually sure what type of impact is has but I found it in some docs here : https://github.com/SAP-samples/btp-cap-multitenant-saas/tree/main/docu/4-expert/-CloudFoundry-/multi...

(though I have a suspicion that this blog post may have inspired the docs if I look at timestamps and the specific wording of titles and descriptions)

Hope this helps!

Thanks,

Brian