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' 
   ...
    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!