Enable a dataset for profile updates using APIs

This tutorial covers the process of enabling a dataset with “upsert” capabilities in order to make updates to Real-Time Customer Profile data. This includes steps for creating a new dataset and configuring an existing dataset.

Getting started

This tutorial requires a working understanding of several Adobe Experience Platform services involved in managing Profile-enabled datasets. Before beginning this tutorial, please review the documentation for these related Platform services:

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:

All requests that contain a payload (POST, PUT, PATCH) require an additional Content-Type header. The correct value for this header is shown in the sample requests where necessary.

All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require an x-sandbox-name header that specifies the name of the sandbox the operation will take place in. For more information on sandboxes in Platform, see the sandbox overview documentation.

Create a dataset enabled for profile updates

When creating a new dataset, you can enable that dataset for Profile and enable update capabilities at the time of creation.

To create a dataset that is enabled for Profile and updates, use a POST request to the /dataSets endpoint.

API format

POST /dataSets

Request

By including both the unifiedIdentity and the unifiedProfile under tags in the request body, the dataset will be enabled for Profile upon creation. Within the unifiedProfile array, adding isUpsert:true will add the ability for the dataset to support updates.

curl -X POST \
  https://platform.adobe.io/data/foundation/catalog/dataSets \
  -H 'Content-Type: application/json' \
  -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}' \
  -d '{
        "name": "Sample dataset",
        "description: "A sample dataset with a sample description.",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/31670881463308a46f7d2cb09762715",
            "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
        },
        "tags": {
            "unifiedIdentity": [
                "enabled: true"
            ],
            "unifiedProfile": [
                "enabled: true",
                "isUpsert: true"
            ]
        }
      }'

Response

A successful response shows an array containing the ID of the newly created dataset in the form of "@/dataSets/{DATASET_ID}".

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Configure an existing dataset configure-an-existing-dataset

The following steps cover how to configure an existing Profile-enabled dataset for update (upsert) functionality.

Check if the dataset is enabled for Profile

Using the Catalog API, you can inspect an existing dataset to determine whether it is enabled for use in Real-Time Customer Profile. The following call retrieves the details of a dataset by ID.

API format

GET /dataSets/{DATASET_ID}

Request

curl -X GET 'https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e' \
  -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

{
    "5b020a27e7040801dedbf46e": {
        "name": "{DATASET_NAME}",
        "imsOrg": "{ORG_ID}",
        "tags": {
            "adobe/pqs/table": [
                "unifiedprofileingestiontesteventsdataset"
            ],
            "unifiedIdentity": [
                "enabled:true"
            ],
            "unifiedProfile": [
                "enabled:true"
            ]
        },
        "version": "1.0.1",
        "created": 1536536917382,
        "updated": 1539793978215,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "viewId": "{VIEW_ID}",
        "files": "@/dataSetFiles?dataSetId=5b020a27e7040801dedbf46e",
        "schema": "{SCHEMA}",
        "schemaRef": {
            "id": "https://ns.adobe.com/xdm/context/experienceevent",
            "contentType": "application/vnd.adobe.xed+json"
        }
    }
}

Under the tags property, you can see that unifiedProfile is present with the value enabled:true. Therefore, Real-Time Customer Profile is enabled for this dataset.

Disable the dataset for Profile

In order to configure a Profile-enabled dataset for updates, you must first disable the unifiedProfile and unifiedIdentity tags and then re-enable them alongside the isUpsert tag. This is done using two PATCH requests, once to disable and one to re-enable.

API format

PATCH /dataSets/{DATASET_ID}

Request

The first PATCH request body includes a path to unifiedProfile and a path to unifiedIdentity, setting the value to enabled:false for both of these paths in order to disable the tags.

curl -X PATCH https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type:application/json-patch+json' \
  -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}' \
  -d '[
        {
            "op": "replace",
            "path": "/tags/unifiedProfile",
            "value": ["enabled:false"]
        },
        {
            "op": "replace",
            "path": "/tags/unifiedIdentity",
            "value": ["enabled:false"]
        }
      ]'

Response

A successful PATCH request returns HTTP Status 200 (OK) and an array containing the ID of the updated dataset. This ID should match the one sent in the PATCH request. The unifiedProfile and unifiedIdentity tags have now been disabled.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Enable the dataset for Profile and upsert enable-the-dataset

An existing dataset can be enabled for Profile and attribute updates using a single PATCH request.

API format

PATCH /dataSets/{DATASET_ID}

Request

The request body includes a path to unifiedProfile setting the value to include the enabled and isUpsert tags, both set to true, and a path to unifiedIdentity setting the value to include the enabled tag set to true.

curl -X PATCH https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type:application/json-patch+json' \
  -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}' \
  -d '[
        {
            "op": "add",
            "path": "/tags/unifiedProfile",
            "value": [
                "enabled:true",
                "isUpsert:true"
            ]
        },
        {
            "op": "add",
            "path": "/tags/unifiedIdentity",
            "value": [
                "enabled:true"
            ]
        }
      ]'

Response

A successful PATCH request returns HTTP Status 200 (OK) and an array containing the ID of the updated dataset. This ID should match the one sent in the PATCH request. The unifiedProfile tag and unifiedIdentity tag have now been enabled and configured for attribute updates.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Next steps

Your Profile and upsert-enabled dataset can now be used by batch ingestion workflows to make updates to profile data. To learn more about ingesting data into Adobe Experience Platform, please begin by reading the data ingestion overview.