Field mapping allows you to control and customize the data sent from Fresh Relevance to your messaging provider. By configuring field mappings, you can ensure that the correct information is transferred, enabling more personalized and effective email campaigns.
This guide aims to help you set up field mappings for different tasks, including:
Send Triggered emails
Add To List triggers
Expand the User menu and go to Settings > Triggers and Messaging integrations > Messaging Provider(s) and then select Field Mapping for the relevant provider.
Load analytics records
Expand the User menu and go to Settings > Exports > Analytics Field Mappings.
Export Firehose records
Expand the User menu and go to Settings > Exports > Firehose > Configure Firehose > Configure Field Mappings.
Build a segment
Expand the User menu and go to Settings > All settings > Exports > Segment Export Field Mapping.
Fresh Relevance fields
Fresh Relevance fields capture and store various types of data about your visitors. Mapping these fields ensures that your messaging provider receives accurate and comprehensive data for personalized marketing efforts.
Fieldname | Description |
fn | First name |
ln | Last name |
sbr | Site Brand |
curr | Currency used by this visitor ("currency" for triggered messages) |
Email Address | |
mobile | Mobile number, in E.164 format |
extend | Dictionary of custom data collected by the data collection script. Only fields specified in Settings > Allowed Fields are passed to the server. Learn more in HTML API for examples of data that comes after "extend:". |
query_data | Values captured from the query collection, to configure this, expand the User menu and go to Settings > Website Settings > Query Collection Fields. Normally used for Analytics codes, for example, utm_campaign, but can be used to capture other data too. Learn more in Integration API. |
Fresh Relevance triggered messages fields
Fresh Relevance triggered messages fields are specifically designed to capture data related to triggered email events, such as cart abandonment or product recommendations.
Fieldname | Description |
n | Full name. Most messaging providers support either Full name, or First name and Last name, but not both. |
cp | Cart price: the total price of all the items in the cart. Includes the currency symbol (except for Shopify and some custom carts). This will be in the base currency configured for the client account. |
cart_html | A single block of HTML for the cart contents, also called the cart layout. To configure what is included in this, go to Content > Cart Layout. |
cart_url | A link back to the cart page seen by this visitor. Use as an alternative to the URL of the product, for creating links where you want the visitor to return. |
tms_person_id | The internal unique ID assigned to the person record in the database. |
tms_product_url tms_product_url[0] | The URL of the product on the web store. Where you want the visitor to return when they click. So create links using this URL around everything related to the product, for example, the product image. Optional zero-based index for the 'nth' product in the cart. |
tms_product_name tms_product_name[0] | The name of the product. Optional zero-based index for the 'nth' product in the cart. |
tms_product_img tms_product_img[0] | The URL of the product image on the web store. This is commonly used as the image to be inserted into an email. Optional zero-based index for the 'nth' product in the cart. |
tms_product_id tms_product_id[0] | The ID of the product on the web-store, often a SKU (stock-keeping unit). Optional zero-based index for the 'nth' product in the cart. |
tms_product_up tms_product_up[0] | The unit price of the product. Includes the currency symbol (except for Shopify and some custom carts). This is in the base currency configured for the client account. Optional zero-based index for the 'nth' product in the cart. |
tms_product_qty tms_product_qty[0] | The quantity of the product. |
tms_product_cat tms_product_cat[0] tms_product_cat[0].id tms_product_cat[0].id|csv | The tag values (categories) of the product. The brackets denote the product index in the current cart. By default the category name is used, by you can use the category ID, tag, or group ID by appending .id, .groupname, or .gid after the product index. The output defaults to being a list usable in Jinja, with the option of appending |csv to the end to get a comma separated (CSV) value in plain text instead. |
product_extra product_extra[0] | Dictionary of data which extends the products within a cart. Fields for the first product may be mapped using the syntax product_extra:fieldname. Optional zero-based index for the 'nth' product in the cart. |
product_option product_option[0] | Product options, for example, size or color. Optional zero-based index for the 'nth' product in the cart. |
cart_extra cart_extra[0] | Dictionary of data that extends the data for a cart. For example: cart_extra:delivery, cart_extra:cp_exc_vat, cart_extra:cp_inc_vat, cart_extra:vat |
cart_id | Automatically generated cart ID - a new ID is created for every visitor session. Useful for sending to external analytics systems using the firehose. |
category:current[0] category:current[0].id category:current[0].name | Categories of products in the current cart; either IDs or names. This is different from tms_product_cat in that it represents the categories for the whole cart (or alternative context), not a single product. |
category:current:id|csv | CSV list of all the tag values (categories) of products in the current cart. |
category:browsed[0] category:abandoned[0].id category:purchased[0].id | Categories of products which were browsed, abandoned, or purchased by this person; either IDs or names. |
feed:[feed name] | Maps a personalized feed to a block of HTML in a field in the messaging provider. |
analytics:[field name] | Maps a calculated analytics value to the messaging provider. The field name takes the form: [analytic type]_[analytic statistic]_ [number of days] For example, the quantity of products browsed in the last 7 days would be: browsed_qty_7 To add these:
|
categoryGroupValue:name_number[number] | This uses Advanced Customer Tagging. For example, categoryGroupValue:shoetype_7[0] could be the top favorite type of shoe for each person, within the last 7 days. The name comprises: categoryGroupValue prefix, colon, tag name, underscore, analytic days, open square bracket, number for how big a favorite it is (0 is top favorite, 1 is next, and so on), close square bracket. Check carefully that these numbers are what you want. To edit them:
|
{{ extra.field_name }} | Extra field data, which may be present in a Custom Signal where field_name is the dynamic name of the field captured. |
Firehose fields
Firehose fields capture and export detailed data streams from Fresh Relevance to external systems.
Fieldname | Description |
tms_type | Signal type, for example, Product Browsed (pb). |
unique_id | Unique ID for each output row. |
signal_id | ID for each signal (may cover multiple rows). |
{{ signal.custom_ns }} | Trigger namespace for custom signals. |
{{ signal.fdt }} | Session - first activity date/time. |
{{ signal.edt }} | Session - expiry date/time. |
{{ signal.ldt }} | Session - last activity date/time. |
{{ signal.first_url }} | Session - first URL. |
{{ signal.last_url }} | Session - last URL. |
{{ signal.len_secs }} | Session length, between first date and last activity date, in seconds. |
{{ signals.pd | length }} | Number of product details signals. |
{{ signals.t | length }} | Number of purchase complete signals. |
{{ signals.cu | length }} | Number of custom signals. |
{{ signals.b | length }} | Number of cart abandon signals. |
{{ signals.ba | length }} | Number of browse abandon signals. |
{{ signals.c | length }} | Number of cart signals. |
{{ signals.cc | length }} | Number of cart changed signals. |
Jinja2 Filters
The field mapping page allows control of how data is formatted when it is sent to your messaging provider. This is done using Jinja2 filters. Not all of the above field names can be used within the Jinja2 filters.
The filters in the table below can be used:
Filter | Description |
{{ person.fn | title}} | Person first name, in title case. |
{{ person.n | title}} | Person name, in title case. |
{{ products[0].n | title}} | First product name, in title case |
{{ cart.cp | format_currency('£',2)}} | Cart price, forced to display as a currency with 2 decimal places. |
{{ cart.dt | convert_utc_to_timezone("Europe/Paris") }} | The date/time of the cart in the specified time zone. |
{{ trigger.contact_type }} | b for cart abandonment, ba for browse abandonment. |
When using Jinja in a Segment field mapping, only the person fields are available. Other fields, such as products, cart, and trigger, won’t work and should not be used.