Skip to content
Search

    Managing Data Privacy

    CAP helps application projects to comply with data privacy regulations using SAP Business Technology Platform (BTP) services.

    Content

    Introduction

    Data protection is associated with numerous legal requirements and privacy concerns. In addition to compliance with general data protection and privacy acts, you need to consider compliance with industry-specific legislation in different countries.

    SAP provides specific features and functions to support compliance regarding the relevant legal requirements, including data protection. SAP does not give any advice on whether these features and functions are the best method to support company, industry, regional, or country-specific requirements. Furthermore, this information should not be taken as advice or a recommendation regarding additional features that would be required in specific IT environments. Decisions related to data protection must be made on a case-by-case basis, considering the given system landscape and the applicable legal requirements.

    CAP supports applications in their obligations to comply to data privacy regulations, by automating tedious tasks as much as possible based on annotated models. Using annotations and configurations, CAP supports you using SAP BTP services, which enable you to fulfill specific data privacy requirements in your application. This means at first, personal data management, with the help of annotations and configurations and the SAP Personal Data Manager service.

    ❗ To follow this cookbook hands-on you need an enterprise account. The SAP Personal Data Manager service is currently only available for enterprise accounts. An entitlement in trial accounts is not possible.

    Indicate Personal Data in Your Domain Model

    Use @PersonalData annotations to indicate entities and elements in your domain model, which will contain personal data.

    The best practice is to do that in separate files.
    See also: Using Aspects for Separation of Concerns.

    Let’s have a look at our sample.

    Open the db/data-privacy.cds file, which contains our data privacy-related annotations.

    // Proxy for importing schema from bookshop sample
    using {sap.capire.bookshop} from './schema';
    
    // annotations for Data Privacy
    annotate bookshop.Customers with @PersonalData : {
      DataSubjectRole : 'Customer',
      EntitySemantics : 'DataSubject'
    }
    {
      ID           @PersonalData.FieldSemantics : 'DataSubjectID';
      emailAddress @PersonalData.IsPotentiallyPersonal;
      firstName    @PersonalData.IsPotentiallyPersonal;
      lastName     @PersonalData.IsPotentiallyPersonal;
      creditCardNo @PersonalData.IsPotentiallySensitive;
      dateOfBirth  @PersonalData.IsPotentiallyPersonal;
    }
    
    annotate bookshop.CustomerPostalAddress with @PersonalData : {
      DataSubjectRole : 'Customer',
      EntitySemantics : 'DataSubjectDetails'
    }
    {
      Customer @PersonalData.FieldSemantics : 'DataSubjectID';
      street   @PersonalData.IsPotentiallyPersonal;
      town     @PersonalData.IsPotentiallyPersonal;
      country  @PersonalData.IsPotentiallyPersonal;
    }
    

    It is important to annotate the data privacy-relevant entities as DataSubject, DataSubjectDetails, or Other.

    You can annotate different CDS artifacts, such as entities or fields. The data privacy annotations work on different levels - from the entity level to the field level, as described below.

    Entity-Level Annotations

    Entity-level annotations indicate which entities are relevant for data privacy. The most important annotations are:

    @PersonalData.EntitySemantics: 'DataSubject'
    @PersonalData.EntitySemantics: 'DataSubjectDetails'
    @PersonalData.EntitySemantics: 'Other'
    
    Annotation Description
    DataSubject The entities of this set describe a data subject (an identified or identifiable natural person), for example, Customer or Vendor.
    DataSubjectDetails The entities of this set contain details of a data subject (an identified or identifiable natural person) but do not by themselves identify/describe a data subject, for example, CustomerPostalAddress.
    Other Entities containing personal data or references to data subjects, but not representing data subjects or data subject details by themselves. For example, customer quote, customer order, or purchase order with involved business partners. These entities are relevant for audit logging. There are no restrictions on their structure. The properties should be annotated suitably with FieldSemantics.

    Key-Level Annotations

    Key-level annotations indicate the corresponding key information.

    @PersonalData.FieldSemantics: 'DataSubjectID'
    

    This key information consists of the DataSubject (= Person) and its identifiers and the corresponding personal documents (such as Order, Consent, …) and its identifiers. The latter is always captured implicitly, so we mainly have to specify the type and the key of the DataSubject.

    Field-Level Annotations

    Field-level annotations tag which fields are relevant for data privacy in detail.

    @PersonalData.IsPotentiallyPersonal
    

    This allows you to manage the data privacy-related actions on a fine granular level only using metadata definitions with annotations and without any need of implementation.

    Provide a Service Interface to SAP Personal Data Manager

    SAP Personal Data Manager needs to call into your application to read personal data so you have to define a respective service endpoint, complying to the interface required by SAP Personal Data Manager. Following the CAP principles, we recommend adding a new dedicated CAP service that handles all the personal data manager requirements for you. This keeps the rest of your data model clean and enables reuse, just as CAP promotes it.

    CAP Service Model for SAP Personal Data Manager

    Open the srv/pdm-service.cds file, which contains the content for the Personal Data Manager service.

    //using from '@capire/orders';
    using {sap.capire.bookshop as db} from '../db/data-privacy';
    using {sap.capire.bookshop.Books} from '@capire/bookshop';
    using {sap.capire.bookshop.Orders} from '@capire/orders';
    using {sap.capire.bookshop.OrderItems} from '@capire/orders';
    
    @requires: 'PersonalDataManagerUser' // security check
    service PDMService{
    
      entity Customers             as projection on db.Customers;
      entity CustomerPostalAddress as projection on db.CustomerPostalAddress;
    
      //   create view on Orders and Items as flat projection
      entity OrderItemView         as
        select from Orders {
              ID,
          key Items.ID        as Item_ID,
              OrderNo,
              Customer.ID     as Customer_ID,
              Customer.email  as Customer_Email,
              Items.book.ID   as Item_Book_ID,
              Items.quantity    as Item_Quantity,
              Items.netQuantity as Item_NetQuantity
        };
    
      //  annotate new view
      annotate PDMService.OrderItemView with @(PersonalData.EntitySemantics : 'Other') {
        Item_ID        @PersonalData.FieldSemantics : 'ContractRelatedID';
        Customer_ID    @PersonalData.FieldSemantics : 'DataSubjectID';
        Customer_Email @PersonalData.IsPotentiallyPersonal;
      };
    
      //  Data Privacy annotations on 'Customers' and 'CustomerPostalAddress' are derived from original entity definitions.
    
    
    // annotations for Personal Data Manager - Search Fields
    annotate bookshop.Customers with @Communication.Contact : {
      n    :
      {
        surname : lastName,
        given   : firstName
      },
      bday : dateOfBirth
    }
    
    };
    

    Provide Flat Projections

    As an additional step, you have to create flat projections on the additional business data, like transactional data.

    In our model, we have Orders and OrderItems, which are connected via a composition. Since SAP Personal Data Manager needs flattened out structures, we define a helper view OrderItemView to flatten this out.

    We have to then add data privacy-specific annotations to this new view as well. The OrderItemView as transactional data is marked as Other. In addition, it is important to tag the correct field, which defines the corresponding data subject, in our case that is Customer_ID @PersonalData.FieldSemantics: 'DataSubjectID';

    Annotating Search Fields

    In addition, the most important search fields of the data subject have to be annotated with the corresponding annotation @Communication.Contact.

    To perform a valid search in the SAP Personal Data Manager application, you will need Surname, Given Name, and Birthday or the Data Subject ID. Details about this annotation can be found in Communication Vocabulary.

    Restrict Access Using the @requires Annotation

    To restrict access to this sensitive data, the PDMservice is protected by the @requires: 'PersonalDataManagerUser' annotation. Calling the PDMservice externally without the corresponding permission is forbidden. The Personal Data Manager service calls the PDMservice with the needed role granted. This is configured in the xs-security.json file, which is explained later.

    Learn more about security configuration and the SAP Personal Data Manager.

    Activate Access Checks in xs-security.json

    Because we protected the PDMservice, we need to establish the security check properly. In particular, you need the xs-security.json file to make the security check active. The following xs-security.json is from our sample.

    {
        "xsappname": "gdpr-bookshop",
        "tenant-mode": "shared",
        "scopes": [
            {
                "name": "$XSAPPNAME.PersonalDataManagerUser",
                "description": "Authority for Personal Data Manager",
                "grant-as-authority-to-apps": [
                    "$XSSERVICENAME(pdm)"
                ]
            }
        ]
    }
    

    Here you define that your personal data manager service instance, called pdm, is allowed to access your CAP application granting the PersonalDataManagerUser role.

    Add @sap/xssec Library

    To make the authentication work, you have to enable the security strategy by installing the @sap/xssec package:

    npm install @sap/xssec
    

    Learn more about authorization in CAP using Node.js.

    At this point, you are done with your application. Let’s set up the SAP Personal Data Manager and try it out.

    Connecting SAP Personal Data Manager

    Build and Deploy Your Application

    The Personal Data Manager can’t connect to your application running locally. Therefore, you first need to deploy your application. In our sample, we added two manifest files using cds add cf-manifest and SAP HANA configuration using cds add hana.

    The general deployment is described in detail in Deploy Using Manifest Files.

    Make a production build:

    cds build --production
    

    Deploy your application:

    cf create-service-push
    

    For multitenant-specific information, refer to our Multitenancy Guide.

    Subscribe to SAP Personal Data Manager Service

    Subscribe to the service from the Service Marketplace in the SAP BTP cockpit.

    tile in the cockpit

    Follow the wizard to create your subscription.

    Create Role Collections

    SAP Personal Data Manager comes with the following roles:

    Role Name Role Template
    PDM_Administrator PDM_Administrator
    PDM_CustomerServiceRepresentative PDM_CustomerServiceRepresentative
    PDM_OperatorsClerk PDM_OperatorsClerk

    All of these roles have two different Application Identifiers.

    Application identifiers with !b are needed for the UI, and identifiers with !t are needed for executing the Postman collection.

    Learn more about defining a role collection in SAP BTP cockpit

    Create a Service Instance

    You need a configuration file, like the following, to create a service instance for the Personal Data Manager.

    {
      "xs-security": {
        "xsappname": "gdpr-bookshop",
        "authorities": ["$ACCEPT_GRANTED_AUTHORITIES"]
      },
      "fullyQualifiedApplicationName": "gdpr-bookshop",
      "appConsentServiceEnabled": true
    }
    
    
    

    Create a service instance using the SAP BTP cockpit or execute the following command:

    cf create-service personal-data-manager-service standard pdm -c ./.pdm/pdm-instance-config.json
    

    Bind the Service Instance to Your Application.

    With both the application deployed and the SAP Personal Data Manger service set up, you can now bind the service instance of the Personal Data Manager to your application. Use the URL of your application in a configuration file, such as the following example, which you need when binding a service instance.

    {
      "fullyQualifiedApplicationName": "gdpr-bookshop",
      "fullyQualifiedModuleName": "gdpr-srv",
      "applicationTitle": "PDM Bookshop",
      "applicationTitleKey": "PDM Bookshop",
      "applicationURL": "https://gdpr-srv.cfapps.eu10.hana.ondemand.com/", // get the URL from the CF CLI command: cf apps
      "endPoints": [
        {
          "type": "odatav4",
          "serviceName": "pdm-service",
          "serviceTitle": "GDPR",
          "serviceTitleKey": "GDPR",
          "serviceURI": "pdm",
          "hasGdprV4Annotations": true,
          "cacheControl": "no-cache"
        }
      ]
    }
    

    Here the applicationURL, the fullyQualifiedModuleName, and the serviceURI have to be those of your Cloud Foundry deployment and your CAP service definition (services-manifest.yaml).

    Bind the service instance using the SAP BTP cockpit or execute the following command:

    cf bind-service gdpr-srv pdm -c ./.pdm/pdm-config.json
    

    You need two configuration files for the Personal Data Manager service. In our sample, you can find the .pdm/pdm-instance-config.json and .pdm/pdm-config.json files. Use them in addition to the reference documentation to build your own files later on.

    Using the SAP Personal Data Manager Application

    Open the SAP Personal Data Manager application from the Instances and Subscriptions page in the SAP BTP cockpit.

    tile in the cockpit

    In the personal data manager application you can search for data subjects with First Name, Last Name, and Date of Birth, or alternatively with their ID.

    PDM UI

    Audit Logging

    This section deals with Audit Logging for reading sensitive data and changes to personal data.

    In CDS, this can be handled mostly automatically by adding certain annotations to your business entity definitions.

    Audited Object is the Data Subject

    Let’s first look at the business entity Customers.

    using { cuid, Country } from '@sap/cds/common';
    
     entity Customers : cuid, managed {
      email        : String;
      firstName    : String;
      lastName     : String;
      creditCardNo : String;
      dateOfBirth  : Date;
    }
    
    

    This entity is annotated in the db/data-privacy.cds file.

    
    annotate bookshop.Customers with @PersonalData : {
      DataSubjectRole : 'Customer',
      EntitySemantics : 'DataSubject'
    }
    {
      ID           @PersonalData.FieldSemantics : 'DataSubjectID';
      emailAddress @PersonalData.IsPotentiallyPersonal;
      firstName    @PersonalData.IsPotentiallyPersonal;
      lastName     @PersonalData.IsPotentiallyPersonal;
      creditCardNo @PersonalData.IsPotentiallySensitive;
      dateOfBirth  @PersonalData.IsPotentiallyPersonal;
    }
    
    annotate bookshop.Customers with @AuditLog.Operation : {
      Read   : true,
      Insert : true,
      Update : true,
      Delete : true
    };
    
    

    The following description shows the four levels from the previous section, going through the sample from top to bottom.

    Entity level - We annotate the entity as relevant for data privacy. In this case, the entity itself is marked as DataSubject.

    Key information level - We specify the header data of the audit log. The data subject is the customer itself. The customer is specified by the key in the ID field, which is introduced via the cuid aspect. So we annotate the ID as DataSubjectID.

    Field level - All data privacy-relevant data fields are marked with the annotations IsPotentiallyPersonal or IsPotentiallySensitive respectively.

    • IsPotentiallyPersonal is relevant for inducing audit logs for Insert, Update, Delete.
    • IsPotentiallySensitive is relevant for inducing audit logs for Insert, Update, Delete and read access audit logs in addition..

    Operational level - Finally, we annotate all standard operations (Read, Insert, Update, Delete) as relevant for the audit log - which should be the default case for most of the relevant business entities.

    When you’ve annotated your (business) entity like this, the audit logs for read access and data modifications will be written automatically by the underlying CAP framework. For more information, see the respective sections for Java and Node.js.

    Audited Object Is Not a Data Subject

    In the first example, the audited object was identical to the data subject, but this is not always the case.

    Now, let’s look at a second example with the business entity CustomerPostalAddress.

    
    entity CustomerPostalAddress : cuid, managed {
      Customer       : Association to one Customers;
      street         : String(128);
      town           : String(128);
      country        : Country;
      someOtherField : String(128);
    };
    
    

    This entity is annotated in the db/data-privacy.cds file.

    annotate bookshop.CustomerPostalAddress with @PersonalData : {
      DataSubjectRole : 'Customer',
      EntitySemantics : 'DataSubjectDetails'
    }
    {
      Customer @PersonalData.FieldSemantics : 'DataSubjectID';
      street   @PersonalData.IsPotentiallyPersonal;
      town     @PersonalData.IsPotentiallyPersonal;
      country  @PersonalData.IsPotentiallyPersonal;
    }
    
    annotate bookshop.CustomerPostalAddress with @AuditLog.Operation : {
      Read   : true,
      Insert : true,
      Update : true,
      Delete : true
    };
    
    

    The following description shows the four levels from the previous section, going through the sample from top to bottom.

    Entity level - We annotate the entity as relevant for data privacy. In this case, the entity itself is marked as DataSubjectDetails.

    Key information level - We specify the header data of the audit log. The corresponding data subject is the Customer, specified by the implicitly generated key, which is introduced via the association to the entity Customers.

    Field level - All data privacy-relevant data fields are marked with the annotations IsPotentiallyPersonal or IsPotentiallySensitive respectively. In this case only IsPotentiallyPersonal is needed, since we do not have any sensitive data here.

    Operational level - Finally, we annotate all standard operations (Read, Insert, Update,Delete) as relevant for the audit log - which should be the default case for most of the relevant business entities.

    ❗ Data Subject and Data Object
    Semantically for each audit log on a data object (like a Sales Order) a valid data subject (like a Customer) is needed. The application has to clarify that this link between data object and data subject - which is typically induced by an annotation like Customer @PersonalData.FieldSemantics : 'DataSubjectID'; is never broken. Thus, semantically correct audit logs can only be written on top of a semantical correctly built application.