Incorporating Common Reuse Aspects

Let us now explore how the definition of entities can be enhanced with new elements using so-called aspects.

Watch the video to learn about CDS aspects.

In this lesson, we will learn about the extend directive. We will discuss the annotate directive later in another lesson.

Using the extend directive you can add extension fields to existing definitions as shown in the following figure:

In the example, element someAdditionalField is added to the Authors domain entity. This also adds this field to the generated database table.

With the extend directive, metadata such as annotations can also be added to existing definitions or existing metadata can be overwritten.

Type properties can also be set via extend. For example, the length of an existing element of type String can be increased.

You can use extend with predefined aspects to apply the same extensions to multiple targets, as shown in the following figure:

The example shows a named aspect ManagedObject that defines the two elements createdAt and createdBy. Both the Books and the Authors entity are extended by these fields via this named aspect.

A named extension can contain anything, such as fields, types or entities.

You can also use named aspects as includes in an inheritance-like syntax. This syntax allows you to extend a definition with several named aspects at the same time. In the following figure, the Authors entity is extended by the two named aspects ManagedObject and AnotherAspect.

Includes are syntactical sugar. The example shown is equivalent to using a sequence of extends as follows:

1234567
entity Authors {}
extend Authors with ManagedObject;
extend Authors with AnotherAspect;
extend Authors with {
  key ID : UUID;
  ...
}

CDS ships with a pre-built model @sap/cds/common that provides common types and aspects for reuse.

It is recommended that all applications use the common types and aspects provided through @sap/cds/common. This allows you to benefit from best practices learned from real business applications.

In the following section, we will take a closer look at the two aspects cuid and managed from @sap/cds/common. Later we will also discuss the CodeList aspect and the Country and Currency types from this model.

The cuid aspect is a convenient shortcut that allows you to add canonical, universally unique primary keys to your entity definitions.

The managed aspect can be used to add the four fields createdAt, createdBy, modifiedAt and modifiedBy to an entity. These fields are used to track who created and updated data records and when.

By using this aspect, you can store the relevant record-related management information and still keep your core domain model clean and comprehensible.

The fields createdBy and modifiedBy have the data type User, which is a common reuse type from @sap/cds/common.

The annotations @cds.on.insert and @cds.on.update used in the aspect denote elements that are automatically filled in by the generic handlers when inserting and updating.

The pseudo variables used in these annotations are resolved as follows:

• $now is replaced by the current server time (in UTC)
• $user is the ID of the current user as received from the authentication middleware

To be able to use aspects from the @sap/cds/common model, you must import them via the using directive. In the following figure, for example, this is done for the common reuse aspects cuid and managed via the ES6-like deconstructor variant of using.

The two imported aspects are used as includes in the example to extend the Authors entity with the corresponding fields. Without the two predefined aspects, the following definition of the Authors entity would be required to achieve the same outcome as in the example shown using native means:

123456789101112
entity Authors {
  key ID: UUID;
      createdAt   : Timestamp @cds.on.insert: $now;
      createdBy   : User      @cds.on.insert: $user;
      modifiedAt  : Timestamp @cds.on.insert: $now  @cds.on.update: $now;
      modifiedBy  : User      @cds.on.insert: $user @cds.on.update: $user;
      name        : String(100);
      dateOfBirth : Date;
      dateOfDeath : Date;
      books       : Association to many Books
                        on books.author = $self;
}

Watch the video to see how to use pre-defined aspects.