Skip to content
Search

    Personal Data Management with CAP

    Use the SAP Personal Data Manager (PDM) with a CAP application

    Content

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

    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
}

};

    Make sure to have indicated all relevant entities and elements in your domain model.

    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

    ✉