Search

February 2020

@sap/cds 3.31, @sap/cds-dk 1.6, cds.java 1.3

Welcome to the February 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 as well as introducing new release procedures and new release notes.

With this release, it’s the first time we formally document, and therefore officially release things that have been around before, without being announced. Hence, in the following you find an unusual comprehensive list of news.

See also: Latest Changelog


Important Changes❗️

Open SemVer Ranges in Node Dependencies

Node.js Version

CDS no longer supports Node.js 8.x, as this version is now out of maintenance.

Check with node --version that you don’t use Node.js 8.x. If you still have Node.js 8.x installed, uninstall it and install a newer version, preferably Node.js 12.x.

New Release Procedure

Starting with this release, we adjust our release process as follows:

New Release Notes

Also starting with this release, we introduce new release notes as in this format, which we hope gives you a better overview of what’s new, structured by logical packages. You should always pay attention to the Important Changes sections in there.

New Changelogs

Finally, from now on you always find a combined up-to-date changelog for all CAP packages at Releases - Changelog. The first page contains all changes of all releases of the current year. Older changelogs are available through appended links.

See also…

Enterprise Features

Localized Data

The CDL keyword localized allows to mark entity elements that require translated texts. For more details, see Cookbook - Localized Data.

Temporal Data

The new aspect temporal allows marking an entity as logical records of information for which changes are tracked over time as time slices with from/to boundaries. For more details, see Cookbook - Temporal Data.

Managed Data

Use the annotations @cds.on.insert and @cds.on.update to signify elements to be auto-filled by the generic handlers. For more details, see Cookbook - Generic Providers - Managed Data

Command Line

Update your cds-dk: npm i -g @sap/cds-dk.

Jumpstart with cds init

Use cds init to start new projects. The command’s implementation has been cleaned up and streamlined to only do the most necessary setup. For example, there’s no automatic npm install anymore, Java projects anyways should never need that.

cds init has been moved to @sap/cds-dk now.

Legacy: The former implementation had numerous other options, which we removed, yet you can restore them if needed short term. Just invoke cds init with one of these removed options to get instructions how.

Grow as you go with cds add

The newly added command cds add allows to add new features to an existing project gradually, only when you need them. Currently supported are:

cds add hana      # adds configuration for SAP HANA deployment
cds add mta       # adds an mta.yaml file out of CDS models and config
cds add pipeline  # adds files for CI/CD

Accelerate with cds watch

Use cds watch to start a cds server, even in a newly created and yet empty project. Whenever you feed your project with new content, for example, by adding or modifying .cds, .json, or .js files, the server automatically restarts to serve the new content. — Happy feeding.

Use cds compile with --log-level option

The newly added option --log-level allows to choose which messages to see. For example, use it as follows:

cds compile srv --to sql --log-level warning #> also the default
cds compile srv --to sql --log-level error
cds compile srv --to sql --log-level info

CDS Editors & Tools

The following features are available for all editors based on our language server implementation for CDS in SAP Business Application Studio, Visual Studio Code, and Eclipse. The plugins for Visual Studio Code and Eclipse are available for download at https://tools.hana.ondemand.com.

Code Formatting

Use the code formatting options, to beautify your code during the whole process or after you finished writing your code. This helps you and other contributors to have clean and consistent code throughout your project.

Code Snippets

We added additional Code Snippets for entity and extend to the code completion. You get suggestions, reflecting the recent syntax and can add them using the code completion of your IDE.

i18n Support

You can explicitly enable design-time support for translation.

Translation support includes quick fixes and direct navigation to translation.

Supported Files: .properties, .json, .csv

For translation support at design-time, use your settings from the .cdsrc.json file. This file can contain information on the basename, folder, default language, fallback language.

CDS Language & Compiler

Important Changes❗️

SAP HANA-Specific Data Types

You can now specify native SAP HANA data types in CDL. For example:

entity Foo {
    coord : hana.ST_POINT;
}

Learn more in CDS - Definition Language - Predefined Types

This is not yet supported by the Node.js and Java runtimes.

Preview: Streamlined Compiler Implementation

We streamlined the implementation of several compiler functions, especially compiler backends such as 2sql and 2edmx, which significantly improves performance, e.g. up to factor 10 in several scenarios. As this improvement isn’t yet the default, you can check it out by prepending CDS_FEATURES_SNAPI=y to your cds commands. For example:

CDS_FEATURES_SNAPI=y cds watch   # speed up dev turn-around times
CDS_FEATURES_SNAPI=y npm test    # speed up your tests

Auto-exposed Association Targets

If a service exposes an entity and uses an association to refer to another entity, use @cds.autoexpose to automatically expose this entity. This is especially valuable for code list entities to be used in Fiori value helps.

Learn more in CDS - Definition Language - Auto-Exposed Targets See also @sap/cds/common - Code Lists

Auto-Redirection

When exposing related entities, associations are automatically redirected. If there’s no clear redirection target, redirected to can be used to explicitly define one.

When associations are redirected, the on condition (and foreign key specification) is automatically adopted to reflect renamed element in the new association target. For complex cases, it’s also possible to explicitly provide an on condition.

Learn more in CDS - Definition Language - (Auto-) Redirected Assocations

extend projection

Use extend projection to extend the projection of a view entity to include more elements existing in the underlying entity.

extend projection Foo with {
  foo as bar @car
}

Learn more in the CDL Reference documentation

extend with <named aspect>

extend can now be used to extend an entity with a named aspect instead of anonymous inline aspects only as before.

 extend Foo with Bar;

Learn more in the CDL Reference documentation

Association Filters

The compiler now supports association filters. An association filter is an ‘adhoc’ extension to the defined ON condition of the association. This allows, for example, to express join-like things in a simple and elegant way:

entity E {
    key id: Integer;
};

entity F {
    key id: Integer;
    field1: Integer;
};

view V as select from E JOIN F on E.id = F.id and F.field1 > 3 {
    E.id,
    F.id as F3id
};

This can be expressed with filters like this:

entity E {
    key id: Integer;
    toF: Association to F;
};

entity F {
    key id: Integer;
    field1: Integer;
};

view V as select from E {
    id,
    toF[field1 > 3].id as toF3id
};

Node.js Runtime

Important Changes❗️

This version brings a major refactoring and streamlining of service runtime implementations, which stays fully compatible regarding all documented APIs but in case you used internal not documented (non-)APIs, you have to know these changes:

Removed undocumented features:

It’s unlikely that you ever used these undocumented internal features at all. In case you did use these features, you need to fix that immediately.

Deprecated features (→ might get removed in upcoming versions):

These properties actually were duplicates to the mentioned alternatives.

Also take note of the following changes:

Streamlined and Optimized Bootstrapping

Both the implementation of bootstrapping functions like cds.serve() and cds.connect() as well as the corresponding CLI commands have been thoroughly refactored and optimized to avoid loading models redundantly, thereby drastically improving both, bootstrapping performance as well as memory consumption.

Support for local ./server.js

cds serve now optionally bootstraps from project-local ./server.js or ./srv/server.js. This option gives you more control while you can still benefit from cds serve options like --in-memory or --with-mocks.

Within your local ./server.js you can delegate to the default server.js implementation shipped with @sap/cds. For example:

// local ./server.js
const cds = require('@sap/cds')

cds.on('bootstrap', (app)=>{
  // add your own middleware before any by cds are added
})

cds.on('listening', ()=>{
  // add more middleware ...
})

module.exports = cds.server // delegate to default server.js

Support for .env files

In addition to providing process environment variables in default-env.json, your can now also profide them in .env files in .properties format. For example:

# .env file
CDS_FOO_BAR = foobar
cds env  #> prints:
foo.bar = foobar

Mocking Required Services

For more details, see Getting Started - Grow As You Go - Using Mock Servers

Local Services

It’s possible to connect to locally running services using cds.connect.to.

For more details, see Node.js - APIs - cds.connect

Media Types & Streaming

Elements of an entity can be annotated to indicate that they contain media data. The runtime offers generic streaming support for reading and creating/updating/deleting such resources.

For more details, see Generic Providers - Serving Media Data

Deep Reads & Deep Updates / Upserts

Structured documents represent the concept of relationships between entities, which can be modeled using compositions and associations. The runtime provides generic handlers for structured documents, covering DEEP READ (using $expand) as well as DEEP INSERT, DEEP UPDATE, and DEEP DELETE for compositions.

For more details, see Generic Providers - Serving Structured Data

ETag-based Conflict Detection

You can enable optimistic concurrency control using ETags by applying the @odata.etag annotation.

For more details, see Generic Providers - Serving Structured Data

Miscellaneous

Java Runtime

Important Changes❗️

OData V4 Support

We support OData V4 by default. Recently, we added the following features:

Filtering

We extended the support for filter capabilities (functions like in, add, sub, mul, and div), including support for null and path expressions in filters. In addition, $filter now supports the contains, startsWith, endsWith, and substring functions. You can also make use of the functions tolower and toupper in $filter expressions. For more details, see Query Builder API - Expressions.

Searching

We also support searching entities by means of the OData V4 $search parameter (including search expressions AND, OR, and NOT), see Query Builder API - Filtering.

Authentication and Authorization

We support authentication and authorization using @require and @restrict annotations. For more details, see Java - Security.

Fiori Draft Support

You can now use associations to other draft-enabled entities. This enables path expressions to the inactive entity via the active entity and vice versa. Also in draft, compositions of second grade or higher for draft-enabled entities are supported.

Service Consumption API

With the Service Consumption API, we provide a facade around services and their events.

CAP Java and Spring Boot

We have native Spring Boot integration in place, and in fact, this is now our default. For more details, see Java - Getting Started and Java - Stack Architecture. This enables you to make use of Springs autowiring and Spring Boots autoconfiguration features. In addition, if you want to make use of Spring’s transaction management, this is integrated as well.

Response Messages

You can make use of the Messages interface to return localized response messages. By modifying the sap-message header, you can influence the way error and info messages are shown in a Fiori UI. It’s also possible to return multiple messages in a single response.

Model Reflection API

Using the Model Reflection API, you can introspect the CDS model of an application and retrieve details on the services, types, entities, and their elements. For more details, see Model Reflection API. Additionally, supported are: events, bound and unbound actions and functions, and Arrayed Types.

Query Builder API

Using the Query Builder API, you can fluently construct CDS Query Language (CDS QL) statements, which can be handled by the persistence service or, on a lower level, be executed by the data store. For more details, see Query Builder API.

Support for mocking application users to use authorization in local development.

Deep Reads & Deep Updates / Upserts

We started to make deep upserts available. To start using deep upserts. For more details, see Query Builder API - Upsert. Feel free to make an update with key values in data instead of where condition. For more details, see Query Builder API - Update.

Miscellaneous

Fiori Support

Fiori Preview

Add annotations to your model and quickly visualize the outcome.

This is only a preview and not a toolset from SAP Fiori.

Database Support

Streamlined cds deploy

cds deploy –to hana

cds deploy –dry

cds deploy –with-mocks

( → learn more about these things using cds help ... )

Auto-Generated .hdbtabledata

The effort of adding an .hdbtabledata manually to your imported data (.csv files) is now taken care of by the build and deployment process, for example, in cds deploy --to hana.