Create and test a message transformation template create-template

Overview overview

As part of Destination SDK, Adobe provides developer tools to assist you in configuring and testing your destination. This page describes how to create and test a message transformation template. For information on how to test your destination, read Test your destination configuration.

To create and test a message transformation template between the target schema in Adobe Experience Platform and the message format supported by your destination, use the Template authoring tool described further below. Read more about the data transformation between source and target schema in the message format document.

Illustrated below is how creating and testing a message transformation template fits into the destination configuration workflow in Destination SDK:

Why you need to create and test a message transformation template why-create-message-transformation-template

One of the first steps in creating your destination in Destination SDK is to think about how the data format for audience membership, identities, and profile attributes is transformed when exported from Adobe Experience Platform to your destination. Find information about the transformation between Adobe XDM schema and your destination schema in the message format document.

For the transformation to succeed, you must provide a transformation template, similar to this example: Create a template that sends segments, identities, and profile attributes.

Adobe provides a template tool that allows you to create and test the message template that transforms data from the Adobe XDM format into the format supported by your destination. The tool has two API endpoints that you can use:

Steps to complete before creating the template prerequisites

Before you are ready to create the template, make sure you complete the steps below:

How to use the sample template API and render template API to create a template for your destination iterative-process

The process to get and test the template is iterative. Repeat the steps below until the exported profiles match your destination’s expected data format.

Get a sample template using the sample template API sample-template-api

Add a destination ID to the call, as shown below, and the response will return a template example corresponding to the destination ID.

curl --location --request GET 'https://platform.adobe.io/data/core/activation/authoring/testing/template/sample/5114d758-ce71-43ba-b53e-e2a91d67b67f' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: {API_KEY}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \

If the destination ID you provide corresponds to a destination configuration with best effort aggregation and maxUsersPerRequest=1 in the aggregation policy, the request returns a sample template similar to this one:

{#- THIS is an example template for a single profile -#}
{#- A '-' at the beginning or end of a tag removes all whitespace on that side of the tag. -#}
{
    "identities": [
    {%- for idMapEntry in input.profile.identityMap -%}
    {%- set namespace = idMapEntry.key -%}
        {%- for identity in idMapEntry.value %}
        {
            "type": "{{ namespace }}",
            "id": "{{ identity.id }}"
        }{%- if not loop.last -%},{%- endif -%}
        {%- endfor -%}{%- if not loop.last -%},{%- endif -%}
    {% endfor %}
    ],
    "AdobeExperiencePlatformSegments": {
        "add": [
        {%- for segment in input.profile.segmentMembership.ups | added %}
            "{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
        {% endfor %}
        ],
        "remove": [
        {#- Alternative syntax for filtering audiences by status: -#}
        {% for segment in removedSegments(input.profile.segmentMembership.ups) %}
            "{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
        {% endfor %}
        ]
    }
}

If the destination ID you provide corresponds to a destination server template with configurable aggregation or best effort aggregation with maxUsersPerRequest greater than one, the request returns a sample template similar to this one:

{#- THIS is an example template for multiple profiles -#}
{#- A '-' at the beginning or end of a tag removes all whitespace on that side of the tag. -#}
{
    "profiles": [
    {%- for profile in input.profiles %}
        {
            "identities": [
            {%- for idMapEntry in profile.identityMap -%}
            {%- set namespace = idMapEntry.key -%}
                {%- for identity in idMapEntry.value %}
                {
                    "type": "{{ namespace }}",
                    "id": "{{ identity.id }}"
                }{%- if not loop.last -%},{%- endif -%}
                {%- endfor -%}{%- if not loop.last -%},{%- endif -%}
            {% endfor %}
            ],
            "AdobeExperiencePlatformSegments": {
                "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 %}
    ]
}

Character-escape your template character-escape-template

Before using the template to render profiles that match your destination’s expected format, you must character-escape the template, as shown in the screen recording below.

You can use an online character escaping tool. The demo above uses the JSON Escape formatter.

Render template API render-template-api

After creating a message transformation template using the sample template API, you can render the template to generate exported data based on it. This allows you to verify if the profiles that Adobe Experience Platform would export to your destination match your destination’s expected format.

Refer to the API reference for examples of calls that you can make:

Edit the template and make calls to the render template API endpoint until the exported profiles match your destination’s expected data format.

Add your character-escaped template to the destination server configuration

Once you are satisfied with your message transformation template, add it to your destination server configuration, in httpTemplate.requestBody.value.