Inserting Data From a Related Data Set Into a Message

Prerequisites​

Before you can insert data from a related data set into a message, ensure the following steps have been completed:

1. Create a Related Data Set: A related data set must be created. See Create Related Data Set.

2. Set Up Data Columns: Data columns must be established in the related data set. See Import Data: Create Columns of Related Data Sets During Import.

3. Import Data: Data must be imported into the related data set. For more information, see Related Data: Import Data.

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

Inserting Data Using a Placeholder​

Use a placeholder to include data from a related data set in a message. When the message is sent, this placeholder is replaced by the actual data from the related data set.

• Placeholder Syntax: Placeholders are defined by the symbols <% %>.

• Placeholder Structure: The structure of the placeholder depends on whether the related data set is linked to an attribute and whether the data set is unique or non-unique.

Placeholder Structure Details

1. Linked vs. Unlinked Related Data Set:

   • Linked to an Attribute: The placeholder contains a related attribute.

   • Not Linked to an Attribute: The placeholder uses the function ecx:related.

2. Unique vs. Non-Unique Data Set:

   • Unique Data Set: A single entry in the data set corresponds to each recipient.

   • Non-Unique Data Set: Multiple entries can exist, requiring a ForEach loop.

Types of Data Insertion

1. Data from a Linked, Unique Related Data Set

Use the following syntax for inserting data from a related data set linked to an attribute:

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

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

• dataset: The name of the related data set.

• column: The specific column from which data is taken.

2. Data from an Unlinked, Unique Related Data Set

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

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

• dataset: The name of the related data set.

• key: The specific key to identify the data set.

• column: The column containing the desired data.

Example: Product Catalog

For a product catalog, if you want to insert the description of a product with a defined key (e.g., 1234), use:

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

For a dynamic key based on a recipient's attribute:

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

Handling Non-Unique Data Sets

When dealing with non-unique data sets (where multiple entries can exist with the same key), use a ForEach loop to insert multiple entries:

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

• max="5": Limits the number of entries to be inserted.

• count['column']: Specifies the data to be displayed from each entry.

Example: Displaying Purchase Data

If you want to create a newsletter displaying a customer’s last three purchases, you can use the following code:

<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. To sort or filter the displayed data, use functions like ecx:sort or filtering functions.

Related Data and the CMS​

Using Related Data in a CMS Context

When using Related Data within a CMS, data insertion is handled through pre-defined data retrieval operations tailored to each CMS template. The data columns accessed by various paragraphs in the CMS are preset by your account manager, specific to your CMS template.

Steps for Inserting Data:

1. Identify the Key: You only need to enter the agreed-upon key in the appropriate placeholder.

2. No Manual Placeholders Needed: Manually-created placeholders are not required in this context.

If you are unsure how Related Data is used in your Mapp Engage system, contact your account manager. The method for inserting related data into a CMS message is template-specific and requires detailed configuration for each system.

Selecting and Importing Data from a Unique Related Data Set​

To insert data into a message, use placeholders defined by the tags <% %>. These placeholders are replaced with actual data values when the message is sent.

• For Linked Related Data Set (Unique):

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

  • Components:

    • user.relatedAttribute: Indicates the data set is linked to an attribute.

    • dataset: The name of the related data set.

    • column: The specific column from which data is retrieved.

• For Unlinked Related Data Set (Unique):

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

  • Components:

    • ecx:related: Function to access data from the related data set.

    • dataset: The name of the related data set.

    • key: The key to identify the data set entry.

    • column: The column containing the data to be inserted.

Examples of Using Keys in an Unlinked Related Data Set​

1. Using a Defined Value:

   • Scenario: Insert the description of a product with product number 1234.

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

2. Using an Attribute as the Key:

   • Scenario: Show the product description based on the recipient's last purchase.

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

3. Using a Key from Another Related Data Set:

   • Scenario: Insert offers from the Paris shop.

   • Placeholder: <%${ecx:related('ProductCatalog', ecx:related('Shop', 'Paris')['Product'])['Description']}%>

4. Using an Attribute from Another Related Data Set:

   • Scenario: Select the current offer from the shop most relevant to each recipient.

   • Placeholder: <%${ecx:related('ProductCatalog', ecx:related('CurrentOfferPerShop', user.CustomAttribute['PreferredShop'])['Product'])['Description']}%>

Importing Data from a Non-Unique Related Data Set

For non-unique data sets, where multiple entries can have the same key, use a ForEach loop to insert multiple data sets.

Syntax for Non-Unique Related Data Sets

Data from a linked, non-unique related data set can be inserted in a message by using user.relatedAttribute. As more than one data set is saved in the related data set, use a ​ForEach​-loop as follows:

1. Linked Related Data Set:

   • Placeholder:

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

   • Components:

     • <%ForEach%> </%ForEach%>: Define the loop's start and end.

     • var="count": Variable used for output.

     • items="{ }": Specifies the related data set.

     • max="5": Limits the number of data sets to be selected.

2. Unlinked Related Data Set:

   • Placeholder:

     <%ForEach var="count" items="${ecx:related('dataset', 'key')}" max="5"%>
         <%${count['column']}%>
     <%/ForEach%>

   • Components:

     • Similar structure as linked data sets but uses ecx:related for data retrieval.

Adding the ForEach loop directly to a link

The ForEach loop cannot be added directly to a link. The following syntax is NOT correct and produces an error:

<a href="http://www.domain.com/test?email=<%ForEach var="count" items="$ {user.relatedAttribute['example']}" max="1"%><%$ {count['column1']}%><%/ForEach%>">LINK<a>

The correct syntax for this example is:

<%ForEach var="count" items="${user.RelatedAttribute['example']}" max="1"%> <a href="">linkhttp://www.domain.com?column1=<%${count['column1']}%>">link</a> <%/ForEach%>

Example: Displaying Purchase Data

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

Sorting and Filtering Data

Data retrieved with a ForEach loop is displayed in random order. Use functions like ecx:sort to sort the data as needed.