Using Loop Personalizations

If you want to send e-mails for order confirmations or abandoned carts reminders, you will probably need to display several items. This is where loop personalizations come handy!

Loops are indeed very useful when you need to personalize with several lines of data.

Instead of replacing a personalization variable by a single value, it is possible to display:

• A set of related values (for example, the article name and the corresponding amount).
• Several of these sets one after the others (for example, the last 3 purchases, each of those being characterized by the article name and the amount).

tip

Loops are available both in marketing and transactional e-mails.

Format of the e-mail

The way to insert a loop depends on whether you are creating your e-mail with the template editor or by importing an HTML.

Loops in the template editor

Loop personalizations can be used in a template by using specific loop blocks.

These compatible blocks are identified by the "loop" icon when you select them, next to the condition icons.

There are 2 ways to insert them:

• From a custom design template: if you have ordered a custom template designed by the Actito team, you may have requested a loop block directly in the template.
• From the module library: in all other templates, you can use the library of modules, where a selection of loop blocks are available with different designs (with images, CTAs,...)

The blocks from the module library come with a pre-defined loop called "item".

By clicking on the loop icon in the block, you can declare another name for your loop.

The name of the loop is important, because each element of the loop needs to follow the format: ${loop name.element name}.

For instance, in the screenshot above, the loop is named "item" and ${item.title} and ${item.description} are elements of the loops, where "title" and "description" are variables that will be personalized each time the loop is repeated.

Some personalizations are already defined in each block but you can update them or add extra elements, by following the ${loop name.element name} format. For instance: ${item.price}, ${item.quantity},...

You can change the layout and apply styles to the elements of your loop as you see fit.

info

If you provide personalization values by API (see last section), you will need to refer to the technical name of the loop in your call, which is: the name declared in the loop block + S.

For instance, in the loop above named "item", the technical name called in the API would be "items".

Loops in HTML imports

Loop personalizations can also be used in your imported HTML files by inserting the code snippet made for this purpose.

You will need to use the parameter "data-Actito-each" and to define it as "loop name: ${loop name in plural}". For instance, **data-Actito-each ="example:${examples}"**

Each element of the loop needs to follow the format: ${loop name.element name}. For instance: **${example.element}**

Let's take a practical example:

We want to display a loop containing the last purchases made by contacted profiles and, for each one, to display the article name and its price.
You would need to insert the following piece of code:

data-actito-each

<div data-Actito-each="item:${items}">
  <span> Article: ${item.article} </span>
  <span> Price: ${item.price} </span>
</div>

tip

"Loop name in plural" is simply a suggestion when declaring the second element of the "data-Actito-each" parameter. You can declare another technical name of your choice, as long as it's different from the first element.

For instance: data-Actito-each ="purchase:${example}".

However, please keep it in mind if the personalization values are pushed by API, as the name declared in the ${ } part (here "example") will be used to refer to the loop in the API call.

Personalization parameters

After setting up your loop in a specific block or in the HTML, you have to parameter all the variables used in the loop personalization.

To do so, go to the personalization management modal window.

To reach the loops, you first of all need to activate the "Expert mode" at the top right of the screen. A new section called "Loop personalization" will appear.

The value for each element of the loop can be provided by two types of sources:

• From tables of the Data Model (Custom tables): you will need to select the relevant table beforehand in the "Data Source" section.
• Via API : please see the end of this chapter for additional information on how to use loops via API.

tip

If the "Loop personalizations" section appears in the interface but does not display anything when you expand it by clicking on the small arrow, it means that the system acknowledged your attempt to set up a loop, but your HTML is incorrect. Check your code, the name of the loop and of the variables.

Loop values from the Custom Tables

Value definition

After selecting the source, you can define the values taken by the variables on the loop, in the "Loop personalizations" section.

Select the data source chosen during the preliminary step and assign it to the name of the loop. Each loop can only use one data source.

Next, link the various elements of the loop to the fields of the source table.

info

If the name of a loop variable is identical to the technical name of an attribute of a custom table, mapping will be made automatically when you select the custom table source in the 'Loop personalizations' section.

Defining the number of displayed elements

In addition to letting you display a set of values, loops also enable you to display several of these sets one after the others.

You need to specify the number of elements that you want to display. Without additional parameters, the loop will call every entry of the data source.

To do so, you need to go to the Data Source parameters, by clicking on the cog icon to the right of the data source line.

You will be able to display:

• The maximum number of displayed elements
• What will be the sorting order of the elements and on the basis of which attribute of the source table.

It is also possible to add a filter to the source. In doing so, the only elements of the source taken into account are those which match the criteria you defined based on attributes of the table and aggregates calculated on them.

tip

You can also choose the data Provided by the scenario: this option should be used for your scenarized sendings when the start block of the scenario is related to the value of the personalization (For example, if the scenario is triggered by a ticket creation). This will ensure that the information which triggered the scenario and the information used in the personalization are the same.
This option is only available for scenarized sendings (including transactional).

Next, save your parameters in the top right corner.
A green 'V' on the cog icon will confirm that the source has been parametered.

Data formatting

Data formatting and transformation functions can be applied to loop values when the source is a custom table, including:

• Defining de default value
• Defining a mapping
• Formatting the date (for dates and timestamp attributes)
• Formatting the number (for real number attributes)

More information about formatting functions are available here

info

Loops cannot be used with multi-values attributes.

Loops triggered by API

In addition to Custom Tables, personalizations values be provided by API when the e-mail is triggered by a system external to Actito.

To use APIs as data sources, you need to assign the option "Provided by API" to your loop personalization in the personalization management modal window. No further mapping is required in the interface, as it will be made in the API call.

During the last step, make sure to click on "Activate sending", to make the campaign available to trigger by API.

Testing 'provided by API' variables

As the final e-mail will the triggered by an API call, it might be relevant to carry out tests together with one of your developers.

Nevertheless, Actito gives you the possibility to test your e-mail directly in the interface, without involving technical resources.

If you use a personalization 'provided by API', an additional button will indeed be automatically displayed at the 'Check and test' step.

It lets you simulate test values for your personalizations, so that your test e-mails really use data to validate their final rendering.

These data are stored in the cache of your browser. They therefore do not appear if another user edits the campaign, or if you change session.

Triggering an e-mail via API

To trigger an e-mail and push loop personalization values by API, the call you can use depends on the type of the e-mail:

• For standard scenarized e-mails (such as abandoned carts reminders), use the call POST /entity/{e}/mail/{m}/profile/{p}
• For transactional e-mails (such as order confirmations), use the call POST /entity/{e}/transactionalmail/{m}/contact

You will need to provide the following parameters:

• The entity on which the campaign is stored
• The id of the campaign (auto-generated Id or technical name)
• The id of the targeted profile:
  • in the path of the call for standard scenarized e-mails
  • in the body of the call for transactional e-mails, because the profile can be created/updated at the same time in this case
• Variables:
  • For standard scenarized emails, the body of the call is just an array containing the personalizations values.
  • For transactional e-mails, the body of the call contains both a "profile" section, where you can push the values to create/update the profile, and a "parameters" array containing the personalizations values.

The array containing the values of the variables of your e-mail must be made of:

• "key": You always need to specify "externalData" to trigger a loop via API
• "structuredValue": The "structuredValue" parameter is mandatory for using a loop, unlike standard personalization where simple "values" are pushed. The "structuredValue" is an object containing the 'technical name' of the loop. This 'technical name' depends on how you declared the loop in your e-mail:
  • If you inserted it in your HTML code, it is the second element in the declaration of the loop: the value between curly brackets. It is "items" in the following snippet: data-actito-each="item:${items}".
  • If you inserted your loop in a block of a template, it the name of the loop as defined in the editor, with an S suffix. With this loop, named "item" in the editor, the value used in the API would be "items".

You can then define an array of objects containing the elements of the loop as pairs of "elementName": "value".

The loop will be repeated for each object pushed in the array, with the relevant set of values.

Example of JSON

[
  {
    "key": "externalData",
    "structuredValue": {
      "items": [
        {
          "article": "Screwdriver",
          "price": "25"
        },
        {
          "article": "Hammer",
          "price": "32"
        }
      ]
    }
  }
]

tip

Simple personalizations (not part of a loop) are pushed through "key" - "values" pairs, where "key" is the name of the variable as defined in the e-mail.

See the request sample of the Trigger a transactional e-mail call for a great example of how to push both simple personalizations and loops in the same calls (+ the attribute to create/update the profile in case of a transactional sending).