@sap/xsodata 8.0.2 → 8.1.2

package/CHANGELOG.md

@@ -8,6 +8,18 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ## Unreleased
 
+## [8.1.1] - 2023-11-30
+
+* Add support for node 20
+* Remove support for node 14
+* Remove support for node 16
+* Update dependencies
+* Security fix - update @sap/xssec library to version 3.6.0
+
+## [8.1.0] - 2023-02-20
+* Add support Node.js 18
+* Update node module dependencies
+
 ## [8.0.2] - 2023-01-30
 
 * Security fix - update @sap/xssec library to version 3.2.17.

package/README.md

@@ -2,6 +2,8 @@ XSODATA
 =======
 
 Expose data from HANA database artifacts like tables or views as OData V2 service with the help of .xsodata service definition files. 
+Starting from version 8.1.1 - XSODATA is supported only with @sap/async-xsjs library. @sap/xsjs is deprecated and no new versions will be 
+released. [see CHANGELOG](./CHANGELOG.md)
 
 Note: XSOData was developed to provide XS Classic users using XSOData the possibility to migrate to XS Advanced on node.js. 
       This library contains nearly the same feature set as XSOData provided on SAP HANA XS Classic. This module is already 
@@ -14,19 +16,19 @@ Note: XSOData was developed to provide XS Classic users using XSOData the possib
       For node.js we also provide an OData V4 solution. The development of the OData V4 node.js Library already started in 2016.
       It is also planned that a generic CDS-Odata provider will be deliverd.
 
-      If you are developing an OData service for SAP Business Technology Platform, it is recommended to move to the SAP Cloud Application Programming Model (CP).
-      The XSODATA solution supports HANA as a service, but does **NOT** support SAP HANA Cloud Services (see also SAP note 3013788).
+      If you are developing an OData service for SAP Business Technology Platform, it is recommended to move to the SAP Cloud Application Programming Model (CAP).
+      The XSODATA solution supports HANA as a service, also support was introduced for SAP HANA Cloud Services from XSODATA v8.0.0 and above.
 
 ## Usage
 
-  * This module is used in the XSJS shim for SAP HANA XSC Engine applications to
+  * This module is used in the XSJS/ASYNC-XSJS shim for SAP HANA XSC Engine applications to
     allow the reuse of .xsodata files from XSC applications on SAP HANA XSA.
 
   * It can also be used directly in your own nodejs server application. Be aware that you use the same version of the hdb and winston node module version in your application.
   
 ## Documentation 
 
-[For documentation see here](./documentation.md)
+[For documentation see here](./documentation)
 
 ## Warning
 
@@ -49,7 +51,7 @@ Note: XSOData was developed to provide XS Classic users using XSOData the possib
   * Calculation view support
   * Batch handling
   * Logging:
-    When the xsjs application log is enabled then xsodata also writes log information.
+    When the xsjs/async-xsjs application log is enabled then xsodata also writes log information.
     If, in addition, the environment variable XSODATA_LOG_MEMORY_CONSUMPTION is set to 'true'
     xsodata writes also memory consumption information to the logs
 
@@ -96,28 +98,28 @@ CreateUpdateDelete Requests:
   * Create/update/delete restrictions of OData requests
   * Exposure of table and views (including calculation views) as EntitySet
   * Property Projection: Expose a subset of the table columns as properties of an OData EntityType
-  * [Automatic OData key generation] (/documentation/generatedKeys.md), e.g. required for aggregated views
+  * [Automatic OData key generation](/documentation/generatedKeys.md), e.g. required for aggregated views
   * Simple and complex associations 
-  * [Data aggregation] (/documentation/aggregations.md)
+  * [Data aggregation](/documentation/aggregations.md)
   * Parameter EntitySets for calculation views
   * ETAG handling
   * Nullable properties
   * Cache Control via cache header
-  * [Custom exits] (/documentation/customExits.md) (JavaScript and SQL Script) for modification and validation requests
+  * [Custom exits](/documentation/customExits.md) (JavaScript and SQL Script) for modification and validation requests
   * Custom exits in batch requests
   * Uses only UTF-8
   * Uses "content-type: application/json" for CREATE, UPDATE, DELETE
   * Expose data only via JSON format (ATOM format is not supported)
   * Supported types and type mapping [see here](/documentation/typemapping.md) 
-  * [Supported XSOData features by OSDL] (/documentation/xsodataEbnf.md) 
+  * [Supported XSOData features by OSDL](/documentation/xsodataEbnf.md) 
   
 
 Note: 
 
 * XS1 applications using analytical views, attribute views or calculation views <= SAP HANA SPS 10 have to migrate first their views to the new calculation views of SPS 11. 
 * Authentication/Authorisation is not handled by XSOData node module and has to be done by the application using the node module. 
-* [The module can be used in development mode and productive mode] (/documentation/modes.md)
-* [Debug View is available when using the module in development mode] (/documentation/debugView.md)
+* [The module can be used in development mode and productive mode](/documentation/modes.md)
+* [Debug View is available when using the module in development mode](/documentation/debugView.md)
 
 ## Features per HANA DB Artifact
 

package/documentation/aggregations.md

@@ -0,0 +1,46 @@
+OData Aggregations
+==================
+
+XS Classic SPS10
+----------------
+
+Documentation Chapter 7.1.6.7 p. 488
+
+The results of aggregations on columns change dynamically depending on the grouping conditions. This means that aggregation cannot be performed in SQL views; it needs to be specified in the OData service definition itself. Depending on the type of object to expose, you need to explicitly specify the columns to aggregate and the function to use or derived them from metadata in the database.
+In general, aggregations do not have consequences for the metadata document. It just effects the semantics of the concerning properties during runtime. The grouping condition for the aggregation contain all selected non-aggregated properties. Furthermore, aggregated columns cannot be used in $filter, and aggregation is only possible with generated keys.
+p. 488
+
+XSOData
+-------
+
+In xsodata two types of aggregations are supported, implicit or derived aggregations and explicit aggregations. Both aggregations have to be defined in the OData service definition in the *.xsodata* file.
+
+### Explicit Aggregations
+
+For explicit aggregations the aggregate columns have to be made explicit in the service definition:
+
+```xsodata
+service {
+    "package::revenues" as "Revenues"
+    keys generate local "ID"
+    aggregates always (SUM of "Amount");
+}
+```
+
+Supported aggregations are: **SUM**, **MIN**, **MAX**, **AVG**  
+Supported db artifacts: **Tables**, **Views**  
+
+### Implicit/derived Aggregations
+
+Supported only for **CalculationView** db artifacts which define the aggregations intrinsic.
+
+Assuming PLANNED_ACTUAL_SALES is a calculation view, the service definition would look like:
+
+```xsodata
+service {
+    "package::PLANNED_ACTUAL_SALES " as "PlannedvsActualCalcView"
+    keys generate local "ID"
+    aggregates always
+    parameters via entity "InputParams";
+}
+```

package/documentation/annotations.md

@@ -0,0 +1,401 @@
+# SAP OData Annotations
+
+## Overview
+The second version of the OData protocol allows usage of annotations in the $metadata document. The purpose of the
+annotations is to add a documentation or/and hints to the EDM elements. The added information can be used by the service
+clients (e.g. SAPUI5 application) to better represent the service entities. The annotations are divided into annotation
+elements and annotation attributes, represented as XML elements and XML attributes respectively.
+
+The OData protocol defines the concept of the annotations without adding any concrency concerning the particular names
+and values, which can / should be used for them. SAP defines its own specific set of annotations documented at
+https://scn.sap.com/docs/DOC-44986. Only some of them are supported in XSOData XS2.
+
+By default, the annotations will not be serialized in the $metadata document of an XSOData service. In order to enable
+the annotations for a particular XSOData service, the following configuration has to be specified in the .xsodata file:
+
+```
+annotations {
+    enable OData4SAP;
+}
+```
+
+The configuration has to be specified right after the service element, for example:
+
+```
+service ... {
+    ...
+}
+annotations {
+   enable OData4SAP;
+}
+```
+
+If the annotations are enabled for an XSOData service, the following XML namespace will be added for the Edmx element
+of the $metadata document:
+
+```
+xmlns:sap="http://www.sap.com/Protocols/SAPData"
+```
+
+The sections below describe the annotations (annotation attributes), which are supported by the XSOData XS2. Only the
+values, which are mentioned in the sections below, are supported for the annotations. Mostly only subset of all the
+possible annotation values is supported. Each section describes the annotations, which are supported for a particular
+EDM element. For each of the annotations a default value is defined according to https://scn.sap.com/docs/DOC-44986.
+An annotation is added to the $metadata document only if its value differs from the default one.
+
+## Entity Set Annotations
+
+### sap:addressable
+
+**Description**
+
+Indicates, whether direct access to the entity set is supported.
+
+**Default value**
+
+"true"
+
+**Supported values (other than the default value)**
+
+"false": if the entity set represents either a calculation view or input parameters for a calculation view
+
+### sap:creatable
+
+**Description**
+
+Indicates, whether new entities can be created in this entity set
+
+**Default value**
+
+"true"
+
+**Supported values (other than the default value)**
+
+"false" in one of the following cases:
+* "create forbidden" setting is defined for the entity set in .xsodata file
+* entity set represents a database view (e.g. table or calculation view)
+* entity set represents input parameters for a calculation view
+* aggregation is defined for the entity set using "aggregates" expression in .xsodata file
+
+### sap:updatable
+
+**Description**
+
+Indicates, whether entities in this entity set can be updated
+
+**Default value**
+
+"true"
+
+**Supported values (other than the default value)**
+
+"false" in one of the following cases:
+* "update forbidden" setting is defined for the entity set in .xsodata file
+* entity set represents a database view (e.g. table or calculation view)
+* entity set represents input parameters for a calculation view
+* aggregation is defined for the entity set using "aggregates" expression in .xsodata file
+* generated key is defined for the entity set
+
+
+### sap:deletable
+
+**Description**
+
+Indicates, whether entities can be deleted from this entity set
+
+**Default value**
+
+"true"
+
+**Supported values (other than the default value)**
+
+"false" in one of the following cases:
+* "delete forbidden" setting is defined for the entity set in .xsodata file
+* entity set represents a database view (e.g. table or calculation view)
+* entity set represents input parameters for a calculation view
+* aggregation is defined for the entity set using "aggregates" expression in .xsodata file
+* generated key is defined for the entity set
+
+## Entity Type Annotations
+
+### sap:semantics
+
+**Description**
+
+Semantic of the entity type
+
+**Default value**
+
+undefined
+
+**Supported values (other than the default value)**
+
+"aggregate" value in one of the following cases:
+* aggregation is defined for the entity set of the entity type using "aggregates" expression in .xsodata file
+* entity type represents a calculation view, which has a measure attribute
+
+"parameters" value if the entity type represents input parameters for a calculation view
+
+## Annotations for entity type properties
+
+### sap:semantics
+
+**Description**
+
+Semantic of the property
+
+**Default value**
+
+undefined
+
+**Supported values (other than the default value)**
+
+The annotation is added only for the properties representing calculated attributes or input parameters of a
+calculation view. The annotation value corresponds to the semantic type of a calculated attribute or an input
+parameter.
+
+Semantic type of an input parameter is specified as a value of "type" attribute of "valueDomain" element, defined in
+.hdbcalculationview file. For example:
+
+```xml
+<variable id="parameterID" parameter="true">
+    <variableProperties datatype="VARCHAR" mandatory="true">
+        <valueDomain type="Currency"/>
+        ...
+    </variableProperties>
+</variable>
+```
+
+Semantic type of a calculated attribute is specified as a value of "semanticType" attribute of "calculatedAttribute"
+element, defined in .hdbcalculationview file. For example:
+
+```xml
+<calculatedAttribute id="attributeID" semanticType="currencyCode">
+    ...
+</calculatedAttribute>
+```
+
+The following table shows the mapping from the semantic type values of calculated attributes and input parameters to the
+values of sap:semantics annotation:
+
+| Calculated attribute semantic type | Input parameter semantic type | sap:semantics value |
+|------------------------------------|-------------------------------|---------------------|
+| currencyCode                       | Currency                      | currency-code       |
+| unitOfMeasure                      | UnitOfMeasure                 | unit-of-measure     |
+| date.businessDateFrom              | -                             | dtstart             |
+| date.businessDateTo                | -                             | dtend               |
+
+Only the values from the table are supported.
+
+### sap:parameter
+
+**Description**
+
+A property is annotated with this annotation, if it represents a parameter.
+
+**Default value** 
+
+undefined
+
+**Supported values (other than the default value)**
+
+The annotation is added only to the properties representing input parameters of a calculation view. The annotation value
+corresponds to the value of "mandatory" attribute in the input parameter definition, defined in .hdbcalculationview file.
+
+```xml
+<variable id="inputParameterId" parameter="true">
+	<variableProperties datatype="INTEGER" mandatory="true">
+</variable>
+```
+
+Mapping of "mandatory" attribute values to the values of sap:parameter annotation:
+
+"mandatory" attribute value | sap:parameter value
+--------------------------- | -------------------
+true                        | mandatory
+false                       | optional
+
+
+### sap:label
+
+**Description**
+
+A short, human-readable text suitable for labels and captions in UIs
+
+**Default value**
+
+undefined
+
+**Supported values (other than the default value)**
+
+The annotation is added only for the properties representing calculated attributes or input parameters of a
+calculation view. The annotation value corresponds to the "defaultDescription" attribute in the definition of an input
+parameter or a calculated attribute in .hdbcalculationview file.
+
+```xml
+<variable id="inputParameterId" parameter="true">
+	<descriptions defaultDescription="Input parameter label"/>
+</variable>
+
+<calculatedAttribute id="calcAttributeId">
+	<descriptions defaultDescription="Calculated attribute label"/>
+</calculatedAttribute>
+```
+
+### sap:filterable
+
+**Description**
+
+Indicates, whether the property can be used in $filter system query option.
+
+**Default value** 
+
+"true"
+
+**Supported values (other than the default value)**
+
+The annotation is added with the "false" value if the property satisfies one of the following conditions:
+* The property represents a generated key
+* The property represents a measure attribute of a calculation view
+* The property is used in the aggregation, defined as the "aggregates" expression in .xsodata file
+
+
+### sap:display-format
+
+**Description**
+
+Format, which can be used to display the property
+
+**Default value** 
+
+undefined
+
+**Supported values (other than the default value)**
+
+
+"Date" value, if SQL DATE type is used for the property on the database side.
+
+
+### sap:aggregation-role
+
+**Description**
+
+Aggregation role of the property
+
+**Default value** 
+
+undefined
+
+**Supported values (other than the default value)**
+
+"measure" value, if the property represents a measure attribute of a calculation view or is used in the aggregation,
+defined as the "aggregates" expression in .xsodata file
+
+### sap:unit
+
+**Description**
+
+Name of a property in the context of the entity type containing the currency code or unit of measure for a numeric value of the current property.
+
+**Default value** 
+
+undefined
+
+**Supported values (other than the default value)**
+
+The annotation is added only for the properties representing calculated attributes of a calculation view. The annotation
+value corresponds to the value of "attributeName" attribute of "unitCurrencyAttribute" element of the calculated attribute
+definition in .hdbcalculationview file.
+
+```xml
+<calculatedAttribute id="attributeId">
+	<unitCurrencyAttribute attributeName="currencyCodeAttribute"/>
+</calculatedAttribute>
+```
+
+For the aforementioned example the annotation value will be "currencyCodeAttribute".
+
+### sap:filter-restriction
+
+**Description**
+
+Describes filter restriction for the property, if the one exists.
+
+**Default value** 
+
+undefined
+
+**Supported values (other than the default value)**
+
+The annotation is added only for the properties representing input parameters of a calculation view. The annotation
+value corresponds to the values of "multiLine" and "type" attributes of "selection" element of the input parameter
+definition in .hdbcalculationview file.
+
+```xml
+<variable id="parameterId" parameter="true">
+	<variableProperties datatype="INTEGER">
+		<selection multiLine="false" type="SingleValue"/>
+	</variableProperties>
+</variable>
+```
+
+The table below shows the mapping from "multiLine" and "type" attribute values to the value of sap:filter-restriction
+annotation.
+
+multiLine | type        | sap:filter-restriction
+--------- | ----------- | ---------------------- 
+false     | SingleValue | single-value
+true      | SingleValue | multi-value
+false     | Interval    | interval
+
+Only the values from the table are supported.
+
+
+## Navigation Property Annotations
+
+### sap:creatable
+
+**Description**
+
+Indicates, whether new related entities can be created.
+
+**Default value** 
+
+"true"
+
+**Supported values (other than the default value)**
+
+The annotation value is always "false" because neither "deep insert" (i.e. POST request payload having data for the both,
+parent and related entity) nor POST request for .../EntitySet(key)/navPropertyName URL is supported in XSOData XS2.
+
+
+### sap:filterable
+
+**Description**
+
+Indicates, whether navigation property can be used in $filter system query option.
+
+**Default value**
+
+"true"
+
+**Supported values (other than the default value)**
+
+The annotation value is always "false" because navigation properties cannot be used in $filter system query option in
+XSOData XS2.
+
+## Association Set Annotations
+
+### sap:creatable / sap:updatable / sap:deletable
+
+**Description**
+
+Indicates, whether relations, represented by the association set, can be created / updated / deleted.
+
+**Default value** 
+
+"true"
+
+**Supported values (other than the default value)**
+
+"false": if the association set connects entity sets for calculation view results and calculation view input parameters.

package/documentation/authorization.md

@@ -0,0 +1,94 @@
+# Authorization scopes in XSOData Service Definition
+### Overview
+As XSA provides the possibility to define coarse-grained authorization checks via scopes that are defined in the security configuration file (xs-security.json), the OData service provider is also enabled to use the defined authorization scopes in the XSOData service definition, in order to control access on different levels:
+
+* Service-level
+* EntitySet-level
+* (CRUD) Operation-level
+
+### Definition Rules
+For the definition of scopes in the XSOData service definition, the following rules must be taken into account:  
+
+1. It is possible to **not** define any scopes in the xsodata service definition file. Then no 
+authorization process will be invoked, and all requests are allowed.
+2. Once scopes are defined, scopes on Service-level for all CRUD operations **MUST** be provided
+    a. Any missing operation-scope will lead to an xsodata-parse-error
+    b. To restrict any of the operations, a scope with an “unused-value” is given
+3. On EntitySet-level, scopes are inherited from the Service-level
+4. On EntitySet-level, further scopes for any subset of CRUD operations could be given
+    a. Then, for the corresponding entitySet, both scopes (from Service, and the extra from entitySet) must be validated. See below examples# 2, 3, 5.
+5. scopes for a given operation request are checked independently from scopes of other operations.
+6. On Service- and EntitySet-level, **ONLY ONE** scope can be set per operation
+7. Even with defined scopes, the following requests are excluded from the authorization, and processed as allowed:
+    a. $metadata
+    b. Service document
+
+### Syntax- An Example XSOData service definition
+```
+service {
+   scopes (
+      create ( "unused-scope" ),
+      read ( "scope_R0" ),
+      update ( "unused-scope" ),
+      delete ( "scope_D0" )
+   );
+   
+   entitySet E1 (
+       navigates (
+           ...
+       )
+   );
+
+   entitySet E2 (
+      navigates (
+         ...
+      )
+      scopes ( 
+        read ( "scope_R2" ), 
+        delete ("scope_D2" )
+      )
+   );
+
+   entitySet E3 (
+      scopes ( 
+         read ( "scope_R3" )
+      )
+   );
+}
+
+```
+
+### The special case of $links:
+For $links requests like `service.xsodata/entitySet1(key)/$links/navProp`, there are 2 entity sets, one of them (named ‘target’) is to update its foreign key with the key that is read from the other entity set (named ‘source’). 
+Therefore, the target must have scopes for the corresponding operation (Create, Update, Delete), and the source must have read scopes. These scopes are inherited from service-level, and (as before) can be extended at the entitySet-level.
+
+### Debug View
+The debug view is callable, if the request has the parameter `sap-ds-debug = json | html`. The debug view is protected by default (as long as the authorization process in invoked by given scopes), unless a certain corresponding scope is defined on the service-level and this scope passes the secrity check.
+The debug scope looks similar to the scopes of other operations, except that it is optionally defined:
+
+```
+service {
+   scopes (
+     ...
+     debug ( "scope_name" )
+   );
+   
+   ...
+}
+
+```
+
+### Example Requests:
+
+| Nr. | Request                 | Expected scopes from user         |
+|-----|-------------------------|-----------------------------------|
+| 1   | Read on E1	            | R0                                |
+| 2   |	Read on E2	            | R0, R2                            |
+| 3   |	Read on E3	            | R0, R3                            |
+| 4   |	Delete on E1	        | D0                                |
+| 5   |	Delete on E2	        | D0, D2                            |
+| 6   |	Delete on E3	        | D0                                |
+| 7   |	Create on any entitySet	| Request denied on Service-level   |
+| 8   |	Update on any entitySet	| Request denied on Service-level   |
+| 9   |	Read on E1/$links/E3	| R0, R3                            |
+| 10  |	Delete on E2/$links/E3	| D2, R0, R3                        |

package/documentation/calcviewSample.md

@@ -0,0 +1,17 @@
+Sample for calculation views
+============================
+
+### Exposition of calculation view PlannedvsActualCalcView in an xsodata file:
+
+```xsodata
+service  {
+    "package::PLANNED_ACTUAL_SALES " as "PlannedvsActualCalcView"
+    keys generate local "ID"
+    aggregates always
+    parameters via entity "InputParams";
+}
+```
+
+### Sample URL
+
+http://server:port/copaxs/odata/PlannedvsActualCalcView.xsodata/InputParams(ip_discount=’.20’,ip_region=’NW’)/Results?$select=salesorg,material,anetrevn&$filter=startswith(material,'DPC')&$format=json