Evaluate and access segment definition results

This document provides a tutorial for evaluating segment definitions and accessing these results using the Segmentation API.

Getting started

This tutorial requires a working understanding of the various Adobe Experience Platform services involved in creating audiences. Before beginning this tutorial, please review the documentation for the following services:

Required headers

This tutorial also requires you to have completed the authentication tutorial in order to successfully make calls to Platform APIs. Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

All POST, PUT, and PATCH requests require an additional header:

Evaluate a segment definition evaluate-a-segment

Once you have developed, tested, and saved your segment definition, you can then evaluate the segment definition through either scheduled evaluation or on-demand evaluation.

Scheduled evaluation (also known as ‘scheduled segmentation’) allows you to create a recurring schedule for running an export job at a specific time, whereas on-demand evaluation involves creating a segment job to build the audience immediately. Steps for each are outlined below.

If you have not yet completed the create a segment definition using the Segmentation API tutorial or created a segment definition using Segment Builder, please do so before proceeding with this tutorial.

Scheduled evaluation scheduled-evaluation

Through scheduled evaluation, your organization can create a recurring schedule to automatically run export jobs.

Create a schedule

By making a POST request to the /config/schedules endpoint, you can create a schedule and include the specific time when the schedule should be triggered.

More detailed information about using this endpoint can be found in the schedules endpoint guide

Enable a schedule

By default, a schedule is inactive when created unless the state property is set to active in the create (POST) request body. You can enable a schedule (set the state to active) by making a PATCH request to the /config/schedules endpoint and including the ID of the schedule in the path.

More detailed information about using this endpoint can be found in the schedules endpoint guide

Update the schedule time

Schedule timing can be updated by making a PATCH request to the /config/schedules endpoint and including the ID of the schedule in the path.

More detailed information about using this endpoint can be found in the schedules endpoint guide

On-demand evaluation

On-demand evaluation allows you to create a segment job in order to generate an audience whenever you require it. Unlike scheduled evaluation, this will happen only when requested and is not recurring.

Create a segment job

A segment job is an asynchronous process that creates an audience segment on demand. It references a segment definition, as well as any merge policies controlling how Real-Time Customer Profile merges overlapping attributes across your profile fragments. When a segment job successfully completes, you can gather various information about the segment definition, such as any errors that may have occurred during processing and the ultimate size of your audience. A segment job needs to be run every time you want to refresh the audience that the segment definition currently qualifies.

You can create a new segment job by making a POST request to the /segment/jobs endpoint in the Real-Time Customer Profile API.

More detailed information about using this endpoint can be found in the segment jobs endpoint guide

Look up segment job status

You can use the id for a specific segment job to perform a lookup request (GET) in order to view the current status of the job.

More detailed information about using this endpoint can be found in the segment jobs endpoint guide

Interpret segment job results

When segment jobs are successfully run, the segmentMembership map is updated for each profile included within the segment definition. segmentMembership also stores any pre-evaluated audiences that are ingested into Platform, allowing for integration with other solutions like Adobe Audience Manager.

The following example shows what the segmentMembership attribute looks like for each individual profile record:

{
  "segmentMembership": {
    "UPS": {
      "04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
        "timestamp": "2018-04-26T15:52:25+00:00",
        "status": "realized"
      },
      "53cba6b2-a23b-454a-8069-fc41308f1c0f": {
        "lastQualificationTime": "2018-04-26T15:52:25+00:00",
        "status": "realized"
      }
    },
    "Email": {
      "abcd@adobe.com": {
        "lastQualificationTime": "2017-09-26T15:52:25+00:00",
        "status": "exited"
      }
    }
  }
}

Access segment job results

The results of a segment job can be accessed in one of two ways: you can access individual profiles or export an entire audience to a dataset.

The following sections outline these options in more detail.

Look up a profile

If you know the specific profile that you would like to access, you can do so using the Real-Time Customer Profile API. The complete steps for accessing individual profiles are available in the Access Real-Time Customer Profile data using the Profile API tutorial.

Export a segment export

After a segmentation job has successfully completed (the value of the status attribute is “SUCCEEDED”), you can export your audience to a dataset where it can be accessed and acted upon.

The following steps are required to export your audience:

Create a target dataset create-dataset

When exporting an audience, a target dataset must first be created. It is important that the dataset be configured correctly to ensure the export is successful.

One of the key considerations is the schema upon which the dataset is based (schemaRef.id in the API sample request below). In order to export a segment definition, the dataset must be based on the XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union). A union schema is a system-generated, read-only schema that aggregates the fields of schemas which share the same class, in this case that is the XDM Individual Profile class. For more information on union view schemas, please see the Real-Time Customer Profile section of the Schema Registry developer guide.

There are two ways to create the necessary dataset:

If you already have a compatible dataset and know its ID, you can proceed directly to the step for generating audience profiles.

API format

POST /dataSets

Request

The following request creates a new dataset, providing configuration parameters in the payload.

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": "Segment Export",
    "schemaRef": {
        "id": "https://ns.adobe.com/xdm/context/profile__union",
        "contentType": "application/vnd.adobe.xed+json;version=1"
    }
}'

Response

A successful response returns an array containing the read-only, system-generated unique ID of the newly created dataset. A properly configured dataset ID is required in order to successfully export audience members.

[
  "@/datasets/5b020a27e7040801dedba61b"
]

Generate profiles for audience members generate-profiles

Once you have a union-persisting dataset, you can create an export job to persist the audience members to the dataset by making a POST request to the /export/jobs endpoint in the Real-Time Customer Profile API and providing the dataset ID and the segment definition information for the segment definitions that you wish to export.

More detailed information about using this endpoint can be found in the export jobs endpoint guide

Monitor export progress

As an export job processes, you can monitor its status by making a GET request to the /export/jobs endpoint and including the id of the export job in the path. The export job is complete once the status field returns the value “SUCCEEDED”.

More detailed information about using this endpoint can be found in the export jobs endpoint guide

Next steps

Once the export has completed successfully, your data is available within the Data Lake in Experience Platform. You can then use the Data Access API to access the data using the batchId associated with the export. Depending on the size of the segment definition, the data may be in chunks and the batch may consist of several files.

For step-by-step instructions on how to use the Data Access API to access and download batch files, follow the Data Access tutorial.

You can also access successfully exported segment definition data using Adobe Experience Platform Query Service. Using the UI or RESTful API, Query Service allows you to write, validate, and run queries on data within the Data Lake.

For more information on how to query audience data, please review the documentation on Query Service.