Key-User Extensibility for Simple Field Extensions ​

Overview ​

CAP has added a first experimental support for simple field extensibility that can be turned on in the latest release of the CAP Node.js runtime. This is a first step to enable extensibility in CAP applications without depending on an MTX/HDI based deployment and an SAP HANA database. The UI Adaptation tool in UI5 already provides experimental support for key-user extensions using SAPUI5 flexibility.

Test it with CAP Samples ​

The CAP Samples @capire/bookshop already has everything setup to give key-user extensibility a try. The changes are located in the branch key-user-ext. You can either switch to the branch, if you've already cloned samples, or clone it directly via

git clone https://github.com/SAP-samples/cloud-cap-samples.git -b key-user-ext

We need an SAP Fiori UI, so we're running the @capire/fiori sample, which uses the @capire/bookshop. Switch to the fiori folder and deploy a file-based database.

cd fiori
cds deploy --to sqlite

This is only necessary due to the current limitation that a server restart is required. The exact changes to CAP Samples can be found in this commit.

Run the application using cds watch and open the browser with the URL indicated in the command line.

[cds] - connect using bindings from: { registry:'~/.cds-services.json' }
[cds] - connect to db > sqlite { url:'sqlite.db', database:'sqlite.db' }
[cds] - connect to messaging > file-based-messaging { file:'~/.cds-msg-box' }
[cds] - mocking ReviewsService { at:'/reviews', impl:'./../reviews/srv/reviews-service.js' }
[cds] - serving CatalogService { at:'/browse', impl:'./../bookshop/srv/cat-service.js' }
[cds] - serving AdminService { at:'/admin', impl:'./../bookshop/srv/admin-service.js' }
[cds] - connect to OrdersService > odata { url:'http://localhost:4006/orders' }

[cds] - server listening on { url:'http://localhost:4004' }
[cds] - launched at 09/12/2021, 21:16:49, in: 2.853s
[cds] - [ terminate with ^C ]

Open the fiori-apps.html application.

Extensibility is set up for authors, so switch over to the Manage Authors page and open the detail page of Emily Brontë.

Open the Adapt UI Tool.

Open the context menu on any input field and follow the + button.

In the following dialog, a CAP-specific + button opens the CAP field extension tool.

Fill out the form to create a new extension field. Following Create, the UI will reload.

Open the Adapt UI Tool again to add the newly created field to the UI.

After saving and exiting the Adapt UI mode, the new field is visible in the UI and also shows a default value if it was specified.

Enable for CAP ​

CAP has added a new aspect, called extensible in @sap/cds/common. This aspect provides the necessary plumbing for simple field extensibility. Add this aspect to any entity in your schema to enable extensibility for all services exposing it without any additional work.

To enable the underlying technology, please add the following to your package.json:

"cds": {
   ...
    "requires": {
      ...,
      "extensibility": "uiflex"
      ...
    }
  }
...

In your data model, for example schema.cds, add the aspect extensible to the entity that you want to be extensible.

using { localized,Currency,managed,extensible } from '@sap/cds/common';

entity Authors : managed, extensible {
  key ID : Integer;
  name   : String(111);
  dateOfBirth  : Date;
  dateOfDeath  : Date;
  placeOfBirth : String;
  placeOfDeath : String;
  books  : Association to many Books on books.author = $self;
}

Deploy to your file-based SQLite database using cds deploy --to sqlite.

Behind the Scenes ​

With simple field extensibility turned on in your package.json, a new service and an action are added to the application to accept field extensions at runtime. While the API accepts any valid CSN snippet, only simple field extensions are allowed for the time being. The simple field extensibility in CAP is using property-bags. Property-bags are generic attachments to base entities, that can accept content for multiple extensions without changes to the underlying database schema. The aspect extensible is adding this property-bag to an entity, and the property-bags are automatically merged to the rest of the model.

Enable for UI5 ​

The following changes have to be made for all UI applications that you want to enable for key-user extensibility.

To turn on the Adapt UI tooling, each UI application needs to add the following in their respective entry HTML page:

This is typically the index.html in the app Folder

<script>
window["sap-ushell-config"] = {
  defaultRenderer: "fiori2",
  applications: {
    ...
  },
  bootstrapPlugins: {
    RuntimeAuthoringPlugin: {
      component: "sap.ushell.plugins.rta",
      config: {
        validateAppVersion: false,
      },
    },
    PersonalizePlugin: {
      component: "sap.ushell.plugins.rta-personalize",
      config: {
        validateAppVersion: false,
      },
    },
  },
...
};
</script>

At the same place, the UIFlex session storage should be configured as UIFlex target for local development:

<script>
  sap.ui
    .getCore()
    .attachInit(() =>
      sap.ushell.Container.createRenderer().placeAt("content")
    );
  sap.ui
    .getCore()
    .getConfiguration()
    .setFlexibilityServices([{ connector: "SessionStorageConnector" }]);
</script>

In each manifest.json of the application that should allow key-user extensibility, add the sap.ui5.flexEnabled and sap.ui5.config.experimentalCAPScenario parameter as follows:

"sap.ui5": {
  "flexEnabled": true,
  ...,
  "config": {
    ...,
    "experimentalCAPScenario": true,  // temporary workaround until @extensibility vocabulary is finalized
    ...
  },
  ...
}

As a fallback to this manifest parameter, also the following URL parameter: sap-ui-fl-xx-capScenario=true can be used to enable key-user extensibility on the fly within the home page:

http://localhost:4004/admin-fiori.html?sap-ui-language=en&sap-ui-fl-xx-capScenario=true#Shell-home

Current Limitations ​

• Only works locally using cds watch.
• Extensions cannot be altered or deleted. Redeploying the database will erase all extensions to start over.
• No Export or Transport of extensions to other systems and also no activation into productive mode.
• Needs to be deployed to a file-based SQLite database. An in-memory setup would erase all extension fields upon restart.
• Filtering or sorting extended fields is not possible.
• Only available for the Node.js runtime.
• The server restarts automatically after each successful extension. This makes it unsuitable for productive use or cloud-based deployment.