Skip to content
Search

    Deploy SaaS Solutions

    This guide explains how CAP supports multitenant SaaS applications and what you as an implementor and provider of such applications should know.

    Content

    How It Works

    SAP BTP exposes a method for implementing and provisioning SaaS applications on Cloud Foundry. To effectively operate and run SaaS applications and to make them economically successful (TCO), such applications can be deployed once by the application provider, and then be shared by many customers. Such sharing of applications and related computational resources between many tenants is addressed by the multitenancy capabilities of SAP BTP. One important aspect is to guarantee separation between different tenants, so that a tenant isn’t allowed to access the data of other tenants. Apart from data separation, Identity and Access Management must also be isolated between tenants.

    CAP supports application developers implementing the APIs required by SAP BTP. If the application uses a SAP HANA database, multitenancy is available out of the box. CAP features provided include:

    • Expose endpoints for un/subscribing tenants, for returning subscription dependencies, and for tenant database updates
    • Out-of-the-box default implementation for un/subscribing using SAP HANA HDI containers
    • Out-of-the-box default implementation for tenant database updates
    • Application can implement handlers for its own un/subscribing logic
    • Tenant-specific routing of service requests → use tenant-specific metadata and tenant-specific database connection

    The cds-mtx Module

    CAP provides the NPM module for Node.js published as @sap/cds-mtx on npmjs.com:

    Java SaaS application deployment

    It provides a number of APIs for implementing SaaS applications on SAP BTP. All APIs are based on CDS. They can be exposed through plain REST, and/or consumed by other Node.js modules when running on the same server as cds-mtx:

    • provisioning: Implements the subscription callback API as required by SAP BTP. If a tenant subscribes to the SaaS application, the onboarding request is handled. cds-mtx contacts the SAP Service Manager to create a new HDI container for the tenant. Database artifacts are then deployed into this HDI container. In addition, the unsubscribe operation and the “get dependencies” operations are supported.

    • metadata: Can be used to get CSN and EDMX models, and to get a list of available services and languages.

    • model: Used to extend existing CDS models and to perform tenant model upgrades after having pushed a new version of the SaaS application.

    Setup

    Prerequisites

    To get started, you need a space in SAP BTP and a HANA Cloud or HANA-as-a-Service database connected to it. See section SAP HANA in our Troubleshooting guide. We also recommend creating a second BTP subaccount for testing the subscription of the deployed application.

    Bootstrapping

    You can bootstrap a multitenant project using cds init <project name> --add mtx,mta,samples. In this case, you can skip the following section and jump right to Deploy to Cloud Foundry.

    Configuration

    First, add the required services to your .cdsrc.json or package.json:

    "cds": {
  "requires": {
    "db": {
      "kind": "hana",
      "vcap": {
        "label": "service-manager"
      }
    },
    "multitenancy": true,
    "uaa": {
      "kind": "xsuaa"
    }
  }
}

    Now, install the required dependencies:

    npm add @sap/cds-mtx @sap/xssec hdb passport

    Further, add one of the following annotations to the AdminService (admin-service.cds) and the CatalogService (cat-service.cds) of the bookshop app:

    • If you intend to use the Postman collection for testing (see Testing with Postman), enable access by technical users: 
      @(requires:'system-user')
    • Otherwise, enable access by authenticated natural persons: 
      @(requires:'authenticated-user')

    Deployment

    Each SaaS application must have bindings to at least three SAP BTP service instances:

    Service Description
    User Account and Authentication Service (xsuaa service) Binding information contains the OAuth client ID and client credentials. The XSUAA security library can be used to validate the JWT token from requests and to retrieve the tenant context from the JWT.
    Service Manager (service-manager service) CAP uses this service for creating a new SAP HANA Deployment Infrastructure (HDI) container for each tenant and for retrieving the tenant-specific database connection.
    SaaS Provisioning Service (saas-registry service) To make a SaaS application available for subscription to SaaS consumer tenants, the application provider must register the application in the SAP BTP, Cloud Foundry environment through the SaaS Provisioning Service.

    Configure your MTA for Deployment

    The following mta.yaml is a minimal example creating all the services required for a multitenant bookshop application. It can be used to build and deploy the project as described in Deploy Using MTA.

    mta.yaml

    _schema-version: '3.1'
ID: bookshop
version: 1.0.0
description: "A simple multitenant bookshop application"
parameters:
  enable-parallel-deployments: true

build-parameters:
  before-all:
   - builder: custom
     commands:
      - npm install --production
      - npx -p @sap/cds-dk cds build --production

modules:
 - name: bookshop-srv
   type: nodejs
   path: gen/srv
   requires:
    - name: bookshop-db
    - name: bookshop-uaa
    - name: bookshop-registry
   provides:
    - name: srv-api # required by consumers of CAP services (e.g. approuter)
      properties:
        srv-url: ${default-url}
    - name: mtx-api # potentially required by approuter
      properties:
        mtx-url: ${default-url}

resources:
 - name: bookshop-db
   type: org.cloudfoundry.managed-service
   parameters:
     service: service-manager
     service-plan: container
   properties:
     hdi-service-name: ${service-name} # required for Java apps

 - name: bookshop-uaa
   type: org.cloudfoundry.managed-service
   parameters:
     service: xsuaa
     service-plan: application
     path: ./xs-security.json

 - name: bookshop-registry
   type: org.cloudfoundry.managed-service
   requires:
       - name: bookshop-uaa
       - name: mtx-api
         properties:
           prop: ~{mtx-url}
         parameters:
           param: ~{mtx-url}
   parameters:
       service: saas-registry
       service-plan: application
       config:
         xsappname: bookshop-${space}
         appName: bookshop-${space}
         displayName: bookshop
         description: A simple CAP project.
         #category: "Category"
         appUrls:
             onSubscription: ~{mtx-api/mtx-url}/mtx/v1/provisioning/tenant/{tenantId}
             onSubscriptionAsync: false
             onUnSubscriptionAsync: false
             callbackTimeoutMillis: 300000

    Additionally, an xs-security.json file has to be created, to specify the XSUAA service settings, with roles for subscription and deployment.

    xs-security.json

    {
  "xsappname": "bookshop-${space}",
  "tenant-mode": "shared",
  "scopes": [
    { "name": "$XSAPPNAME.MtxDiagnose", "description": "Diagnose MTX sidecar" },
    { "name": "$XSAPPNAME.mtdeployment", "description": "Deploy applications" },
    { "name": "$XSAPPNAME.mtcallback", "description": "Subscribe to applications", "grant-as-authority-to-apps": [
      "$XSAPPNAME(application,sap-provisioning,tenant-onboarding)"
    ]}
  ],
  "authorities": [
    "$XSAPPNAME.mtdeployment",
    "$XSAPPNAME.mtcallback",
    "$XSAPPNAME.MtxDiagnose"
  ],
  "role-templates": [
    {
      "name": "MultitenancyAdministrator",
      "description": "Administrate multitenant applications",
      "scope-references": [
        "$XSAPPNAME.MtxDiagnose",
        "$XSAPPNAME.mtdeployment",
        "$XSAPPNAME.mtcallback"
      ]
    }
  ]
}

    Deploy to Cloud Foundry

    First, make sure the dependencies are installed and a package-lock.json exists in your repository.

    npm install

    You can now build the project using:

    mbt build

    and deploy it using:

    cf deploy mta_archives/bookshop_1.0.0.mtar

    Testing

    Testing with Server Running Locally

    You can run the bookshop server (bookshop-srv) locally and have it connected to the remote database. To achieve this, you need to provide database connection details, which you can obtain as follows:

    1. Deploy the MTA as described previously.
    2. Run cf env bookshop-srv to obtain output similar to the following: 
       [...]
 {
  "VCAP_SERVICES": {
   "service-manager": [
    {
     "binding_name": null,
     "credentials": {
       [...]
     },
     [...]
    }
   ],
   "xsuaa": [
    [...]
   ]
  }
 }

 [...]
    3. Copy the VCAP_SERVICES definition, that is, the part between and including the outermost curly braces.
    4. Create a default-env.json file in the db subfolder of your app.
    5. Paste the copied data.

    To start the server, run npm run start in the root directory of bookshop-srv. By default, the server listens on localhost:4004. (The port can be changed through the PORT environment variable.)

    This address can be used as the server URL in the rest of this documentation. You can also run the Postman requests against it by simply adjusting the appurl accordingly.


    Postman

    Import the MTX API collection and the MTX environment into Postman.

    Remember to select the environment MTX Environment at the top right.

    The environment contains a set of variables which you have to set. Run cf env bookshop-srv to extract the values for those variables from the response.

    Variable Description
    identityzone,
    clientid, and
    clientsecret
    		Extract them from the xsuaa binding information.
    appurl The URL of the bookshop-srv application.
    mtxappurl The URL of the application providing the MTX APIs.
    Using Node.js as the runtime, mtxappurl is the same as appurl.
    Using Java as the runtime, mtxappurl is the URL of the sidecar application.
    subscriberTenantId,
    subscriberSubdomain    		 The tenant ID and subdomain of the subscriber BTP subaccount. You can find that information on the subaccounts Overview page in the SAP BTP Cockpit. For testing purposes, you can use the tenant ID and subdomain of the provider subaccount.
    region The SAP BTP region of your subaccount. For example eu10 for the AWS Europe (Frankfurt) region.
    accessToken A variable that is filled when fetching a JWT token.
    currentJobId A variable that caches the job ID for asynchronous jobs.

    Send requests:

    1. Fetch a JWT token with the request “Authenticate → Get Token w/ Client Credentials”. If you check your environment, you can see that the JWT token is now stored in the accessToken variable.
    2. Subscribe the PaaS tenant with the request “mtx API → Onboard PaaS tenant”
    3. Try all other requests …


    Event Handlers

    If you’re using a CAP Java server, it re-exposes the APIs required by SAP BTP’s SaaS Manager (the Provisioning API). We recommended leveraging the corresponding Java-based mechanisms to add handlers to these APIs. Handlers for the Model-API of cds-mtx must always be implemented on the Node.js server, because this API isn’t re-exposed by the CAP Java runtime.

    cds-mtx APIs are implemented as CDS services. Therefore, service implementations can be overridden using CDS event handlers. For cds-mtx APIs, custom handlers have to be registered on the mtx event in a custom server.js:

    const cds = require('@sap/cds')

cds.on('mtx', async () => {
    const provisioning = await cds.connect.to('ProvisioningService')
    provisioning.prepend(() => {
      provisioning.on('UPDATE', 'tenant', async (req, next) => {
        await next() // default implementation creating HDI container
        return '<bookshop-srv-url>/admin'
     })
})

// Delegate bootstrapping to built-in server.js
module.exports = cds.server

    See the following use cases for more examples.

    Use Case: Implement a Tenant Provisioning Handler

    You can set an application entry point for the subscription in the SAP BTP Cockpit (usually a UI).

    Create a provisioning.js file in the srv folder:

    module.exports = (service) => {
  service.on('UPDATE', 'tenant', async (req, next) => {
    await next() // default implementation creating HDI container
    return '<bookshop-srv-url>/admin'
  })
}

    In the provided code sample, you have to replace <bookshop-srv-url> with the URL of your bookshop-srv application on Cloud Foundry. In this example, the /admin endpoint is returned. It’s important that this endpoint isn’t protected (doesn’t require a JWT token).

    Custom code after asynchronous provisioning can be invoked with handlers for the internal endpoint to create tenants. This endpoint is called for both synchronous and asynchronous provisioning:

    module.exports = (service) => {
  service.on('createTenant', async (req, next) => {
    await next() // default implementation creating HDI container
    const { subscriptionData } = req.data // original request payload
    // custom code
    return '<bookshop-srv-url>/admin'
  })
}

    Use Case: Handler for Tenant Upgrade

    To execute custom code for tenant upgrades (see also Tenant upgrade API), you can add handlers for the upgrade API that is called by cds-mtx. This API is called for the synchronous, as well as the asynchronous upgrade for each tenant.

    module.exports = (service) => {
  service.on('upgradeTenant', async (req, next) => {
    await next() // call the upgrade
    const {
      instanceData, // HDI container metadata
      deploymentOptions // additional deployment options, e.g. `autoUndeploy`
    } = cds.context.req.body
    // custom code
  })
}

    Use Case: Handler for Database Deployment

    To add custom code to the deployment of your application model to the SAP HANA database, you can add handlers for the deployment API called by cds-mtx.

    This example dynamically adds an additional SAP HANA service to the environment, so it can be used through synonyms (see also Enable Access to Objects in Another HDI Container):

    module.exports = (service) => {
  service.before('deployToDb', async (context) => {
    const {
      sourceDir, // directory with generated SAP HANA sources
      instanceData, // HDI container metadata
      deploymentOptions // additional deployment options, e.g. `autoUndeploy`
    } = cds.context.req.body;
    // ...
    const hana = [{
	    "label": "hana",
	    "provider": null,
	    "plan": "hdi-shared",
	    "name": "common-db-sample",
	    "<custom-key>": "value"
    }];
    context.data.additionalServices.hana = hana;
  });

    Advanced

    SAP BTP Dependencies

    If you require SAP reuse services, use cds.mtx.dependencies in your package.json and pass an array of their xsappnames. The SaaS Provisioning service (getDependencies handler) needs this information.

    "mtx": {
  "dependencies": ["xsappname-1", "xsappname-2"]
}

    Job Queue Size

    The job queue size can be modified to allow for more concurrently running operations. For instance, its size could be increased to 10 by adding

    "mtx": {
  "jobqueue": {
    "size": 10
  }
}

    to your package.json or .cdsrc.json, or by setting the environment variable CDS_MTX_JOBQUEUE_SIZE=10.

    API Reference

    All APIs receive and respond with JSON payloads. Application-specific logic (for example, scope checks) can be added using Event Handlers.

    Provisioning API

    Subscribe Tenant

    PUT /mtx/v1/provisioning/tenant/<tenantId>

    Minimal request body:

    {
  "subscribedSubdomain": "<subdomain>",
  "eventType": "CREATE"
}

    Only if eventType is set to CREATE, the subscription is performed.

    An application can mix in application-specific parameters into this payload, which it can interpret within application handlers. Use the _application_ object to specify those parameters. There’s one predefined sap object, which is interpreted by cds-mtx default handlers. With that object, you can set service creation parameters to be used by the SAP Service Manager when creating HDI container service instances. A typical use case is to provide the database_id to distinguish between multiple SAP HANA databases mapped to one Cloud Foundry space.

    {
  "subscribedSubdomain": "<subdomain>",
  "eventType": "CREATE",
  "_application_": {
    "sap": {
      "service-manager": {
        "provisioning_parameters": { "database_id" : "<HANA DB GUID>" },
        "binding_parameters": {"<key>" : "<value>"}
    }
  }
}

    If you have more than one SAP HANA database mapped to one space, subscription doesn’t work out of the box, unless you’ve specified a default database. This can be achieved by specifying a default when mapping a database to a space (not available for HANA Cloud). See Share an Instance with another Cloud Foundry Space for more details.

    Unsubscribe Tenant

    DELETE /mtx/v1/provisioning/tenant/<tenantId>

    Subscription Dependencies

    GET /mtx/v1/provisioning/dependencies

    Response body: Array of String. The default implementation returns an empty array.

    GET Subscribed Tenants

    GET /mtx/v1/provisioning/tenant/

    Returns the list of subscribed tenants. For each tenant, the request body that was used for subscribing the tenant is returned.

    Model API

    Get CDS Model Content

    GET mtx/v1/model/content/<tenantId>

    Returns the two objects base and extension in the response body:

    {
  "base": "<base model cds files>",
  "extension": "<extension cds files>"
}

    Activate Extensions

    POST mtx/v1/model/activate

    Request body (example):

    {
  "tenant": "tenant-extended",
  "extension": "<cds extension files>",
  "undeployExtension": false
}

    The extension element must be a JSON array of arrays. Each first-level array element corresponds to a CDS file containing CDS extensions. Each second-level array element must be a two-entry array. The first entry specifies the file name. The second entry specifies the file content. Extension files for data models must be placed in a db folder. Extensions for services must be placed in an srv folder. Entities of the base model (the nonextended model) are imported by using ... from '_base/...'.

    If the undeployExtension flag is set, all extensions are undeployed from the database that are no longer part of the extensions in the current activation call.

    ❗ Warning undeployExtension has to be used with care as it potentially removes tables and their content from the database.

    Request body detailed sample:

    {
"tenant": "tenant-extended",
"extension": [
  [
  "db/ext-entities.cds",
  "using my.bookshop from '_base/db/data-model'; \n extend entity bookshop.Books with { \n ISBN: String; \n rating: Integer \n  }"
  ],
  [
  "db/new-entities.cds",
  "namespace com.acme.ext; \n entity Categories { \n key ID: String; \n description: String; \n }"
  ],
  [
  "srv/ext-service.cds",
  "using CatalogService from '_base/srv/cat-service'; \n using com.acme.ext from '../db/new-entities'; \n extend service CatalogService with { \n  @insertonly entity Categories as projection on ext.Categories; \n }"
  ]
  ],
"undeployExtension": false
}

    Deactivate Extension

    POST /mtx/v1/model/deactivate

    Request body (example):

    {
  "tenant": "tenant-extended",
  "extension_files": [
    "srv/ext-service.cds"
  ]
}

    extension_files is an array of the files that are to be removed from the extensions.

    Use this API to deactivate extension. To activate and deactivate an extension in one call, use activate with undeployExtension: true.

    ❗ Warning The API has to be used with care as it removes tables and their content from the database.

    Reset Extension

    POST /mtx/v1/model/reset

    Request body (example):

    {
  "tenant": "tenant-extended",
}

    Use this API to remove all extensions.

    ❗ Warning The API has to be used with care as it removes tables and their content from the database.

    Upgrade Base Model from Filesystem (Asynchronous)

    POST mtx/v1/model/asyncUpgrade

    Request body:

    {
  "tenants": ["tenant-extended-1", "tenant-non-extended-2", ...],
  "autoUndeploy": <boolean>
}

    Upgrade all tenants with request body { "tenants": ["all"] }.

    If autoUndeploy is set to true, the auto-undeploy mode of the HDI deployer is used. See HDI Delta Deployment and Undeploy Allow List for more details.

    Response (example):

    { "jobID": "iy5u935lgaq" }

    You can use the jobID to query the status of the upgrade process:

    GET /mtx/v1/model/status/<jobID>

    During processing, the response can look like this:

    {
  "error": null,
  "status": "RUNNING",
  "result": null
}

    Once a job is finished, the collective status is reported like this:

    {
  "error": null,
  "status": "FINISHED",
  "result": {
      "tenants": {
          "<tenantId1>": {
              "status": "SUCCESS",
              "message": "",
              "buildLogs": "<build logs>"
          },
          "<tenantId2>": {
              "status": "FAILURE",
              "message": "<some error log output>",
              "buildLogs": "<build logs>"
          }
      }
  }
}

    The status of a job can be QUEUED (not started yet), RUNNING, FINISHED, or FAILED.

    The result status of the upgrade operation per tenant can be RUNNING, SUCCESS, or FAILURE.

    Logs are persisted for a period of 30 minutes before they get deleted automatically. If you request the job status after that, you’ll get a 404 Not Found response.

    Metadata API

    All metadata APIs support eTags. By setting the corresponding header, you can check for model updates.

    GET EDMX

    GET /mtx/v1/metadata/edmx/<tenantId>

    Returns the EDMX metadata of the (extended) model of the application.

    Optional URL parameters

    name=<service-name>
language=<language-code>

    GET CSN

    GET /mtx/v1/metadata/csn/<tenantId>

    Returns the compiled (extended) model of the application.

    GET Languages

    GET /mtx/v1/metadata/languages/<tenantId>

    Returns the supported languages of the (extended) model of the application.

    GET Services

    GET /mtx/v1/metadata/services/<tenantId>

    Returns the services of the (extended) model of the application.

    Diagnose API

    GET Jobs

    GET /mtx/v1/diagnose/jobs

    Returns information about the job queue, including waiting or running jobs.

    GET Memory

    GET /mtx/v1/diagnose/memory

    Returns information about the memory usage.

    GET Container

    GET /mtx/v1/diagnose/container/<tenantId>

    Returns information about a tenant’s HDI container.

    Extensibility

    Extend Tenant Data and Service Models

    cds-mtx provides an API to extend data and service models in a tenant-specific way. The CDS Software Development Kit, @sap/cds-dk, contains a command-line client with which an extension developer can maintain and activate cds model extension files. See Extending SaaS Applications for more details.

    Perform the following steps to enable and perform extensions of the Getting Started Bookshop SaaS application:

    1. Add required scopes to XSUAA configuration.
    2. Authorize Extension Developer on SAP BTP.
    3. Set up an Extension Project.
    4. Create extension cds files and activate.

    Add Required Scopes

    Tenant-specific CDS model extensions are performed by an extension developer, usually a customer. Therefore, those activities are protected by XSUAA scopes. You can add the following configuration to your xs-security.json:

    {
  "scopes": [
    { "name": "$XSAPPNAME.ExtendCDS", "description": "Create extensions" },
    { "name": "$XSAPPNAME.ExtendCDSdelete", "description": "Undeploy extensions" }
  ],
  "role-templates": [
    {
      "name": "ExtensionDeveloper",
      "description": "CDS Extension Developer",
      "scope-references": [
        "$XSAPPNAME.ExtendCDS",
        "$XSAPPNAME.ExtendCDSdelete"
      ]
    }
  ]
}

    Rebuild the application while applying the extension descriptor with:

    mbt build -t ./ -e scopes.mtaext

    Then redeploy while just updating the bookshop-uaa service instance:

    cf deploy bookshop_1.0.0.mtar -r bookshop-uaa

    You need to have the User & Role Administrator role to be able to define role templates. If the previous command gives you an error message, assign this role to yourself.


    Authorize Extension Developer

    • Open the overview screen of a subaccount in SAP BTP cockpit. This can be any subaccount that is already subscribed to your application. For first testing, you can choose your PaaS/Provider subaccount into which you’ve deployed your application. Note down the value for “Subdomain”. In the following sections, we refer to it as <subdomain>. It represents the tenant.

    • Choose Trust Configuration and click on the active Default identity provider name. Trust Configuration

    • Enter your e-mail address and choose Show Assignments.
    • Choose Assign Role Collection.
    • From the popup, assign CAP-Getting-Started.

    You’re now authorized to use the extension API to extend cds models for your PaaS/Provider tenant.


    Set Up an Extension Project

    Initialize a new extension project for the <subdomain> tenant:

    • Execute cds extend <bookshop-srv-url> -s <subdomain>
    • The system will respond with the message “Invalid passcode”.
    • Fetch a one-time passcode used for authentication by following the link given in the system message. Log on in the browser logon screen. Note down the shown authentication code <passcode>.
    • Execute cds extend <bookshop-srv-url> -s <subdomain> -p <passcode>. A project structure will be generated in a new folder called <subdomain>.

    Create and Activate an Extension

    • In the db/ folder of this project, create the new file ext.cds: 
      using sap.capire.bookshop from '_base/db/schema.cds';
extend entity bookshop.Books with {
ISBN : String;
}
    • Execute cds activate <subdomain> (from the folder one above the <subdomain> folder). For the <subdomain> tenant, the new ISBN field is activated on the database.
    • Verify that the new field is exposed for Books. Use Postman to fetch a JWT for the extended tenant and send a GET request to <bookshop-srv-url>/browse/$metadata.


    Extensibility Configuration

    Extensibility settings can be added to the mtx settings of your .cdsrc.json file:

    "mtx": {
  "element-prefix": ["Z_", "ZZ_"],
  "namespace-blocklist": ["com.sap.", "sap."],
  "extension-allowlist": [
    {
        "for": ["my.bookshop.Authors", "my.bookshop.Books"],
        "new-fields": 2
    }, {
        "for": ["CatalogService"],
        "new-entities": 2
    }
  ]
}

    Element Prefixes and Namespace Blocklist

    Field extensions can only be performed with prefixes listed in the `element-prefix’ prefix list.

    Similarly, new entities and services can’t be created within the blocked CDS namespaces listed in namespace-blocklist.
    Namespace restrictions are “inherited”, that is, protecting “com.sap.” also protects “com.sap.*”

    Entity Allowlist

    The mtx section also lists the entities and services that can be extended; their fully qualified names are listed in the entity-allowlist.
    The entity-allowlist can contain restrictions to limit the number of extensions that can be created. Use new-fields and new-entities to set the maximum number of fields for entities and the number of new entities for services.
    You can also specify the entity and service names as namespaces. The restrictions then apply to all entities and services in that namespace.

    "extension-allowlist": [
  {
    "for": ["my.bookshop"],
    "new-fields": 2
  },
  {
    "for": ["*"],
    "kind": "service"
  }
]

    The example allows two new fields for all entities in the my.bookshop namespace and an unlimited number of new entities for all services.

    If this list isn’t provided, no entities or services can be extended.

    ✉