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.

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

Create a supplement collection

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

• Via the UI
• Via the API

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 file—but only index headers you need to be searchable.

Create a supplement via the API

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

• You can learn more about creating supplement collections via the API here.

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

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.

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 to learn more.

API methods for adding supplement records

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

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

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

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.

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

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.

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.

Filter Event Data Reports

Event Data Reports—navigation: Analytics > Event Data Reports—allow you to view reports of event activity. You can filter reports using audience rules much the same as event dashboards.