Enable a dataset for Profile and Identity Service using APIs

This tutorial covers the process of enabling a dataset for use in Real-Time Customer Profile and Identity Service, broken down into the following steps:

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 and Identity create-a-dataset-enabled-for-profile-and-identity

You can enable a dataset for Real-Time Customer Profile and Identity Service immediately upon creation or at any point after the dataset has been created. If you would like to enable a dataset that has already been created, follow the steps for configuring an existing dataset found later in this document.

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

API format

POST /dataSets

Request

By including unifiedProfile and unifiedIdentity under tags in the request body, the dataset will be immediately enabled for Profile and Identity Service, respectively. The values of these tags must be an array containing the string "enabled:true".

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 '{
    "schemaRef": {
        "id": "https://ns.adobe.com/{TENANT_ID}/schemas/31670881463308a46f7d2cb09762715",
        "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
    },
    "tags": {
       "unifiedProfile": ["enabled:true"],
       "unifiedIdentity": ["enabled:true"]
    }
  }'

Response

A successful response shows an array containing the ID of the newly created dataset in the form of "@/dataSets/{DATASET_ID}". Once you have successfully created and enabled a dataset, please proceed to the steps for uploading data.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Configure an existing dataset configure-an-existing-dataset

The following steps cover how to enable a previously created dataset for Real-Time Customer Profile and Identity Service. If you have already created a Profile-enabled dataset, please proceed to the steps for ingesting data.

Check if the dataset is enabled check-if-the-dataset-is-enabled

Using the Catalog API, you can inspect an existing dataset to determine whether it is enabled for use in Real-Time Customer Profile and Identity Service. 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": "Commission Program Events DataSet",
        "imsOrg": "{ORG_ID}",
        "tags": {
            "adobe/pqs/table": [
                "unifiedprofileingestiontesteventsdataset"
            ],
            "unifiedProfile": [
                "enabled:true"
            ],
            "unifiedIdentity": [
                "enabled:true"
            ]
        },
        "version": "1.0.1",
        "created": 1536536917382,
        "updated": 1539793978215,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "viewId": "5b020a27e7040801dedbf46f",
        "files": "@/dataSetFiles?dataSetId=5b020a27e7040801dedbf46e",
        "schema": "@/xdms/context/experienceevent",
        "schemaRef": {
            "id": "https://ns.adobe.com/xdm/context/experienceevent",
            "contentType": "application/vnd.adobe.xed+json"
        }
    }
}

Under the tags property, you can see that unifiedProfile and unifiedIdentity are both present with the value enabled:true. Therefore, Real-Time Customer Profile and Identity Service are enabled for this dataset, respectively.

Enable the dataset enable-the-dataset

If the existing dataset has not been enabled for Profile or Identity Service, you can enable it by making a PATCH request using the dataset ID.

API format

PATCH /dataSets/{DATASET_ID}

Request

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"] },
        { "op": "add", "path": "/tags/unifiedIdentity", "value": ["enabled:true"] }
      ]'

The request body includes a path to two types of tags, unifiedProfile and unifiedIdentity. The value of each are arrays containing the string 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 and unifiedIdentity tags have now been added and the dataset is enabled for use by Profile and Identity services.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Ingest data into the dataset ingest-data-into-the-dataset

Both Real-Time Customer Profile and Identity Service consume XDM data as it is being ingested into a dataset. For instructions on how to upload data into a dataset, refer to the tutorial on creating a dataset using APIs. When planning what data to send to your Profile-enabled dataset, consider the following best practices:

Confirm data ingest by Real-Time Customer Profile confirm-data-ingest-by-real-time-customer-profile

When uploading data to a new dataset for the first time, or as part of a process involving a new ETL or data source, it is recommended to carefully check the data to ensure it has been uploaded as expected. Using the Real-Time Customer Profile Access API, you can retrieve batch data as it gets loaded into a dataset. If you are unable to retrieve any of the entities you expect, your dataset may not be enabled for Real-Time Customer Profile. After confirming that your dataset has been enabled, ensure that your source data format and identifiers support your expectations. For detailed instructions on how to use the Real-Time Customer Profile API to access Profile data, please refer to the entities endpoint guide, also known as the “Profile Access” API.

Confirm data ingest by Identity Service confirm-data-ingest-by-identity-service

Each data fragment ingested that contains more than one identity creates a link in your private identity graph. For more information on identity graphs and access identity data, please begin by reading the Identity Service overview.