Skip to content

Commit

Permalink
Rewrite readme (#92)
Browse files Browse the repository at this point in the history 
Co-authored-by: sjvans <30337871+sjvans@users.noreply.github.com>
Co-authored-by: Nick Josipovic <nick.josipovic@gmail.com>
  • Loading branch information
@smahati @sjvans @nkaputnik
3 people authored Jun 28, 2024
1 parent 93b2128 commit 2e904bf
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 77 deletions.
153 changes: 76 additions & 77 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,43 @@
# 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)
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

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)
> [!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).
<img width="1300" alt="change-history-loading" src="_assets/change-history.gif">
[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/change-tracking)](https://api.reuse.software/info/github.com/cap-js/change-tracking)

### Table of Contents

- [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)
- [Disable UI Facet generation](#disable-ui-facet-generation)
- [Disable Association to Changes Generation](#disable-association-to-changes-generation)
- [Modelling Samples](#modelling-samples)
- [Specify Object ID](#specify-object-id)
- [Tracing Changes](#tracing-changes)
- [Don'ts](#donts)
- [Contributing](#contributing)
- [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:

- [Try it Locally](#try-it-locally)
- [Detailed Explanation](#detailed-explanation)
- [Human-readable Types and Fields](#human-readable-types-and-fields)
- [Human-readable IDs](#human-readable-ids)
- [Human-readable Values](#human-readable-values)
- [Advanced Options](#advanced-options)
- [Altered Table View](#altered-table-view)
- [Disable Lazy Loading](#disable-lazy-loading)
- [Examples](#examples)
- [Specify Object ID](#specify-object-id)
- [Tracing Changes](#tracing-changes)
- [Don'ts](#donts)
- [Contributing](#contributing)
- [Code of Conduct](#code-of-conduct)
- [Licensing](#licensing)

## Try it Locally

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.

1. [Prerequisites](#1-prerequisites)
2. [Setup](#2-setup)
3. [Annotations](#3-annotations)
4. [Testing](#4-testing)

### 1. Prerequisites

Clone the repository and apply the step-by-step instructions:
```sh
git clone https://github.com/cap-js/incidents-app
cd incidents-app
Expand All @@ -57,15 +56,15 @@ npm i
cds w samples/change-tracking
```

## Setup
### 2. Setup

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

```sh
npm add @cap-js/change-tracking
```

## Annotations
### 3. Annotations

> [!WARNING]
> 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).
Expand All @@ -90,9 +89,31 @@ 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.

### 4. Testing

With the steps above, we have successfully set up change tracking for our reference application. Let's see that in action.

1. **Start the server**:
```sh
cds watch
```
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

> [!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.

## Detailed Explanation

### 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* 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.

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

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

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

```cds
annotate ProcessorService.Conversations {
```

<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:
Expand Down Expand Up @@ -154,29 +171,7 @@ customer @changelog: [customer.name];
<img width="1300" alt="change-history-value-hr" src="_assets/changes-value-hr-wbox.png">
## Test-drive locally

With the steps above, we have successfully set up change tracking for our reference application. Let's see that in action.

1. **Start the server**:

```sh
cds watch
```

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

> [!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
## Advanced Options
### Altered table view
Expand Down Expand Up @@ -220,20 +215,24 @@ annotate sap.changelog.aspect @(UI.Facets: [{
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.
### Disable UI Facet generation

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.

### 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.

> [!IMPORTANT]
> This will also supress the addition of the UI facet, since the change-view is not available as target entity anymore.
## Modelling Samples

This chapter describes more modelling cases for further reference, from simple to complex, including but not limited to the followings.
## 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)
- [Don'ts](#donts)
- [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)
- [Use Case 2: Don't trace changes for field(s) with *Unmanaged Association*](#use-case-2-dont-trace-changes-for-fields-with-unmanaged-association)
- [Use Case 3: Don't trace changes for CUD on DB entity](#use-case-3-dont-trace-changes-for-cud-on-db-entity)
### Specify Object ID
Expand Down
Binary file removed _assets/change-history.gif
View file
Binary file not shown.

0 comments on commit 2e904bf

Please sign in to comment.