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:

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

Setup

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

npm 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:

using { sap.capire.incidents as my } from './schema';

annotate my.Customers with @PersonalData : {
  DataSubjectRole : 'Customer',
  EntitySemantics : 'DataSubject'
} {
  ID           @PersonalData.FieldSemantics: 'DataSubjectID';
  firstName    @PersonalData.IsPotentiallyPersonal;
  lastName     @PersonalData.IsPotentiallyPersonal;
  email        @PersonalData.IsPotentiallyPersonal;
  phone        @PersonalData.IsPotentiallyPersonal;
  creditCardNo @PersonalData.IsPotentiallySensitive;
};

annotate my.Addresses with @PersonalData: {
  EntitySemantics : 'DataSubjectDetails'
} {
  customer      @PersonalData.FieldSemantics: 'DataSubjectID';
  city          @PersonalData.IsPotentiallyPersonal;
  postCode      @PersonalData.IsPotentiallyPersonal;
  streetAddress @PersonalData.IsPotentiallyPersonal;
};

annotate my.Incidents with @PersonalData : {
  EntitySemantics : 'Other'
} {
  customer @PersonalData.FieldSemantics: 'DataSubjectID';
};

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:

cds watch

Send an update request that changes personal data:

PATCH http://localhost:4004/odata/v4/admin/Customers('1004155')
Authorization: Basic alice:in-wonderland
Content-Type: application/json

{
  "firstName": "Danny",
  "lastName": "Joules"
}

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

[audit-log] - PersonalDataModified: {
  data_subject: {
    id: { ID: '1004155' },
    role: 'Customer',
    type: 'AdminService.Customers'
  },
  object: {
   type: 'AdminService.Customers',
   id: { ID: '1004155' }
  },
  attributes: [
    { name: 'firstName', old: 'Daniel', new: 'Danny' },
    { name: 'lastName', old: 'Watts', new: 'Joules' }
  ],
  uuid: '71fa93d9-c993-405f-ba1b-a9ef42668199',
  tenant: 't1',
  user: 'alice',
  time: 2023-02-26T08:13:48.287Z
}

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.