@cap-js/change-tracking 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -4,8 +4,24 @@ 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.0 - TBD
+## Version 1.0.2 - 31.10.23
+
+### Changed
+
+- In README, use view of the full change-tracking table instead of the customized one for the main image.
+
+## Version 1.0.1 - 26.10.23
+
+### Changed
+
+- Flattened README structure.
+
+### Fixed
+
+- Labels are looked up from the service entity (not the db entity only).
+
+## Version 1.0.0 - 18.10.23
 
 ### Added
 
-- Initial release
+- Initial release

package/README.md

@@ -1,23 +1,57 @@
+# Change Tracking Plugin for SAP Cloud Application Programming Model (CAP)
+
+[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/change-tracking)](https://api.reuse.software/info/github.com/cap-js/change-tracking)
+
+The `@cap-js/change-tracking` package is a [CDS plugin](https://cap.cloud.sap/docs/node.js/cds-plugins#cds-plugin-packages) providing out-of-the box support for automatic capturing, storing, and viewing of the change records of modeled entities as simple as that:
+
+1. [Install the plugin: `npm add @cap-js/change-tracking`](#setup)
+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">
+
 
-The `@cap-js/change-tracking` package is a [CDS plugin](https://cap.cloud.sap/docs/node.js/cds-plugins#cds-plugin-packages) providing out-of-the box support for automatic capturing, storing, and viewing of the change records of modeled entities.
 
 ### Table of Contents
 
+- [Preliminaries](#preliminaries)
 - [Setup](#setup)
-- [Usage](#usage)
-  - [Add `@changelog` Annotations](#add-changelog-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)
+- [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)
+- [Code of Conduct](#code-of-conduct)
 - [Licensing](#licensing)
 
 
 
+## Preliminaries
+
+In this guide, we use the [Incidents Management reference sample app](https://github.com/cap-js/incidents-app) as the base to add change tracking to. Clone the repository and apply the step-by-step instructions:
+
+```sh
+git clone https://github.com/cap-js/incidents-app
+cd incidents-app
+npm i
+```
+
+**Alternatively**, you can clone the incidents app including the prepared enhancements for change-tracking:
+
+```sh
+git clone https://github.com/cap-js/calesi --recursive
+cd calesi
+npm i
+```
+
+```sh
+cds w samples/change-tracking
+```
+
+
+
 ## Setup
 
 To enable change tracking, simply add this self-configuring plugin package to your project:
@@ -28,11 +62,7 @@ npm add @cap-js/change-tracking
 
 
 
-## Usage
-
-In this guide, we use the [Incidents Management reference sample app](https://github.com/cap-js/incidents-app) as the base to add change tracking to.
-
-### Add `@changelog` Annotations
+## Annotations
 
 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_:
 
@@ -55,9 +85,9 @@ The minimal annotation we require for change tracking is `@changelog` on element
 Additional identifiers or labels can be added to obtain more *human-readable* change records as described below.
 
 
-#### Human-readable Types and Fields
+### Human-readable Types and Fields
 
-By default the implementation looks up *Object Type* names or *Field* namesfrom respective  `@title` or  `@Common.Label` annotations, and applies i18n lookups. If no such annotations are given, the technical names of the respective CDS definitions are displayed. 
+By default the implementation looks up *Object Type* names or *Field* namesfrom respective  `@title` or  `@Common.Label` annotations, and applies i18n lookups. If no such annotations are given, the technical names of the respective CDS definitions are displayed.
 
 For example, without the `@title` annotation, changes to conversation entries would show up with the technical entity name:
 
@@ -74,7 +104,7 @@ We get a human-readable display for *Object Type*:
 <img width="1300" alt="change-history-type-hr" src="_assets/changes-type-hr-wbox.png">
 
 
-#### Human-readable IDs
+### Human-readable IDs
 
 The changelog annotations for *Object ID* are defined at entity level.
 
@@ -97,7 +127,7 @@ annotate ProcessorService.Conversations with @changelog: [author, timestamp] {
 Expanding the changelog annotation by additional identifiers `[author, timestamp]`, we can now better identify the `message` change events by their respective author and timestamp.
 
 
-#### Human-readable Values
+### Human-readable Values
 
 The changelog annotations for *New Value* and *Old Value* are defined at element level.
 
@@ -120,7 +150,7 @@ Hence, here it is essential to add a unique identifier to obtain human-readable
 <img width="1300" alt="change-history-value-hr" src="_assets/changes-value-hr-wbox.png">
 
 
-### Test-drive locally
+## Test-drive locally
 
 With the steps above, we have successfully set up change tracking for our reference application. Let's see that in action.
 
@@ -130,7 +160,7 @@ With the steps above, we have successfully set up change tracking for our refere
   ```
 2. **Make a change** on your change-tracked elements. This change will automatically be persisted in the database table (`sap.changelog.ChangeLog`) and made available in a pre-defined view, namely the [Change History view](#change-history-view) for your convenience.
 
-### Change History View
+## Change History View
 
 <img width="1300" alt="change-history" src="_assets/changes.png">
 
@@ -154,7 +184,7 @@ annotate sap.changelog.ChangeView with @(
 );
 ```
 
-In the UI, the *Change History* table now contains 4 equally-spaced columns with the desired properties:
+In the UI, the *Change History* table now contains 5 equally-spaced columns with the desired properties:
 
 <img width="1300" alt="change-history-custom" src="_assets/changes-custom.png">
 
@@ -166,7 +196,7 @@ For more information and examples on adding Fiori Annotations, see [Adding SAP F
 This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/change-tracking/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).
 
 
-### Code of Conduct
+## Code of Conduct
 
 We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](CODE_OF_CONDUCT.md) at all times.
 

package/lib/localization.js

@@ -1,8 +1,6 @@
 const cds = require("@sap/cds/lib");
 const LOG = cds.log("change-log");
 const { getNameFromPathVal, getDBEntity } = require("./entity-helper");
-const OBJECT_TYPE_I18N_LABEL_KEY = "@Common.Label"
-const OBJECT_TYPE_I18N_TITLE_KEY = "@title"
 
 const MODIF_I18N_MAP = {
     create: "{i18n>ChangeLog.modification.create}",
@@ -43,7 +41,7 @@ const _localizeDefaultObjectID = function (change, locale) {
         const parentEntityName = getNameFromPathVal(parentNodePathVal);
         const dbEntity = getDBEntity(parentEntityName);
         try {
-            const labelI18nKey = dbEntity[OBJECT_TYPE_I18N_LABEL_KEY];
+            const labelI18nKey = dbEntity['@Common.Label'] || dbEntity['@title'];
             const labelI18nValue = labelI18nKey ? _getLocalization(locale, labelI18nKey) : null;
             change.parentObjectID = labelI18nValue ? labelI18nValue : dbEntity.name;
         } catch (e) {
@@ -56,7 +54,7 @@ const _localizeDefaultObjectID = function (change, locale) {
 const _localizeEntityType = function (change, locale) {
     if (change.entity) {
         try {
-            const labelI18nKey = _getLabelI18nKeyOnEntity(change.entity);
+            const labelI18nKey = _getLabelI18nKeyOnEntity(change.serviceEntity);
             const labelI18nValue = labelI18nKey ? _getLocalization(locale, labelI18nKey) : null;
 
             change.entity = labelI18nValue ? labelI18nValue : change.entity;
@@ -83,12 +81,11 @@ const _localizeAttribute = function (change, locale) {
         try {
             const serviceEntity = cds.model.definitions[change.serviceEntity];
             let labelI18nKey = _getLabelI18nKeyOnEntity(change.serviceEntity, change.attribute);
-            const element = serviceEntity.elements[change.attribute];
-            if (element.isAssociation && !labelI18nKey) {
-                labelI18nKey = _getLabelI18nKeyOnEntity(element.target);
+            if (!labelI18nKey) {
+                const element = serviceEntity.elements[change.attribute];
+                if (element.isAssociation) labelI18nKey = _getLabelI18nKeyOnEntity(element.target);
             }
             const labelI18nValue = labelI18nKey ? _getLocalization(locale, labelI18nKey) : null;
-
             change.attribute = labelI18nValue ? labelI18nValue : change.attribute;
         } catch (e) {
             LOG.error("Failed to localize change attribute", e);
@@ -98,14 +95,10 @@ const _localizeAttribute = function (change, locale) {
 };
 
 const _getLabelI18nKeyOnEntity = function (entityName, /** optinal */ attribute) {
-    const entity = cds.model.definitions[entityName];
-    if (!entity) return "";
-    if (attribute) {
-        const element = entity.elements[attribute] ? entity.elements[attribute] : {};
-        return element[OBJECT_TYPE_I18N_LABEL_KEY];
-    }
-    const entityLabel = entity[OBJECT_TYPE_I18N_LABEL_KEY] ? entity[OBJECT_TYPE_I18N_LABEL_KEY] : entity[OBJECT_TYPE_I18N_TITLE_KEY];
-    return entityLabel;
+    let def = cds.model.definitions[entityName];
+    if (attribute) def = def?.elements[attribute]
+    if (!def) return "";
+    return def['@Common.Label'] || def['@title'];
 };
 
 const localizeLogFields = function (data, locale) {

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "@cap-js/change-tracking",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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)",
-  "homepage": "https://cap.cloud.sap/",
   "license": "SEE LICENSE IN LICENSE",
   "main": "cds-plugin.js",
   "files": [