Search

    Managing Data Privacy

    CAP helps application projects to comply to 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, it is necessary to consider compliance with industry-specific legislation in different countries.

    SAP provides specific features and functions to support compliance with regard to 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 to use SAP BTP services, which enable you to fulfill specific data privacy requirements in your application. This means at first, personal data management with help of annotations & configurations and 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.

    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 like entities or fields. The data privacy annotations work on different levels - from the entity level to the field level, as outlined subsequently.

    Entity-Level Annotations

    Entity-level annotations indicate which entities are relevant for data privacy at all. 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 to 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 (like 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 to manage the data privacy-related actions on a fine granular level only by metadata definition with annotation 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. For that 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.amount    as Item_Amount,
              Items.netAmount as Item_NetAmount
        };
    
      //  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 add then 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.

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

    Restrict Access via @requires Annotation

    To restrict the access to this sensitive data, the PDMservice is protected by the annotation @requires: 'PersonalDataManagerUser'. 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

    As 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 and @sap/xsenv package:

    npm install @sap/xssec @sap/xsenv
    

    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 section 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 common Multitenancy Guide.

    Subscribe to SAP Personal Data Manager Service

    Subscribe 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

    As of now, 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 UI and with !t are needed for executing 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 setup, 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 like the following, 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 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 data subjects with First Name, Last Name, and Date of Birth or alternatively with their ID.

    PDM UI

    Retention Manager

    Goal – find out which personal data has to be deleted at a certain point in time.

    When? Find out the correct time for deletion.

    What? Find out the correct amount of data to be deleted.

    To support this, we’ll invent some new CDS annotation to mark all possible candidates for ‘End of Business’ indicating time fields in each legal ground (like Consent, Order etc.).

    This new CDS annotation for “End of Business” indicators will serve as input for the retention manager.

    An additional configuration at the customer site per type of transactional document defines the actual retention time (like 2 years, 5 years, etc.). Finally, the retention manager searches all candidates (of natural persons) for possible deletion (across all object types).

    Finally, the search results will be cross checked: Check all legal grounds, if deletion of certain data really is allowed. (One active Legal ground is sufficient to stop the deletion!)

    CDS could support this process by building certain queries - based on annotations - to find out which legal ground is invalid at a certain point in time (tt.mm.yyyy) and no other legal ground (of the same type) per person (DataSubject) exists.

    Static implementation for such queries already exists. We try to bring this on a dynamic meta-data-driven level with help of CDS annotations and CDS queries.  

    The consent repository is already built with help of CAP and therefore with CDS and with full OData support.

    See here for more details.

    Central Business Partner

    To reuse the Business Partner from an SAP S/4HANA system, a central Business Partner service is created. If your application makes use of this Business Partner service, you only have to annotate the relation to the Business Partner and your application can make use of the service. In addition, all settings that are necessary to integrate all DPP processes will be performed automatically.

    –>

    Show/Hide Beta Features