Introduction:

Having covered the theoretical foundations in previous blog of this series, let’s examine the implementation of the CAP based application and the steps of integrating DPP services.

We will use a sample application ‘Game Shop’ which is used to order one or more Games for a customer. The sample application looks like as shown below. You can find the code of sample application for this blog here: [ cap-dpp-example ].

In Game Shop Sample, sandbox launchpad is used to provide an entry point for both Manage Customers application and Manage Orders application where Manage Customers application is used to manage/modify customer details and  Manage Orders application is used to manage/modify orders for a customer.

Managing Data Privacy with CAP Applications:

CAP simplifies compliance with data privacy regulations for applications by automating repetitive tasks using annotated models. It assists you in meeting specific data privacy requirements through different SAP BTP services like Personal Data Manager by using annotations and configurations.

To use Personal Data Manager Service (PDM) on BTP, we need to provide an OData or Rest based service that serves personal data stored in our application. In addition, PDM requires certain annotations to interpret the service to extract and render personal data on ui. Annotations required for PDM can be part of service metadata document or can also be provided with a separate endpoint. You can find more information about required annotations for PDM are on following pages: OData V2 Annotations, OData V4 Annotations

In CAP, ‘@PersonalData’ annotations are used to suggest entities or elements/fields in your domain model which will have personal data.

• Entity Level Annotations: Entity-level annotations indicate which entities are relevant for data privacy
• Key-Level Annotations: Key-level annotations indicate the corresponding key information
• Field-Level Annotations: Field-level annotations tag which fields are relevant for data privacy in detail.

Now, Let’s add an OData service to the sample application which will provide the Data Subject’s (individuals) personal data used in the application and add entity/key/field level annotations required for PDM.

using {sap.cap.dpp as db} from '../db/schema';

service PdmService {
    entity Customers               as projection on db.Customers;    
    entity CustomerPostalAddresses as
        select from db.Addresses {
            *,
            type.name as addressType                };
    entity CustomerEmailAddresses  as
        select from db.EmailAddresses {
            *,
            emailType.name as emailAddressType      };
    entity OrderItemView           as
        select from db.Orders {
            key items.ID         as Item_ID,
                ID               as Order_ID,
                orderNo          as Order_No,
                customer.ID      as Customer_ID,
                customer.email   as Customer_Email,
                items.game.title as Item_Game,
                items.quantity   as Item_Quantity,
                items.netprice   as Item_NetPrice   };
}

As shown above, ‘DppService’ OData service provides four entities i.e. Customers, Postal Address, Email Address and OrderItemView. OrderItemView is used to provide transactional information about the Data Subjects (Individuals)

Annotations

annotate service.Customers with @PersonalData: {
    DataSubjectRole: 'Customer',
    EntitySemantics: 'DataSubject'
};
annotate service.CustomerPostalAddresses with @PersonalData: {
    DataSubjectRole: 'Customer',
    EntitySemantics: 'DataSubjectDetails'
};
annotate service.CustomerEmailAddresses with @PersonalData: {
    DataSubjectRole: 'Customer',
    EntitySemantics: 'DataSubjectDetails'
};
annotate service.OrderItemView with @PersonalData: {
    EntitySemantics: 'Other'
};

Entities can be annotated with Semantic Information which in turn informs PDM about the kind of personal data these entities provide as shown above.

@PersonalData.EntitySemantics: ‘DataSubject‘ – Entities marked with this annotation describe a Data Subject i.e. Identifiable natural person. 

@PersonalData.EntitySemantics: ‘DataSubjectDetails‘ – Entities marked with this annotation contain details of a data subject but do not identify/describe a data subject by themselves.

@PersonalData.EntitySemantics: ‘Other‘ – Entities marked with this annotation contain references to data subjects, but not representing data subjects or data subject details by themselves.

@PersonalData.DataSubjectRole: ‘Customer‘ – This annotation is used to define the role of Data Subjects. e.g. A person could be a customer or vendor or partner or an employee or all at the same time. Based on the role, personal data of an individual could be different.

annotate service.Customers with {
 ID           @PersonalData.FieldSemantics: 'DataSubjectID';
 email        @PersonalData.IsPotentiallyPersonal  @Communication.IsEmailAddress;
 firstName    @PersonalData.IsPotentiallyPersonal;
 lastName     @PersonalData.IsPotentiallyPersonal;
 creditCardNo @PersonalData.IsPotentiallySensitive;
 dateOfBirth  @PersonalData.IsPotentiallyPersonal;
}
annotate service.CustomerPostalAddresses with {
 customer       @PersonalData.FieldSemantics: 'DataSubjectID';
 addressType    @PersonalData.IsPotentiallyPersonal;
 country        @PersonalData.IsPotentiallyPersonal;
 state          @PersonalData.IsPotentiallyPersonal;
 town           @PersonalData.IsPotentiallyPersonal;
 street         @PersonalData.IsPotentiallyPersonal;
 someOtherField @PersonalData.IsPotentiallyPersonal;
}
annotate service.CustomerEmailAddresses with {
 customer         @PersonalData.FieldSemantics: 'DataSubjectID';
 emailAddressType @PersonalData.IsPotentiallyPersonal;
 emailAddress     @PersonalData.IsPotentiallyPersonal;
};
annotate service.OrderItemView with {
 Item_ID         @PersonalData.FieldSemantics: 'ContractRelatedID';
 Customer_ID     @PersonalData.FieldSemantics: 'DataSubjectID';
 personalComment @PersonalData.IsPotentiallyPersonal;
}

@PersonalData.FieldSemantics: ‘DataSubjectID‘ – This annotation is used to specify key of Data Subject and can be used to relate corresponding personal information and documents. 

@PersonalData.IsPotentiallyPersonal / @PersonalData.IsPotentiallySensitive : These 2 annotations are used to manage the data privacy-related actions on a fine granular level. 

In the context of audit logging, the @PersonalData.IsPotentiallyPersonal annotation induces audit logs for Insert, Update, and Delete of personal data, whereas the @PersonalData.IsPotentiallySensitive annotation adds audit logs for each and every Read of personal data.

annotate service.Customers with @Communication: {Contact: {
    $Type: 'Communication.ContactType',
    n    : { surname: lastName,
             given  : firstName  },
    bday : dateOfBirth,
    email: [{ type   : #preferred,
              address: email       }]
}};

To perform a valid search for Data Subjects in the SAP Personal Data Manager application, one of the following combination of information is required.

• Surname, Given name, and Birthday
• Surname, Last Name and Email
• the Data Subject ID

Hence to identify required search fields of the data subject, fields have to be annotated with the corresponding annotation @Communication.Contact as shown above. More information about this annotation can be found in Communication Vocabulary.

Security

‘DppService’ needs to be protected for restriction to sensitive personal data using @requires annotation.

using {DppService as service} from './dpp-service';
annotate service with @(
    path    : '/pdm',
    requires: 'PersonalDataManagerUser'
);

PDM service will call into CAP application to read personal data which means PDM needs to be assigned with ‘PersonalDataManagerUser’ role. The call between PDM service and CAP application uses technical communication. Like a trust arrangement, CAP application needs to grant the authority to PDM service to use ‘PersonalDataManagerUser’ scope and PDM service needs to accept such declaration of authority.

The following information needs to be added to xs-security.json in CAP application to initiate trust arrangement.

{
  "scopes": [
    .....
    {
      "name": "$XSAPPNAME.PersonalDataManagerUser",
      "description": "Authority for Personal Data Manager",
      "grant-as-authority-to-apps": [
        "$XSSERVICENAME(cap-dpp-example-pdm)"
      ]
    }
  ],
  "attributes": [],
  "role-templates": [
    .....
    {
      "name": "PersonalDataManagerUser",
      "description": "generated",
      "scope-references": [
        "$XSAPPNAME.PersonalDataManagerUser"
      ],
      "attribute-references": []
    }
  ]
}

The line “grant-as-authority-to-apps”: [“$XSSERVICENAME(cap-dpp-example-pdm)”] indicates xsuaa to grant PersonalDataManagerUser scope to a service with name ‘cap-dpp-example-prm’.

It means we need to create the instance PDM service with the exact name of ‘cap-dpp-example-prm’

Now our CAP application is ready to be deployed on BTP and then PDM service can be bound to manage data privacy requests.

Connecting to Personal Data Manager Service:

Before proceeding with further steps, make sure you have PDM entitlements in your subaccount where CAP application is going to be deployed.

PDM Service Instance Creation

Using BTP Cockpit, Create a PDM servce instance with name ‘cap-dpp-example-pdm’ which is provided in xs-security.json of CAP Applicaition as shown below:

It also requires following security configurations. You can find the security configurations from here as well.xs-security section is provided with “authorities”: [ “$ACCEPT_GRANTED_AUTHORITIES” ]  so that PDM instance accepts the ‘PersonalDataManagerUser’ scope provided by CAP Application. Note that, xsappname should be same as defined in xs-security.json of the CAP application.

You can find the above configuration here [ pdm-security-config.json ].

Deploy CAP Application

Complete CAP application code base is available here [ cap-dpp-example ]. You can clone the complete code base, build and deploy using following comands. Ensure you are logged into cloud foundry using cf login command before using following commands.

npm install
npm run build
npm run deploy

After deployment, Assign the roles ‘GameShop-Admin’ and ‘GameShop-User’ to the user to access the sample application (approuter). Few customers are pre-loaded as part of sample application.

Create an order for a Customer using ‘Manage Orders’ tile as shown below:

Bind PDM Service Instance with CAP Application

Open PDM instance (cap-dpp-example-pdm) on BTP Cockpit and create a binding under bound application section.

Then choose your CAP application service (cap-dpp-example-srv) and create providing following binding parameters from here [ pdm-config.json ].

• fullyQualifiedApplicationName : Application name must be unique across cloud foundry environment. Also the same name should be used while creating the PDM instance as well.
• fullyQualifiedModuleName : This indicates the module of your app e.g. Sales, Purchase or Payment etc
• applicationTitle : name of the application that will be displayed on the UI.
• applicationURL : host url of CAP Application
• endPoints : provide all the OData or RESTful services of CAP application that serves the personal data. It is possible to provide more than one OData endpoints.
• serviceURI : the relative URI of the OData or RESTful service
• endPoints[x] > hasGdprV4Annotations : indicates whether or not the data privacy annotations are part of the OData metadataMore information about the above binding parameters can be found on this page [ Configuration Properties ].

Subscribe PDM Application

Go to BTP Cockpit and subscribe to Personal Data Manager application.

Once subscribed, PDM provides following roles:

1. PDM_CustomerServiceRepresentative : Can view individual’s data, manage correction or deletion requests from individual
2. PDM_OperatorsClerk : can view and process data management requests
3. PDM_Administrator : user can export data

You can assign roles as per your requirement. For purpose of this blog series, we will assign all roles to a single user and explore PDM features. For more information about how to create roles and how to bundle them in role collections using the SAP BTP cockpit, see Building Roles and Role Collections for Applications. and More info about these roles can be found here [ Identification and Access Management ].

Conclusion:

In this blog post, We explored how CAP supports different set of annotations that is required to integrate PDM service. Also, we deployed CAP application and integrated it with PDM service.

In the next blog post of this series we will explore further about how can we use PDM UI application to manage data privacy requests.