How can we help?

Supplements

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 or used to build audience rules and create analytics reports.

Use case

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 Cordial stores supplements

Below is an example of a supplement stored in Cordial as a JSON object.

[
   {
   "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

When adding supplement records, each record must be given a unique ID. Supplement IDs cannot be 24-character hex strings. This is a platform-reserved format.

Create a supplement collection

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

When a supplement index field is passed, its data type (string, integer, etc.) will be recognized and searchable in the Cordial UI. If the field data type is changed, any new supplement values for that field will not be searchable in the UI. It is necessary to create a new field with the updated data type to make the values searchable in the platform UI.

Create a supplement via the UI

1. Log into the Cordial platform and navigate to Data > Supplement Data on the left sidebar.

2. Click the New button at the top of the Supplements page.

3. Fill out the required fields:

  • Name: This 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 filebut only index headers you need to be searchable.

1.) At least one index field must be created. 2.) Supplement record index values cannot be empty. 3.) Individual supplement record index values cannot exceed 1024 bytes. 4.) 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. 5.) The following system-reserved index keys cannot be used as supplement index field names: 'id', '_id', 'lm', ‘ct’.

Additional non-indexed field values can be added via the API. These non-indexed fields are available for message content, but not available for searching or filtering via Smarty.

Create a supplement via the API

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

Add supplement records

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

In table format

Create Supplement

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, such as image header, will be added as strings.

Add arrays

In addition to strings, numbers, and dates, you can upload an array of comma-separated values within the supplement record.

Use case

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

In table format

Create Supplement

In CSV format

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

Arrays should not contain any spaces between each value in the array.

API methods for adding supplement records

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

Learn more about the API methods for adding supplement records here.

Build audience rules using supplement data

You can 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.

To use this feature, it must be enabled in your account. Please submit a support ticket or send an email to support@cordial.com to request this feature.

1. From the Cordial Dashboard, navigate to Data > Supplement Data.

2. Select New on the Supplements page to create a new supplement collection.

3. On the Create Supplement pane, check the option "Use as a contact attribute."

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.

4. Create indexes for each of the fields that you want to be searchable via Smarty.

The contact identifier column should not be an indexed field within the supplement record.

5. Import your data file using the POST /supplements/{supplement}/imports method.

6. To build a new audience, navigate to Contacts > Audiences and select New.

7. In the Audience Builder, choose the Supplement rule and drag the desired supplement into your audience.

8. Add Conditions to define the rule.

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

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

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

To access Audience Trend reports, log into Cordial and navigate to Analytics > Audience Trends. From here, you can view the population of an audience over time based on supplement data.

Use case

You could 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.

To create an event chart, navigate to Analytics > Event Dashboards and select Add Chart.

To edit an event chart (also called a time series chart), navigate to Analytics > Event Dashboards and select Chart Settings in the upper right corner of the chart.

Use case

You could 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 Reportsnavigation: Analytics > Event Data Reportsallow you to view reports of event activity. You can filter reports using audience rules much the same as event dashboards.

Use case

You could filter by a saved audience rule where the contact has multiple business stays at your hotel.

Comments

0 comments

Please sign in to leave a comment.