Skip to content

    March 2020

    @sap/cds 3.33, @sap/cds-dk 1.7, 1.4.0

    Welcome to the March 2020 release of the CAP framework. This release is primarily a quality and consolidation release. We invested much in improving our tests to minimize regressions.

    See also: Latest Changelog

    Important Changes❗️

    cds build Uses New Build System

    The cds build command now delegates to the new build system by default (known as cds build/all).

    The new build system is compatible, but supports additional features, for example:

    • Staging build
    • SAP HANA Cloud Edition support
    • Populating initial data from .csv by generating .hdbtabledata files

    Docs and Samples

    Find below a list of changes and improvements to the capire docs and to cap/samples. These are another major steps in our quality focus early 2020. There’s much more to come → stay tuned…

    Revamped and Reloaded cap/samples

    • cap/samples received a comprehensive cleanup and overhaul, including simplified monorepo setup, improved organization of sub projects, a bookshop with a Vue.js app, and much more…

    Revised Getting Started & Resources

    New and Revised Guides in Cookbook

    New Reference Docs

    Command Line

    Integrate and Mashup with cds watch

    As a bonus, cds watch detects whenever you add an .edmx file to your project in whatever place and automatically triggers cds import to convert them to CSN.

    Get an .edmx file from the SAP API Business Hub, in the Details tab of an API description, to test it.

    Drag-and-drop the .edmx file to your Visual Studio Code window.

    Start Service in Watch Mode

    Use the option --watch on a specific service with command cds serve to start that specific service in nodeman watch mode.

    List All Dependencies of Your Local package.json

    Use cds version --all to list all dependencies of your local package.json. See the CLI command help for more information.

    CDS Editors & Tools

    The following features are available for all editors based on our Visual Studio Code extension for CDS in SAP Business Application Studio and Visual Studio Code. The extension for Visual Studio Code is available for download at the SAP Development Tools page.

    Installation of CDS Development Kit

    The Visual Studio Code extension for CDS detects missing or outdated installation of CDS development kit.

    Select to install the CDS Development Kit:

    Select to update the CDS Development Kit:

    Enable Installation Check:

    CDS Language & Compiler

    Documentation Comments

    If comments of the form /**...*/ appear at positions where annotation assignments are allowed, use option --docs in cds compile to preserve them.

    Documentation comments are propagated like annotations until an empty comment /***/ disrupts the propagation. The documentation comments appear as doc properties in the CSN and in the OData/EDMX, it appears as a value for the annotation @Core.Description.

    /** This is an example for a doc comment */
    entity Foo { key ID:UUID; ... }
      "definitions": {
        "Foo": { "kind": "entity", "doc": "This is an example for a doc comment", ... }


    The compiler supports function calls like count( distinct ... ) and count( all ... ).

    New Option --clean

    Use cds compile --clean to return a CSN, which reflects only what was found in a .cds source. The compiler doesn’t add any derived information.

    Node.js Runtime

    Important Changes❗️

    On SAP HANA with multitenancy enabled (multiTenant: true), the users are being authenticated regardless of whether authorization annotations (@requires/@restrict) are used. The reason is that the user’s identity zone is required to determine the respective HDI container. In production mode, this requirement is now enforced. In development mode, the developer needs to make sure to fulfill this requirement.

    In previous versions, $count=true triggered handlers to be executed twice. This led, for example, to WHERE conditions from security annotations being appended twice. Now, the usage of $count=true triggers handlers only once, so custom handlers that accommodated this behavior might have to be adapted. The resulting array of the original query has a new property $count. Make sure that this property is not lost when you return the result in your custom handlers.

    The req.user object represents the currently logged in user.

    The annotations @FieldControl.Mandatory, @Common.FieldControl.Mandatory, and @mandatory now enforce that empty strings and strings with only whitespaces are rejected as input. Previously only null and undefined were checked.

    Convenient Access to express Request Object

    The req._ object contains the original req and res objects as obtained from express.js. This is now also the case for $batch requests.

    Localized Data - Access to Default Values

    It’s now possible to prevent automatic redirection to the localized views for localized entities with the @cds.localized:false annotation.

    Ordered OData Singletons

    In the CDS model, it’s now possible to order OData Singletons: ... as select from <entity> order by <property>.


    • Enhanced Fiori draft support, see Fiori Support
    • The pool acquire timeout is now set to a default (5,000ms on SQLite and 10,000ms on SAP HANA) and can be configured in the pool options with acquireTimeoutMillis.

    • Functions and properties are now allowed as second parameter in contains, startswith, and endswith.

    • OData requests using $count on navigation-to-many are now supported.

    • OData requests using $count on parameterized views are now supported.

    • INSERT.entries now supports different columns combinations.

    • Support for count in SELECT CQN.

    • @cds.persistence.skip is now also evaluated for deep operations to annotated child entities.

    Java Runtime

    Important Changes❗️

    @mandatory annotated elements of type String now also reject any trimmed empty strings.

    Entities annotated with @cds.autoexpose are now read-only if referenced as root entity in a CQN statement. This policy doesn’t apply if the entity is draft-enabled or explicitly mentioned in the service definition.

    Build Improvements

    • Save time and use a globally installed cds-dk when building your application by using the cdsdk-global profile:

      mvn spring-boot:run -P cdsdk-global
    • When creating new projects with the CAP Java Maven archetype, the cds-starter-cloudfoundry dependency is automatically added.

    • EventContext interfaces for types used in OData actions and functions, which make accessing input and output parameters much more convenient. Newly generated projects now support EventContext interfaces by default. Add this feature to your existing project manually by adding the following to your CDS4J maven plugin configuration:


      For example, consider the action review defined in the following CDS model:

      entity Books {
        action review(stars: Integer) returns Reviews;
      entity Reviews {
          book : Association to Books;
          stars: Integer;

      You can now use type names that you defined in the CDS model directly in your custom code. Hence, the generated type ReviewContext allows you accessing the input value via getStars(). In addition, you can use the generated type Reviews to set the result:

      @On(entity = Books_.CDS_NAME)
      public void review(ReviewContext context) {
          int stars = context.getStars();
          Reviews review = [...]

    Deep Update

    Allows to update a single entity including its associated entities. In contrast to a deep upsert (replace), deep update has patch semantics. Elements that aren’t contained in the update data keep their old value.

    For to-many compositions or associations, the provided list of entities has to be complete, entities that aren’t in the list will be removed and in case of compositions also deleted. See also Java > Query Builder API > Deep Update.

    Spring Framework Integration

    • Use Spring health-check actuators with multitenancy turned on. At each call, the health of each connected HANA database is checked.
    • We now support a Spring actuator returning CDS-related debugging information. Get, for example, version, registered event handlers, and service instances at endpoint <basepath>/actuator/cds. Activate this endpoint by adding the value cds to the property management.endpoints.web.exposure.include in your application configuration, for example:

      management.endpoints.web.exposure.include: info,health,cds

    OData V4

    • We added a configuration switch cds.odatav4.contextAbsoluteUrl. This switch controls if the URL in the @context field of OData V4 responses contains a relative or an absolute path. The default of this property is false (relative path).
    • We improved the startup performance. OData vocabulary files used for validation purposes aren’t loaded during startup anymore.


    • Enhanced Fiori draft support, see Fiori Support
    • The whitelist for normalized locales is now configurable by means of the property cds.locales.normalization in the application configuration, for example:
        defaults: true  # Keep default whitelist as documented in capire 
        whiteList:      # These locales are added to the default whitelist
          - "zh_CN"
          - "zh_HK"
    • .csv files (for example, configuration data) are loaded during startup from either db/data or db/csv folders. To load .csv files is enabled by default for the in-memory SQLite database.

      You can control this behavior further by setting cds.datasource.csv-initialization-mode in your application configuration to either always or never load data. always enables loading of the CSVs regardless of the database type. never turns it off completely.

    • Reactivated tests integrating PostgreSQL DB, nevertheless CAP won’t support PostgreSQL out of the box. More details when setting up PostgreSQL for own purposes are collected in section PostgreSQL.

    Bug Fixes

    • The locales 1Q and 2Q are now handled correctly.
    • $search doesn’t lead to duplicate search results anymore.
    • Fixed a malformed OData response, containing an incorrect @context property instead of @odata.context.
    • XSUAA user names are now normalized by converting them to lower case when persisting. This behavior can be turned off by specifying false in the application configuration.
    • Batch request the Authorization header is now propagated from the parent batch request to child requests. This only affects the visibility of the Authorization header through the ParameterInfo interface.
    • Fixed a bug the prevented to use SAP UI5 versions greater or equal than 1.75.0 by returning the complete structured entity when saving a draft.

    Fiori Support

    Draft for Localized Data

    The compiler supports draft-enabling entities with localized elements.

    To make the generated _texts-entities draftable, additionally annotate the source entity with @fiori.draft.enabled - more details on the usage and the implications can be found in Advanced > Serving Fiori UIs.

    Fiori Drafts with Locks

    Edited draft data is now restricted to the user who created the draft. This also applies to delete and cancelling drafts.