Advanced Dynamic Content Cheatsheet
This section details the variables used for advanced dynamic messages.
| Variable | Type | Description |
|---|---|---|
${user.id} | String | User ID |
${user.userName} | String | Name |
${user.userNameOrAnonLocation} | String | Name or "user from City, State" |
${user.accountType} | String | Account type |
${user.emailAddress} | String | Email address |
| Variable | Type | Description |
|---|---|---|
${user.location.postalCode} | String | ZIP code |
${user.location.city} | String | City |
${user.location.metro} | String | Metro area |
${user.location.metroCode} | Integer | Metro code |
${user.location.region} | String | State/region |
${user.location.stateProvinceCode} | String | State/region code (shorthand) |
${user.location.country} | String | Country |
${user.location.countryCode} | String | Country code (shorthand) |
${user.location.organization} | String | Organization |
${user.location.industry} | String | Industry |
${user.location.naicsCode} | Integer | North American Industry Classification System code |
| Variable | Description |
|---|---|
${user.attributes._________} | Custom Attribute (Use dropdown in editor for specific ID) |
Things that count as items:
- Products
- Articles
- Blogs
- Catalog Objects
- Categories
Must have intended item query selected in message settings
| Variable | Type | Description |
|---|---|---|
${item} | Object | Item object |
${items} | Array | Array of item objects |
${items[0]}...${items[9]} | Object | Item in array |
${page.item} | Object | Current page item object |
${page.category} | Object | Current page category or category of current page item |
${item.name} | String | Item name |
${item.id} | String or Integer | Item ID |
${item.url} | String | Item URL |
${item.imageUrl} | String | Image URL |
${item.description} | String | Item description |
#field(${item.rating}, '0') | Integer | Average rating |
#field(${item.numRatings}, '0') | Integer | Number of ratings |
${item.categories} | Array | Categories objects |
${item.dimensions} | Array | All related Catalog Objects |
| Custom Variables | Description |
|---|---|
${item.attributes.xxxxx.value} | Value of the attribute named "xxxxx" on the item |
| Variable | Type | Description |
|---|---|---|
${item.price} | Integer | Price. NOTE: Unformatted. For more information, see Utilities. |
${item.priceDescription} | String | Price description |
${item.listPrice} | Float | List price. NOTE: Unformatted. For more information, see Utilities. |
${item.inventoryCount} | Integer | Inventory count |
${item.brands} | Array | Brand tag objects |
${item.classes} | Array | Class tag objects |
${item.styles} | Array | Style tag objects |
${item.genders} | Array | Gender tag objects |
| Variable | Description |
|---|---|
${tools.global...} | Query Global Statistics |
${tools.user...} | Query User Statistics |
${tools.global.products...} | Query Products |
${tools.global.articles...} | Query Articles |
${tools.global.blogs...} | Query Blogs |
${tools.global.categories...} | Query Categories |
${tools.global.brands...} | Query Brands |
${tools.global.styles...} | Query Styles |
${tools.global.authors...} | Query Authors |
${tools.global.keywords...} | Query Keywords |
| Variable | Type | Description |
|---|---|---|
${tools.global.products.viewCount()} | Array | Top viewed products by count |
${tools.global.products.viewTime()} | Array | Top viewed products by time |
${tools.global.products.cartCount()} | Array | Products most added to cart by count |
${tools.global.products.cartValue()} | Array | Products most added to cart by currency |
${tools.global.products.purchaseCount()} | Array | Top purchased products by count |
Ensure that you either iterate over every product in an array
| Variable | Type | Description |
|---|---|---|
${tools.global.products.publishedDate()} | Array | Most recently published product |
| Variable | Type | Description |
|---|---|---|
${tools.user.products.viewed()} | Array | Most Recently Viewed |
${tools.user.orders.currentItems()} | Array | Products in cart. Note: Personalization doesn’t currently track cart removals. |
${tools.user.orders.currentValue()} | Float | Total cart value. Note: Unformatted, see utilities. |
${tools.user.get('Engagement', 'none')} | User's Engagement Score |
You can further refine results from query functions by passing them a set of item options, as shown in the following example.
You can specify item options by calling multiple functions on the itemOptions object, as shown in the following example.
By default, a message containing advanced dynamic queries renders only if there's at least 1 result.
To increase the minimum number of items returned, use ${itemOptions.minItems(<Integer>)}.
To increase the maximum number of items returned, use ${itemOptions.maxItems(<Integer>)}.
You can’t increase the maximum number of items returned beyond 10.
You can further filter query results using the following filters.
| Filter | Description |
|---|---|
${itemOptions.withCategory(<CategoryID>)} | Filter results by the category the visitor is currently viewing. |
${itemOptions.withBrand(<BrandID>)} | Filter results to contain only items with a specific brand. |
${itemOptions.withBrandAnyOf([<BrandID1>,<BrandID2>,...])} | Filter results to contain items from any of the specified brands. |
${itemOptions.withGender(<GenderID>)} | Filter results by gender. |
${itemOptions.withGenderAnyOf([<GenderID1>,<GenderID2>,...])} | Filter results by any of the specified gender IDs. |
${itemOptions.withKeyword(<KeywordID)} | Filter results by a specified keyword. |
${itemOptions.withKeywordAnyOf([<KeywordID1>,<KeywordID2>,...])} | Filter results by any of the specified keywords. |
${itemOptions.withAuthor(<AuthorID)} | Filter results by AuthorID. |
${itemOptions.withAuthorAnyOf([<AuthorID1>,<AuthorID2>,...)} | Filter results by any of the specified authors. |
${itemOptions.withContentClass(<ContentClassID>)} | Filter results by ContentClassID. |
${itemOptions.withContentClassAnyOf([<ContentClassID1>,<ContentClassID2>,...])} | Filter results by any of the specified content classes. |
${itemOptions.withStyle(<StyleID>)} | Filter results by style. |
${itemOptions.withStyleAnyOf([<StyleID1>,<StyleID2>,...])} | Filter results by any of the specified styles. |
${itemOptions.withItemClass(<ItemClassID>)} | Filter results by item class. |
${itemOptions.withItemClassAnyOf([<ItemClassID1>,<ItemClassID2>,...])} | Filter results by any of the specified item classes. |
${itemOptions.whereCreated(<TimeObject>)} | Filter results by date or time range of creation. To know more about the available TimeObject functions, see Lookback Period. |
${itemOptions.wherePublished(<TimeObject>)} | Filter results by published or time range. To know more about the available TimeObject functions, see Lookback Period. |
To specify a lookback period apart from the default lookback period of the past week, use:
The following functions are provided by the $time singleton object:
| Function | Description |
|---|---|
today | Today |
thisWeek | Current calendar week (with Monday as first day of week) |
thisMonth | Current calendar month |
since(date) | Since the specified date; date format is “mm/dd/yyyy” (for example “07/07/2017”) |
lastNDays(n) | Last n days, including today; lastNDays(1) would mean today and yesterday |
allTime | Don’t define a specific date range |
The itemOptions object provides several conditional options or methods that you can call to filter or manipulate its properties based on certain conditions.
| Conditional Option | Description |
|---|---|
${itemOptions.whereName()...} | Filter data based on item name. |
${itemOptions.whereDescription()...} | Filter data based on item description. |
${itemOptions.whereUrl()...} | Filter data based on item URL. |
${itemOptions.whereImageUrl()...} | Filter data based on an item's image URL. |
${itemOptions.wherePriceDescription()...} | Filter data based on item price description. |
You can use conditionals with conditional options to further refine the data being filtered.
The following conditionals are available for use.
| Conditional | Description |
|---|---|
exists() | Checks whether the property being filtered exists. |
doesNotExist() | Checks whether the property being filtered doesn’t exist. |
contains(<String>) | Checks whether the property being filtered contains the specified string. |
doesNotContain(<String>) | Checks whether the property being filtered doesn’t contain the specified string. |
To sort the results for display, use the displaySort function.
To sort results for display in the descending order, use the descending function.
The displaySort function provides the following sort options.
| Sort Option | Description |
|---|---|
${productSort.name()} | Sort products by name. |
${productSort.price()} | Sort products by price. |
${articleSort.name()} | Sort articles by name. |
${articleSort.publishedDate()} | Sort articles by published date. |
${blogSort.name()} | Sort blogs by name. |
${blogSort.publishedDate()} | Sort blogs by published date. |
To sort results for display in the descending order, use the descending function.
To include items a visitor is currently viewing in query results, use:
To include items in a visitor's cart in query results, use:
To exclude items a visitor has already purchased from query results, use:
To exclude items a visitor has already viewed from query results, use:
There are two ways to format prices.
-
By passing the price as a floating-point number to the
formatPricemethod. TheformatPricemethod formats the given number as a price, with the default dataset currency symbol and appropriate decimal formatting, and returns the formatted string.In Open Time Email Templates, only the
$currencyTools.formatPrice(<Float>)method is available. This method is used instead of is used instead of the$tools.formatPrice(<Float>)and$tools.formatNumber(<Float>, <Int Number of Fractional Digits>)methods. -
By passing the price as a floating-point number and a fixed number of digits after the decimal point to the
formatNumbermethod.
The #field utility enables you to provide a fallback value for an attribute.