Use Related Data in a Message

Overview

This guide provides instructions on inserting data stored in a Related Data Set into a message. This functionality is useful for personalizing messages based on stored datasets.

Prerequisites

Before inserting related data into a message, ensure the following:

1. Create a Related Data Set: The dataset must be created beforehand. See Create Related Data Set.

2. Set Up Data Columns: The dataset must have columns set up. See Managing Related Data Sets.

3. Import Data: The data must be imported into the related data set. See Import Data Into Related Data Set.

Note:

The name of the related data set is case-sensitive.

Inserting Data Using Placeholders

Use placeholders to include related data in a message. When the message is sent, these placeholders are replaced with actual data from the dataset.

Placeholder Syntax

• Placeholders use the symbols <% %>.

• The structure depends on whether the related data set is linked to an attribute and whether it is unique or non-unique.

Types of Data Insertion

1. Data from a Linked, Unique Related Data Set

Use the following syntax:

<%${user.relatedAttribute['dataset']['column']}%>

Components:

• user.relatedAttribute: Indicates a linked related data set.

• dataset: The name of the related data set.

• column: The specific column containing the data.

2. Data from an Unlinked, Unique Related Data Set

Use the ecx:related function when the data set is not linked to an attribute:

<%${ecx:related('dataset', 'key')['column']}%>

Components:

• dataset: The name of the related data set.

• key: The key to identify the data set.

• column: The column containing the desired data.

Example: Product Catalog

Using a Defined Key

<%${ecx:related('ProductCatalog', '1234')['Description']}%>

Using a Dynamic Key Based on a Recipient's Attribute

<%${ecx:related('ProductCatalog', user.CustomAttribute['Purchase'])['Description']}%>

Handling Non-Unique Data Sets

For non-unique related data sets (where multiple entries exist), use a ForEach loop.

Syntax for Non-Unique Data Sets

<%ForEach var="count" items="${user.relatedAttribute['dataset']}" max="5"%>
    <%${count['column']}%>
<%/ForEach%>

Components:

• ForEach var="count" items="${user.relatedAttribute['dataset']}" max="5"%>: Loops through the dataset with a maximum of 5 entries.

• count['column']: Retrieves and inserts data from the column.

Example: Displaying Purchase Data

<table>
    <tbody>
        <%ForEach var="count" items="${user.relatedAttribute['Purchase']}" max="3"%>
            <tr>
                <td><%${count['Date']}%></td>
                <td><%${count['Price']}%></td>
            </tr>
        <%/ForEach%>
    </tbody>
</table>

Sorting and Filtering Data

Data from a ForEach loop is displayed in random order by default. Use functions like ecx:sort to sort or filter the displayed data.

Using Related Data in a CMS Context

When using Related Data within a CMS, data insertion follows predefined rules specific to the CMS template. Data columns accessible in CMS paragraphs are preset during CMS onboarding.

Steps for Inserting Data in CMS

1. Identify the Key: Enter the pre-agreed key in the placeholder.

2. Use CMS-Specific Placeholders: No manual placeholders are needed.

3. Configuration: The data retrieval method is template-specific and predefined within the CMS.