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