@rizing/cds-extension

Rizing CDSX

INTRODUCTION

In a nutshell, Rizing CDSX (@rizing/cds-extension or just CDSX) node module is used to help in consuming OData Service APIs from cloud or on-premise systems.

OData APIs commonly support basic CRUD operations and are completely devoid of the facade needed by Fiori Elements framework (i.e. draft capability). CDSX helps CAP developers in consuming OData APIs by strapping the additional logic that consumes CAP's external service API and handles OData Draft automatically without the need for implementing custom handler logic.

NOTE:

• CDSX is a node module that is intended to be used as a dependency in CAP projects. It is not intended to be used as a standalone module.
• CDSX is not intended to be used in conjunction with @sap/cds-odata-v2-adapter-proxy module.
• CDSX complements the gaps in CAP's ability to consume external services, and is not intended to replace the existing CAP's external service API.

GETTING STARTED

1. Install the module as dependency:

> npm install @rizing/cds-extension

2. Bootstrap the node module in server.js file:

const cds = require("@sap/cds");
const cdsx = require("@rizing/cds-extension");

cds.on("bootstrap", () => {
	cdsx.load();
});

3. Import OData V2 service metadata you want to consume from S/4HANA:

> cds import API_MAINTNOTIFICATION.xml

NOTE:

• csn file will be generated under ./srv/external folder.
• package.json file will be updated with remote service configuration:

  "cds": {
  	"requires": {
  		"API_MAINTNOTIFICATION": {
  			"kind": "odata-v2",
  			"model": "srv/external/API_MAINTNOTIFICATION"
  		}
  	}
  }

• the above steps are standard CAP steps and is not specific to CDSX module.

4. Create the Shadow Persistence Entity in db/schema.cds:

context md {
    @cdsx.api : 'API_MAINTNOTIFICATION'
    entity MaintenanceNotification {
            @cdsx.object.key
        key MaintenanceNotification : String(12);
            NotificationType        : String(2);
            NotificationText        : String(40);
            FunctionalLocation      : String(30);
            CompanyCode             : String(4);
            ReportedByUser          : String(12);
            ReporterFullName        : String(80);
            @readonly
            CreationDateTime        : Timestamp;
            @readonly
            LastChangeDateTime      : Timestamp;
            @cdsx.extension
            CustomField             : String(10) default 'Default Data';
            @cdsx.extension
            ExtensionField          : String(20);
    }
}

NOTE:

• Shadow Persistence Entity means that properties from the remote service are recreated in the CAP persistence entity but will never be persisted in the actual table generated by CAP. The only exception to this is when the property of an entity was enriched with @cdsx.extension.
• @cdsx.extension (experimental) is an annotation to denote that the property should be persisted in the actual table generated by CAP. It is used as field extensions of the remote entity.

5. Consume the Shadow Persistence Entity in srv/notification.cds:

using {md} from '../db/schema';

service NotificationService {

    @odata.draft.enabled
    entity MaintenanceNotification as projection on md.MaintenanceNotification;

}

6. Consume the CAP service in a Fiori Elements application and add your own UI Annotations as you would normally do in any regular CAP-based application.

ANNOTATIONS

Annotation	Target	Data Type	Description
@cdsx.api	Entity	String	Annotate entities with its corresponding remote service name. This required if you use multiple remote service.
@cdsx.extension	Property	Boolean	Annotate properties as extension fields (experimental)
@cdsx.object.key	Property	Boolean	Annotate properties as object key using number range (semantic keys) i.e. 10000000.
@cdsx.item.key	Property	Boolean / Object	Annotate properties as item key using incrementing number starting with 1.
@cdsx.item.key.padded	Property	Boolean	Annotate properties just like in @cdsx.item.key but with the addition of padded zeroes i.e. 0001.
@cdsx.datetime.persistency	Property	String[ ]	Annotate properties as timestamps that has a separate Date & Time fields for persistency. This is akin to ABAP stack server where date and time fields are persisted in the database as separate fields.

Example

    @cdsx.api : 'API_MAINTNOTIFICATION'
    entity MaintNotificationItemActivity {
            @cdsx.object.key
        key MaintenanceNotification        : String(12);
            @cdsx.item.key
        key MaintNotificationActivity      : String(4);
            @mandatory
            MaintNotifActyTxt              : String(40);
            @cdsx.datetime.persistency : [
                'PlannedStartDate',
                'PlannedStartTime'
            ]
            MaintNotifItmActyStrtDateTime  : Timestamp;
            @cdsx.datetime.persistency : [
                'PlannedEndDate',
                'PlannedEndTime'
            ]
            MaintNotifItemActyEndDateTime  : Timestamp;
    }

SAMPLE PROJECT

• Manage Business Partners app

SUPPORTED FEATURES

• Auto-generate temporary value for Semantic Keys on draft creation. The Semantic Key field should have @cdsx.object.key: true annotation and data type equal to cds.String.
• handles OData CRUD operations

LICENSE

This project is licensed under the MIT License. See LICENSE file.

GETTING SUPPORT

The software is provided as is and without any warranty or support. If you have any questions, please open an issue in this repository.