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:
- 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 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 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"
]
}
}'
schemaRef.id
{TENANT_ID}
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.
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}
{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}
{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}
{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.