۶Ƶ

DocumentationExperience PlatformCatalog and Datasets Guide

Enable a dataset for profile updates using APIs

Last update: Tue May 28 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer

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.

NOTE
The workflow described in this tutorial only works for batch ingestion. For streaming ingestion upserts, please refer to the guide on sending partial row updates to Real-Time Customer Profile using Data Prep.

Getting started

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

  • Real-Time Customer Profile: Provides a unified, real-time consumer profile based on aggregated data from multiple sources.
  • Catalog Service: A RESTful API that allows you to create datasets and configure them for Real-Time Customer Profile and Identity Service.
  • Experience Data Model (XDM): The standardized framework by which Platform organizes customer experience data.
  • Batch ingestion: The Batch Ingestion API allows you to ingest data into Experience Platform as batch files.

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

NOTE
To create a new Profile-enabled dataset, you must know the ID of an existing XDM schema that is enabled for Profile. For information on how to look-up or create a Profile-enabled schema, see the tutorial on creating a schema using the Schema Registry API.

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"
            ]
        }
      }'
Property
Description
schemaRef.id
The ID of the Profile-enabled schema upon which the dataset will be based.
{TENANT_ID}
The namespace within the Schema Registry which contains resources belonging to your organization. See the TENANT_ID section of the Schema Registry developer guide for more information.

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.

NOTE
In order to configure an existing Profile-enabled dataset for upsert, you must first disable the dataset for Profile and then re-enable it alongside the isUpsert tag. If the existing dataset is not enabled for Profile, you can proceed directly to the steps for enabling the dataset for Profile and upsert. If you are unsure, the following steps show you how to check if the dataset is enabled already.

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}
Parameter
Description
{DATASET_ID}
The ID of a dataset you want to inspect.

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.

WARNING
Data ingested into the dataset while it is disabled will not be ingested into the Profile store. You should avoid ingesting data into the dataset until it has been re-enabled for Profile.

API format

PATCH /dataSets/{DATASET_ID}
Parameter
Description
{DATASET_ID}
The ID of the dataset you want to update.

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.

IMPORTANT
When enabling your dataset for Profile, please ensure the schema the dataset is associated with is also Profile-enabled. If the schema is not Profile-enabled, the dataset will not appear as Profile-enabled within the Platform UI.

API format

PATCH /dataSets/{DATASET_ID}
Parameter
Description
{DATASET_ID}
The ID of a dataset you want to update.

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 ۶Ƶ Experience Platform, please begin by reading the data ingestion overview.

recommendation-more-help
c5c02be6-79a3-4a2f-b766-136bffe8b676