How can we help?

Search

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

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 collection via the API

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

Add and import supplement records

After you create a supplement collection, you can add and import records to the collection. Records can be imported via data job in the UI or added via the API (one at a time or in bulk).

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.

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.

Import supplement records in the UI

Cordial's UI makes it simple to import supplement records via data job.

1. Log in to Cordial and navigate to Data Jobs > Create New Data Job.

2. Under Import, select Supplements.

3. Fill in the Name and Tags fields. For Type, choose either One-time or Recurring. Assign a Priority for the job and click Continue.

4. From the Data Job creation page, click Edit in the Data Source pane. Choose the Data Location. For our example, we'll use a local CSV file. Click Continue and follow the prompt to upload the file.

For recurring data jobs, select one of the available external sources: FTP, SFTP, HTTP(S), AWS S3 bucket, Google Cloud, Azure Blob.

5. Under Data Mapping, choose the desired Import option:

  • Insert new records and update existing records
  • Only update existing records (ignore new records)
  • Only insert new records (ignore existing records)

6. Select the appropriate Supplement, and map your data file columns to the appropriate attributes.

  • For attributes and lists that already exist in the system with the same name as the header column, they should be automatically mapped.
  • For attributes that have a different name than the header column, use the dropdown to map to a previously created attribute in the system.
  • You can also select the Ignore checkbox to ignore the column entirely.

7. Choose whether or not to trigger any actions as a result of your import.

8. If the job is recurring, click Recurring on the left sidebar and configure the desired settings in the Schedule pane.

9. In the On Completion pane, enter an email address where you'd like to receive a notification when the job is complete.

10. Click the Run Data Job button on the left.

Add and import supplement records via API

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

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

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

Use case

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

Export supplements

You can export supplement records in the UI via data job. There are endless possibilities to easily pull highly specific and relevant supplement data.

1. Log in to Cordial and navigate to Data Jobs > Create New Data Job. 

2. Under Export, select Supplements. 

3. Fill in the Name and Tags fields. For Type, choose either One-time or Recurring. Assign a Priority for the job and click Continue.

4. From the Data Job creation page, click Edit in the Data Source pane to specify the supplements you want to export.

5. In the Supplements pane, configure the supplements you'd like to export: specify the actual Supplements and click + Add Conditions for more specificity on the data you're exporting.

Use case

You could export supplement records for anyone with a specific car made during a specific year.

6. Select Edit under Data Mapping and enter the required fields:

  • Export name: give your export a unique name consisting only of letters and numbers
  • Export file name: give your export file a unique name consisting only of letters and numbers
  • Export file type: choose CSV or JSONL
  • Column key(s): specify the column key(s) to use in your exported file
  • Check the Header box to include a header row in your exported file
  • Select whether to Compress file(s) or Split file per chunks. If splitting the file, specify the amount of records to appear in each file.

7. Select Edit under Data Destination and choose the destination for your exported supplements file. You can select Local, FTP, SFTP, AWS S3 bucket, Google Cloud, or Azure Blob.

This method of exporting supplements automatically prepares that data for the destination you specify above, so you don't need to run an additional data transformation.

8. In the On Completion pane, enter an email address where you'd like to receive a notification once the job is complete. This step is optional.

9. If your data job is recurring, Publish the data job then select Recurring under Settings on the left. From here, set the Schedule for your data job and then Enable it.

10. Run the export events data job. Once completed, you can find the job under the Jobs Widget.

In the next article, you can learn about supplements.

Comments

0 comments

Please sign in to leave a comment.