---
title: "Use Related Data in a Message"
slug: "use-related-data-in-a-message"
updated: 2025-02-06T14:39:48Z
published: 2025-02-06T14:39:48Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.mapp.com/v1/docs/create-related-data-set).
2. **Set Up Data Columns**: The dataset must have columns set up. See [Managing Related Data Sets](/v1/docs/managing-related-data-sets).
3. **Import Data**: The data must be imported into the related data set. See [Import Data Into Related Data Set](https://docs.mapp.com/v1/docs/import-data-into-related-data-set).

> [!NOTE]
> **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:

```plaintext
<%${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:

```plaintext
<%${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

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

#### Using a Dynamic Key Based on a Recipient's Attribute

```plaintext
<%${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

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

**Components:**

- `ForEach var="count" items="${user.relatedAttribute['dataset']}" max="5"%&gt;`: Loops through the dataset with a maximum of 5 entries.
- `count['column']`: Retrieves and inserts data from the column.

### Example: Displaying Purchase Data

```xml
<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.

## Related

- [Personalization with Related Data](/personalization-with-related-data.md)