Welcome to @cap-js/audit-logging

@cap-js/audit-logging is a CDS plugin providing integration to the SAP Audit Log service as well as out-of-the-box personal data-related audit logging based on annotations.

Documentation can be found at cap.cloud.sap.

[!IMPORTANT] The information in this file is by no means complete but enables you to get started quickly. Make sure to read the provided documentation at cap.cloud.sap to get the full picture.

Preliminaries

In this guide, we use the Incidents Management reference sample app as the base to add change tracking to. Clone the repository and apply the step-by-step instructions:

1git clone https://github.com/cap-js/incidents-app
2cd incidents-app
3npm i

Setup

To enable audit logging, simply add this self-configuring plugin package to your project:

1npm add @cap-js/audit-logging

Annotate Personal Data

Identify entities and elements (potentially) holding personal data using @PersonalData annotations. Create a db/data-privacy.cds file and add the following:

1using { sap.capire.incidents as my } from './schema';
2
3annotate my.Customers with @PersonalData : {
4  DataSubjectRole : 'Customer',
5  EntitySemantics : 'DataSubject'
6} {
7  ID           @PersonalData.FieldSemantics: 'DataSubjectID';
8  firstName    @PersonalData.IsPotentiallyPersonal;
9  lastName     @PersonalData.IsPotentiallyPersonal;
10  email        @PersonalData.IsPotentiallyPersonal;
11  phone        @PersonalData.IsPotentiallyPersonal;
12  creditCardNo @PersonalData.IsPotentiallySensitive;
13};
14
15annotate my.Addresses with @PersonalData: {
16  EntitySemantics : 'DataSubjectDetails'
17} {
18  customer      @PersonalData.FieldSemantics: 'DataSubjectID';
19  city          @PersonalData.IsPotentiallyPersonal;
20  postCode      @PersonalData.IsPotentiallyPersonal;
21  streetAddress @PersonalData.IsPotentiallyPersonal;
22};
23
24annotate my.Incidents with @PersonalData : {
25  EntitySemantics : 'Other'
26} {
27  customer @PersonalData.FieldSemantics: 'DataSubjectID';
28};
29

Learn more about the annotations in capire:

• @PersonalData.EntitySemantics
• @PersonalData.EntitySemantics: 'DataSubject'
• @PersonalData.FieldSemantics: 'DataSubjectID'
• @PersonalData.IsPotentiallyPersonal
• @PersonalData.IsPotentiallySensitive

Test-Drive Locally

You've prepared everything to log personal data-related events. Let's see that in action.

Start the server as usual:

1cds watch

Send an update request that changes personal data:

1PATCH http://localhost:4004/odata/v4/admin/Customers('1004155')
2Authorization: Basic alice:in-wonderland
3Content-Type: application/json
4
5{
6  "firstName": "Danny",
7  "lastName": "Joules"
8}

See the audit logs in the server's console output:

1[audit-log] - PersonalDataModified: {
2  data_subject: {
3    id: { ID: '1004155' },
4    role: 'Customer',
5    type: 'AdminService.Customers'
6  },
7  object: {
8   type: 'AdminService.Customers',
9   id: { ID: '1004155' }
10  },
11  attributes: [
12    { name: 'firstName', old: 'Daniel', new: 'Danny' },
13    { name: 'lastName', old: 'Watts', new: 'Joules' }
14  ],
15  uuid: '71fa93d9-c993-405f-ba1b-a9ef42668199',
16  tenant: 't1',
17  user: 'alice',
18  time: 2023-02-26T08:13:48.287Z
19}

In Production

The end-to-end out-of-the-box functionality provided by this plugin requires a paid-for instance of the SAP Audit Log service for customers. However, it is possible to provide an own implementation that writes the audit logs to a custom store.

Learn more about using the SAP Audit Log service.

Learn more about custom audit logging.

Support, Feedback, Contributing

This project is open to feature requests/suggestions, bug reports etc. via GitHub 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.

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 at all times.

Licensing

Copyright 2023 SAP SE or an SAP affiliate company and contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.