Supplements

Used for:

•  Message Content
•  Building Audiences
•  Analytics

Overview

Supplements are data collections hosted in your Cordial account that allow you to store an unlimited number of records in a custom schema. Supplements provide a flexible mechanism for storing structured data objects that don't fit well into contact attributes, lists or orders. Supplement data can be rendered in a message, utilized to build audience rules and create analytics reports.

Note: In order to build audience rules using supplements, the necessary feature must be enabled in your account. Please contact your Client Success Manager for more info.

A potential use case for supplement data is a business using a supplement to store information related to its store locations. Fields in the supplement might be the following:

• Store ID
• Store City
• Store Manager

Supplement records are often related to a contact through a common key or data attribute. This association allows you to use filtered supplement data in a message. For example, a contact attribute could be created to hold a Store ID value for each contact.  The Store ID value in the contact attribute would correspond with the Store ID field in the store supplement collection.

How Supplements Are Stored

Supplements are stored in Cordial as JSON objects. Here is an example of how supplement records are stored in JSON:

[
   {
   "id": "0",
    "storeid": "123",
    "city": "Phoenix",
    "manager": "John Doe",
    "ct": "2017-03-23T18:24:53+0000",
    "lm": "2017-03-23T18:24:53+0000"
   },
   {
    "id": "1",  
    "storeid": "124",
    "state": "CA",
    "manager": "Jane Doe",
    "ct": "2017-03-23T17:42:21+0000",
    "lm": "2017-03-23T17:45:18+0000"
   }
]

When supplement records are added, Cordial automatically creates additional fields to hold metadata about the supplement:

• ct: Date Created
• lm: Date Last Modified

Creating a Supplement Collection

Before adding supplement records, a supplement collection must be created. There are 2 ways to create a supplement collection:

• Via the UI
• Via the API

Creating a Supplement Via the UI

1. Log into the Cordial platform and navigate to Data › Supplement Data.
2. Click the button New.
   
   
3. Fill out the fields:
   • At least one index field must be created.
   • Supplement record index values cannot be empty.
   • Individual supplement record index values cannot exceed 1024 bytes.
   • Certain special characters may be interpreted as Boolean operators when stored within indexed fields, which can cause supplement data query failures. We recommend altogether omitting special characters from indexed field data.
   • The following system reserved index keys cannot be used as supplement index field names: 'id', '_id', 'lm', ‘ct’.
• Name: Will be seen in the UI as a friendly reference for the supplement.
• Key: A unique name that will be referenced in messages and the API. No spaces or special characters are allowed.
• Indexes: Fields within supplement records that are searchable and referenced in messages. Indexes should match the column headers of your CSV file, but only index headers you need to be searchable.

Creating a Supplement Via the API

Cordial also allows creation of supplement collections via the API using the POST /supplements method.

Learn more about creating supplement collections via the API.

Adding Supplement Records

After you create a supplement collection, you can add records to the collection. Records can be added via the API one at a time or imported in bulk in a CSV document.

In table format:

In CSV format:

model,brand,price,milage,image,id
pilot,honda,33000,100000,http://www.example.com/image1.png,1
explorer,ford,34000,39000,http://www.example.com/image2.png,2
prius,toyota,27000,66000,http://www.example.com/image3.png,3

• Each record in the import file must have a unique id value, which is stored as a string.
• The id column header must be in lower case.
• Values under column headers that have not been indexed, image header for example, will be added as strings.

Adding arrays

In addition to strings, numbers, and dates, you can upload an array of comma-separated values within the supplement record. For example, you might have an array of values for automobile color. Because array values are separated by commas, they need to be escaped by double-quotes to avoid errors while uploading the CSV file. Your data file might look like the following:

In table format:

In CSV format:

"[""gray"",""sky blue"",""true blue""]"
"[""green"",""silver"",""electric yellow""]"
"[""red"",""tan"",""gold""]"

Note: arrays should NOT contain any spaces between each value in the array.

  Watch the video about importing supplement data:

Supplement records are added via the API using the following methods:

• POST /supplements/{supplement}/imports
  Creates a supplement data import job of a CSV file containing supplement records.
• POST /supplements/{supplement}/records
  Creates a new data record in the specified supplement.
• PUT /supplements/{supplement}/records/{id}
  Updates an existing record in the specified supplement.

Learn more about the API methods for adding supplement records.

Building Audience Rules Using Supplement Data

You are able to create audience rules based on supplement records that are used as contact attributes. Contact attribute supplements are associated with individual contact records using the unique contact identifier. For this reason, import files that are updating contact attribute supplements must contain a contact identifier column such as cID, email or a custom contact identifier key used in your account.

1. Create a new supplement collection and check the option "Use as a contact attribute".
   
   Note: Depending on your account settings, the possible identifier keys that can be provided for each contact attribute enabled record will be different, and may include custom identifier keys.
2. Create indexes for each of the fields that you would like to be searchable when building audience rules.
   
   Note: The contact identifier column should not be an indexed field within the supplement record.
3. Import your data file using the POST /supplements/{supplement}/imports method.
4. When building audiences, choose the Supplement rule, select the supplement and add any conditions to define the rule.
   

Using Supplements in a Message

Supplement data can be rendered in a message using the Smarty getSupplementRecords method. You can query supplement data, filter it according to certain rules, and then render it in message content for each contact.

Building Analytics Reports Using Supplements

Audiences based on supplements can be saved as audience rules and either visualized over time with audience trend reports or used as filters for event data dashboards and event data reports.

Note: To build audiences using supplements, the feature must be enabled in your account. Please contact your Client Success Manager for more info.

Audience Trend Reports

Using audience trend reports, you can view the population of an audience over time based on supplement data.

For example, you can create an audience based on if a contact has multiple business stays at your hotel, enable audience trend analytics on the audience rule, then view the population over time on an audience trends chart.

Filter Event Dashboards

Event dashboards provide a way to visualize event activity over time by creating customizable charts. You can take advantage of supplement data in event dashboard charts using audience filters.

For example, you can create a chart that plots message activity over time filtered by a saved audience rule where the contact has multiple business stays at your hotel.

Filter Event Data Reports

Event data reports allow you to view reports of event activity. You are able to filter reports using audience rules much the same as event dashboards.

For example you can filter by a saved audience rule where the contact has multiple business stays at your hotel.