@cap-js/change-tracking 2.0.0-beta.2 → 2.0.0-beta.3

package/CHANGELOG.md

@@ -4,7 +4,7 @@ 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 2.0.0-beta.3 - tbd
+## Version 2.0.0-beta.4 - tbd
 
 ### Added
 
@@ -12,6 +12,17 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ### Changed
 
+
+## Version 2.0.0-beta.3 - 13.03.26
+
+### Fixed
+- CSV data for `i18nKeys` and `CHANGE_TRACKING_DUMMY` is now correctly generated during the HANA build
+
+### Changed
+- Changes from child entities are shown on the parent ChangeView by default
+- Depth of displayed child changes can be configured via `maxDisplayHierarchyDepth`
+- Improved search capabilities for changes
+
 ## Version 2.0.0-beta.2 - 11.03.26
 
 ### Fixed
@@ -51,6 +62,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - Localization is performed on database level and therefore the table `sap.changelog.i18nKeys` that stores localized labels was added
 - Expose localized label fields on `sap.changelog.ChangeView`
 
+### Removed
+- Removed configuration option `considerLocalizedValues`
+
 ## Version 1.1.4 - 03.12.25
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # Change Tracking Plugin for SAP Cloud Application Programming Model (CAP)
 
-a [CDS plugin](https://cap.cloud.sap/docs/node.js/cds-plugins#cds-plugin-packages) for automatic capturing, storing, and viewing of the change records of modeled entities
+a [CDS plugin](https://cap.cloud.sap/docs/node.js/cds-plugins#cds-plugin-packages) for automatic capturing, storing, and viewing of change records for modelled entities.
 
 [![REUSE status](https://api.reuse.software/badge/github.com/cap-js/change-tracking)](https://api.reuse.software/info/github.com/cap-js/change-tracking)
 
@@ -19,9 +19,8 @@ a [CDS plugin](https://cap.cloud.sap/docs/node.js/cds-plugins#cds-plugin-package
   - [Altered Table View](#altered-table-view)
   - [Disable Lazy Loading](#disable-lazy-loading)
   - [Disable UI Facet generation](#disable-ui-facet-generation)
-    - [Disable Association to Changes Generation](#disable-association-to-changes-generation)
+  - [Disable Association to Changes Generation](#disable-association-to-changes-generation)
 - [Examples](#examples)
-  - [Specify Object ID](#specify-object-id)
   - [Tracing Changes](#tracing-changes)
   - [Don'ts](#donts)
 - [Contributing](#contributing)
@@ -30,12 +29,23 @@ a [CDS plugin](https://cap.cloud.sap/docs/node.js/cds-plugins#cds-plugin-package
 
 ## Try it Locally
 
-To enable change tracking, simply add this self-configuring plugin package to your project:
+To enable change tracking, simply add this self-configuring plugin package to your project and add the `@changelog` annotation to your data model, as explained in the [Detailed Explanation](#detailed-explanation).
 
 ```sh
 npm add @cap-js/change-tracking
 ```
 
+Alternatively, a full sample application is provided in the `tests/bookshop` folder, against which you can test your changes:
+
+```sh
+git clone https://github.com/cap-js/change-tracking
+cd change-tracking
+npm i
+cd tests/bookshop
+cds watch
+```
+
+
 > [!Warning]
 >
 > Please note that if your project is multi-tenant, then the CDS version must be higher than 8.6 and the mtx version higher than 2.5 for change-tracking to work.
@@ -83,10 +93,6 @@ cds watch
 
 #### 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.
@@ -95,7 +101,7 @@ If you have a Fiori Element application, the CDS plugin automatically provides a
 
 ### Human-readable Types and Fields
 
-By default the implementation looks up *Object Type* names or *Field* names from 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* names from respective  `@title` or  `@Common.Label` annotations and uses the technical name as a fall back.
 
 For example, without the `@title` annotation, changes to conversation entries would show up with the technical entity name:
 
@@ -104,7 +110,7 @@ For example, without the `@title` annotation, changes to conversation entries wo
 With an annotation, and possible i18n translations like so:
 
 ```cds
-annotate Conversations with @title: 'Conversations';
+annotate Incidents.conversations with @title: '{i18n>CONVERSATION}';
 ```
 
 We get a human-readable display for *Object Type*:
@@ -115,21 +121,39 @@ We get a human-readable display for *Object Type*:
 
 The changelog annotations for *Object ID* are defined at entity level.
 
-These are already human-readable by default, unless the `@changelog` definition cannot be uniquely mapped such as types `enum` or `Association`.
-
-For example, having a `@changelog` annotation without any additional identifiers, changes to conversation entries would show up as simple entity IDs:
+Having a `@changelog` annotation without any additional identifiers, changes to conversation entries show up as simple entity IDs:
 
 <img width="1300" alt="change-history-id" src="_assets/changes-id-wbox.png">
 
-However, this is not advisable as we cannot easily distinguish between changes. It is more appropriate to annotate as follows:
+However, this is not advisable, with an explicit object ID increasing readability as follows:
 
 ```cds
-annotate ProcessorService.Conversations with @changelog: [author, timestamp] {
+annotate Incidents.conversation with @changelog: [author, timestamp];
 ```
 
 <img width="1300" alt="change-history-id-hr" src="_assets/changes-id-hr-wbox.png">
 
-Expanding the changelog annotation by additional identifiers `[author, timestamp]`, we can now better identify the `message` change events by their respective author and timestamp.
+The annotation accepts a list of paths, meaning the following examples are all possible as well:
+
+```cds
+type CustomType : String;
+
+extend Customers with elements {
+  note: CustomType
+}
+
+annotate Incidents with @changelog: [
+  title, customer.note, urgency.name
+];
+```
+
+```cds
+annotate Incidents with @changelog: [
+  customer.address.city, customer.address.streetAddress, status.criticality
+] {
+  title    @changelog;
+}
+```
 
 ### Human-readable Values
 
@@ -153,27 +177,33 @@ customer @changelog: [customer.name];
 
 <img width="1300" alt="change-history-value-hr" src="_assets/changes-value-hr-wbox.png">
 
+### Tracing any kind of change
+
+Change tracking is implemented with Database triggers and supports HANA Cloud, SQLite, Postgres and H2.
+
+Leveraging database triggers means any change will be tracked no matter how it is represented in the service. Thus tracking changes made via unions, or via views with joins will still work.
+
 ## Advanced Options
 
 ### Altered table view
 
-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:
+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 `db/change-tracking.cds` as follows:
 
 ```cds
 using from '@cap-js/change-tracking';
 
 annotate sap.changelog.ChangeView with @(
   UI.LineItem : [
-    { Value: modification, @HTML5.CssDefaults: { width:'20%' }},
-    { Value: createdAt,    @HTML5.CssDefaults: { width:'20%' }},
-    { Value: createdBy,    @HTML5.CssDefaults: { width:'20%' }},
-    { Value: entity,       @HTML5.CssDefaults: { width:'20%' }},
-    { Value: objectID,     @HTML5.CssDefaults: { width:'20%' }}
+    { Value: modificationLabel },
+    { Value: createdAt },
+    { Value: createdBy },
+    { Value: entityLabel },
+    { Value: objectID }
   ]
 );
 ```
 
-In the UI, the *Change History* table now contains 5 equally-spaced columns with the desired properties:
+In the UI, the *Change History* table now contains only the five columns with the desired properties:
 
 <img width="1300" alt="change-history-custom" src="_assets/changes-custom.png">
 
@@ -181,7 +211,7 @@ For more information and examples on adding Fiori Annotations, see [Adding SAP F
 
 ### 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`:
+To disable the lazy loading feature of the *Change History* table, you can add the following annotation to your `db/change-tracking.cds`:
 
 ```cds
 using from '@cap-js/change-tracking';
@@ -191,11 +221,11 @@ annotate sap.changelog.aspect @(UI.Facets: [{
   ID    : 'ChangeHistoryFacet',
   Label : '{i18n>ChangeHistory}',
   Target: 'changes/@UI.PresentationVariant',
-  ![@UI.PartOfPreview]
+  @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.
+The system now uses the SAP Fiori elements default setting `@UI.PartOfPreview: true`, such that the table will always be shown when navigating to that respective Object page.
 
 ### Disable UI Facet generation
 
@@ -220,10 +250,10 @@ entity SalesOrders {
 
 ### Disable Association to Changes Generation
 
-For some scenarios, e.g. when doing `UNION` and the `@changelog` annotion is still propageted, the automatic addition of the association to `changes` does not make sense. You can use `@changelog.disable_assoc`for this to be disabled on entity level.
+For some scenarios, e.g. when doing `UNION` and the `@changelog` annotation is still propagated, the automatic addition of the association to `changes` does not make sense. You can use `@changelog.disable_assoc`for this to be disabled on entity level.
 
 > [!IMPORTANT]
-> This will also supress the addition of the UI facet, since the change-view is not available as target entity anymore.
+> This will also suppress the addition of the UI facet, since the change-view is no longer available as the target entity.
 
 ### Select types of changes to track
 
@@ -249,25 +279,39 @@ By default, deleting a record will also automatically delete all associated chan
 You can turn this behavior off globally by adding the following switch to the `package.json` of your project
 
 ```json
-...
 "cds": {
   "requires": {
-    ...
     "change-tracking": {
       "preserveDeletes": true
     }
-   ...
   }
 }
-...
 ```
+
 > [!IMPORTANT]
 > Preserving the change logs of deleted data can have a significant impact on the size of the change logging table, since now such data also survives automated data retention runs. 
 > You must implement an own **data retention strategy** for the change logging table in order to manage the size and performance of your database.
 
+### Adjust the depth of the entity hierarchy tracking
+
+By default, the depth of the changes hierarchy for any entity is 3. This means, its changes as well as the changes of its compositions and the compositions of its compositions are shown on the UI.
+
+```json
+"cds": {
+  "requires": {
+    "change-tracking": {
+      "maxDisplayHierarchyDepth": 3
+    }
+  }
+}
+```
+
+> [!IMPORTANT]
+> The depth of the hierarchy has a performance impact, so be careful with increasing it!
+
 ### Tracking localized values
 
-If you are using a model like 
+Localized properties, like `descr` in the example, are respected and the localized value during change log creation is used for the label.
 
 ```cds
 entity Incidents : cuid, managed {
@@ -281,129 +325,20 @@ entity Status {
 }
 ```
 
-you can save the localized values into the change log instead of the default values, by setting `considerLocalizedValues`:
-
-```json
-...
-"cds": {
-  "requires": {
-    "change-tracking": {
-      "considerLocalizedValues": true
-    }
-  }
-}
-...
-```
-
 Please be aware this means the localized value is then stored and shown in the change log, e.g. if a user speaking another language accesses the change log later, they will still see the value in the language used by the user who caused the change log.
 
 ## Examples
 
 This section describes modelling cases for further reference, from simple to complex, including the following:
 
-- [Specify Object ID](#specify-object-id)
-  - [Use Case 1: Annotate single field/multiple fields of associated table(s) as the Object ID](#use-case-1-annotate-single-fieldmultiple-fields-of-associated-tables-as-the-object-id)
-  - [Use Case 2: Annotate single field/multiple fields of project customized types as the Object ID](#use-case-2-annotate-single-fieldmultiple-fields-of-project-customized-types-as-the-object-id)
-  - [Use Case 3: Annotate chained associated entities from the current entity as the Object ID](#use-case-3-annotate-chained-associated-entities-from-the-current-entity-as-the-object-id)
 - [Tracing Changes](#tracing-changes)
   - [Use Case 1: Trace the changes of child nodes from the current entity and display the meaningful data from child nodes (composition relation)](#use-case-1-trace-the-changes-of-child-nodes-from-the-current-entity-and-display-the-meaningful-data-from-child-nodes-composition-relation)
   - [Use Case 2: Trace the changes of associated entities from the current entity and display the meaningful data from associated entities (association relation)](#use-case-2-trace-the-changes-of-associated-entities-from-the-current-entity-and-display-the-meaningful-data-from-associated-entities-association-relation)
-  - [Use Case 3: Trace the changes of fields defined by project customized types and display the meaningful data](#use-case-3-trace-the-changes-of-fields-defined-by-project-customized-types-and-display-the-meaningful-data)
-  - [Use Case 4: Trace the changes of chained associated entities from the current entity and display the meaningful data from associated entities (association relation)](#use-case-4-trace-the-changes-of-chained-associated-entities-from-the-current-entity-and-display-the-meaningful-data-from-associated-entities-association-relation)
-  - [Use Case 5: Trace the changes of union entity and display the meaningful data](#use-case-5-trace-the-changes-of-union-entity-and-display-the-meaningful-data)
+  - [Use Case 3: Trace the changes of chained associated entities from the current entity and display the meaningful data from associated entities (association relation)](#use-case-3-trace-the-changes-of-chained-associated-entities-from-the-current-entity-and-display-the-meaningful-data-from-associated-entities-association-relation)
 - [Don&#39;ts](#donts)
   - [Use Case 1: Don&#39;t trace changes for field(s) with `Association to many`](#use-case-1-dont-trace-changes-for-fields-with-association-to-many)
   - [Use Case 2: Don&#39;t trace changes for field(s) with *Unmanaged Association*](#use-case-2-dont-trace-changes-for-fields-with-unmanaged-association)
 
-### Specify Object ID
-
-Use cases for Object ID annotation
-
-#### Use Case 1: Annotate single field/multiple fields of associated table(s) as the Object ID
-
-Modelling in `db/schema.cds`
-
-```cds
-entity Incidents : cuid, managed {
-  ...
-  customer       : Association to Customers;
-  title          : String @title: 'Title';
-  urgency        : Association to Urgency default 'M';
-  status         : Association to Status default 'N';
-  ...
-}
-```
-
-Add the following `@changelog` annotations in `srv/change-tracking.cds`
-
-```cds
-annotate ProcessorService.Incidents with @changelog: [customer.name, urgency.code, status.criticality] {
-  title    @changelog;
-}
-```
-
-![AssociationID](_assets/AssociationID.png)
-
-#### Use Case 2: Annotate single field/multiple fields of project customized types as the Object ID
-
-Modelling in `db/schema.cds`
-
-```cds
-entity Incidents : cuid, managed {
-  ...
-  customer       : Association to Customers;
-  title          : String @title: 'Title';
-  ...
-}
-
-entity Customers : cuid, managed {
-  ...
-  email          : EMailAddress;  // customized type
-  phone          : PhoneNumber;   // customized type
-  ...
-}
-```
-
-Add the following `@changelog` annotations in `srv/change-tracking.cds`
-
-```cds
-annotate ProcessorService.Incidents with @changelog: [customer.email, customer.phone] {
-  title    @changelog;
-}
-```
-
-![CustomTypeID](_assets/CustomTypeID.png)
-
-#### Use Case 3: Annotate chained associated entities from the current entity as the Object ID
-
-Modelling in `db/schema.cds`
-
-```cds
-entity Incidents : cuid, managed {
-  ...
-  customer       : Association to Customers;
-  ...
-}
-
-entity Customers : cuid, managed {
-  ...
-  addresses : Association to Addresses;
-  ...
-}
-```
-
-Add the following `@changelog` annotations in `srv/change-tracking.cds`
-
-```cds
-annotate ProcessorService.Incidents with @changelog: [customer.addresses.city, customer.addresses.postCode] {
-  title    @changelog;
-}
-```
-
-![ChainedAssociationID](_assets/ChainedAssociationID.png)
-
-> Change-tracking supports annotating chained associated entities from the current entity as object ID of current entity in case the entity in consumer applications is a pure relation table. However, the usage of chained associated entities is not recommended due to performance cost.
-
 ### Tracing Changes
 
 Use cases for tracing changes
@@ -426,16 +361,14 @@ aspect Conversation: managed, cuid {
 }
 ```
 
-Add the following `@changelog` annotations in `srv/change-tracking.cds`
+Add the following `@changelog` annotations in `db/change-tracking.cds`
 
 ```cds
-annotate ProcessorService.Incidents with @changelog: [title] {
+annotate Incidents with @changelog: [title] {
   conversation @changelog: [conversation.message];
 }
 ```
 
-![CompositionChange](_assets/CompositionChange.png)
-
 #### Use Case 2: Trace the changes of associated entities from the current entity and display the meaningful data from associated entities (association relation)
 
 Modelling in `db/schema.cds`
@@ -455,42 +388,15 @@ entity Customers : cuid, managed {
 }
 ```
 
-Add the following `@changelog` annotations in `srv/change-tracking.cds`
+Add the following `@changelog` annotations in `db/change-tracking.cds`
 
 ```cds
-annotate ProcessorService.Incidents with @changelog: [title] {
+annotate Incidents with @changelog: [title] {
   customer @changelog: [customer.email];
 }
 ```
 
-![AssociationChange](_assets/AssociationChange.png)
-
-#### Use Case 3: Trace the changes of fields defined by project customized types and display the meaningful data
-
-Modelling in `db/schema.cds`
-
-```cds
-type StatusType : Association to Status;
-
-entity Incidents : cuid, managed {
-  ...
-  title          : String @title: 'Title';
-  status         : StatusType default 'N';
-  ...
-}
-```
-
-Add the following `@changelog` annotations in `srv/change-tracking.cds`
-
-```cds
-annotate ProcessorService.Incidents with @changelog: [title] {
-  status   @changelog: [status.code];
-}
-```
-
-![CustomTypeChange](_assets/CustomTypeChange.png)
-
-#### Use Case 4: Trace the changes of chained associated entities from the current entity and display the meaningful data from associated entities (association relation)
+#### Use Case 3: Trace the changes of chained associated entities from the current entity and display the meaningful data from associated entities (association relation)
 
 Modelling in `db/schema.cds`
 
@@ -504,73 +410,21 @@ entity Incidents : cuid, managed {
 
 entity Customers : cuid, managed {
   ...
-  addresses : Association to Addresses;
+  address : Composition of one Addresses;
   ...
 }
 ```
 
-Add the following `@changelog` annotations in `srv/change-tracking.cds`
+Add the following `@changelog` annotations in `db/change-tracking.cds`
 
 ```cds
-annotate ProcessorService.Incidents with @changelog: [title] {
-  customer @changelog: [customer.addresses.city, customer.addresses.streetAddress];
+annotate Incidents with @changelog: [title] {
+  customer @changelog: [customer.address.city, customer.address.streetAddress];
 }
 ```
 
-![ChainedAssociationChange](_assets/ChainedAssociationChange.png)
-
 > Change-tracking supports analyzing chained associated entities from the current entity in case the entity in consumer applications is a pure relation table. However, the usage of chained associated entities is not recommended due to performance cost.
 
-#### Use Case 5: Trace the changes of union entity and display the meaningful data
-
-`Payable.cds`:
-
-```cds
-entity Payables : cuid {
-    displayId    : String;
-    @changelog
-    name         : String;
-    cryptoAmount : Decimal;
-    fiatAmount   : Decimal;
-};
-```
-
-`Payment.cds`:
-
-```cds
-entity Payments : cuid {
-    displayId : String; //readable ID
-    @changelog
-    name      : String;
-};
-```
-
-Union entity in `BusinessTransaction.cds`:
-
-```cds
-entity BusinessTransactions          as(
-    select from payments.Payments{
-        key ID,
-            displayId,
-            name,
-            changes  : Association to many ChangeView
-                on changes.objectID = ID AND changes.entity = 'payments.Payments'
-    }
-)
-union all
-(
-    select from payables.Payables {
-        key ID,
-            displayId,
-            name,
-            changes  : Association to many ChangeView
-               on changes.objectID = ID AND changes.entity = 'payables.Payables'
-    }
-);
-```
-
-![UnionChange.png](_assets/UnionChange.png)
-
 ### Don'ts
 
 Don'ts
@@ -605,17 +459,6 @@ The reason is that: When deploying to relational databases, Associations are map
 
 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).
 
-### Testing changes locally
-
-In the `tests/bookshop` folder a full sample application is provided, against which you can test your changes:
-
-```sh
-git clone https://github.com/cap-js/change-tracking
-npm i
-cd tests/bookshop
-cds watch
-```
-
 ## 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/index.cds

@@ -33,27 +33,18 @@ entity aspect @(UI.Facets: [{
 view ChangeView as
   select from Changes as change
   left outer join i18nKeys as attributeI18n
-    on   attributeI18n.ID     = change.attribute
-    and (
-         attributeI18n.locale = $user.locale
-      or attributeI18n.locale = 'en'
-    )
+    on  attributeI18n.ID     = change.attribute
+    and attributeI18n.locale = $user.locale
   left outer join i18nKeys as entityI18n
-    on   entityI18n.ID     = change.entity
-    and (
-         entityI18n.locale = $user.locale
-      or entityI18n.locale = 'en'
-    )
+    on  entityI18n.ID     = change.entity
+    and entityI18n.locale = $user.locale
   left outer join i18nKeys as modificationI18n
-    on   modificationI18n.ID     = change.modification
-    and (
-         modificationI18n.locale = $user.locale
-      or modificationI18n.locale = 'en'
-    )
+    on  modificationI18n.ID     = change.modification
+    and modificationI18n.locale = $user.locale
   {
     key change.ID                                     @UI.Hidden,
-        change.parent: redirected to ChangeView,
-        change.children: redirected to ChangeView,
+        change.parent                  : redirected to ChangeView,
+        change.children                : redirected to ChangeView,
         change.attribute,
         change.valueChangedFrom,
         change.valueChangedTo,
@@ -66,20 +57,41 @@ view ChangeView as
         change.createdBy,
         change.transactionID,
         COALESCE(
-          attributeI18n.text, change.attribute
+          attributeI18n.text, (
+            select text from i18nKeys
+            where
+                  ID     = change.attribute
+              and locale = 'en'
+          ), change.attribute
         )    as attributeLabel         : String(15)   @title: '{i18n>Changes.attribute}',
         COALESCE(
-          entityI18n.text, change.entity
+          entityI18n.text, (
+            select text from i18nKeys
+            where
+                  ID     = change.entity
+              and locale = 'en'
+          ), change.entity
         )    as entityLabel            : String(24)   @title: '{i18n>Changes.entity}',
         COALESCE(
-          modificationI18n.text, change.modification
+          modificationI18n.text, (
+            select text from i18nKeys
+            where
+                  ID     = change.modification
+              and locale = 'en'
+          ), change.modification
         )    as modificationLabel      : String(16)   @title: '{i18n>Changes.modification}',
         COALESCE(
           change.valueChangedFromLabel, change.valueChangedFrom
-        )    as valueChangedFromLabel  : String(5000) @title: '{i18n>Changes.valueChangedFrom}',
+        )    as valueChangedFromLabel  : String(5000) @(
+                                           title: '{i18n>Changes.valueChangedFrom}',
+                                           UI.MultiLineText
+                                         ),
         COALESCE(
           change.valueChangedToLabel, change.valueChangedTo
-        )    as valueChangedToLabel    : String(5000) @title: '{i18n>Changes.valueChangedTo}',
+        )    as valueChangedToLabel    : String(5000) @(
+                                           title: '{i18n>Changes.valueChangedTo}',
+                                           UI.MultiLineText
+                                         ),
         // For the hierarchy
         null as LimitedDescendantCount : Int16        @UI.Hidden,
         null as DistanceFromRoot       : Int16        @UI.Hidden,
@@ -216,3 +228,28 @@ annotate ChangeView with @(
     'LimitedRank'
   ],
 );
+
+// Annotations for searching
+annotate ChangeView with @(cds.search: {
+  valueChangedFrom: false,
+  valueChangedTo  : false,
+  entity          : false,
+  attribute       : false,
+  modification    : false,
+  valueDataType   : false,
+  modificationLabel,
+  entityLabel,
+  entityKey,
+  objectID,
+  attributeLabel,
+  valueChangedFromLabel,
+  valueChangedToLabel,
+  createdBy,
+}) {
+  entityLabel       @Search.ranking: HIGH;
+  attributeLabel    @Search.ranking: HIGH;
+  objectID          @Search.ranking: HIGH;
+
+  entityKey         @Search.ranking: LOW;
+  modificationLabel @Search.ranking: LOW;
+};

package/lib/h2/java-codegen.js

@@ -709,7 +709,7 @@ function _generateObjectIDCalculation(objectIDs, entity, refRow, model) {
 
 	for (const oid of objectIDs) {
 		if (oid.included) {
-			parts.push(`SELECT CAST(? AS VARCHAR) AS val`);
+			parts.push(`SELECT COALESCE(CAST(? AS VARCHAR), '<empty>') AS val`);
 			bindings.push(`${refRow}.getString("${oid.name}")`);
 		} else {
 			// Sub-select needed (Lookup)

package/lib/hana/register.js

@@ -1,7 +1,7 @@
 const cds = require('@sap/cds');
-const { fs } = cds.utils;
 
-const { prepareCSNForTriggers, generateTriggersForEntities, writeLabelsCSV, ensureUndeployJsonHasTriggerPattern } = require('../utils/trigger-utils.js');
+const { prepareCSNForTriggers, generateTriggersForEntities, ensureUndeployJsonHasTriggerPattern } = require('../utils/trigger-utils.js');
+const { getLabelTranslations } = require('../localization.js');
 
 function registerHDICompilerHook() {
 	const _hdi_migration = cds.compiler.to.hdi.migration;
@@ -10,17 +10,36 @@ function registerHDICompilerHook() {
 		const { runtimeCSN, hierarchy, entities } = prepareCSNForTriggers(csn, true);
 
 		const triggers = generateTriggersForEntities(runtimeCSN, hierarchy, entities, generateHANATriggers);
-
+		const data = [];
 		if (triggers.length > 0) {
 			delete csn.definitions['sap.changelog.CHANGE_TRACKING_DUMMY']['@cds.persistence.skip'];
-			writeLabelsCSV(entities, runtimeCSN);
-			const dir = 'db/src/gen/data/';
-			fs.writeFileSync(`${dir}/sap.changelog-CHANGE_TRACKING_DUMMY.csv`, `X\n1`);
 			ensureUndeployJsonHasTriggerPattern();
+
+			const labels = getLabelTranslations(entities, runtimeCSN);
+			const header = 'ID;locale;text';
+			const escape = (v) => {
+				const s = String(v ?? '');
+				return s.includes(';') || s.includes('\n') || s.includes('"') ? `"${s.replace(/"/g, '""')}"` : s;
+			};
+			const rows = labels.map((row) => `${escape(row.ID)};${escape(row.locale)};${escape(row.text)}`);
+			const i18nContent = [header, ...rows].join('\n') + '\n';
+
+			data.push(
+				{
+					name: 'sap.changelog-CHANGE_TRACKING_DUMMY',
+					sql: 'X\n1',
+					suffix: '.csv'
+				},
+				{
+					name: 'sap.changelog-i18nKeys',
+					sql: i18nContent,
+					suffix: '.csv'
+				}
+			);
 		}
 
 		const ret = _hdi_migration(csn, options, beforeImage);
-		ret.definitions = [...ret.definitions, ...triggers];
+		ret.definitions = ret.definitions.concat(triggers).concat(data);
 		return ret;
 	};
 }

package/lib/hana/sql-expressions.js

@@ -152,7 +152,7 @@ function buildObjectIDExpr(objectIDs, entity, rowRef, model) {
 	const parts = [];
 	for (const oid of objectIDs) {
 		if (oid.included) {
-			parts.push(`TO_NVARCHAR(:${rowRef}.${oid.name})`);
+			parts.push(`COALESCE(TO_NVARCHAR(:${rowRef}.${oid.name}), '<empty>')`);
 		} else {
 			const where = keys.reduce((acc, k) => {
 				acc[k] = { val: `:${rowRef}.${k}` };

package/lib/postgres/sql-expressions.js

@@ -137,7 +137,7 @@ function buildObjectIDAssignment(objectIDs, entity, keys, recVar, targetVar, mod
 	const parts = [];
 	for (const oid of objectIDs) {
 		if (oid.included) {
-			parts.push(`${recVar}.${oid.name}::TEXT`);
+			parts.push(`COALESCE(${recVar}.${oid.name}::TEXT, '<empty>')`);
 		} else {
 			const where = keys.reduce((acc, k) => {
 				acc[k] = { val: `${recVar}.${k}` };

package/lib/sqlite/sql-expressions.js

@@ -148,7 +148,7 @@ function buildObjectIDSelect(objectIDs, entityName, entityKeys, refRow, model) {
 		objectID.selectSQL = toSQL(query, model);
 	}
 
-	const unionParts = objectIDs.map((id) => (id.included ? `SELECT ${refRow}.${id.name} AS value WHERE ${refRow}.${id.name} IS NOT NULL` : `SELECT (${id.selectSQL}) AS value`));
+	const unionParts = objectIDs.map((id) => (id.included ? `SELECT COALESCE(${refRow}.${id.name}, '<empty>') AS value` : `SELECT (${id.selectSQL}) AS value`));
 
 	return `(SELECT GROUP_CONCAT(value, ', ') FROM (${unionParts.join('\nUNION ALL\n')}))`;
 }

package/lib/utils/change-tracking.js

@@ -105,8 +105,12 @@ function extractTrackedColumns(entity, model = cds.context?.model ?? cds.model,
 		// Use override annotation if provided, otherwise use the element's own annotation
 		const changelogAnnotation = overrideAnnotations?.elementAnnotations?.[name] ?? col['@changelog'];
 
-		// Skip non-changelog columns + association columns (we want the generated FKs instead)
-		if (!changelogAnnotation || col._foreignKey4 || col['@odata.foreignKey4']) continue;
+		// Skip foreign key columns (we want the generated FKs instead)
+		if (col._foreignKey4 || col['@odata.foreignKey4']) continue;
+
+		// Auto-include composition elements, unless explicitly defined with @changelog: false
+		const isComposition = col.type === 'cds.Composition';
+		if ((!changelogAnnotation && !isComposition) || changelogAnnotation === false) continue;
 
 		// skip any PersonalData* annotation
 		const hasPersonalData = Object.keys(col).some((k) => k.startsWith('@PersonalData'));

package/lib/utils/composition-helpers.js

@@ -2,8 +2,6 @@ const utils = require('./change-tracking.js');
 
 /**
  * Finds composition parent info for an entity.
- * Checks if root entity has a @changelog annotation on a composition field pointing to this entity.
- *
  * Returns null if not found, or an object with:
  *   { parentEntityName, compositionFieldName, parentKeyBinding, isCompositionOfOne }
  */
@@ -13,9 +11,9 @@ function getCompositionParentInfo(entity, rootEntity, rootMergedAnnotations) {
 	for (const [elemName, elem] of Object.entries(rootEntity.elements)) {
 		if (elem.type !== 'cds.Composition' || elem.target !== entity.name) continue;
 
-		// Check if this composition has @changelog annotation
+		// Check if this composition has @changelog: false annotation
 		const changelogAnnotation = rootMergedAnnotations?.elementAnnotations?.[elemName] ?? elem['@changelog'];
-		if (!changelogAnnotation) continue;
+		if (changelogAnnotation === false) continue;
 
 		// Found a tracked composition - get the FK binding from child to parent
 		const parentKeyBinding = utils.getCompositionParentBinding(entity, rootEntity);
@@ -46,12 +44,12 @@ function getCompositionParentInfo(entity, rootEntity, rootMergedAnnotations) {
 function getGrandParentCompositionInfo(rootEntity, grandParentEntity, grandParentMergedAnnotations, grandParentCompositionField) {
 	if (!grandParentEntity || !grandParentCompositionField) return null;
 
-	// Check if the grandparent's composition field has @changelog annotation
+	// Check if the grandparent's composition field has @changelog: false annotation
 	const elem = grandParentEntity.elements?.[grandParentCompositionField];
 	if (!elem || elem.type !== 'cds.Composition' || elem.target !== rootEntity.name) return null;
 
 	const changelogAnnotation = grandParentMergedAnnotations?.elementAnnotations?.[grandParentCompositionField] ?? elem['@changelog'];
-	if (!changelogAnnotation) return null;
+	if (changelogAnnotation === false) return null;
 
 	// Get FK binding from rootEntity to grandParentEntity
 	const grandParentKeyBinding = utils.getCompositionParentBinding(rootEntity, grandParentEntity);

package/lib/utils/entity-collector.js

@@ -8,6 +8,11 @@ function isChangeTracked(entity) {
 	return Object.values(entity.elements).some((e) => e['@changelog']);
 }
 
+function _hasTrackedElements(entity) {
+	if (!entity?.elements) return false;
+	return Object.values(entity.elements).some((e) => e['@changelog'] && e['@changelog'] !== false);
+}
+
 // Compares two @changelog annotation values for equality
 function _annotationsEqual(a, b) {
 	// Handle null/undefined/false cases
@@ -97,20 +102,27 @@ function _mergeChangelogAnnotations(dbEntity, serviceEntities) {
 	};
 }
 
-function getEntitiesForTriggerGeneration(model, collected) {
-	const result = [];
-	const processedDbEntities = new Set();
+function _extractServiceAnnotations(serviceEntity) {
+	const entityAnnotation = serviceEntity['@changelog'];
+	const elementAnnotations = {};
+	for (const element of serviceEntity.elements) {
+		if (element['@changelog'] !== undefined) {
+			elementAnnotations[element.name] = element['@changelog'];
+		}
+	}
+	return { entity: serviceEntity, entityAnnotation, elementAnnotations };
+}
 
-	// Process collected service entities - resolve entities and annotations from names
+// Resolve collected service entities into DB entities with merged annotations
+function _collectServiceEntities(model, collected, result, processed) {
 	for (const [dbEntityName, serviceEntityNames] of collected) {
-		processedDbEntities.add(dbEntityName);
+		processed.add(dbEntityName);
 		const dbEntity = model[dbEntityName];
 		if (!dbEntity) {
 			DEBUG?.(`DB entity ${dbEntityName} not found in model, skipping`);
 			continue;
 		}
 
-		// Resolve service entities and extract their annotations
 		const serviceEntities = [];
 		for (const name of serviceEntityNames) {
 			const serviceEntity = model[name];
@@ -118,21 +130,7 @@ function getEntitiesForTriggerGeneration(model, collected) {
 				DEBUG?.(`Service entity ${name} not found in model, skipping`);
 				continue;
 			}
-
-			// Extract @changelog annotations from the service entity
-			const entityAnnotation = serviceEntity['@changelog'];
-			const elementAnnotations = {};
-			for (const element of serviceEntity.elements) {
-				if (element['@changelog'] !== undefined) {
-					elementAnnotations[element.name] = element['@changelog'];
-				}
-			}
-
-			serviceEntities.push({
-				entity: serviceEntity,
-				entityAnnotation,
-				elementAnnotations
-			});
+			serviceEntities.push(_extractServiceAnnotations(serviceEntity));
 		}
 
 		try {
@@ -144,42 +142,68 @@ function getEntitiesForTriggerGeneration(model, collected) {
 			throw error;
 		}
 	}
+}
 
-	// Add table entities that have @changelog but weren't collected
+// Include standalone DB entities that have @changelog but no service projection
+function _collectStandaloneEntities(model, result, processed) {
 	for (const def of model) {
 		const isTableEntity = def.kind === 'entity' && !def.query && !def.projection;
-		if (!isTableEntity || processedDbEntities.has(def.name)) continue;
+		if (!isTableEntity || processed.has(def.name)) continue;
 
 		if (isChangeTracked(def)) {
-			// No service entities collected, use null for mergedAnnotations (use entity's own annotations)
 			result.push({ dbEntityName: def.name, mergedAnnotations: null });
-			processedDbEntities.add(def.name);
+			processed.add(def.name);
 			DEBUG?.(`Including DB entity ${def.name} directly (no service entities collected)`);
 		}
 	}
+}
 
-	// Add composition-of-many target entities that have @changelog on the composition field
-	for (const { dbEntityName, mergedAnnotations } of [...result]) {
-		const dbEntity = model[dbEntityName];
+/**
+ * Auto-discover composition target entities up to the configured hierarchy depth
+ * Compositions are auto-tracked when the parent is tracked and field is not set to @changelog: false, and target has at least one @changelog element (or the field has an explicit @changelog)
+ */
+function _discoverCompositionTargets(model, result, processed) {
+	const maxDepth = cds.env.requires?.['change-tracking']?.maxDisplayHierarchyDepth ?? 3;
+	let currentEntities = [...result];
+
+	for (let depth = 1; depth < maxDepth; depth++) {
+		const newEntities = [];
 
-		for (const element of Object.values(dbEntity.elements)) {
-			if (element.type !== 'cds.Composition' || !element.is2many || !element.target) continue;
+		for (const { dbEntityName, mergedAnnotations } of currentEntities) {
+			const dbEntity = model[dbEntityName];
+			if (!dbEntity) continue;
 
-			const changelogAnnotation = mergedAnnotations?.elementAnnotations?.[element.name] ?? element['@changelog'];
-			if (!changelogAnnotation) continue;
+			for (const element of Object.values(dbEntity.elements)) {
+				if (element.type !== 'cds.Composition' || !element.target) continue;
+				if (processed.has(element.target)) continue;
 
-			// Skip if target entity is already processed
-			if (processedDbEntities.has(element.target)) continue;
+				const changelogAnnotation = mergedAnnotations?.elementAnnotations?.[element.name] ?? element['@changelog'];
+				if (changelogAnnotation === false) continue;
 
-			const targetEntity = model[element.target];
-			if (!targetEntity) continue;
+				const targetEntity = model[element.target];
+				if (!targetEntity) continue;
+				if (!changelogAnnotation && !_hasTrackedElements(targetEntity)) continue;
 
-			// Add target entity with null mergedAnnotations (it uses its own annotations, if any)
-			result.push({ dbEntityName: element.target, mergedAnnotations: null });
-			processedDbEntities.add(element.target);
-			DEBUG?.(`Including composition target ${element.target} for tracked composition ${element.name} on ${dbEntityName}`);
+				const entry = { dbEntityName: element.target, mergedAnnotations: null };
+				result.push(entry);
+				processed.add(element.target);
+				newEntities.push(entry);
+				DEBUG?.(`Including composition target ${element.target} for ${changelogAnnotation ? 'tracked' : 'auto-tracked'} composition ${element.name} on ${dbEntityName} (depth ${depth})`);
+			}
 		}
+
+		if (newEntities.length === 0) break;
+		currentEntities = newEntities;
 	}
+}
+
+function getEntitiesForTriggerGeneration(model, collected) {
+	const result = [];
+	const processed = new Set();
+
+	_collectServiceEntities(model, collected, result, processed);
+	_collectStandaloneEntities(model, result, processed);
+	_discoverCompositionTargets(model, result, processed);
 
 	return result;
 }
@@ -225,11 +249,12 @@ function analyzeCompositions(csn) {
 
 	// Second pass: build hierarchy with grandparent info
 	const hierarchy = new Map();
+	const maxDepth = cds.env.requires?.['change-tracking']?.maxDisplayHierarchyDepth ?? 3;
 	for (const [childName, parentInfo] of childParentMap) {
 		const { parent: parentName, compositionField } = parentInfo;
 
-		// Check if the parent itself has a parent (grandparent)
-		const grandParentInfo = childParentMap.get(parentName);
+		// Only include grandparent info if maxDisplayHierarchyDepth allows it (depth > 2 needed for grandparent)
+		const grandParentInfo = maxDepth > 2 ? childParentMap.get(parentName) : null;
 
 		hierarchy.set(childName, {
 			parent: parentName,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cap-js/change-tracking",
-	"version": "2.0.0-beta.2",
+	"version": "2.0.0-beta.3",
 	"publishConfig": {
 		"access": "public",
 		"tag": "beta"
@@ -44,7 +44,6 @@
 		"requires": {
 			"change-tracking": {
 				"model": "@cap-js/change-tracking",
-				"considerLocalizedValues": false,
 				"maxDisplayHierarchyDepth": 3,
 				"preserveDeletes": false
 			}