Adding Custom Logic

As most standard tasks and use cases are covered by generic service providers, the need to add service implementation code is greatly reduced and minified.

The remaining cases reduce to real custom logic, specific to your domain and application, such as domain-specific programmatic validations.

As an example, let's program a validation that ensures that the date of birth passed is before the date of death passed when creating a new author via the AdminService.

The easiest way to add custom service implementations is to simply place an equally named .js file next to the .cds file containing the respective service definition. I.e. in our case we place a file named admin-service.js in the srv folder of our project, as this folder also contains the file admin-service.cds, which is used to define the AdminService (see following figure).

There are different ways to implement the required custom logic in the .js file. The most common way is to use a subclass of cds.ApplicationService to benefit from generic out-of-the-box implementations. This is because the cds.ApplicationService class is the default service provider implementation, which adds the generic providers already discussed to a service definition.

To create a subclass of cds.ApplicationService, we first assign the @sap/cds module to the constant cds in our code (line 1). The @sap/cds module is the cds facade object that provides access to all CAP Node.js APIs.

We then create a subclass of cds.ApplicationService in lines 4 to 6, in which we will later implement our custom logic. The name of the subclass is arbitrary. We call it here like our service interface, i.e. AdminService.

In line 9, we make the AdminService class available for import into other modules. This is common practice in Node.js to structure code.

[cds] - serving AdminService { path: '/admin', impl: 'srv/admin-service.js' }

Custom service implementations are carried out with the help of custom event handlers, whereby a distinction is made between different types of handlers.

Watch the video to get an overview of the different event handlers.

For the validation we want to implement, we need a before handler that should be registered for CREATE and UPDATE operations on the Authors entity.

To register custom event handlers, overwrite the inherited init() method in the created implementation class (see following figure). Do not forget to call super.init() in the implementation to allow subclasses to register their handlers.

To register a before handler in the init() method, call the inherited before() method via this.before(). To do this, you must supply the following interface. A detailed description of the individual parameters can be found in the CAP documentation:

12345
function before (
  event : string | string[] | '*',
  entity? : CSN definition | CSN definition[] | string | string[] | '*',
  handler : function
)

In the example shown, the named function this.validateLifeData is registered for CREATE and UPDATE operations on the Authors entity. We will discuss the implementation of this function later.

The entity or entities for which the registration is to take place can be passed to the before() method as string. However, it is recommended to pass CSN definitions here instead. The CSN definitions of the entities that are exposed via the service are conveniently made available via the this.entities property.

In the example shown, the required CSN definition for the Authors entity is assigned to the Authors constant via a destructuring assignment.

Finally, let's take a look at how the validateLifeData function that has been registered as a before handler can be implemented on the AdminService class.

Before handlers generally receive a single argument, an instance of cds.Request. This instance provides properties and methods that can be used to implement the handler. In the example, we have named the argument req (see following figure).

For CREATE and UPDATE requests, which we are concerned with here, the data property of the interface parameter contains the HTTP body of the request. We use a destructuring assignment to assign the passed values from the HTTP body to the constants dateOfBirth and dateOfDeath.

If the date of death is before the date of birth, we issue a corresponding error message via the req.error() method.

Watch the video to see how to provide a .before event handler.