Catalog Items

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")

• 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 and lon. 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:

1. Navigate to Content > Catalogs and click the name of the catalog you'd like to view.

2. 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:

• JSON editor

  Useful for editing single catalog items, the JSON editor provides a point-and-click interface for creating and editing catalog items.

• Text editor

  The text editor can be used to input raw JSON that represents a catalog item.

• CSV files

  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:

1. Navigate to Content > Catalogs and open a catalog.

2. 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:

     

3. 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.

4. 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.

5. Delete fields by hovering over an unnecessary field and clicking its delete icon.

6. 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:

1. Navigate to Content > Catalogs and open a catalog.

2. 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:

     

3. Click Use TextArea to open the text editor and view the JSON for the current catalog item.

4. 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 a Restaurants 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.

5. 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.

To create catalog items with CSV:

1. Navigate to Content > Catalogs and open a catalog.

2. 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.

3. 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 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:

1. Navigate to Content > Catalogs and open a catalog.

2. Hover over the item you'd like to delete and click the trash can icon.

   

3. 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.

# Further reading

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