Enforce data usage compliance for a segment definition using APIs
This tutorial covers the steps for enforcing data usage compliance for segment definitions using APIs.
Getting started
This tutorial requires a working understanding of the following components of Adobe Experience Platform:
-
Real-Time Customer Profile: Real-Time Customer Profile is a generic lookup entity store, and is used to manage Experience Data Model (XDM) data within Platform. Profile merges data across various enterprise data assets and provides access to that data in a unified presentation.
- Merge policies: Rules used by Real-Time Customer Profile to determine what data can be merged into a unified view under certain conditions. Merge policies can be configured for Data Governance purposes.
-
Segmentation: How Real-Time Customer Profile divides a large group of individuals contained in the profile store into smaller groups that share similar traits and will respond similarly to marketing strategies.
-
Data Governance: Data Governance provides the infrastructure for data usage labeling and enforcement, using the following components:
- Data usage labels: Labels used to describe datasets and fields in terms of the level of sensitivity with which to handle their respective data.
- Data usage policies: Configurations indicating which marketing actions are allowed on data categorized by particular data usage labels.
- Policy enforcement: Allows you to enforce data usage policies and prevent data operations that constitute policy violations.
-
Sandboxes: Experience Platform provides virtual sandboxes which partition a single Platform instance into separate virtual environments to help develop and evolve digital experience applications.
The following sections provide additional information that you will need to know in order to successfully make calls to the Platform APIs.
Reading sample API calls
This tutorial provides example API calls to demonstrate how to format your requests. These include paths, required headers, and properly formatted request payloads. Sample JSON returned in API responses is also provided. For information on the conventions used in documentation for sample API calls, see the section on how to read example API calls in the Experience Platform troubleshooting guide.
Gather values for required headers
In order to make calls to Platform APIs, you must first complete the authentication tutorial. Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:
- Authorization: Bearer
{ACCESS_TOKEN}
- x-api-key:
{API_KEY}
- x-gw-ims-org-id:
{ORG_ID}
All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:
- x-sandbox-name:
{SANDBOX_NAME}
All requests that contain a payload (POST, PUT, PATCH) require an additional header:
- Content-Type: application/json
Look up a merge policy for a segment definition merge-policy
This workflow begins by accessing a known segment definition. Segment definitions that are enabled for use in Real-Time Customer Profile contain a merge policy ID within their segment definition. This merge policy contains information about which datasets are to be included in the segment definition, which in turn contain any applicable data usage labels.
Using the Segmentation API, you can look up a segment definition by its ID to find its associated merge policy.
API format
GET /segment/definitions/{SEGMENT_DEFINITION_ID}
{SEGMENT_DEFINITION_ID}
Request
curl -X GET \
https://platform.adobe.io/data/core/ups/segment/definitions/24379cae-726a-4987-b7b9-79c32cddb5c1 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns the details of the segment definition.
{
"id": "24379cae-726a-4987-b7b9-79c32cddb5c1",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 90,
"imsOrgId": "{ORG_ID}",
"name": "Cart abandons in CA",
"description": "",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "homeAddress.countryISO = 'US'"
},
"mergePolicyId": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"creationTime": 1556094486000,
"updateEpoch": 1556094486000,
"updateTime": 1556094486000
}
}
mergePolicyId
Find the source datasets from the merge policy datasets
Merge policies contain information about the their source datasets, which in turn contain data usage labels. You can lookup the details of a merge policy by providing the merge policy ID in a GET request to the Profile API. More information about merge policies can be found in the merge policies endpoint guide.
API format
GET /config/mergePolicies/{MERGE_POLICY_ID}
{MERGE_POLICY_ID}
Request
curl -X GET \
https://platform.adobe.io/data/core/ups/config/mergePolicies/2b43d78d-0ad4-4c1e-ac2d-574c09b01119 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns the details of the merge policy.
{
"id": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
"imsOrgId": "{ORG_ID}",
"schema": {
"name": "_xdm.context.profile"
},
"version": 1,
"identityGraph": {
"type": "none"
},
"attributeMerge": {
"type":"dataSetPrecedence",
"data": {
"order": ["5b95b155419ec801e6eee780", "5b7c86968f7b6501e21ba9df"]
}
},
"default": false,
"updateEpoch": 1551127597
}
schema.name
attributeMerge.type
dataSetPrecedence
, the datasets associated with this merge policy are listed under attributeMerge > data > order
. If the value is timestampOrdered
, then all datasets associated with the schema referenced in schema.name
are used by the merge policy.attributeMerge.data.order
attributeMerge.type
is dataSetPrecedence
, this attribute will be an array containing the IDs of the datasets used by this merge policy. These IDs are used in the next step.Evaluate datasets for policy violations
Once you have obtained the IDs of the merge policy’s source datasets, you can use the Policy Service API to evaluate those datasets against specific marketing actions in order to check for data usage policy violations.
To evaluate the datasets, you must provide the name of the marketing action in the path of a POST request, while providing the dataset IDs within the request body, as shown in the example below.
API format
POST /marketingActions/core/{MARKETING_ACTION_NAME}/constraints
POST /marketingActions/custom/{MARKETING_ACTION_NAME}/constraints
{MARKETING_ACTION_NAME}
/marketingActions/core
or /marketingActions/custom
, respectively.Request
The following request tests the exportToThirdParty
marketing action against datasets obtained in the previous step. The request payload is an array containing the IDs of each dataset.
curl -X POST \
https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty/constraints
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '[
{
"entityType": "dataSet",
"entityId": "5b95b155419ec801e6eee780"
},
{
"entityType": "dataSet",
"entityId": "5b7c86968f7b6501e21ba9df"
}
]'
entityType
entityID
Response
A successful response returns the URI for the marketing action, the data usage labels that were collected from the provided datasets, and a list of any data usage policies that were violated as a result of testing the action against those labels. In this example, the “Export Data to Third Party” policy is shown in the violatedPolicies
array, indicating that the marketing action triggered a policy violation.
{
"timestamp": 1556324277895,
"clientId": "{CLIENT_ID}",
"userId": "{USER_ID}",
"imsOrg": "{ORG_ID}",
"marketingActionRef": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty",
"duleLabels": [
"C1",
"C2",
"C4",
"C5"
],
"discoveredLabels": [
{
"entityType": "dataSet",
"entityId": "5b95b155419ec801e6eee780",
"dataSetLabels": {
"connection": {
"labels": []
},
"dataSet": {
"labels": [
"C5"
]
},
"fields": [
{
"labels": [
"C2",
],
"path": "/properties/_customer"
},
{
"labels": [
"C5"
],
"path": "/properties/geoUnit"
},
{
"labels": [
"C1"
],
"path": "/properties/identityMap"
}
]
}
},
{
"entityType": "dataSet",
"entityId": "5b7c86968f7b6501e21ba9df",
"dataSetLabels": {
"connection": {
"labels": []
},
"dataSet": {
"labels": [
"C5"
]
},
"fields": [
{
"labels": [
"C5"
],
"path": "/properties/createdByBatchID"
},
{
"labels": [
"C5"
],
"path": "/properties/faxPhone"
}
]
}
}
],
"violatedPolicies": [
{
"name": "Export Data to Third Party",
"status": "ENABLED",
"marketingActionRefs": [
"https://platform-stage.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
],
"description": "Conditions under which data cannot be exported to a third party",
"deny": {
"operator": "OR",
"operands": [
{
"label": "C1"
},
{
"operator": "AND",
"operands": [
{
"label": "C3"
},
{
"label": "C7"
}
]
}
]
},
"imsOrg": "{ORG_ID}",
"created": 1565651746693,
"createdClient": "{CREATED_CLIENT}",
"createdUser": "{CREATED_USER",
"updated": 1565723012139,
"updatedClient": "{UPDATED_CLIENT}",
"updatedUser": "{UPDATED_USER}",
"_links": {
"self": {
"href": "https://platform-stage.adobe.io/data/foundation/dulepolicy/policies/custom/5d51f322e553c814e67af1a3"
}
},
"id": "5d51f322e553c814e67af1a3"
}
]
}
duleLabels
discoveredLabels
violatedPolicies
marketingActionRef
) against the provided duleLabels
.Using the data returned in the API response, you can set up protocols within your experience application to appropriately enforce policy violations when they occur.
Filter data fields
If your segment definition does not pass evaluation, you can adjust the data included in the segment definition through one of the two methods outlined below.
Update the merge policy of the segment definition
Updating the merge policy of a segment definition will adjust the datasets and fields that will be included when the segment job is run. See the section on updating an existing merge policy in the API merge policy tutorial for more information.
Restrict specific data fields when exporting the segment definition
When exporting a segment definition to a dataset using the Segmentation API, you can filter the data that is included in the export by using the fields
parameter. Any data fields added to this parameter will be included in the export, while all other data fields will be excluded.
Consider a segment definition that has data fields named “A”, “B”, and “C”. If you wished to only export field “C”, then the fields
parameter would contain field “C” alone. By doing this, fields “A” and “B” would be excluded when exporting the segment definition.
See the section on exporting a segment definition in the segmentation tutorial for more information.
Next steps
By following this tutorial, you have looked up the data usage labels associated with a segment definition and tested them for policy violations against specific marketing actions. For more information on Data Governance in Experience Platform, please read the overview for Data Governance.