Category: SAP

Preface – This post is part of the SAP CAPM series.

Introduction

In previous articles we have defined modeling in CAP, learnt Defining Services in SAP CAP and performing operations on SAP CAP Services. In this article we will learn Consuming Services in SAP CAP.

Consuming Services in SAP CAP

To keep the consumption of services uniform irrespective of the type of service being consumed, CAP provides a generic paradigm.

const srv = cds.connect.to('some-service')

// could be any of...

// - local service

// - remote service client

// - database client

let query = SELECT.from(Books).where({ID:111})

let books = await srv.run (query)

 

The above code snippets can be demonstrated as following:

Note: CAP treats even Database as a service which eventually enhances the database interaction with the help of generic event handlers.

Types of Service Consumption

• Event-Based Consumption

The local services can be accessed by Node.js event emitter asynchronously and directly. But to access the external service, we will have to configure the package.json or .cdsrc.json file. We can also enable the Enterprise messaging¹ by setting the property kind as “enterprise-messaging”.

Example:

{ 

"cds":

    {   

    "requires":

        {     

        "my.external.Service":

            {       

            "kind": "enterprise-messaging",       

             "credentials": {       

               "namespace": "my/custom/namespace"    

                 }  

           }   

     } 

  }

}

In case we want to enable Enterprise Messaging for all the external and internal services, then we will define the configuration under “messaging” section, the same is shown below:

{ 

"cds":

{ 

   "requires":

{

      "my.external.Service":

{

        "kind": "odata"     

},

      "messaging":

{       

"kind": "enterprise-messaging",

        "credentials":

{

          "namespace": "my/custom/namespace" 

       }

      }

    }

  }

}

In case, you just want the local service to be enabled for Enterprise Messaging, it should be mentioned under the section cds.provides.

Example:

{  "cds": 
 {    
   "provides": 
 {      
    "my.own.Service": 
 {        
   "kind": "enterprise-messaging"
      }
    }
  }
}

 

• HTTP-Based Consumption

To consume external service in SAP CAP, we need to define it under Destination Service².

In the package.json or in the .cdsrc.json the consumed service needs to be configured with the following:

• Destination:Name of the destination (optional)
• requestTimeout: ms until a request times out Default is 60,000 ms (optional)
• model:The CSN³ model of the external service
• poolConnections to the external service are pooled to prevent DOS-Attacks (optional)

 

Example:

{  "cds": {    "requires": {      "externalService": {        "kind": "rest/odata",        "model": "path/to/model",        "credentials": {          "destination": "destinationName",          "requestTimeout": 30000        },        "pool": {          "min": 1,          "max": 10        }      }    }  }}

If the external service is further extended to used by some other application, then its parameters can be mentioned under credentials section, as below:

{  "destination": "destinationName",  "url": "...",  "username": "...",  "password": "..",  "requestTimeout": 30000}

Sending Requests

Simple examples for reading data (works also for create, update, and delete):

// Connect to external serverconst srv = cds.connect.to('my.external.service')const { Authors } = srv.entities // share request context with the external service// inside a custom handlerconst tx = srv.transaction(req) // url string inputconst response = await tx.get('/Authors?$select=name') // CSN entity input and fluent query APIconst response = await tx.read(Authors).where('ID', 1) // CQN input from fluent query APIconst cqn = SELECT.from(Authors)const response = await tx.run(cqn)

 

Adding Event Handlers

We can add event handlers while consuming a service. This will help us to perform specific tasks on success and failure of the service consuming operation. To handle errors, you can register an .on.error(() => {…}) handler.

There are two ways to handle the events:

1. By specifying the event name

Example:

const srv = cds.connect.to('my.external.service')srv.on('myEvent', msg => console.log(msg.data))srv.on(['myEvent', 'myOtherEvent'], msg => console.log(msg.data))srv.on('myBoundEvent', 'myEntity', msg => { 
   if (msg.data.age < 18) 
{
      throw new Error('Cannot handle this event.')    
}
})

2. By specifying the topic directly

Example:

const srv = cds.connect.to('my.external.service')srv.on.error(err => { // handle error})

Emitting Events

To emit events, you can use the .emit method described in srv.emit.

There are two ways to create Emits:

1. By specifying the event name
2. By specifying the topic directly

Example:

const srv = cds.connect.to('my.external.service') srv.emit('myEvent', {some: 'payload'})srv.emit('myBoundEvent', 'myEntity', {some: 'payload'})srv.emit('my/custom/namespace/my/custom/topic', {some: 'payload'})srv.emit('topic:myCustomTopic', {some: 'payload'})srv.emit('myEvent', {some: 'payload'}, {some: 'headers'})

Best Practises related to Service Consumption:

• Make sure, that destination configurations for deployment aren’t shared on any file shares
• There are different types of messaging instances, use only enterprise-messaging for production environment
• It is good to provide the destination name, else the runtime will look for the name of the configured data source i.e. externalService in previous example
• To connect to an external service, connect.to should be used
• As of now only CRUD operations can be performed using send requests. And only Read all, read single can be performed using send requests. No query like filtering or ordering is supported for send request operations
• An Enterprise Messaging service creates a queue⁴ for every request and in case it is unused, it must be removed from the SAP Cloud Platform manually

Preface – This post is part of the SAP CAPM series.

Introduction

In previous article we have explored the ways to define services in SAP CAP. In this article we will learn about the operations on Services in SAP CAP.

Operations on Services in SAP CAP

1. Ignoring fields from Services: We can ignore fields using annotation @cds.api.ignore
2. Adding Action and Functions: We can directly call a function/action, like we have used cancelLeave above, by mentioning it in node.js while calling the service. This can be done in two ways:
   1. Unbound action: For this type of actions, we mention the action in the service itself

srv.on('cancelLeave', (req) => {

// do something ...

})

 

1. Bound action: For this type of actions, we mention the action at entity level. It means, we will have to mention the name of the entity during the call

srv.on('getEmployeeCount', 'Employees', (req) => {

// do something ...

})

 

 

Preface – This post is part of the SAP CAPM series.

Introduction

A service or a metadata service is used to define the data and its structure. It includes all the data models with annotation as well as associations and navigations. In this article we will explore more about Defining Services in SAP CAP.

Defining Services in SAP CAP

In CAP, we have already defined multiple entities with association. Later we have added annotations too using Aspects. In service definition, we write all the entities within another entity and give it the name of a service. Here we have created a service in file “service.cd”.

entity EmployeeService {

enity Employee {

key ID : UUID;

name  : String;

Role : Association to Manager;

}

entity Manager {

key ID : UUID;

name   : String;

Role  : Association to many Role on Employee.Manager = $self;

}

}

 

To separate the entity sets from the service, unlike the example mentioned above, we will call the domain modals in our services. Hence, all the models will be as usual defined within a model cds e.g.  schema.cds and then it would be called from a Service using CQL (CAP Query Language).

Example:

using { empInfo as info } from 'db/schema';




entity EmployeeService{




entity Employee as SELECT from info.Employees{ *,

Employees.firstname ||' '|| Employees.lastname as name : String,

manager.name as manager,

} excluding { salary, currency};

entity Manager as projection on empInfo.Manager

where Manager.Department = 'IT'

order by name;

}

 

It is recommended to use one service per use case. It helps us to maintain proper authentication and checks.

Example:

using { empInfo as info } from './db/schema';

/** Serves end users browsing Employee and Insert Employee Details */ 

service EmployeeService{

@readonly  entity Employee as SELECT from info.Employees{ *,

firstName, lastname

};

@requires: 'authenticated-user'@insertonly entity Salary as projection on info.Salary;




}

/** Serves registered users managing their salary and leave */

service UsersService {

@readonly entity Salary as projection on info.Salary

where EmployeeID = $user; // limit to own ones

action cancelLeave ( ID: Salary.ID, reason:String );

}




/** Serves administrators managing everything */

@requires: 'authenticated-user'

service AdminService {  entity Employee   as projection on info.Employees;

entity Salary as projection info.Salary;

}

 

Preface – This post is part of the SAP CAPM series.

Introduction

A Domain Model in SAP CAP is a model which describes the static, data-related aspects of a problem domain in terms of entity-relationship models. In this article we will study the Domain Modelling in SAP CAP in detail.

Domain Modelling

In simple words, a CDS in SAP CAP produces domain model in such a way that it defines the business problem in terms of keys, fields and annotations. The code to generate a domain model is written in a CDS schema (db/schema.cds). These domain models can be used in Service Definitions, Persistence Models, Databases or even reused within another domain model.

Sample Example:

Namespace empInfo;

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




entity Employees: managed {

key ID: Integer;

firstName: localized String (111);

lastName: localized String (1111);

manager: Association to Managers;

dateofJoining: Integer;

salary: Decimal (9,2);

currency: Currency;

}

 

In this example we have created a file schema.cds where we have created an entity Employees which includes basic details of an Employee

This whole schema has been given a namespace i.e. empInfo

This schema uses a standard data type i.e. Currency. Using the standard data type like this helps us to bring all the predefined value helps related to it.

We use CDS to create a Model. In that CDS, we use

1. Entities to represent set of unique objects e.g.:
   1. Employee Basic Information
   2. Employee Communication Information
   3. Employee Salary Information
2. Associations to define relationships
   1. Manager association to another entity Manager which will have all the Managers list

Naming Convention & Recommendations

1. The name of entity should start with a capital letter and it should be human readable and self-explanatory – for example, Employees
2. Start elements with a lowercase letter – for example, firstName
3. It is recommended to use plural form of entities – for example, Employees
4. It is recommended to use singular form of types – for example, Currency
5. don’t repeat contexts – for example, Employees.name instead of Employees.EmployeeName
6. prefer one-word names – for example, salary instead of salaryAmount
7. use ID for technical primary keys – for example, ID for Employee ID
8. You can use Namespace to make your entities unique. It is like client concept in SAP where you can have duplicate schemas (cds files) with unique Namespace to differentiate them. Namespaces are optional, use namespaces if your models might be reused in other projects. At the end of the day they’re just prefixes, which are automatically applied to all relevant names in a file. – for example,

namespace laptop;entity Dell {}

..… is equivalent to:

entity laptop.Dell {}

9. You can use contexts for nested namespace sections. – for example,

namespace laptop;entity Dell {}           //> laptop.Dellcontext Apple {      entity MacBookPro {}       //> laptop.Apple.MacBookPro     entity MacBookAir {}         }

 

Entities

Entities are like tables with primary keys. We can perform CRUD operation using these Entities. Keep it as flat as possible. Do not over Normalize it. Do not use non-reusable types. This section is only for modelling, only annotation related to individual fields should be added and no technical details (logics) should be added.

Types

Types are like Domain in SAP ABAP, it used to define the typed of Data elements.

Aspects

Aspects are the extensions of the Models and are mainly used to extend the existing definitions and annotations. Once a model is defined, we can use different cds files (Aspect) to add annotations on top of them for specific task.

For example-

• cds– your core domain model, kept clean, simple and understandable
• audit-model.cds– adds additional fields required for auditing in a file
• auth-model.cds– adds annotations for authorization.

Primary Keys

Like tables & CDS in SAP ABAP, we maintain Primary keys for Entity using keyword key.

A primary key can be reused across the model by using the methodology of common definitions.

We can create a common.cds Model where all the common definitions can be stored.

// common definitions

entity StandardEntity {

key ID : UUID;

}

Now these  common definitions can be reused as below:

using { StandardEntity } from './common';

entity Employee : StandardEntity {

name : String;

...

}

entity Manager : StandardEntity {

name : String;

...

}

 

The common file is already created by default with a predefined entity named cuid.

Mapping UUIDs to OData

CDS maps UUIDs to Edm.Guid, by default, in all of the OData models. However, the OData standard puts up restrictive rules for Edm.Guid values – for example, only hyphenated strings are allowed – which may conflict with existing data. Therefore, we allow the default mapping to be overridden as follows:

entity Books {

key ID : UUID @odata.Type:’Edm.String’;

…

}

If necessary, you can also add the annotation @odata.MaxLength to override the corresponding property, too.

Association

It is used to define relationship between two entities. Like ABAP CDS, here too we use the word Association. Here, the keyword many indicates a 0..* cardinality. The restrictions for cardinality can be added as a constraint (where condition) – for example, using not null.

Compositions

Unlike Association where we associate a field of entity with the objects of an entire entity, the compositions just refer to specific field of another entity. It has extra advantage of self-managed deep operations(Insert/Update) and cascaded deletion(Multi Dependent table deletion).

// Define Orders with contained OrderItemsentity Orders {  key ID   : UUID;  Items    : Composition of many Order_Items on Items.parent=$self;}entity Order_Items { // shall be accessed through Orders only  key parent : Association to Orders;  key book   : Association to Books;  quantity   : Integer;}

Best Practises

1. Don’t add technical details in Models, we use Aspectsfor that
2. Use short names and simple flat models
3. Don’t over Normalize the entities in Models
4. Use local integer sequences if you really deal with high loads and volumes. Otherwise, prefer UUIDs

Till now what we have learned: Creation of Model and Aspects on top of it .