Collections

Collections use information about a recipient's interests, location, preferences, behavior, and history—anything stored on their Iterable user profile—to search for relevant catalog items (products, locations, events, etc.). Messages can then embed these collections to provide engaging, relevant content to each recipient of a campaign.

This document describes how to build and edit collections.

# In this article

# Viewing a catalog's collections

Every collection belongs to a single catalog and can only search data contained in that catalog. To view a project's collections, and the associated catalog for each.

1. Navigate to Content > Catalogs.

2. Click Collections (on the left-hand side of the screen).

3. Use the Filter box to filter the list of collections by name or catalog.

4. Click Customize Columns to customize the columns shown in the table.

5. Click a collection to open its definition.

# Creating a new collection

To create a collection:

1. Navigate to Content > Catalogs.

2. Click Create New Collection.

3. Specify a Name, choose a Catalog, and add a Description.

4. Click Build Collection to bring up the Collection Builder.

# Editing an existing collection

To edit a collection:

1. Navigate to Content > Catalogs.

2. Click Collections (on the left-hand side of the screen).

3. Click the name of the collection you'd like to edit. This will open the Collection Builder in Read mode (to edit the collection definition, click Edit).

   

4. Alternatively, click the edit icon that appears when you hover over the row associated with a collection, and edit the collection's name and description.

   

# Collection Builder overview

The Collection Builder provides an interface for defining collections that find particular items stored in a particular catalog. It supports boolean logic, static search criteria, dynamic search criteria, various search operators, ordering, sorting, and limiting.

Use the Collection Builder to define a collection that combines multiple groups of static and dynamic search criteria into a single, overall search that finds relevant items in a catalog.

The Collection Builder has the following interface (this example shows a sample collection definition with empty search criteria).

The above screenshot demonstrates the following things about a collection definition:

• A collection definition contains a set of groups (each one denoted by a dark blue box on the left-hand side of the definition). At the top level, a collection definition specifies that matching catalog items must satisfy None of the groups, Any of the groups, or All of the groups.

• A group contains a set of clauses (shown in grey boxes). Each group specifies that matching catalog items must satisfy None of the group's clauses, Any of its clauses, or All of its clauses.

• Each clause contains a set of search criteria (shown as line items inside the grey box), all of which must be true for matching catalog items. It is not possible to specify that catalog items should match any or none of a clause's search criteria.

For example, in the above screenshot:

• The Any selection at the top of the definition indicates that the collection matches catalog items satisfying at least one of its three groups.

• The top group's All selection indicates that the group matches catalog items satisfying all of its clauses (of which there is only one).

• The middle group's Any selection indicates that the group matches catalog items satisfying at least one of its clauses (of which there are two).

• The bottom group's None selection indicates that the group matches catalog items satsifying none of its clauses (of which there is only one).

• In each clause throughout the collection, there are multiple search criteria. For a catalog item to match any particular clause, it must satisfy all of its search criteria.

# Using the Collection Builder

To use the Collection Builder to define a collection:

• Click the collection's title to change it.
• Click the collection's description to change it.
• Click the Use In Template button to get a Handlebars snippet that can be used to embed the collection in a message template.
• Click Edit to put the Collection Builder interface in editing mode, or Read to put it in read-only mode.
• Click Undo (counter-clockwise arrow) and Redo (clockwise arrow) to undo and redo edits.
• Click a trash can icon to delete the associated group, clause, or search criteria.
• Click a stacked paper icon to copy the associated group, clause, or search criteria.
• Drag the upper left-hand corner of a clause to reorder it within a group or move it to a different group.
• Click All, Any, or None to change the logical operator associated with the whole collection or one of its groups.
• Click Add a Group to add another group to the collection definition.
• Click + And, + Or, or + Nor to add another clause to a group.
• Click Add Field to add a search criteria to a clause.
• Use the Select a Field drop-down menu to select a catalog item field to use in a search criteria.
• Use the Comparator drop-down menu to select an operator for a search criteria.
• Use the Custom Value drop-down menu to set a search criteria to compare catalog item fields against a custom value (static search) or user profile field (dynamic search).
• Use the Items to Return input to limit the number of results returned by the collection.
• Use the Ordered By menu to choose a catalog item field by which to order the collection results.
• Use the sort input to choose whether to sort the results in an Ascending or Descending fashion.
• Use the Preview with Sample Data from input to enter an email address to use when previewing the collection's results, the Save and Preview button to save the collection definition and view its results, and the Save Only button to save the collection definition.

# Static search criteria

Static search criteria allow you to find catalog items that have attributes that match known values.

To create static search criteria:

1. In the Collection Builder, select the catalog field to search on (for example, averagePrice).

2. Select an operator (for example, Less Than or Equal).

3. Select Custom Value from the drop-down menu.

4. Provide a custom value to use with the operator (for example, 10.00).

The following example is a static search criteria configured in the Collection Builder to search for catalog items having an averagePrice field less than or equal to 10.00.

# Example static search criteria

The following example static search criteria might be relevant to a collection for a Restaurants catalog:

• String fields

  cuisine Equals Ethiopian

• Date fields

  grandOpening Is After 06/14/2016 12:00 PM

• Long fields

  numberOfLocations Greater Than or Equal 1

• Double fields

  averagePrice Less Than Or Equal 7.00

• geo_location fields

  location Is Within 100 Miles of Lat 37.773972 Long -122.431297

• Boolean fields

  delivery Equals false

• Object fields

  currentSpecial Is Set

# Dynamic search criteria

Dynamic search criteria allow you to find catalog items that have attributes that match values on particular user profile fields. Since a collection will be queried for each user, this allows you to find the items that are most relevant to that specific user.

To create dynamic search criteria:

1. In the Collection Builder, select the catalog field to search on (for example, averagePrice).

2. Select an operator (for example, Less Than or Equal).

3. Select Contact Property from the drop-down menu.

4. Select a user profile field (for example, dinnerBudget).

The following example shows a static search criteria that searches for catalog items that have an averagePrice that is less than or equal to the user's dinnerBudget.

# Example dynamic search criteria

The following example dynamic search criteria might be relevant to a collection for a Restaurants catalog:

• String fields

  cuisine Equals favoriteCuisine

  Locates restaurants having the user's favorite cuisine.

• Date fields

  grandOpening Is After ageCutoff

  Locates restaurants that meet the user's specifications about how new they must be.

• Long fields

  numberOfLocations Less Than or Equal maxChainSize

  Locates restaurants that haven't expanded to more locations than the user prefers.

• Double fields

  averagePrice Greater Than Or Equal averagePricePreference

  Locates restaurants that might be considered a splurge for the user.

• geo_location fields

  location Is Within 2 Miles of workplace_geo_location

  Locates restaurants close to the user's workplace, as defined by the workplace_geo_location field on their user profile.

  IMPORTANT

  On an Iterable user profile, the name of a geo_location field must have a _geo_location suffix. For example:

  "workplace_geo_location": { "lat": 39.742043, "lon": -104.991531 }

  Catalog item fields do not have this same restriction. For example, the following is a valid geo_location field on a catalog item:

  "location": { "lat": 39.742043, "lon": -104.991531 }

• Boolean fields

  delivery Equals deliveryPreference

  Locates restaurants matching the user's delivery preference.

# Nested user profile fields

When defining a collection, you'll often set up search criteria that compare your catalog items to standalone, top-level user profile fields.

But sometimes, you may want the collection to examine user profile fields that live on deeply nested objects and objects stored in arrays. These user profile fields show up in the Contact Property drop-down menu of the Collection Builder, right alongside top-level user profile fields. However, they're displayed with periods separating one object or array in the hierarchy from the next ("dot notation").

For example, shoppingCartItems.categories selects the categories field found on objects in the shoppingCartItems array.

# Shopping cart example

You might want to recommend products to a user based on the items that are already in the shopping cart on their Iterable user profile. To do this, you can use a collection definition that looks at nested user profile fields. For an example, keep reading.

Consider a user (user@example.com) whose Iterable user profile has this shopping cart:

"shoppingCartItems": [
	{
		"price": 4.99,
		"id": "1",
		"categories": [
			"vehicle"
		],
		"name": "Toy truck",
		"quantity": 1
	},
	{
		"price": 2.99,
		"id": "2",
		"categories": [
			"classic"
		],
		"name": "Yo-yo",
		"quantity": 1
	}
]

And suppose your project has a Toys catalog with the following items (for convenience, shown here as comma-separated values):

id,key,name,price,category
"1","toytruck","Toy truck",4.99,"vehicle"
"2","yoyo","Yo-yo",2.99,"classic"
"3","toycar","Toy car",3.99,"vehicle"
"4","woodblocks","Wood blocks",20.00,"classic"
"5","magglass","Magnifying glass",5.99,"scientific"

To use the items already in the cart to recommend toys from the Toys catalog, you can use a collection configured to find all items where category equals shoppingCartItems.categories. Such a collection returns each catalog item (toy) whose category matches any category that's already found on an item in the shopping cart (in their categories arrays).

Here's what this collection would look like in the Collection Builder, with a preview of the data returned for user@example.com:

To make sure the collection doesn't return items that are already in the user's cart, add a search criteria specifying that the catalog item id does not equal shoppingCartItems.id.

As expected, the preview results here don't include the Toy truck or the Yo-yo, since those are already in the user's cart.

# Operators

To select catalog items, a collection definition can use various search operators to compare those items against known values and user profile fields.

The Collection Builder provides the following search operators, which depend on the data type of the catalog item field being searched:

# String field operators

• Equals

  For static criteria, returns true if any string stored in the catalog item field in question matches the string on the right-hand side of the operator.

  For dynamic criteria, returns true if any string stored in the catalog item field in question matches any string stored in the specified user profile field on the right-hand side of the operator.

• Does Not Equal

  For static criteria, returns true if none of the strings stored in the catalog item field in question matches the string on the right-hand side of the operator.

  For dynamic criteria, returns true if none of the strings stored in the catalog item field in question matches any string stored in the specified user profile field on the right-hand side of the operator.

• Is Set

  Returns true if the relevant string field on the catalog item in question has a value.

# Date field operators

• Is After

  For static criteria, returns true if any dates stored in the catalog item field in question comes after the date on the right-hand side of the operator.

  For dynamic criteria, returns true if any dates stored in the catalog item field in question comes after the single dates stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of dates).

• Is On or After

  For static criteria, returns true if any dates stored in the catalog item field in question comes on or after the date on the right-hand side of the operator.

  For dynamic criteria, returns true if any dates stored in the catalog item field in question comes on or after the single dates stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of dates).

• Is Before

  For static criteria, returns true if any dates stored in the catalog item field in question comes before the date on the right-hand side of the operator.

  For dynamic criteria, returns true if any dates stored in the catalog item field in question comes before the single dates stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of dates).

• Is On or Before

  For static criteria, returns true if any dates stored in the catalog item field in question comes on or before the date on the right-hand side of the operator.

  For dynamic criteria, returns true if any dates stored in the catalog item field in question comes on or before the single dates stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of dates).

• Is Exactly

  For static criteria, returns true if any dates stored in the catalog item field in question matches the date on the right-hand side of the operator.

  For dynamic criteria, returns true if any dates stored in the catalog item field in question matches at least one of the dates stored in the specified user profile field on the right-hand side of the operator.

• Is Any Time Except

  For static criteria, returns true if any dates stored in the catalog item field in question is any time except the date on the right-hand side of the operator.

  For dynamic criteria, returns true if none of the dates stored in the catalog item field in question matches any of the dates stored in the specified user profile field on the right-hand side of the operator.

• Is Set

  Returns true if the relevant date field on the catalog item in question has a value.

# Long field operators

• Greater Than

  For static criteria, returns true if any long stored in the catalog item field in question is greater than the long on the right-hand side of the operator.

  For dynamic criteria, returns true if any long stored in the catalog item field in question is greater than the single long stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of longs).

• Greater Than or Equal

  For static criteria, returns true if any long stored in the catalog item field in question is greater than or equal to the long on the right-hand side of the operator.

  For dynamic criteria, returns true if any long stored in the catalog item field in question is greater than or equal to the single long stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of longs).

• Less Than

  For static criteria, returns true if any long stored in the catalog item field in question is less than the long on the right-hand side of the operator.

  For dynamic criteria, returns true if any long stored in the catalog item field in question is less than the single long stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of longs).

• Less Than Or Equal

  For static criteria, returns true if any long stored in the catalog item field in question is less than or equal to the long on the right-hand side of the operator.

  For dynamic criteria, returns true if any long stored in the catalog item field in question is less than or equal to the single long stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of longs).

• Equals

  For static criteria, returns true if any long stored in the catalog item field in question is equal to the long on the right-hand side of the operator.

  For dynamic criteria, returns true if any long stored in the catalog item field in question is equal to at least one of the longs stored in the specified user profile field on the right-hand side of the operator.

• Does Not Equal

  For static criteria, returns true if none of the longs stored in the catalog item field in question equal the long on the right-hand side of the operator.

  For dynamic criteria, returns true if none of the longs stored in the catalog item field in question equals any long stored in the specified user profile field on the right-hand side of the operator.

• Is Set

  Returns true if the relevant long field on the catalog item in question has a value.

# Double field operators

• Greater Than

  For static criteria, returns true if any double stored in the catalog item field in question is greater than the double on the right-hand side of the operator.

  For dynamic criteria, returns true if any double stored in the catalog item field in question is greater than the single double stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of doubles).

• Greater Than or Equal

  For static criteria, returns true if any double stored in the catalog item field in question is greater than or equal to the double on the right-hand side of the operator.

  For dynamic criteria, returns true if any double stored in the catalog item field in question is greater than or equal to the single double stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of doubles).

• Less Than

  For static criteria, returns true if any double stored in the catalog item field in question is less than the double on the right-hand side of the operator.

  For dynamic criteria, returns true if any double stored in the catalog item field in question is less than the single double stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of doubles).

• Less Than Or Equal

  For static criteria, returns true if any double stored in the catalog item field in question is less than or equal to the double on the right-hand side of the operator.

  For dynamic criteria, returns true if any double stored in the catalog item field in question is less than or equal to the single double stored in the specified user profile field on the right-hand side of the operator (this operator does not work with arrays of doubles).

• Equals

  For static criteria, returns true if any double stored in the catalog item field in question is equal to the double on the right-hand side of the operator.

  For dynamic criteria, returns true if any double stored in the catalog item field in question is equal to at least one of the doubles stored in the specified user profile field on the right-hand side of the operator.

• Does Not Equal

  For static criteria, returns true if any double stored in the catalog item field in question is does not equal the double on the right-hand side of the operator.

  For dynamic criteria, returns true if none of the doubles stored in the catalog item field in question equals any of the doubles stored in the specified user profile field on the right-hand side of the operator.

• Is Set

  Returns true if the relevant long field on the catalog item in question has a value.

# geo_location field operators

• Is Within

  For static criteria, returns true if any geo_location stored in the catalog item field in question is within the specified distance from the specified location on the right-hand side of the operator.

  For dynamic criteria, returns true if any geo_location stored in the catalog item field in question is within the specified distance from the single geo_location value stored on the right-hand side of the operator (this operator does not work with arrays of geo_location values).

# Boolean field operators

• Equals

  For static criteria, returns true if any boolean stored in the catalog item field in question matches the boolean value on the right-hand side of the operator.

  For dynamic criteria, returns true if any boolean stored in the catalog item field in question is equal to at least one of the boolean values stored in the specified user profile field on the right-hand side of the operator.

• Does Not Equal

  For static criteria, returns true if any boolean stored in the catalog item field in question does not equal the boolean on the right-hand side of the operator.

  For dynamic criteria, returns true if none of the booleans stored in the catalog item field in question equals any of the boolean values stored in the specified user profile field on the right-hand side of the operator.

# Object field operators

• Is Set

  Returns true if the relevant object field on the catalog item in question has a value.

# Limiting, ordering, and sorting a collection

# Limiting

To limit the number of items in a collection, specify a number in the Items to Return input.

# Ordering and sorting

To order and sort the collection:

1. In the query builder, use the Ordered By drop-down menu to select a catalog item field by which to order the results.

   NOTE

   When ordering by a geo_location field, use a Custom Value to sort the collection relative to a known location. Use a Contact Property to sort the collection relative to a location stored on the recipient's user profile.

   

2. For Sorted, choose Ascending or Descending.

Modifying the ordering and sorting of a collection changes the items it returns. Be sure to preview the collection before using it in a template.

# Previewing a collection

To preview a collection:

1. Open the collection in the Collection Builder.

2. Enter an email address.

3. Click Save and Preview to show the items in the collection:

   

4. Use the JSON / Tabular toggle to select a viewing mode. JSON is optimized for viewing the fields in a single catalog item; Tabular is optimized for comparing multiple catalog items.

# Using a collection in a message

To use the results of a collection in a message:

• Click the Use in Template button to retrieve a Handlebars snippet that can be used to call this collection from message templates:

  

• Place this Handlebars snippet in a message template.

For more information, read Using Catalogs & Collections in Messages.

# Want to learn more?

For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Iterable Academy

• Collections 101

Support docs

• Catalog Overview
• Using Catalog
• Catalog Items
• Defining Data Types for Catalog Item Fields
• Using Catalogs & Collections in Messages
• Catalog Limitations
• Catalog APIs
• API Overview and Sample Payloads