# 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:

```shell
> npm install @rizing/cds-extension
```

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

```javascript
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:

```shell
> 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:
> ```json
>	"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`:

```sql
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`:

```sql
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

```sql
    @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](https://github.com/RizInno/cdsx-samples) 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](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](https://github.com/RizInno/cdsx-samples/issues).