Skip to content

    Migration from Old MTX

    Towards new multitenancy capabilities

    Explains how to migrate from @sap/cds-mtx (aka Old MTX) to @sap/cds-mtxs (‘streamlined’ MTX)


    Functional Differences

    Before you start to migrate towards the ‘streamlined’ MTX, read about the differences compared to the old MTX.


    For ‘streamlined’ MTX, we have no support for the following:

    • i18n [temporary limitation]
    • async extensibility (push) [temporary limitation]
    • undeploy [temporary limitation]
    • hdbmigrationtable for extensibility
    • setup of extension projects via cds extend
    • custom content


    For ‘streamlined’ MTX, we have no support for the following:

    • diagnose API [temporary limitation]
    • configurable scopes
    • tenant-individual basemodel version stored


    • served event is not emitted if you use your own bootstrap in server.js w/o delegating to cds.server
    • When filtering all services to get your own application services, you will catch the cds.xt.ModelProviderService as well.

    Adapt Project Configuration

    To switch your project to ‘streamlined’ MTX, perform the following steps:

    1. Remove @sap/cds-mtx:
       npm remove @sap/cds-mtx
    2. Add @sap/cds-mtxs:
      npm add @sap/cds-mtxs
    3. Open your package.json and add the following:
       "cds": {
           "requires": {
               "multitenancy": true,
               "extensibility": true // if needed

    Build Configuration

    cds build will create the correct cloud deployment contents if your project matches the default layout as proposed for CAP projects and created by cds init.

    Note: Additional changes might be required if custom build tasks are configured. So, check if defaults would fit and if a custom build configuration is really needed. cds build logs the effective build configuration to the console. The default values will kick in for all build task properties that have not been configured.

    Configuration for Custom Build Tasks

    In case you need custom build tasks, make sure the CDS models for multitenancy, extensibility and toggles are defined as options.model in your build configuration. They represent the CDS model description of the required MTX Services. Otherwise, database artifacts will be missing or required services couldn’t be loaded in the cloud environment.

    "cds": {"build": {"tasks": [
      {"for": "nodejs", "options": {"model":[...,"@sap/cds/srv/mtx","@sap/cds/srv/extensions"]}}
    MTX Service Required CDS Model
    requires.multitenancy: true "@sap/cds/srv/mtx"
    requires.extensibility: true "@sap/cds/srv/mtx","@sap/cds/srv/extensions"
    requires.toggles: true "@sap/cds/srv/mtx"

    Handler Registration

    A typical handler registration in server.js now looks like

    cds.on('served', () => {
      const { 'cds.xt.SaasProvisioningService': provisioning } =
      const { 'cds.xt.DeploymentService': deployment } =
      provisioning.prepend(() => {
        provisioning.on('UPDATE', 'tenant', async (req, next) => { ... })
        provisioning.on('dependencies', async (req, next) => { ... })
      deployment.prepend(() => {
        // previously this was `upgradeTenant`
        deployment.on('upgrade', async (req) => {
          // HDI container credentials are not yet available here
        // previously this was `deployToDb`
        deployment.on('deploy', async (req) => {
          const { tenant, options: { container } } =

    Here’s what has changed:

    • ProvisioningService changed to cds.xt.SaasProvisioningService
    • DeploymentService changed to cds.xt.DeploymentService
    • Use cds.on('served') instead of cds.on('mtx').

    Saas Registry Endpoints

    The saas-registry endpoints in mta.yaml need to be changed to .../-/cds/saas-provisioning/...:

      service: saas-registry
          getDependencies: ~{mtx-api/mtx-url}/-/cds/saas-provisioning/dependencies
          onSubscription: ~{mtx-api/mtx-url}/-/cds/saas-provisioning/tenant/{tenantId}


    Scopes ExtendCDS and ExtendCDSdelete have changed to cds.ExtensionDeveloper.

    • Communicate to customer admins and extension developers to add the new scope to their role collection.
    • Adjust the documentation for the SaaS application accordingly.

    Use Local Sandbox

    • Run locally (w/ sqlite)
    • Try build for SAP HANA deployment w/ cds build
    • Call MTX endpoints locally