ÃÛ¶¹ÊÓƵ

DocumentationExperience PlatformDestinations Guide

Message format

Last update: Mon Jan 22 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • User

Prerequisites - ÃÛ¶¹ÊÓƵ Experience Platform concepts prerequisites

To understand the message format and profile configuration and transformation process on the ÃÛ¶¹ÊÓƵ side, please familiarize yourself with the following Experience Platform concepts:

IMPORTANT
All parameter names and values supported by Destination SDK are case sensitive. To avoid case sensitivity errors, please use the parameters names and values exactly as shown in the documentation.

Supported integration types supported-integration-types

Refer to the table below for details on which types of integrations support the functionality described on this page.

Integration type
Supports functionality
Real-time (streaming) integrations
Yes
File-based (batch) integrations
Yes (only steps 1 and 2 in the diagram further below)

Overview overview

This page addresses the message format and the profile transformation in data exported from ÃÛ¶¹ÊÓƵ Experience Platform to destinations.

ÃÛ¶¹ÊÓƵ Experience Platform exports data to a significant number of destinations, in various data formats. Some examples of destination types are advertising platforms (Google), social networks (Facebook), and cloud storage locations (Amazon S3, Azure Event Hubs).

Experience Platform can adjust the message format of exported profiles to match the expected format on your side. To understand this customization, the following concepts are important:

  • The source (1) and target (2) XDM schema in ÃÛ¶¹ÊÓƵ Experience Platform
  • The expected message format on the partner side (3), and
  • The transformation layer between XDM schema and expected message format, which you can define by creating a message transformation template.

Schema to JSON transformation

Experience Platform uses XDM schemas to describe the structure of data in a consistent and reusable way.

Source XDM schema (1): This item refers to the schema that customers use in Experience Platform. In Experience Platform, in the mapping step of the activate destination workflow, customers map fields from their XDM schema to your destination’s target schema (2).

Target XDM schema (2): Based on the JSON standard schema (3) of your destination’s expected format and the attributes that your destination can interpret, you can define profile attributes and identities in your target XDM schema. You can do this in the destinations configuration, in the schemaConfig and identityNamespaces objects.

JSON standard schema of your destination profile attributes (3): This example represents a of all the profile attributes that your platform supports and their types (for example: object, string, array). Example fields that your destination could support could be firstName, lastName, gender, email, phone, productId, productName, and so on. You need a message transformation template to tailor the data exported out of Experience Platform to your expected format.

Based on the schema transformations described above, here is how a profile configuration changes between the source XDM schema and a sample schema on the partner side:

Transformations message example

Getting started - transforming three basic attributes getting-started

To demonstrate the profile transformation process, the example below uses three common profile attributes in ÃÛ¶¹ÊÓƵ Experience Platform: first name, last name, and email address.

NOTE
The customer maps the attributes from the source XDM schema to the partner XDM schema in the ÃÛ¶¹ÊÓƵ Experience Platform UI, in the Mapping step of the activate destination workflow.

Let’s say your platform can receive a message format like:

POST https://YOUR_REST_API_URL/users/
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

{
  "attributes":
    {
      "first_name": "Yours",
      "last_name": "Truly",
      "external_id": "yourstruly@adobe.com"
    }
}

Considering the message format, the corresponding transformations are as follows:

Attribute in partner XDM schema on the ÃÛ¶¹ÊÓƵ side
Transformation
Attribute in HTTP message on your side
_your_custom_schema.firstName
attributes.first_name
first_name
_your_custom_schema.lastName
attributes.last_name
last_name
personalEmail.address
attributes.external_id
external_id

Profile structure in Experience Platform profile-structure

To understand the examples further below on the page, it is important to know the structure of a profile in Experience Platform.

Profiles have 3 sections:

  • segmentMembership (always present on a profile)

    • this section contains all the audiences that are present on the profile. The audiences can have one of two statuses: realized or exited.

  • identityMap (always present on a profile)

    • this section contains all the identities that are present on the profile (email, Google GAID, Apple IDFA, and so on) and that the user mapped for exporting in the activation workflow.

  • attributes (depending on the destination configuration, these might be present on the profile). There is also a slight difference to note between predefined attributes and freeform attributes:

    • for freeform attributes, these contain a .value path if the attribute is present on the profile (see the lastName attribute from example 1). If they aren’t present on the profile, they won’t contain the .value path (see firstName attribute from example 1).
    • for predefined attributes, these do not contain a .value path. All mapped attributes that are present on a profile will be present in the attributes map. The ones that are not will not be present (see Example 2 - the firstName attribute does not exist on the profile).

See below two examples of profiles in Experience Platform:

Example 1 with segmentMembership, identityMap and attributes for freeform attributes example-1

{
  "segmentMembership": {
    "ups": {
      "11111111-1111-1111-1111-111111111111": {
        "lastQualificationTime": "2019-04-15T02:41:50.000+0000",
        "status": "realized"
      }
    }
  },
  "identityMap": {
    "mobileIds": [
      {
        "id": "e86fb215-0921-4537-bc77-969ff775752c"
      }
    ]
  },
  "attributes": {
    "firstName": {
    },
    "lastName": {
      "value": "lastName"
    }
  }
}

Example 2 with segmentMembership, identityMap and attributes for predefined attributes example-2

{
  "segmentMembership": {
    "ups": {
      "11111111-1111-1111-1111-111111111111": {
        "lastQualificationTime": "2019-04-15T02:41:50.000+0000",
        "status": "realized"
      }
    }
  },
  "identityMap": {
    "mobileIds": [
      {
        "id": "e86fb215-0921-4537-bc77-969ff775752c"
      }
    ]
  },
  "attributes": {
    "lastName": "lastName"
  }
}

Using a templating language for the identity, attributes, and audience membership transformations using-templating

ÃÛ¶¹ÊÓƵ uses , a templating language similar to , to transform the fields from the Experience Platform XDM schema into a format supported by your destination.

This section provides several examples of how these transformations are made - from the input XDM schema, through the template, and outputting into payload formats accepted by your destination. The examples below are presented by increasing complexity, as follows:

  1. Simple transformation examples. Learn how templating works with simple transformations for Profile attributes, Audience membership, and Identity fields.
  2. Increased complexity examples of templates that combine the fields above: Create a template that sends audiences and identities and Create a template that sends segments, identities, and profile attributes.
  3. Templates that include the aggregation key. When you use configurable aggregation in the destination configuration, Experience Platform groups the profiles exported to your destination based on criteria such as audience ID, audience status, or identity namespaces.

Profile Attributes attributes

To transform the profile attributes exported to your destination, see the JSON and code samples below.

IMPORTANT
For a list of all available profile attributes in ÃÛ¶¹ÊÓƵ Experience Platform, see the XDM field dictionary.

Input

Profile 1:

{
    "attributes": {
        "firstName": {
            "value": "Hermione"
    },
    "birthDate": {}
  }
}

Profile 2:

{
  "attributes": {
    "firstName": {
      "value": "Harry"
    },
    "birthDate": {
        "value": "1980/07/31"
    }
  }
}

Template

IMPORTANT
For all templates that you use, you must escape the illegal characters, such as double quotes "" before inserting the template in the destination server configuration. For more information on escaping double quotes, see Chapter 9 in the .
{
    "profiles": [
        {% for profile in input.profiles %}
        {
            {% for attribute in profile.attributes %}
            "{{ attribute.key }}":
                {% if attribute.value is empty %}
                    null
                {% else %}
                    "{{ attribute.value.value }}"
                {% endif %}
            {% if not loop.last %},{% endif %}
            {% endfor %}
        }{% if not loop.last %},{% endif %}
        {% endfor %}
    ]
}

Result

{
    "profiles": [
        {
            "firstName": "Hermione",
            "birthDate": null
        },
        {
            "firstName": "Harry",
            "birthDate": "1980/07/31"
        }
    ]
}

Audience membership audience-membership

The segmentMembership XDM attribute informs which audiences a profile is a member of.
For the three different values in the status field, read the documentation on Audience Membership Details schema field group.

Input

Profile 1:

{
  "segmentMembership": {
    "ups": {
      "36a51c13-9dd6-4d2c-8aa3-07d785ea5075": {
        "lastQualificationTime": "2019-11-20T13:15:49Z",
        "status": "realized"
      },
      "788d8874-8007-4253-92b7-ee6b6c20c6f3": {
        "lastQualificationTime": "2019-11-20T13:15:49Z",
        "status": "realized"
      },
      "8f812592-3f06-416b-bd50-e7831848a31a": {
        "lastQualificationTime": "2019-11-20T13:15:49Z",
        "status": "exited"
      }
    }
  }
}

Profile 2:

{
  "segmentMembership": {
    "ups": {
      "32396e4b-16f6-4033-9702-fc69b5e24e7c": {
        "lastQualificationTime": "2021-08-20T17:23:04Z",
        "status": "realized"
      },
      "af854278-894a-4192-a96b-320fbf2623fd": {
        "lastQualificationTime": "2021-08-20T16:44:37Z",
        "status": "realized"
      },
      "66505bf9-bc08-4bac-afbc-8b6706650ea4": {
        "lastQualificationTime": "2019-08-20T17:23:04Z",
        "status": "realized"
      }
    }
  }
}

Template

IMPORTANT
For all templates that you use, you must escape the illegal characters, such as double quotes "" before inserting the template in the destination server configuration. For more information on escaping double quotes, see Chapter 9 in the .
{
    "profiles": [
        {% for profile in input.profiles %}
        {
            "ÃÛ¶¹ÊÓƵExperiencePlatformSegments": {
                "add": [
                {% for segment in profile.segmentMembership.ups | added %}
                "{{ segment.key }}"{% if not loop.last %},{% endif %}
                {% endfor %}
                ],
                "remove": [
                {# Alternative syntax for filtering audiences by status: #}
                {% for segment in removedSegments(profile.segmentMembership.ups) %}
                "{{ segment.key }}"{% if not loop.last %},{% endif %}
                {% endfor %}
                ]
            }
        }{% if not loop.last %},{% endif %}
        {% endfor %}
    ]
}

Result

{
    "profiles": [
        {
            "ÃÛ¶¹ÊÓƵExperiencePlatformSegments": {
                "add": [
                    "36a51c13-9dd6-4d2c-8aa3-07d785ea5075",
                    "788d8874-8007-4253-92b7-ee6b6c20c6f3"
                ],
                "remove": [
                    "8f812592-3f06-416b-bd50-e7831848a31a"
                ]
            }
        },
        {
            "ÃÛ¶¹ÊÓƵExperiencePlatformSegments": {
                "add": [
                    "32396e4b-16f6-4033-9702-fc69b5e24e7c",
                    "af854278-894a-4192-a96b-320fbf2623fd",
                    "66505bf9-bc08-4bac-afbc-8b6706650ea4"
                ],
                "remove": [
                ]
            }
        }
    ]
}

Identities identities

For information about identities in Experience Platform, see the Identity namespace overview.

Input

Profile 1:

{
    "identityMap": {
        "email": [
            {
                "id": "johndoe@example.com"
            },
            {
                "id": "jd@example.com"
            }
        ],
        "external_id": [
            {
                "id": "123456"
            }
        ]
    }
}

Profile 2:

{
    "identityMap": {
        "email": [
            {
                "id": "jane.doe@example.com"
            }
        ]
    }
}

Template

IMPORTANT
For all templates that you use, you must escape the illegal characters, such as double quotes "" before inserting the template in the destination server configuration. For more information on escaping double quotes, see Chapter 9 in the .
{
    "profiles": [
        {% for profile in input.profiles %}
        {
            "identities": [
                {% for email in profile.identityMap.email %}
                {
                    "type": "email",
                    "id": "{{ email.id }}"
                }{% if not loop.last %},{% endif %}
                {% endfor %}

                {# Add a comma only if you have both emails and external_ids. #}
                {% if profile.identityMap.email is not empty and profile.identityMap.external_id is not empty %}
                    ,
                {% endif %}

                {% for external in profile.identityMap.external_id %}
                {
                    "type": "external_id",
                    "id": "{{ external.id }}"
                }{% if not loop.last %},{% endif %}
                {% endfor %}
            ]
        }{% if not loop.last %},{% endif %}
        {% endfor %}
    ]
}

Result

{
    "profiles": [
        {
            "identities": [
                {
                    "type": "email",
                    "id": "johndoe@example.com"
                },
                {
                    "type": "email",
                    "id": "jd@example.com"
                },
                {
                    "type": "external_id",
                    "id": "123456"
                }
            ]
        },
        {
            "identities": [
                {
                    "type": "email",
                    "id": "jane.doe@example.com"
                }
            ]
        }
    ]
}

Create a template that sends audiences and identities segments-and-identities

This section provides an example of a commonly used transformation between the ÃÛ¶¹ÊÓƵ XDM schema and partner destination schema.
The example below shows you how to transform the audience membership and identities format and output them to your destination.

Input

Profile 1:

{
    "identityMap": {
        "email": [
            {
                "id": "johndoe@example.com"
            },
            {
                "id": "jd@example.com"
            }
        ],
        "external_id": [
            {
                "id": "123456"
            }
        ]
    },
    "segmentMembership": {
        "ups": {
            "36a51c13-9dd6-4d2c-8aa3-07d785ea5075": {
                "lastQualificationTime": "2019-11-20T13:15:49Z",
                "status": "realized"
            },
            "788d8874-8007-4253-92b7-ee6b6c20c6f3": {
              "lastQualificationTime": "2019-11-20T13:15:49Z",
              "status": "realized"
            },
            "8f812592-3f06-416b-bd50-e7831848a31a": {
                "lastQualificationTime": "2019-11-20T13:15:49Z",
                "status": "exited"
            }
        }
    }
}

Profile 2:

{
    "identityMap": {
        "email": [
            {
                "id": "jane.doe@example.com"
            }
        ]
    },
    "segmentMembership": {
        "ups": {
            "36a51c13-9dd6-4d2c-8aa3-07d785ea5075": {
                "lastQualificationTime": "2021-08-31T10:01:42Z",
                "status": "realized"
            }
        }
    }
}

Template

IMPORTANT
For all templates that you use, you must escape the illegal characters, such as double quotes "" before inserting the template in the destination server configuration. For more information on escaping double quotes, see Chapter 9 in the .
{
    "profiles": [
        {% for profile in input.profiles %}
        {
            "identities": [
                {% for email in profile.identityMap.email %}
                {
                    "type": "email",
                    "id": "{{ email.id }}"
                }{% if not loop.last %},{% endif %}
                {% endfor %}

                {# Add a comma only if you have both emails and external_ids. #}
                {% if profile.identityMap.email is not empty and profile.identityMap.external_id is not empty %}
                    ,
                {% endif %}

                {% for external in profile.identityMap.external_id %}
                {
                    "type": "external_id",
                    "id": "{{ external.id }}"
                }{% if not loop.last %},{% endif %}
                {% endfor %}
            ],
            "ÃÛ¶¹ÊÓƵExperiencePlatformSegments": {
                "add": [
                    {% for segment in profile.segmentMembership.ups | added %}
                    "{{ segment.key }}"{% if not loop.last %},{% endif %}
                    {% endfor %}
                ],
                "remove": [
                    {# Alternative syntax for filtering audiences by status: #}
                    {% for segment in removedSegments(profile.segmentMembership.ups) %}
                    "{{ segment.key }}"{% if not loop.last %},{% endif %}
                    {% endfor %}
                ]
            }
        }{% if not loop.last %},{% endif %}
        {% endfor %}
    ]
}

Result

The json below represents the data exported out of ÃÛ¶¹ÊÓƵ Experience Platform.

{
    "profiles": [
        {
            "identities": [
                {
                    "type": "email",
                    "id": "johndoe@example.com"
                },
                {
                    "type": "email",
                    "id": "jd@example.com"
                },
                {
                    "type": "external_id",
                    "id": "123456"
                }
            ],
            "ÃÛ¶¹ÊÓƵExperiencePlatformSegments": {
                "add": [
                    "36a51c13-9dd6-4d2c-8aa3-07d785ea5075",
                    "788d8874-8007-4253-92b7-ee6b6c20c6f3"
                ],
                "remove": [
                    "8f812592-3f06-416b-bd50-e7831848a31a"
                ]
            }
        },
        {
            "identities": [
                {
                    "type": "email",
                    "id": "jane.doe@example.com"
                }
            ],
            "ÃÛ¶¹ÊÓƵExperiencePlatformSegments": {
                "add": [
                    "36a51c13-9dd6-4d2c-8aa3-07d785ea5075"
                ],
                "remove": []
            }
        }
    ]
}

Create a template that sends segments, identities, and profile attributes segments-identities-attributes

This section provides an example of a commonly used transformation between the ÃÛ¶¹ÊÓƵ XDM schema and partner destination schema.

Another common use case is exporting data that contains audience membership, identities (for example: email address, phone number, advertising ID), and profile attributes. To export data in this manner, see the example below:

Input

Profile 1:

{
    "attributes": {
        "firstName": {
            "value": "Hermione"
        },
        "birthDate": {}
    },
    "identityMap": {
        "email": [
            {
                "id": "johndoe@example.com"
            },
            {
                "id": "jd@example.com"
            }
        ],
        "external_id": [
            {
                "id": "123456"
            }
        ]
    },
    "segmentMembership": {
        "ups": {
            "36a51c13-9dd6-4d2c-8aa3-07d785ea5075": {
                "lastQualificationTime": "2019-11-20T13:15:49Z",
                "status": "realized"
            },
            "788d8874-8007-4253-92b7-ee6b6c20c6f3": {
              "lastQualificationTime": "2019-11-20T13:15:49Z",
              "status": "realized"
            },
            "8f812592-3f06-416b-bd50-e7831848a31a": {
                "lastQualificationTime": "2019-11-20T13:15:49Z",
                "status": "exited"
            }
        }
    }
}

Profile 2:

{
    "attributes": {
        "firstName": {
            "value": "Harry"
        },
        "birthDate": {
            "value": "1980/07/31"
        }
    },
    "identityMap": {
        "email": [
            {
                "id": "harry.p@example.com"
            }
        ]
    },
    "segmentMembership": {
        "ups": {
            "36a51c13-9dd6-4d2c-8aa3-07d785ea5075": {
                "lastQualificationTime": "2019-11-20T13:15:49Z",
                "status": "realized"
            }
        }
    }
}

Template

IMPORTANT
For all templates that you use, you must escape the illegal characters, such as double quotes "" before inserting the template in the destination server configuration. For more information on escaping double quotes, see Chapter 9 in the .
{
    "profiles": [
        {% for profile in input.profiles %}
        {
            "attributes": {
            {% for attribute in profile.attributes %}
                "{{ attribute.key }}":
                    {% if attribute.value is empty %}
                        null
                    {% else %}
                        "{{ attribute.value.value }}"
                    {% endif %}
                {% if not loop.last %},{% endif %}
            {% endfor %}
            },
            "identities": [
                {% for email in profile.identityMap.email %}
                {
                    "type": "email",
                    "id": "{{ email.id }}"
                }{% if not loop.last %},{% endif %}
                {% endfor %}

                {# Add a comma only if we have both emails and external_ids. #}
                {% if profile.identityMap.email is not empty and profile.identityMap.external_id is not empty %}
                    ,
                {% endif %}

                {% for external in profile.identityMap.external_id %}
                {
                    "type": "external_id",
                    "id": "{{ external.id }}"
                }{% if not loop.last %},{% endif %}
                {% endfor %}
            ],
            "ÃÛ¶¹ÊÓƵExperiencePlatformSegments": {
                "add": [
                {% for segment in profile.segmentMembership.ups | added %}
                    "{{ segment.key }}"{% if not loop.last %},{% endif %}
                {% endfor %}
                ],
                "remove": [
                {# Alternative syntax for filtering audiences by status: #}
                {% for segment in removedSegments(profile.segmentMembership.ups) %}
                    "{{ segment.key }}"{% if not loop.last %},{% endif %}
                {% endfor %}
                ]
            }
        }
    ]
}

Result

The json below represents the data exported out of ÃÛ¶¹ÊÓƵ Experience Platform.

{
    "profiles": [
        {
            "attributes": {
                "firstName": "Hermione",
                "birthDate": null
            },
            "identities": [
                {
                    "type": "email",
                    "id": "johndoe@example.com"
                },
                {
                    "type": "email",
                    "id": "jd@example.com"
                },
                {
                    "type": "external_id",
                    "id": "123456"
                }
            ],
            "ÃÛ¶¹ÊÓƵExperiencePlatformSegments": {
                "add": [
                    "36a51c13-9dd6-4d2c-8aa3-07d785ea5075",
                    "788d8874-8007-4253-92b7-ee6b6c20c6f3"
                ],
                "remove": [
                    "8f812592-3f06-416b-bd50-e7831848a31a"
                ]
            }
        },
        {
            "attributes": {
                "firstName": "Harry",
                "birthDate": "1980/07/21"
            },
            "identities": [
                {
                    "type": "email",
                    "id": "harry.p@example.com"
                }
            ],
            "ÃÛ¶¹ÊÓƵExperiencePlatformSegments": {
                "add": [
                    "36a51c13-9dd6-4d2c-8aa3-07d785ea5075"
                ],
                "remove": []
            }
        }
    ]
}

Include aggregation key in your template to access exported profiles grouped by various criteria template-aggregation-key

When you use configurable aggregation in the destination configuration, you can group the profiles exported to your destination based on criteria such as audience ID, audience alias, audience membership, or identity namespaces.

In the message transformation template, you can access the aggregation keys mentioned above, as shown in the examples in the following sections. Use aggregation keys to structure the HTTP message exported out of Experience Platform to match the format and rate limits expected by your destination.

Use audience ID aggregation key in the template aggregation-key-segment-id

If you use configurable aggregation and set includeSegmentId to true, the profiles in the HTTP messages exported to your destination are grouped by audience ID. See below how you can access the audience ID in the template.

Input

Consider the four profiles below, where:

  • the first two are part of the audience with the audience ID 788d8874-8007-4253-92b7-ee6b6c20c6f3
  • the third profile is part of the audience with the audience ID 8f812592-3f06-416b-bd50-e7831848a31a
  • the fourth profile is part of both audiences above.

Profile 1:

{
   "attributes":{
      "firstName":{
         "value":"Hermione"
      }
   },
   "segmentMembership":{
      "ups":{
         "788d8874-8007-4253-92b7-ee6b6c20c6f3":{
            "lastQualificationTime":"2020-11-20T13:15:49Z",
            "status":"realized"
         }
      }
   }
}

Profile 2:

{
   "attributes":{
      "firstName":{
         "value":"Harry"
      }
   },
   "segmentMembership":{
      "ups":{
         "788d8874-8007-4253-92b7-ee6b6c20c6f3":{
            "lastQualificationTime":"2020-11-20T13:15:49Z",
            "status":"realized"
         }
      }
   }
}

Profile 3:

{
   "attributes":{
      "firstName":{
         "value":"Tom"
      }
   },
   "segmentMembership":{
      "ups":{
         "8f812592-3f06-416b-bd50-e7831848a31a":{
            "lastQualificationTime":"2021-02-20T12:00:00Z",
            "status":"realized"
         }
      }
   }
}

Profile 4:

{
   "attributes":{
      "firstName":{
         "value":"Jerry"
      }
   },
   "segmentMembership":{
      "ups":{
         "8f812592-3f06-416b-bd50-e7831848a31a":{
            "lastQualificationTime":"2021-02-20T12:00:00Z",
            "status":"realized"
         },
         "788d8874-8007-4253-92b7-ee6b6c20c6f3":{
            "lastQualificationTime":"2020-11-20T13:15:49Z",
            "status":"realized"
         }
      }
   }
}

Template

IMPORTANT
For all templates that you use, you must escape the illegal characters, such as double quotes "" before inserting the template in the destination server configuration. For more information on escaping double quotes, see Chapter 9 in the .

Notice below how audienceId is used in the template to access audience IDs. This example assumes that you use audienceId for audience membership in your destination taxonomy. You can use any other field name instead, depending on your own taxonomy.

{
    "audienceId": "{{ input.aggregationKey.segmentId }}",
    "profiles": [
        {% for profile in input.profiles %}
        {
            "first_name": "{{ profile.attributes.firstName.value }}"
        }{% if not loop.last %},{% endif %}
        {% endfor %}
    ]
}

Result

When exported to your destination, the profiles are split into two groups, based on their audience ID.

{
   "audienceId":"788d8874-8007-4253-92b7-ee6b6c20c6f3",
   "profiles":[
      {
         "firstName":"Hermione"
      },
      {
         "firstName":"Harry"
      },
      {
         "firstName":"Jerry"
      }
   ]
}

{
   "audienceId":"8f812592-3f06-416b-bd50-e7831848a31a",
   "profiles":[
      {
         "firstName":"Tom"
      },
      {
         "firstName":"Jerry"
      }
   ]
}

Use audience alias aggregation key in the template aggregation-key-segment-alias

If you use configurable aggregation and set includeSegmentId to true, you can also access audience alias in the template.

Add the line below to the template to access the exported profiles grouped by audience alias.

customerList={{input.aggregationKey.segmentAlias}}

Use audience status aggregation key in the template aggregation-key-segment-status

If you use configurable aggregation and set includeSegmentId and includeSegmentStatus to true, you can access the audience status in the template. This way, you can group profiles in the HTTP messages exported to your destination based on whether the profiles should be added or removed from segments.

Possible values are:

  • realized
  • existing
  • exited

Add the line below to the template to add or remove profiles from segments, based on the values above:

action={% if input.aggregationKey.segmentStatus == "exited" %}REMOVE{% else %}ADD{% endif%}

Use identity namespace aggregation key in the template aggregation-key-identity

Below is an example where the configurable aggregation in the destination configuration is set to aggregate exported profiles by identity namespaces, in the form "namespaces": ["email", "phone"] and "namespaces": ["GAID", "IDFA"]. Refer to the groups parameter in the create destination configuration documentation for more details about grouping.

Input

Profile 1:

{
   "identityMap":{
      "email":[
         {
            "id":"e1@example.com"
         },
         {
            "id":"e2@example.com"
         }
      ],
      "phone":[
         {
            "id":"+40744111222"
         }
      ],
      "IDFA":[
         {
            "id":"AEBE52E7-03EE-455A-B3C4-E57283966239"
         }
      ],
      "GAID":[
         {
            "id":"e4fe9bde-caa0-47b6-908d-ffba3fa184f2"
         }
      ]
   }
}

Profile 2:

{
   "identityMap":{
      "email":[
         {
            "id":"e3@example.com"
         }
      ],
      "phone":[
         {
            "id":"+40744333444"
         },
         {
            "id":"+40744555666"
         }
      ],
      "IDFA":[
         {
            "id":"134GHU45-34HH-GHJ7-K0H8-LHN665998NN0"
         }
      ],
      "GAID":[
         {
            "id":"47bh00i9-8jv6-334n-lll8-nb7f24sghg76"
         }
      ]
   }
}

Template

IMPORTANT
For all templates that you use, you must escape the illegal characters, such as double quotes "" before inserting the template in the destination server configuration. For more information on escaping double quotes, see Chapter 9 in the .

Notice that input.aggregationKey.identityNamespaces is used in the template below

{
            "profiles": [
            {% for profile in input.profiles %}
            {
                {% for ns in input.aggregationKey.identityNamespaces %}
                "{{ns}}": [
                    {% for id in profile.identityMap[ns] %}
                    "{{id.id}}"{% if not loop.last %},{% endif %}
                    {% endfor %}
                ]{% if not loop.last %},{% endif %}
                {% endfor %}
            }{% if not loop.last %},{% endif %}
            {% endfor %}
        ]
}

Result

When exported to your destination, the profiles are split into two groups, based on their identity namespaces. Email and phone are in one group, while GAID and IDFA are in another.

{
   "profiles":[
      {
         "email":[
            "e1@example.com",
            "e2@example.com"
         ],
         "phone":[
            "+40744111222"
         ]
      },
      {
         "email":[
            "e3@example.com"
         ],
         "phone":[
            "+40744333444",
            "+40744555666"
         ]
      }
   ]
}

{
   "profiles":[
      {
         "IDFA":[
            "AEBE52E7-03EE-455A-B3C4-E57283966239"
         ],
         "GAID":[
            "e4fe9bde-caa0-47b6-908d-ffba3fa184f2"
         ]
      },
      {
         "IDFA":[
            "134GHU45-34HH-GHJ7-K0H8-LHN665998NN0"
         ],
         "GAID":[
            "47bh00i9-8jv6-334n-lll8-nb7f24sghg76"
         ]
      }
   ]
}

Use the aggregation key in a URL template aggregation-key-url-template

Depending on your use case, you can also use the aggregation keys described here in a URL, as shown below:

https://api.example.com/audience/{{input.aggregationKey.segmentId}}

Reference: Context and functions used in the transformation templates reference

The context provided to the template contains input (the profiles / data that is exported in this call) and destination (data about the destination that ÃÛ¶¹ÊÓƵ is sending data to, valid for all profiles).

The table below provides descriptions for the functions in the examples above.

Function
Description
Example
input.profile
The profile, represented as a . Follows the partner XDM schema mentioned further above on this page.
hasSegments
This function takes a map of namespace audience IDs as parameter. The function returns true if there is at least one audience in the map (regardless of its status), and false otherwise. You can use this function to decide whether to iterate over a map of audiences or not.
hasSegments(input.profile.segmentMembership)
destination.namespaceSegmentAliases
Map from audience IDs in a specific ÃÛ¶¹ÊÓƵ Experience Platform namespace to audience aliases in the partner’s system.
destination.namespaceSegmentAliases["ups"]["seg-id-1"]
destination.namespaceSegmentNames
Map from audience names in specific ÃÛ¶¹ÊÓƵ Experience Platform namespaces to audience names in the partner’s system.
destination.namespaceSegmentNames["ups"]["seg-name-1"]
destination.namespaceSegmentTimestamps
Returns the time when a audience was created, updated, or activated, in UNIX timestamp format.
  • destination.namespaceSegmentTimestamps["ups"]["seg-id-1"].createdAt: returns the time when the segment with the ID seg-id-1, from the ups namespace, was created, in UNIX timestamp format.
  • destination.namespaceSegmentTimestamps["ups"]["seg-id-1"].updatedAt: returns the time when the audience with the ID seg-id-1, from the ups namespace, was updated, in UNIX timestamp format.
  • destination.namespaceSegmentTimestamps["ups"]["seg-id-1"].mappingCreatedAt: returns the time when the audience with the ID seg-id-1, from the ups namespace, was activated to the destination, in UNIX timestamp format.
  • destination.namespaceSegmentTimestamps["ups"]["seg-id-1"].mappingUpdatedAt: returns the time when the audience activation was updated on the destination, in UNIX timestamp format.
addedSegments(mapOfNamespacedSegmentIds)
Returns only the audiences that have status realized, across all namespaces.
addedSegments(input.profile.segmentMembership)
removedSegments(mapOfNamespacedSegmentIds)
Returns only the audiences that have status exited, across all namespaces.
removedSegments(input.profile.segmentMembership)
destination.segmentAliases
Deprecated. Replaced by destination.namespaceSegmentAliases

Map from audience IDs in the ÃÛ¶¹ÊÓƵ Experience Platform namespace to audience aliases in the partner’s system.
destination.segmentAliases["seg-id-1"]
destination.segmentNames
Deprecated. Replaced by destination.namespaceSegmentNames

Map from audience names in the ÃÛ¶¹ÊÓƵ Experience Platform namespace to audience names in the partner’s system.
destination.segmentNames["seg-name-1"]
destination.segmentTimestamps
Deprecated. Replaced by destination.namespaceSegmentTimestamps

Returns the time when a audience was created, updated, or activated, in UNIX timestamp format.
  • destination.segmentTimestamps["seg-id-1"].createdAt: returns the time when the audience with the ID seg-id-1 was created, in UNIX timestamp format.
  • destination.segmentTimestamps["seg-id-1"].updatedAt: returns the time when the audience with the ID seg-id-1 was updated, in UNIX timestamp format.
  • destination.segmentTimestamps["seg-id-1"].mappingCreatedAt: returns the time when the audience with the ID seg-id-1 was activated to the destination, in UNIX timestamp format.
  • destination.segmentTimestamps["seg-id-1"].mappingUpdatedAt: returns the time when the audience activation was updated on the destination, in UNIX timestamp format.

Next steps next-steps

After reading this document, you now know how data exported out of Experience Platform is transformed. Next, read the following pages to complete your knowledge about creating message transformation templates for your destination:

To learn more about the other destination server components, see the following articles:

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6