Extending SaaS Applications

How SaaS subscribers can extend SaaS applications on a tenant level.


Extend SaaS Applications

Subscribers (customers) of a SaaS application can extend data and service models in the context of their subscription (= tenant context = subaccount context). New fields can be added to SAP provided database tables. Those fields can be added to UIs as well, if these have been built with SAP’s Fiori Elements technology.

The overall process is depicted in the following figure:

customization process

Setup Tenant Landscape

Using SAP Cloud Platform Cockpit, an account administrator is setting-up a “landscape of tenants” (= multiple subaccounts) to enable a staged extension development scenario (for example, development and productive tenants). We recommend to setup at least a development tenant to test extended data-, service-, and UI models before activating these into the productive tenant.

Subscribe to SaaS Application

Using SAP Cloud Platform Cockpit, a subaccount administrator is subscribing to the SaaS application. During this subscription, the SaaS application automatically performs a tenant onboarding step, which (in case of using SAP HANA) allocates an SAP HANA persistence for this tenant (= subaccount) and deploys all database objects.

Extending cds services and database entities is only possible if the SaaS application is using the SAP HANA database service. Further, the SaaS application must have been enabled for extensibility by the SaaS provider.

Authorize Extension Developer

The extension is done by an extension developer (a customer role). The privilege to extend the base model of a tenant is linked to a scope of the SaaS application. Therefore, the security administrator of a subaccount has to grant this scope to the developer using SAP Cloud Platform Cockpit. As a prerequisite, the developer has to be registered within the Identity Provider linked to the subaccount.

There are two relevant scopes, which can be assigned to extension developers:

ExtendCDS Create extension projects and apply extension files. Not authorized to delete tables created by previous extensions
ExtendCDSdelete In addition, enables deletion of tables created by previous extension, which can cause data loss!

The SaaS application delivers role templates including these scopes. To know these, consult the documentation of the SaaS application.

Start Extension Project

Extension developers initialize an extension project on the file system on a computer. Prerequisites:

  • The cds command line tools must be installed (see Local Setup).
  • The Identity Provider linked to the tenant’s subaccount must support the SAML standard.
  • It’s recommended to use an Integrated Development Environment (IDE) with one of the available CDS editors for authoring extension cds files.
  • Basic knowledge of the cds language.

Use the regular cds help feature to learn more about command options. For instance, to see a description of the command cds extend, use cds help extend.

The cds client is communicating with the SaaS application and fetches the “base model” (the not-yet-extended model) from there. An extension project folder is generated on the local file system. If an extension has already happened before, the last activated extension is fetched as well.

As an extension developer, initialize an extension project with the following command:

cds extend <app-url> -d <project-directory> -p <passcode>

<app-url> is specific to the SaaS application you’re going to extend. This URL can be found in the documentation for the respective SaaS application. Usually, <app-url> is the same URL visible on the subscriptions tab of SAP Cloud Platform Cockpit, which is used to launch the application, enhanced with an additional URL path segment (for example, /extend). However, the SaaS application can decide to provide a different URL for working with extensions.

<project-directory> is the folder on local disk, which will contain the extension project files.

<passcode> is a temporary authentication code, which is used to connect to the SaaS application. This passcode can be retrieved by opening a browser logon page. The URL of this browser page depends on SAP Cloud Platform landscape where the SaaS application is running and the tenant, which shall be extended:

<url> = https://<tenant-subdomain>.authentication.<landscape>

A passcode can be used only once and within a limited period of time. If the connection is successfully established, subsequent commands can be executed for a time period, which depends on the configuration of the Identity Provider linked to the Subaccount on SAP Cloud Platform. When expired, a new passcode has to be generated and send again.

As the connection is tenant-specific, <tenant-subdomain> must be the subdomain contained in <app-url> (the string preceding the first dot ‘.’). If not the case, the option -s <tenant-subdomain> can be used.

As a result of cds extend, an extension project is created in the specified folder. As an example, the following file/folder structure is generated on local disk:

  package.json    # extension project descriptor
            # will contain service and ui-related extension cds files
            # will contain db-related extension cds files
       ...   # contains the base model provided by the SaaS application

The node_modules folder should be hidden when using an IDE, because it contains artifacts (the base cds model of the SaaS application) which can’t be changed. SaaS applications can provide templates to document how to do meaningful extensions of base entities and services.

This project structure follows the same conventions as introduced for developing entire cds applications. Model extension files, which are relevant for a database deployment must be placed in folder db/. Service extension files must be placed in folder srv/. The base model is treated like a reuse model. You can refer to it in extension files simply by using ... from '_base/...'

Extension developer should drive extension projects similar to other development projects. It’s recommended to use a version control system (for example, Git) to host the extension project sources.

Develop & Activate Extensions

Developing cds model files is supported by cds editor and cds build tools. Within these files, you can reference base model files through using ... from '_base/...' statements. Entities and services can be extended using the cds extend technique. The following example shows how to add two fields to a Books database table of a hypothetical Bookshop application. A file extension.cds is created (the file name doesn’t matter) within the db-folder:

using sap.bookshop from '_base/db/datamodel';

extend entity bookshop.Books with {
  GTIN: String(14);
  rating: Integer;

Extensions can be activated into a test tenant using the following command:

cds activate <extension-project-directory>

This uses the current connection for activation. If this connection doesn’t exist or has expired, then the options ‘-p <passcode>’, ‘-s <tenant-subdomain>’, and ‘--to <app-url>’ can be used to (re)connect. Activating an existing project into a different tenant requires setting <passcode> and <app-url> appropriately.

By using cds activate, it isn’t possible to upload csv-files into the extended tenant.

Executing cds extend on an Existing Extension Project

cds extend is used to create and initialize an extension project. Subsequent executions of cds extend must be done with the --force option to overwrite existing files (base model files and extension files). No files will be deleted. Features of a version control system should be used to detect and merge changes.

Fetching Extension Templates from the SaaS Application

SaaS applications can deliver template files, which demonstrate how to extend entities and services for this SaaS application. Such templates can be fetched from the server by using the --templates option of the cds extend command. As a result, a folder tpl will be generated which contains the extension template files.

Deploy Extensions to Production

The productive tenant (the productive subaccount on SAP Cloud Platform) is technically treated the same way as any development tenant. Role-based authorization can restrict the access to the productive tenant to dedicated extension developers. An extension project, which has been generated by referencing a development tenant, can be activated into a productive tenant by using cds activate with appropriate options.