Skip to content

    Deploy as Multitenant SaaS Application

    This guide explains how to deploy CAP multitenant SaaS applications to SAP BTP Cloud Foundry environment, and how SaaS Customers would subscribe to them.

    Intro & Overview

    Software-as-a-Service (SaaS) solutions are deployed once by a SaaS provider, and then used by multiple SaaS customers subscribing to the software.

    SaaS applications need to register with the SaaS Provisioning Service to handle subscribe and unsubscribe events. In contrast to single-tenant deployments, databases or other tenant-specific resources aren’t created and bootstrapped upon deployment, but upon subscription per tenant.

    CAP includes the MTX services, which provide out-of-the-box handlers for subscribe/unsubscribe events, with automatic creation of SAP HANA database containers or SAP Event Mesh instances.

    If everything is set up, the following graphic shows what’s happening when a user subscribes to a SaaS application:


    1. The SaaS Provisioning Service sends a subscribe event to the CAP application.
    2. The CAP application delegates the request to the MTX services.
    3. The MTX services use Service Manager to create the database tenant.
    4. The CAP Application connects to this tenant at runtime using Service Manager.


    The detailed procedure is described in the Deploy to Cloud Foundry guide. To start with this guide, you fulfill all Prerequisites and went through Prepare for Production, or instead run this command to fast-forward:

    cds add hana,xsuaa,approuter,mta --for production

    Add MTX

    To enable MTX services for your project, run the following command:

    cds add mtx --for production

    This modifies the modules and resources in mta.yaml for multitenant deployment.

    Learn more about MTX services.

    Build & Deploy

    You know the build and deploy steps from the Deploy to Cloud Foundry guide.

    mbt build -t gen --mtar mta.tar

    Learn more about Build & Assemble

    cf deploy gen/mta.tar

    Learn more about Deploy to Cloud Foundry.


    Create a BTP subaccount to subscribe to your deployed application. This subaccount has to be in the same region, for example, us10.

    Global Account view

    In your subscriber account go to Instances and Subscription and select Create. subscriber account

    Select bookshop and use the only available plan default. Inst

    Go to Application. subscribed bookshop

    As you can see, your route doesn’t exist yet. You need to create and map it first.

    Leave the window open. You need the information to create the route.

    route doesn't exist

    Switch to your provider account and go to your space → Routes Route Screen

    Click New Route New Route wizard

    Use the broken route to fill the fields. For the following explanations let’s use this route as example:

    • As Domain, use the part that usually starts with cfapps… and ends with .com

      In our example, the domain is:

    • As Host Name, use the part between https:// and .cfapps

      In our example, host name is: my-account

    • Click Save

    You can now see the route is created but not mapped yet (none). Overview

    Click Map Route Map Route

    Select bookshop, which is the App Router application we just deployed, and save. Overview with new mapped route

    You’ve successfully created the route for your subscribed bookshop multitenant application. Refresh the browser tab of the bookshop application and log in.

    Behind the Scenes

    With adding the MTX services, your project configuration is adapted at all relevant places. Configuration and dependencies are added to your package.json and an xs-security.json containing MTX-specific scopes and roles is created.

    For the MTA deployment service dependencies are added to the mta.yaml file. Each SaaS application will have bindings to at least three SAP BTP service instances.

    Service Description
    Service Manager (service-manager) CAP uses this service for creating a new SAP HANA Deployment Infrastructure (HDI) container for each tenant and for retrieving tenant-specific database connections.
    SaaS Provisioning Service (saas-registry) 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.
    User Account and Authentication Service (xsuaa) Binding information contains the OAuth client ID and client credentials. The XSUAA service can be used to validate the JSON Web Token (JWT) from requests and to retrieve the tenant context from the JWT.

    If you’re interested, use version control to spot the exact changes.

    Appendix — Configuration

    Configuring 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.

    SaaS Service Dependencies

    If you require SAP reuse services, that need subscriptions, 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"]