@cap-js/change-tracking 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
+## Version 1.0.4 - 08.01.24
+
+### Added
+
+- Side effect annotation now allows automatic refresh after a custom action caused changes
+
+### Changed
+
+- Added a check to disable change tracking for views with a UNION
+
+### Fixed
+
+- Handling of associations within change tracked entities
+- Handling of change log when custom actions on child entities are called
+
+## Version 1.0.3 - 10.11.23
+
+### Added
+
+- Added note about using `SAPUI5 v1.120.0` or later for proper lazy loading of the *Change History* table.
+- In README, add warning about tracking personal data.
+
+### Changed
+
+- Support cases where parent/child entries are created simultaneously.
+- Allow for lazy loading of change history table (with SAP UI5 release 1.120.0).
+
 ## Version 1.0.2 - 31.10.23
 
 ### Changed
@@ -25,3 +52,4 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 ### Added
 
 - Initial release
+

package/README.md

@@ -8,23 +8,28 @@ The `@cap-js/change-tracking` package is a [CDS plugin](https://cap.cloud.sap/do
 2. [Add `@changelog` annotations to your CDS models](#annotations)
 3. [Et voilà:](#change-history-view)
 
-<img width="1300" alt="change-history-custom" src="_assets/changes.png">
+<img width="1300" alt="change-history-loading" src="_assets/change-history.gif">
 
 
 
 ### Table of Contents
 
-- [Preliminaries](#preliminaries)
-- [Setup](#setup)
-- [Annotations](#annotations)
-  - [Human-readable Types and Fields](#human-readable-types-and-fields)
-  - [Human-readable IDs](#human-readable-ids)
-  - [Human-readable Values](#human-readable-values)
-- [Test-drive locally](#test-drive-locally)
-- [Change History View](#change-history-view)
-- [Contributing](#contributing)
-- [Code of Conduct](#code-of-conduct)
-- [Licensing](#licensing)
+- [Change Tracking Plugin for SAP Cloud Application Programming Model (CAP)](#change-tracking-plugin-for-sap-cloud-application-programming-model-cap)
+    - [Table of Contents](#table-of-contents)
+  - [Preliminaries](#preliminaries)
+  - [Setup](#setup)
+  - [Annotations](#annotations)
+    - [Human-readable Types and Fields](#human-readable-types-and-fields)
+    - [Human-readable IDs](#human-readable-ids)
+    - [Human-readable Values](#human-readable-values)
+  - [Test-drive locally](#test-drive-locally)
+  - [Change History View](#change-history-view)
+  - [Customizations](#customizations)
+    - [Altered table view](#altered-table-view)
+    - [Disable lazy loading](#disable-lazy-loading)
+  - [Contributing](#contributing)
+  - [Code of Conduct](#code-of-conduct)
+  - [Licensing](#licensing)
 
 
 
@@ -64,6 +69,9 @@ npm add @cap-js/change-tracking
 
 ## Annotations
 
+> [!WARNING]
+> Please be aware that [**sensitive** or **personal** data](https://cap.cloud.sap/docs/guides/data-privacy/annotations#annotating-personal-data) should not be change tracked, since viewing the log allows users to circumvent [audit-logging](https://cap.cloud.sap/docs/guides/data-privacy/audit-logging#setup).
+
 All we need to do is to identify what should be change-tracked by annotating respective entities and elements in our model with the `@changelog` annotation. Following the [best practice of separation of concerns](https://cap.cloud.sap/docs/guides/domain-modeling#separation-of-concerns), we do so in a separate file _srv/change-tracking.cds_:
 
 ```cds
@@ -162,13 +170,19 @@ With the steps above, we have successfully set up change tracking for our refere
 
 ## Change History View
 
+> [!IMPORTANT]
+> To ensure proper lazy loading of the Change History table, please use **SAPUI5 version 1.120.0** or higher.<br>
+> If you wish to *disable* this feature, please see the customization section on how to [disable lazy loading](#disable-lazy-loading).
+
 <img width="1300" alt="change-history" src="_assets/changes.png">
 
 If you have a Fiori Element application, the CDS plugin automatically provides and generates a view `sap.changelog.ChangeView`, the facet of which is automatically added to the Fiori Object Page of your change-tracked entities/elements. In the UI, this corresponds to the *Change History* table which serves to help you to view and search the stored change records of your modeled entities.
 
-### Customizations
+## Customizations
+
+### Altered table view
 
-The view can be easily adapted and configured to your own needs by simply changing or extending it. For example, let's assume we only want to show the first 5 columns in equal spacing, we would extend `srv/change-tracking.cds` as follows:
+The *Change History* view can be easily adapted and configured to your own needs by simply changing or extending it. For example, let's assume we only want to show the first 5 columns in equal spacing, we would extend `srv/change-tracking.cds` as follows:
 
 ```cds
 using from '@cap-js/change-tracking';
@@ -190,6 +204,24 @@ In the UI, the *Change History* table now contains 5 equally-spaced columns with
 
 For more information and examples on adding Fiori Annotations, see [Adding SAP Fiori Annotations](https://cap.cloud.sap/docs/advanced/fiori#fiori-annotations).
 
+### Disable lazy loading
+
+To disable the lazy loading feature of the *Change History* table, you can add the following annotation to your `srv/change-tracking.cds`:
+
+```cds
+using from '@cap-js/change-tracking';
+
+annotate sap.changelog.aspect @(UI.Facets: [{
+  $Type : 'UI.ReferenceFacet',
+  ID    : 'ChangeHistoryFacet',
+  Label : '{i18n>ChangeHistory}',
+  Target: 'changes/@UI.PresentationVariant',
+  ![@UI.PartOfPreview]
+}]);
+
+```
+
+The system now uses the SAPUI5 default setting `![@UI.PartOfPreview]: true`, such that the table will always shown when navigating to that respective Object page.
 
 ## Contributing
 

package/cds-plugin.js

@@ -1,10 +1,28 @@
 const cds = require('@sap/cds')
 
 const isChangeTracked = (entity) => (
-  entity['@changelog']
-  || entity.elements && Object.values(entity.elements).some(e => e['@changelog'])
+  (entity['@changelog']
+  || entity.elements && Object.values(entity.elements).some(e => e['@changelog'])) && entity.query?.SET?.op !== 'union'
 )
 
+// Add the appropriate Side Effects attribute to the custom action
+const addSideEffects = (actions, flag, element) => {
+  for (const se of Object.values(actions)) {
+    const target = flag ? 'TargetProperties' : 'TargetEntities'
+    const sideEffectAttr = se[`@Common.SideEffects.${target}`]
+    const property = flag ? 'changes' : { '=': `${element}.changes` }
+    if (sideEffectAttr?.length >= 0) {
+      sideEffectAttr.findIndex(
+        (item) =>
+          (item['='] ? item['='] : item) ===
+          (property['='] ? property['='] : property)
+      ) === -1 && sideEffectAttr.push(property)
+    } else {
+      se[`@Common.SideEffects.${target}`] = [property]
+    }
+  }
+}
+
 
 // Unfold @changelog annotations in loaded model
 cds.on('loaded', m => {
@@ -23,7 +41,9 @@ cds.on('loaded', m => {
       for (let e in elms) if (elms[e].key) keys.push(e)
 
       // Add association to ChangeView...
-      const on = [...changes.on]; keys.forEach((k, i) => { i && on.push('||'); on.push({ ref: [k] }) })
+      const on = [...changes.on]; keys.forEach((k, i) => { i && on.push('||'); on.push({
+        ref: k === 'up_' ? [k,'ID'] : [k] // REVISIT: up_ handling is a dirty hack for now
+      })})
       const assoc = { ...changes, on }
       const query = entity.projection || entity.query?.SELECT
       if (query) {
@@ -34,6 +54,31 @@ cds.on('loaded', m => {
 
       // Add UI.Facet for Change History List
       entity['@UI.Facets']?.push(facet)
+
+      // The changehistory list should be refreshed after the custom action is triggered
+      if (entity.actions) {
+
+        // Update the changehistory list on the current entity when the custom action of the entity is triggered
+        if (entity['@UI.Facets']) {
+          addSideEffects(entity.actions, true)
+        }
+
+        // When the custom action of the child entity is performed, the change history list of the parent entity is updated
+        if (entity.elements) {
+          //ToDo: Revisit Breaklook with node.js Expert
+          breakLoop: for (const [ele, eleValue] of Object.entries(entity.elements)) {
+            const parentEntity = m.definitions[eleValue.target]
+            if (parentEntity && parentEntity['@UI.Facets'] && eleValue.type === 'cds.Association') {
+              for (const value of Object.values(parentEntity.elements)) {
+                if (value.target === name) {
+                  addSideEffects(entity.actions, false, ele)
+                  break breakLoop
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
 })

package/index.cds

@@ -9,8 +9,7 @@ aspect aspect @(UI.Facets: [{
   ID    : 'ChangeHistoryFacet',
   Label : '{i18n>ChangeHistory}',
   Target: 'changes/@UI.PresentationVariant',
-  //TODO: Use for lazy-loading once Fiori fixes bugs and v1.120 is released
-  //![@UI.PartOfPreview]: false
+  ![@UI.PartOfPreview]: false
 }]) {
   // Essentially: Association to many Changes on changes.changeLog.entityKey = ID;
   changes : Association to many ChangeView on changes.entityKey = ID;

package/lib/change-log.js

@@ -359,7 +359,7 @@ async function track_changes (req) {
   if (!changes) return
 
   await _formatChangeLog(changes, req)
-  if (isComposition && !isDraftEnabled) {
+  if (isComposition) {
     [ target, entityKey ] = await _prepareChangeLogForComposition(target, entityKey, changes, this)
   }
   const dbEntity = getDBEntity(target)

package/lib/entity-helper.js

@@ -85,7 +85,9 @@ async function getObjectId (entityName, fields, curObj) {
         if (IDval) try {
           // REVISIT: This always reads all elements -> should read required ones only!
           let ID = assoc.keys?.[0]?.ref[0] || 'ID'
-          _db_data = await SELECT.one.from(assoc._target).where({[ID]: IDval}) || {}
+          // When parent/child nodes are created simultaneously, data is taken from draft table
+          _db_data = await SELECT.one.from(assoc._target).where({[ID]: IDval}) ||
+            await SELECT.one.from(`${assoc._target}.drafts`).where({[ID]: IDval}) || {}
         } catch (e) {
           LOG.error("Failed to generate object Id for an association entity.", e)
           throw new Error("Failed to generate object Id for an association entity.", e)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/change-tracking",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "CDS plugin providing out-of-the box support for automatic capturing, storing, and viewing of the change records of modeled entities.",
   "repository": "cap-js/change-tracking",
   "author": "SAP SE (https://www.sap.com)",