Documentation Experience Platform Data Governance Guide

Policy evaluation endpoints

Last update: February 27, 2024

Topics:
Data Governance

CREATED FOR:

Developer

Once marketing actions have been created and data usage policies have been defined, you can use the Policy Service API to evaluate if any policies are violated by certain actions. The returned constraints take the form of a set of policies that would be violated by attempting the marketing action on the specified data containing data usage labels.

By default, only policies whose status is set to ENABLED participate in evaluation. However, you can use the query parameter ?includeDraft=true to include DRAFT policies in evaluation.

Evaluation requests can be made in one of three ways:

Given a marketing action and a set of data usage labels, does the action violate any policies?
Given a marketing action and one or more datasets, does the action violate any policies?
Given a marketing action, one or more datasets, and a subset of one or more fields within each of those datasets, does the action violate any policies?

Getting started

The API endpoints used in this guide is part of the Policy Service API. Before continuing, please review the getting started guide for links to related documentation, a guide to reading the sample API calls in this document, and important information regarding required headers that are needed to successfully make calls to any Experience Platform API.

Evaluate for policy violations using data usage labels

You can evaluate for policy violations based on the presence of a specific set of data usage labels by using the duleLabels query parameter in a GET request.

API format

GET /marketingActions/core/{MARKETING_ACTION_NAME}/constraints?duleLabels={LABELS_LIST}
GET /marketingActions/custom/{MARKETING_ACTION_NAME}/constraints?duleLabels={LABELS_LIST}

Parameter	Description
`{MARKETING_ACTION_NAME}`	The name of the marketing action to test against a set of data usage labels. You can retrieve a list of available marketing actions by making a GET request to the marketing actions endpoint.
`{LABELS_LIST}`	A comma-separated list of data usage labels names to test the marketing action against. For example: `duleLabels=C1,C2,C3` Note that label names are case-sensitive. Ensure that you are using the correct case when listing them in the `duleLabels` parameter.

Request

The example request below evaluates a marketing action against the labels C1 and C3.

IMPORTANT

Be aware of the AND and OR operators in your policy expressions. In the example below, if either label (C1 or C3) had appeared alone in the request, the marketing action would not have violated this policy. It takes both labels (C1 and C3) to return the violated policy. Ensure you are evaluating policies carefully and defining policy expressions with equal care.

curl -X GET \
  'https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/sampleMarketingAction/constraints?duleLabels=C1,C3' \
  -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 includes a violatedPolicies array, which contains the details of the policies that were violated as a result of performing the marketing action against the provided labels. If no policies are violated, the violatedPolicies array will be empty.

{
    "timestamp": 1551134846737,
    "clientId": "{CLIENT_ID}",
    "userId": "{USER_ID}",
    "imsOrg": "{ORG_ID}",
    "marketingActionRef": "https://platform.adobe.io/marketingActions/custom/sampleMarketingAction",
    "duleLabels": [
        "C1",
        "C3"
    ],
    "violatedPolicies": [
        {
            "name": "Export Data to Third Party",
            "status": "ENABLED",
            "marketingActionRefs": [
                "https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/sampleMarketingAction"
            ],
            "description": "NEW content for description.",
            "deny": {
                "operator": "AND",
                "operands": [
                    {
                        "label": "C1"
                    },
                    {
                        "operator": "OR",
                        "operands": [
                            {
                                "label": "C3"
                            },
                            {
                                "label": "C7"
                            }
                        ]
                    }
                ]
            },
            "imsOrg": "{ORG_ID}",
            "created": 1550703519823,
            "createdClient": "{CREATED_CLIENT}",
            "createdUser": "{CREATED_USER}",
            "updated": 1550714340335,
            "updatedClient": "{UPDATED_CLIENT}",
            "updatedUser": "{UPDATED_USER}",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5c6ddb9f5c404513dc2dc454"
                }
            },
            "id": "5c6ddb9f5c404513dc2dc454"
        }
    ]
}

Evaluate for policy violations using datasets

You can evaluate for policy violations based on a set of one or more datasets from which data usage labels can be collected. This is done by performing a POST request to the /constraints endpoint for a specific marketing action and providing a list of dataset IDs within the request body.

API format

POST /marketingActions/core/{MARKETING_ACTION_NAME}/constraints
POST /marketingActions/custom/{MARKETING_ACTION_NAME}/constraints

Parameter	Description
`{MARKETING_ACTION_NAME}`	The name of the marketing action to test against one or more datasets. You can retrieve a list of available marketing actions by making a GET request to the marketing actions endpoint.

Request

The following request performs the crossSiteTargeting marketing action against a set of three datasets to evaluate for any policy violations.

curl -X POST \
  https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/crossSiteTargeting/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": "5c423dc25f2f2e00005e2319"
        },
        {
            "entityType": "dataSet",
            "entityId": "5cc323e15410ef14b749481e"
        },
        {
            "entityType": "dataSet",
            "entityId": "5cc1fb685410ef14b748c55f"
        }
      ]'

Property	Description
`entityType`	The type of entity whose ID is indicated in the sibling `entityId` property. Currently, the only accepted value is `dataSet`.
`entityId`	The ID of a dataset to test the marketing action against. A list of datasets and their corresponding IDs can be obtained by making a GET request to the `/dataSets` endpoint in the Catalog Service API. See the guide on listing Catalog objects for more information.

Response

A successful response includes a violatedPolicies array, which contains the details of the policies that were violated as a result of performing the marketing action against the provided datasets. If no policies are violated, the violatedPolicies array will be empty.

{
    "timestamp": 1556324277895,
    "clientId": "{CLIENT_ID}",
    "userId": "{USER_ID}",
    "imsOrg": "{ORG_ID}",
    "marketingActionRef": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/crossSiteTargeting",
    "duleLabels": [
        "C1",
        "C2",
        "C4",
        "C5",
        "C6"
    ],
    "discoveredLabels": [
        {
            "entityType": "dataSet",
            "entityId": "5c423dc25f2f2e00005e2319",
            "dataSetLabels": {
                "connection": {
                    "labels": []
                },
                "dataSet": {
                    "labels": [
                        "C6"
                    ]
                },
                "fields": [
                    {
                        "labels": [
                            "C2",
                            "C5"
                        ],
                        "path": "/properties/_customer"
                    },
                    {
                        "labels": [
                            "C4",
                            "C5"
                        ],
                        "path": "/properties/geoUnit"
                    },
                    {
                        "labels": [
                            "C4"
                        ],
                        "path": "/properties/identityMap"
                    },
                    {
                        "labels": [
                            "C4"
                        ],
                        "path": "/properties/journeyAI"
                    },
                    {
                        "labels": [
                            "C5"
                        ],
                        "path": "/properties/createdByBatchID"
                    },
                    {
                        "labels": [
                            "C5"
                        ],
                        "path": "/properties/faxPhone"
                    }
                ]
            }
        },
        {
            "entityType": "dataSet",
            "entityId": "5cc323e15410ef14b749481e",
            "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": "5cc1fb685410ef14b748c55f",
            "dataSetLabels": {
                "connection": {
                    "labels": []
                },
                "dataSet": {
                    "labels": [
                        "C5"
                    ]
                },
                "fields": [
                    {
                        "labels": [
                            "C5"
                        ],
                        "path": "/properties/createdByBatchID"
                    },
                    {
                        "labels": [
                            "C5"
                        ],
                        "path": "/properties/faxPhone"
                    }
                ]
            }
        }
    ],
    "violatedPolicies": [
        {
            "name": "Targeting Ads or Content",
            "status": "ENABLED",
            "marketingActionRefs": [
                "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/crossSiteTargeting"
            ],
            "description": "Data cannot be used for targeting any ads or content, either on-site or cross-site.",
            "deny": {
                "operator": "AND",
                "operands": [
                    {
                        "label": "C4"
                    },
                    {
                        "label": "C6"
                    }
                ]
            },
            "imsOrg": "{ORG_ID}",
            "created": 1551141210463,
            "createdClient": "{CREATED_CLIENT}",
            "createdUser": "{CREATED_USER}",
            "updated": 1551146178603,
            "updatedClient": "{UPDATED_CLIENT}",
            "updatedUser": "{UPDATED_USER}",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/dulepolicy/policies/custom/5c74895a74744d13dc2d87cc"
                }
            },
            "id": "5c74895a74744d13dc2d87cc"
        }
    ]
}

Property	Description
`duleLabels`	The response object includes a `duleLabels` array that contains a consolidated list of all labels found within the specified datasets. This list includes dataset- and field-level labels on all fields within the dataset.
`discoveredLabels`	The response also includes a `discoveredLabels` array containing objects for each dataset, showing `datasetLabels` broken down into dataset- and field-level labels. Each field-level label shows the path to the specific field with that label.

Evaluate for policy violations using specific dataset fields

You can evaluate for policy violations based on a subset of fields from within one or more datasets, so that only the data usage labels applied those fields are evaluated.

When evaluating policies using dataset fields, please keep the following in mind:

Field names are case sensitive: When providing fields, they must be written exactly as they appear in the dataset (for example, firstName vs firstname).
Dataset label inheritance: Individual fields in a dataset inherit any labels that have been applied at the dataset level. If your policy evaluations are not returning as expected, be sure to check for any labels that may have been inherited from the dataset level down to fields, in addition to those applied at the field level.

API format

POST /marketingActions/core/{MARKETING_ACTION_NAME}/constraints
POST /marketingActions/custom/{MARKETING_ACTION_NAME}/constraints

Parameter	Description
`{MARKETING_ACTION_NAME}`	The name of the marketing action to test against a subset of dataset fields. You can retrieve a list of available marketing actions by making a GET request to the marketing actions endpoint.

Request

The following request tests the marketing action crossSiteTargeting on a specific set of fields belonging to three datasets. The payload is similar to an evaluation request involving only datasets, adding specific fields for each dataset to collect labels from.

curl -X POST \
  https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/crossSiteTargeting/constraints \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
            "entityType": "dataSet",
            "entityId": "5c423dc25f2f2e00005e2319",
            "entityMeta": {
                "fields": [
                    "/properties/_customer",
                    "/properties/faxPhone"
                ]
            }
        },
        {
            "entityType": "dataSet",
            "entityId": "5cc323e15410ef14b749481e",
            "entityMeta": {
                "fields": [
                    "/properties/_customer",
                    "/properties/geoUnit"
                ]
            }
        },
        {
            "entityType": "dataSet",
            "entityId": "5cc1fb685410ef14b748c55f",
            "entityMeta": {
                "fields": [
                    "/properties/faxPhone"
                ]
            }
        }
      ]'

Property	Description
`entityType`	The type of entity whose ID is indicated in the sibling `entityId` property. Currently, the only accepted value is `dataSet`.
`entityId`	The ID of a dataset whose fields are to be evaluated against the marketing action. A list of datasets and their corresponding IDs can be obtained by making a GET request to the `/dataSets` endpoint in the Catalog Service API. See the guide on listing Catalog objects for more information.
`entityMeta.fields`	An array of paths to specific fields within the dataset’s schema, provided in the form of JSON Pointer strings. See the section on JSON Pointer in the API fundamentals guide for details on the accepted syntax for these strings.

Response

A successful response includes a violatedPolicies array, which contains the details of the policies that were violated as a result of performing the marketing action against the provided dataset fields. If no policies are violated, the violatedPolicies array will be empty.

Comparing the example response below to the response involving only datasets, note that the list of collected labels is shorter. The discoveredLabels for each dataset have also been reduced, as they only include the fields specified in the request body. In addition, the previously violated policy Targeting Ads or Content requires both C4 AND C6 labels to present, and is therefore no longer violated as indicated by the empty violatedPolicies array.

{
    "timestamp": 1556325503038,
    "clientId": "{CLIENT_ID}",
    "userId": "{USER_ID}",
    "imsOrg": "{ORG_ID}",
    "marketingActionRef": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/crossSiteTargeting",
    "duleLabels": [
        "C2",
        "C5",
        "C6"
    ],
    "discoveredLabels": [
        {
            "entityType": "dataSet",
            "entityId": "5c423dc25f2f2e00005e2319",
            "dataSetLabels": {
                "connection": {
                    "labels": []
                },
                "dataSet": {
                    "labels": [
                        "C6"
                    ]
                },
                "fields": [
                    {
                        "labels": [
                            "C2",
                            "C5"
                        ],
                        "path": "/properties/_customer"
                    },
                    {
                        "labels": [
                            "C5"
                        ],
                        "path": "/properties/faxPhone"
                    }
                ]
            }
        },
        {
            "entityType": "dataSet",
            "entityId": "5cc323e15410ef14b749481e",
            "dataSetLabels": {
                "connection": {
                    "labels": []
                },
                "dataSet": {
                    "labels": [
                        "C5"
                    ]
                },
                "fields": [
                    {
                        "labels": [
                            "C2",
                            "C5"
                        ],
                        "path": "/properties/_customer"
                    },
                    {
                        "labels": [
                            "C5"
                        ],
                        "path": "/properties/geoUnit"
                    }
                ]
            }
        },
        {
            "entityType": "dataSet",
            "entityId": "5cc1fb685410ef14b748c55f",
            "dataSetLabels": {
                "connection": {
                    "labels": []
                },
                "dataSet": {
                    "labels": [
                        "C5"
                    ]
                },
                "fields": [
                    {
                        "labels": [
                            "C5"
                        ],
                        "path": "/properties/faxPhone"
                    }
                ]
            }
        }
    ],
    "violatedPolicies": []
}

Evaluate policies in bulk

The /bulk-eval endpoint allows you to run multiple evaluation jobs in a single API call.

API format

POST /bulk-eval

Request

The payload of a bulk evaluation request should be an array of objects; one for each evaluation job to be performed. For jobs that evaluate based on datasets and fields, an entityList array must be provided. For jobs that evaluate based on data usage labels, a labels array must be provided.

WARNING

If any listed evaluation job contains both an entityList and a labels array, an error will result. If you wish to evaluate the same marketing action based on both datasets and labels, you must include separate evaluation jobs for that marketing action.

curl -X POST \
  https://platform.adobe.io/data/foundation/dulepolicy/bulk-eval \
  -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 '[
        {
          "evalRef": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting/constraints",
          "includeDraft": false,
          "labels": [
            "C1",
            "C2",
            "C3"
          ]
        },
        {
          "evalRef": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting/constraints",
          "includeDraft": false,
          "entityList": [
            {
              "entityType": "dataSet",
              "entityId": "5b67f4dd9f6e710000ea9da4",
              "entityMeta": {
                "fields": [
                  "address"
                ]
              }
            }
          ]
        }
      ]'

Property	Description
`evalRef`	The URI of the marketing action to test against labels or datasets for policy violations.
`includeDraft`	By default, only enabled policies participate in evaluation. If `includeDraft` is set to `true`, policies that are in `DRAFT` status will also participate.
`labels`	An array of data usage labels to test the marketing action against. IMPORTANT: When using this property, an `entityList` property must NOT be included in the same object. To evaluate the same marketing action using datasets and/or fields, you must include a separate object in the request payload that contains an `entityList` array.
`entityList`	An array of datasets and (optionally) specific fields within those datasets to test the marketing action against. IMPORTANT: When using this property, a `labels` property must NOT be included in the same object. To evaluate the same marketing action using specific data usage labels, you must include a separate object in the request payload that contains a `labels` array.
`entityType`	The type of entity to test the marketing action against. Currently, only `dataSet` is supported.
`entityId`	The ID of a dataset to test the marketing action against.
`entityMeta.fields`	(Optional) A list of specific fields within the dataset to test the marketing action against.

Response

A successful response returns an array of evaluation results; one for each policy evaluation job sent in the request.

[
  {
    "status": 200,
    "body": {
      "timestamp": 1595866566165,
      "clientId": "{CLIENT_ID}",
      "userId": "{USER_ID}",
      "imsOrg": "{ORG_ID}",
      "sandboxName": "prod",
      "marketingActionRef": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting",
      "duleLabels": [
        "C1",
        "C2",
        "C3"
      ],
      "violatedPolicies": []
    }
  },
  {
    "status": 200,
    "body": {
      "timestamp": 1595866566165,
      "clientId": "{CLIENT_ID}",
      "userId": "{USER_ID}",
      "imsOrg": "{ORG_ID}",
      "sandboxName": "prod",
      "marketingActionRef": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting",
      "duleLabels": [
        "C1",
        "C2"
      ],
      "discoveredLabels": [
        {
          "entityType": "dataset",
          "entityId": "5b67f4dd9f6e710000ea9da4",
          "dataSetLabels": {
            "connection": {
              "labels": [

              ]
            },
            "dataset": {
              "labels": [
                "C1",
                "C2"
              ]
            },
            "fields": []
          }
        }
      ],
      "violatedPolicies": [
        {
          "name": "Email Policy",
          "status": "DRAFT",
          "marketingActionRefs": [
            "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting"
          ],
          "description": "Conditions under which we won't send marketing-based email",
          "deny": {
            "label": "C1",
            "operator": "AND",
            "operands": [
              {
                "label": "C1"
              },
              {
                "label": "C3"
              }
            ]
          },
          "id": "76131228-7654-11e8-adc0-fa7ae01bbebc",
          "imsOrg": "{ORG_ID}",
          "created": 1529696681413,
          "createdClient": "{CLIENT_ID}",
          "createdUser": "{USER_ID}",
          "updated": 1529697651972,
          "updatedClient": "{CLIENT_ID}",
          "updatedUser": "{USER_ID}",
          "_links": {
            "self": {
              "href": "./76131228-7654-11e8-adc0-fa7ae01bbebc"
            }
          }
        }
      ]
    }
  }
]

Policy evaluation endpoints

Getting started

Evaluate for policy violations using data usage labels

Evaluate for policy violations using datasets

Evaluate for policy violations using specific dataset fields

Evaluate policies in bulk

Policy evaluation for Real-Time Customer Profile