Skip to content

Commit 2e904bf

Browse files
smahatisjvansnkaputnik
authored
Rewrite readme (#92)
Co-authored-by: sjvans <[email protected]> Co-authored-by: Nick Josipovic <[email protected]>
1 parent 93b2128 commit 2e904bf

File tree

2 files changed

+76
-77
lines changed

2 files changed

+76
-77
lines changed

‎README.md‎

Lines changed: 76 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,43 @@
11
# Change Tracking Plugin for SAP Cloud Application Programming Model (CAP)
22

3-
[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/change-tracking)](https://api.reuse.software/info/github.com/cap-js/change-tracking)
3+
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
44

5-
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:
65

7-
1. [Install the plugin: `npm add @cap-js/change-tracking`](#setup)
8-
2. [Add `@changelog` annotations to your CDS models](#annotations)
9-
3. [Et voilà:](#change-history-view)
6+
> [!WARNING]
7+
> 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).
108
11-
<img width="1300" alt="change-history-loading" src="_assets/change-history.gif">
9+
[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/change-tracking)](https://api.reuse.software/info/github.com/cap-js/change-tracking)
1210

1311
### Table of Contents
1412

15-
- [Change Tracking Plugin for SAP Cloud Application Programming Model (CAP)](#change-tracking-plugin-for-sap-cloud-application-programming-model-cap)
16-
- [Table of Contents](#table-of-contents)
17-
- [Preliminaries](#preliminaries)
18-
- [Setup](#setup)
19-
- [Annotations](#annotations)
20-
- [Human-readable Types and Fields](#human-readable-types-and-fields)
21-
- [Human-readable IDs](#human-readable-ids)
22-
- [Human-readable Values](#human-readable-values)
23-
- [Test-drive locally](#test-drive-locally)
24-
- [Change History View](#change-history-view)
25-
- [Customizations](#customizations)
26-
- [Altered table view](#altered-table-view)
27-
- [Disable lazy loading](#disable-lazy-loading)
28-
- [Disable UI Facet generation](#disable-ui-facet-generation)
29-
- [Disable Association to Changes Generation](#disable-association-to-changes-generation)
30-
- [Modelling Samples](#modelling-samples)
31-
- [Specify Object ID](#specify-object-id)
32-
- [Tracing Changes](#tracing-changes)
33-
- [Don'ts](#donts)
34-
- [Contributing](#contributing)
35-
- [Code of Conduct](#code-of-conduct)
36-
- [Licensing](#licensing)
37-
38-
## Preliminaries
39-
40-
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:
41-
13+
- [Try it Locally](#try-it-locally)
14+
- [Detailed Explanation](#detailed-explanation)
15+
- [Human-readable Types and Fields](#human-readable-types-and-fields)
16+
- [Human-readable IDs](#human-readable-ids)
17+
- [Human-readable Values](#human-readable-values)
18+
- [Advanced Options](#advanced-options)
19+
- [Altered Table View](#altered-table-view)
20+
- [Disable Lazy Loading](#disable-lazy-loading)
21+
- [Examples](#examples)
22+
- [Specify Object ID](#specify-object-id)
23+
- [Tracing Changes](#tracing-changes)
24+
- [Don'ts](#donts)
25+
- [Contributing](#contributing)
26+
- [Code of Conduct](#code-of-conduct)
27+
- [Licensing](#licensing)
28+
29+
## Try it Locally
30+
31+
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.
32+
33+
1. [Prerequisites](#1-prerequisites)
34+
2. [Setup](#2-setup)
35+
3. [Annotations](#3-annotations)
36+
4. [Testing](#4-testing)
37+
38+
### 1. Prerequisites
39+
40+
Clone the repository and apply the step-by-step instructions:
4241
```sh
4342
git clone https://github.com/cap-js/incidents-app
4443
cd incidents-app
@@ -57,15 +56,15 @@ npm i
5756
cds w samples/change-tracking
5857
```
5958

60-
## Setup
59+
### 2. Setup
6160

6261
To enable change tracking, simply add this self-configuring plugin package to your project:
6362

6463
```sh
6564
npm add @cap-js/change-tracking
6665
```
6766

68-
## Annotations
67+
### 3. Annotations
6968

7069
> [!WARNING]
7170
> Please be aware that [**sensitive** or **personal** data](https://cap.cloud.sap/docs/guides/data-privacy/annotations#annotating-personal-data) (annotated with `@PersonalData`) is not change tracked, since viewing the log allows users to circumvent [audit-logging](https://cap.cloud.sap/docs/guides/data-privacy/audit-logging#setup).
@@ -90,9 +89,31 @@ The minimal annotation we require for change tracking is `@changelog` on element
9089

9190
Additional identifiers or labels can be added to obtain more *human-readable* change records as described below.
9291

92+
### 4. Testing
93+
94+
With the steps above, we have successfully set up change tracking for our reference application. Let's see that in action.
95+
96+
1. **Start the server**:
97+
```sh
98+
cds watch
99+
```
100+
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.
101+
102+
#### Change History View
103+
104+
> [!IMPORTANT]
105+
> To ensure proper lazy loading of the Change History table, please use **SAPUI5 version 1.120.0** or higher.<br>
106+
> If you wish to *disable* this feature, please see the customization section on how to [disable lazy loading](#disable-lazy-loading).
107+
108+
<img width="1300" alt="change-history" src="_assets/changes.png">
109+
110+
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.
111+
112+
## Detailed Explanation
113+
93114
### Human-readable Types and Fields
94115

95-
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.
116+
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.
96117

97118
For example, without the `@title` annotation, changes to conversation entries would show up with the technical entity name:
98119

@@ -116,10 +137,6 @@ These are already human-readable by default, unless the `@changelog` definition
116137

117138
For example, having a `@changelog` annotation without any additional identifiers, changes to conversation entries would show up as simple entity IDs:
118139

119-
```cds
120-
annotate ProcessorService.Conversations {
121-
```
122-
123140
<img width="1300" alt="change-history-id" src="_assets/changes-id-wbox.png">
124141

125142
However, this is not advisable as we cannot easily distinguish between changes. It is more appropriate to annotate as follows:
@@ -154,29 +171,7 @@ customer @changelog: [customer.name];
154171

155172
<img width="1300" alt="change-history-value-hr" src="_assets/changes-value-hr-wbox.png">
156173

157-
## Test-drive locally
158-
159-
With the steps above, we have successfully set up change tracking for our reference application. Let's see that in action.
160-
161-
1. **Start the server**:
162-
163-
```sh
164-
cds watch
165-
```
166-
167-
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.
168-
169-
## Change History View
170-
171-
> [!IMPORTANT]
172-
> To ensure proper lazy loading of the Change History table, please use **SAPUI5 version 1.120.0** or higher.<br>
173-
> If you wish to *disable* this feature, please see the customization section on how to [disable lazy loading](#disable-lazy-loading).
174-
175-
<img width="1300" alt="change-history" src="_assets/changes.png">
176-
177-
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.
178-
179-
## Customizations
174+
## Advanced Options
180175

181176
### Altered table view
182177

@@ -220,20 +215,24 @@ annotate sap.changelog.aspect @(UI.Facets: [{
220215

221216
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.
222217

223-
### Disable UI Facet generation
224-
225-
If you do not want the UI facet added to a specific UI, you can annotate the service entity with `@changelog.disable_facet`. This will disable the automatic addition of the UI faced to this specific entity, but also all views or further projections up the chain.
226-
227-
### Disable Association to Changes Generation
228-
229-
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.
230-
231-
> [!IMPORTANT]
232-
> This will also supress the addition of the UI facet, since the change-view is not available as target entity anymore.
233-
234-
## Modelling Samples
235-
236-
This chapter describes more modelling cases for further reference, from simple to complex, including but not limited to the followings.
218+
## Examples
219+
220+
This section describes modelling cases for further reference, from simple to complex, including the following:
221+
222+
- [Specify Object ID](#specify-object-id)
223+
- [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)
224+
- [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)
225+
- [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)
226+
- [Tracing Changes](#tracing-changes)
227+
- [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)
228+
- [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)
229+
- [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)
230+
- [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)
231+
- [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)
232+
- [Don'ts](#donts)
233+
- [Use Case 1: Don't trace changes for field(s) with `Association to many`](#use-case-1-dont-trace-changes-for-fields-with-association-to-many)
234+
- [Use Case 2: Don't trace changes for field(s) with *Unmanaged Association*](#use-case-2-dont-trace-changes-for-fields-with-unmanaged-association)
235+
- [Use Case 3: Don't trace changes for CUD on DB entity](#use-case-3-dont-trace-changes-for-cud-on-db-entity)
237236

238237
### Specify Object ID
239238

‎_assets/change-history.gif‎

-1.88 MB
Binary file not shown.

0 commit comments

Comments
 (0)