NOTE
To add Catalog to your Iterable account, talk to your customer success manager.
This document provides an overview of catalog items. It describes what they are and discusses how to add, edit, and delete them using Iterable's web interface.
To learn how to using Iterable's API to create, view, update, and delete catalog items, take a look at the API Overview documentation.
In this article
What is a catalog item?
A catalog is a set of related items, each of which has various descriptive fields. Each item stored in a catalog is a catalog item.
For example, a Restaurants
catalog might contain items such as
JoesRestaurant
, KellysCafe
, and SalsKitchen
. Each of these items could
have descriptive fields such as cuisine
, averagePrice
, and rating
.
When sending a campaign, a collection can examine the items in a catalog, searching for data specifically relevant to each of the campaign's recipients. This data can then be used to personalize the message before it is sent.
How are catalog items stored?
Iterable stores catalog items in JSON. For example, in a Restaurants
catalog, a KellysCafe
item might be stored as follows:
{ "name": "Kelly's Cafe", "cuisine": "Ethiopian", "numberOfLocations": 1, "averagePrice": 10.00, "veganOptions": true, "location": { "lat": 37.773972, "lon": -122.431297 }, "bestItem": { "dish": "Tibs", "price": 12.00, "calories": 600 }, "grandOpeningDate": "2016-06-15 11:00:00 -0500", "tags": [ "spicy", "popular" ] }
Because of this, some (but not all) of the ways to create and edit catalog items involve creating and editing JSON.
Data types for catalog item fields
Catalog item fields can have the following data types:
string (
"car"
)long (
42
)double (
3.14
)boolean (
true
)-
date
Acceptable formats:
-
yyyy-MM-dd HH:mm:ss ZZ (
"2000-01-01 00:00:00 -0400"
) -
yyyy-MM-dd HH:mm:ss (
"2000-01-01 00:00:00"
) -
yyyy-MM-ddTHH:mm:ss.SSSZZ (
"2000-01-01T00:00:00.000-0400"
) -
yyyy-MM-dd (
"2000-01-01"
)
-
yyyy-MM-dd HH:mm:ss ZZ (
-
object (
{ "name": "widget", "size": "large" }
)TIP
Objects can contain other objects. However, you can't use fields in nested objects as the criteria for a collection.
-
geo_location
A geo_location is an object that contains only two fields:
lat
andlon
. Each of these must be a double. For example:{ "lat": 39.742043, "lon": -104.991531 }
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 }
Multiple-value fields
Any field on a catalog item can store zero, one, or many values. For example, a string field can have the following values:
"car"
["car", "motorcycle", "van"]
Similarly, a long field can have the following values:
42
[41, 42, 43]
This is true for all the data types listed above. When a single field has multiple values, each of those values must have the same data type.
For information about how collection search operators work with multiple-value fields, read Collections.
Equivalent types for equivalent fields
Since each Iterable catalog contains a set of related items, they should all have similar (or identical) fields. In a given catalog, identically named fields on different catalog items must have the same data type.
For example, consider two items in a Restaurants
catalog: KellysCafe
and SalsKitchen
. If KellysCafe
has an averagePrice
of 10.00
(a double),
then SalsKitchen
cannot have an averagePrice
of "$$$"
(a string).
Field type definition
When creating new catalog items, Iterable prompts you to provide explicit type definitions for their fields. For more information, read Defining Data Types for Catalog Item Fields.
Viewing a catalog's items
To view the items in a catalog:
Navigate to Content > Catalogs and click the name of the catalog you'd like to view.
-
Click the JSON / Tabular toggle to switch between the two ways of viewing a catalog's items.
JSON is optimized for viewing the fields in a single catalog item:
Tabular is optimized for comparing fields across multiple items:
Click Customize Columns to choose which fields to show in tabular view.
Creating and modifying catalog items
Iterable's web interface provides three ways to create and edit catalog items:
-
Useful for editing single catalog items, the JSON editor provides a point-and-click interface for creating and editing catalog items.
-
The text editor can be used to input raw JSON that represents a catalog item.
-
Uploading a CSV file makes it possible to create up to 1000 catalog items at once. However, CSV files may only include fields of type string, date, boolean, long, and double.
Creating catalog items with the JSON editor
The JSON editor provides a user interface for building catalog items:
To use the JSON editor to add or edit a catalog item, follow these steps:
Navigate to Content > Catalogs and open a catalog.
-
Create a new catalog item or edit an existing one.
To create a new catalog item:
Click Update Catalog Items and select Add Using JSON. The Create or Update Item in Catalog modal window will appear.
-
In the Key field, specify the name of the catalog item. For example, in a
Restaurants
catalog, the Key might be the restaurant's name.NOTE
A catalog key may contain letters, numbers, and dashes (no spaces, underscores, or other special characters) and must be 255 characters or less.
To edit an existing catalog item, click the edit button that appears when you hover over the item:
-
Add fields to the catalog item.
-
Hover the mouse pointer over the Value field and click the + button that appears. This will bring up the Key Name entry:
-
For Key Name, specify a name for the new field. For example, a restaurant might have an
averagePrice
field.NOTE
Do not use periods in field names.
After typing a field name, a checkmark icon will appear. Click it to create the new field on the catalog item.
-
-
Modify field values.
-
Hover over a field's value (NULL by default), and click the edit icon that appears:
-
Enter a value in the text input (do not surround it with quotes):
For a list of acceptable data types and their formats, read Data Types for Catalog Item Fields.
-
Select whether or not to save the data as a string.
To save the data as a string, click the larger checkmark button immediately below the input.
-
To save the value as something other than a string:
If Iterable infers that the field might not be a string, it will present a secondary checkmark button below the input, next to the data type. Click this.
NOTES
Choosing to store the value as a string or a non-string does not define the field's explicit data type—it only changes the way it is stored in the JSON. For information about defining data types, read Defining Data Types for Catalog Item Fields.
The catalog item JSON editor shows dates as strings, but templates can use Handlebars to manipulate these fields as dates. See Personalizing Templates with Handlebars.
When the catalog item editor identifies a date, the UI's data type suggestion popup will format that date in the browser's local time zone. However, the value will be saved in UTC.
-
Delete fields by hovering over an unnecessary field and clicking its delete icon.
-
Define field data types and create the catalog item.
If the bottom of the Create or Update Item in Catalog window shows a New Fields indicator, the catalog item contains fields not previously seen in the catalog:
Click Define Field Types to define the types for the new catalog item fields (or explicitly skip defining them if necessary).
Otherwise, the catalog item doesn't contain any new fields. To create the item, click Create.
Creating catalog items with the text editor
Use the text editor to specify raw JSON that defines a catalog item:
Follow these steps:
Navigate to Content > Catalogs and open a catalog.
-
Create a new catalog item or edit an existing one.
To create a new catalog item:
Click Update Catalog Items and select Add Using JSON. The Create or Update Item in Catalog modal window will appear.
-
In the Key field, specify the name of the catalog item. For example, in a
Restaurants
catalog, the Key might be the restaurant's name.NOTE
A catalog key may contain letters, numbers, and dashes (no spaces, underscores, or other special characters) and must be 255 characters or less.
To edit an existing catalog item:
-
Click the edit button that appears when you hover over the item:
Click Use TextArea to open the text editor and view the JSON for the current catalog item.
-
Update the JSON for the catalog item.
For a list of valid data types, read Data Types for Catalog Item Fields.
Field names should contain periods.
-
For example, a
RicksBurgerJoint
catalog item in aRestaurants
catalog might have JSON such as the following:{ "name": "Rick's Burger Joint", "cuisine": "American", "numberOfLocations": 1, "averagePrice": 6.00, "orderAtCounter": true, "delivery": false, "location": { "lat": 37.773972, "lon": -122.431297 }, "bestItem": { "dish": "Hamburger", "price": 6.00, "calories": 800 }, "grandOpeningDate": "2016-06-15 11:00:00 -0500", "tags": [ "fast", "cheap" ] }
IMPORTANT
Iterable treats the provided JSON as a complete representation of the object to update. If the JSON omits one of the catalog's previously existing fields, it will be deleted from the catalog item. It is not possible to use the text editor to update a subset of a catalog item's fields.
-
Define field data types and create the catalog item.
If the bottom of the Create or Update Item in Catalog window shows a New Fields indicator, the catalog item contains fields not previously seen in the catalog:
Click Define Field Types to define the types for the new catalog item fields (or explicitly skip defining them if necessary).
Otherwise, the catalog item doesn't contain any new fields. To create the item, click Create..
Creating catalog items by uploading CSV files
Uploading CSV files makes it possible to create up to 1000 catalog items at a single time. However, CSV files may only include fields of type string, date, boolean, long, and double.
IMPORTANT
Iterable treats each row in an uploaded CSV file as a complete description of the object it represents. If a previously existing field on the catalog item is omitted from that item's row in the CSV, it will be deleted from the object. It is not possible to use CSV to update a subset of a catalog item's fields.
To create catalog items with CSV:
Navigate to Content > Catalogs and open a catalog.
-
Upload a CSV file.
-
Click Update Catalog Items and select Bulk Update with CSV. The Bulk Update to Catalog modal window will appear:
Select a CSV file:
Drag and drop a CSV file onto the Drop File Here To Upload text of the Bulk Update to Catalog window, or click Choose File and select one.
-
-
Define field data types and create the catalog item.
If the bottom of the Create or Update Item in Catalog window shows a New Fields indicator, the catalog item contains fields not previously seen in the catalog:
Click Define Field Types to define the types for the new catalog item fields (or explicitly skip defining them if necessary).
Otherwise, the catalog item doesn't contain any new fields. To create the item, click Create..
NOTE
After uploading a CSV file, you may need to wait a moment before the catalog items appear in the catalog. If you don't see them, refresh the browser.
CSV file specification for catalog items
A CSV file containing catalog items should meet the following specification:
The file must have no more than 1000 rows of data (excluding the header row).
Each row must be less than 30kb.
The top (header) row of the file should contain the field names to be included on each catalog item, separated by commas.
The commas in a CSV file should not be surrounded by spaces, unless those spaces are part of the data in the associated column.
Field names in the header row must not contain periods.
-
The header row must contain a field named
key
(not case sensitive).- The value for
key
represents the ID or name of the item in each row. - Values in the
key
column of a CSV file may contain letters, numbers, and dashes (no spaces, underscores, or other special characters) and must be 255 characters or less.
- The value for
The data in the file is of type string, date, boolean, double, or long.
CSV files cannot include objects, arrays, or geo_location data. For more information about data types, read Defining Data Types for Catalog Item Fields.
Example CSV file
The following CSV file contains example catalog items for a Restaurants
catalog:
key,cuisine,delivery,numberOfLocations,averagePrice,grandOpening JoesRestaurant,Italian,false,1,6.00,2005-04-10 17:00:00 -0500 PhilsBarAndGrill,American,false,3,8.50,2012-06-01 14:00:00 -0600 KellysCafe,Ethiopian,true,2,10.00,2018-11-06 18:30:00 -0700 SalsKitchen,Mexican,true,4,9.00,2014-04-10 17:00:00 -0500
Deleting catalog items
To delete items from a catalog:
Navigate to Content > Catalogs and open a catalog.
-
Hover over the item you'd like to delete and click the trash can icon.
On the confirmation alert, click Yes, Delete.
After deleting an item from a catalog, it may remain visible until the delete has been fully processed. After a few moments, refresh the page to verify that the item has been deleted.