Smart Ingest lets you sync custom events and purchase events to Iterable, and can update shopping cart items with update cart events.
When syncing custom events and purchase events, Smart Ingest inserts new events into Iterable and lets you modify existing events (as long as you provide their event ID).
Continue reading for more information on the settings available for Smart Ingest event syncs.
In this article
Data model requirements
To run an event sync, your data model needs to contain a user identifier to locate records in Iterable (either user ID or email address, depending on the project type you’re using).
The model should also contain additional fields depending on the event type you're syncing. The event sync descriptions below detail the fields required for each event type.
Make sure your data model contains columns for each of the fields you intend to update in Iterable.
Event types
Custom event
This sync type tracks one or many types of custom events in Iterable.
The custom event sync type uses upsert mode, which means that Iterable first tries to update an event if it already exists. If your sync provides an event ID and your data model contains a particular event ID that already exists in Iterable, Smart Ingest updates the event with new data from the sync. When there is no event ID provided, or if the provided event ID doesn’t exist, Iterable creates new events.
Custom events use the settings and field mappings described in the sections below.
Custom event fields available in Smart Ingest
When syncing custom events, your data model should contain columns that you can map to the following fields in Iterable:
id
: (optional, recommended) the unique identifier of the event. Learn more.-
eventName
: the name of the custom event. Add a column for this if the data table contains multiple kinds of eventsIf the table contains events of only one kind, you can instead use a static value that you define during sync setup. Learn more.
createdAt
: (optional, recommended) the timestamp that the event occurred. Learn more.campaignId
: (optional) the unique ID of the Iterable campaign. Smart Ingest lets you select the campaign by name. Learn more.templateId
: (optional) the unique ID of the Iterable campaign. Smart Ingest lets you select the template by name. Learn more.dataFields
: (optional) any additional custom event fields you wish to sync that would normally be nested on thedataFields
object for events. Learn more.
Purchase event
This sync type uses the purchase event action in Iterable's Commerce API, which does two things:
- Tracks a purchase event in Iterable.
- Clears the user's shopping cart items.
The purchase event sync type uses insert mode. This means that if your sync includes a field with an event ID, and your data model contains a particular event ID already exists in Iterable, Smart Ingest updates the purchase event with new data from the sync. When there is no event ID provided, or if the provided event ID doesn’t exist, Iterable creates new purchase events.
Purchase events use the following settings and field mappings that are described in more detail in the sections below: Event timestamp, Event details, User matching, Purchase fields, Additional event fields, and Additional user fields.
Purchase event fields available in Smart Ingest
When syncing purchase events, your data model should contain columns that you can map to the following fields in Iterable:
id
: (optional, recommended) the unique identifier of the event. Learn more.createdAt
: (optional, recommended) the timestamp that the event occurred. Learn more.campaignId
: (optional) the unique ID of the Iterable campaign. Smart Ingest lets you select the campaign by name. Learn more.templateId
: (optional) the unique ID of the Iterable campaign. Smart Ingest lets you select the template by name. Learn more.dataFields
for events: (optional) any additional custom event fields you wish to sync that would normally be nested on thedataFields
object for events. Learn more.items
: a JSON object array that includes each shopping cart item, each with pre-set fields. To learn more, read Purchase fields.total
: the purchase value total. Learn more.dataFields
for users: (optional) any additional custom fields you wish to sync that would normally be nested within thedataFields
object for users. Learn more.
Shopping cart update
This sync type leverages the update cart action using Iterable's Commerce API, which does two things:
- Updates the
shoppingCartItems
field on a user's profile. - Tracks update cart events in Iterable.
This sync type uses insert mode to add new events into Iterable when they first appear in your query results.
Shopping cart updates use the following settings and field mappings that are described in more detail in the sections below: User matching, Shopping cart items, Additional user fields.
Shopping cart items fields available in Smart Ingest
When syncing shopping cart updates, your data model should contain columns that you can map to the following fields in Iterable:
-
items
: a JSON object array that includes each shopping cart item, each with pre-set fields:id
,sku
,name
,description
,categories
,price
,quantity
,imageUrl
,url
, anddataFields
.To learn more, read Shopping cart items.
dataFields
for users: (optional) any additional custom fields you wish to sync that would normally be nested on thedataFields
object for users. Learn more.
Event settings
Settings for an event sync vary depending on the event type. In the descriptions below, settings that apply only to a certain event type are noted as such.
During sync setup, select the event type that you want to sync to Iterable. The sync setup wizard changes dynamically to show the settings required for each event type.
Event name
This setting applies to custom events only.
Providing an event name is required to send a custom event to Iterable. This
corresponds to the eventName
custom event property.
There are two ways to provide an event name: a static value, or a column from your data model.
If your data table contains events that are all of the same type, you can use a static value.
If your data table contains a variety of events, and there is a column (like
EVENT_NAME
) that identifies the name of the event with each row, then use the
column value and then select the column that contains the event’s name.
IMPORTANT
Don't use periods in field names, as they can cause problems for Handlebars
references. Normally, Handlebars uses "dot notation" to reference fields in
objects (for example, {{objectName.fieldName}}
). Because of this, a field name that actually contains a period can create ambiguity and cause errors with
Handlebars operations.
Event timestamp
This setting applies to custom events and purchase events only.
You can select a column that contains timestamps of when events occurred. If this field is empty, Iterable uses the time the event arrives at the server. This field is optional, but recommended.
Event details
These settings apply to custom events and purchase events only.
You can also optionally include these fields as part of your event sync:
Event ID (recommended): Select a column from your model. When this isn’t provided, Iterable treats each data row as a new event and subsequently generates a unique ID. You must include this configuration if you want to modify existing events. This corresponds to the
id
field in the event body custom event property.Campaign name: Select a static value, or use a column from your model.
Template name: Select a static value or use a column from your model.
User matching
This setting applies to custom events only. To add user matching for purchase events, use Purchase fields and Shopping cart items mapping areas to add the user’s unique identifier.
Select either an email or user ID to match users found in Iterable. Smart Ingest uses these fields for identifying the user associated with this event.
For more information on selecting an identifier to match users, read Users sync type > User matching.
Purchase fields
This setting applies to purchase events only.
Purchase events should have the following fields mapped in this section:
- A user identifier (either user ID or email address, depending on the project type you’re using)
- Items (as a JSON object array called
items
in Iterable) - Total (
total
in Iterable)
For purchase event syncs, Smart Ingest automatically adds the items
array and
total
field. These are required to track a purchase, and you need to map this
from the data source columns. To learn more about mapping an array of
objects, read Create an object array.
When building the items array, make sure to use this format:
{ "items": [ { "id": "string", "sku": "string", "name": "string", "description": "string", "categories": [ "string" ], "price": 0, "quantity": 0, "imageUrl": "string", "url": "string", "dataFields": {} } ] }
Shopping cart items
This setting applies to shopping cart updates only.
Purchase event fields should have the following fields mapped in this section:
A user identifier (either user ID or email address, depending on the project type you’re using).
Items (as a JSON object array). To learn more about mapping an array of objects, read Create an object array.
Smart Ingest automatically adds the Shopping cart items array as a destination field in Iterable. To track a shopping cart update, you need to map this from the data warehouse columns.
When building the items array, make sure to use the same format as listed above in the Purchase fields description.
Additional event fields
This setting applies to custom events and purchase events.
Smart Ingest sends any additional custom fields you include as part of the in the dataFields property of the event's body, which adds fields to the custom event properties.
Additional user fields
This setting applies to purchase events and shopping cart updates.
Smart Ingest sends any additional custom fields you include as part of the in the user.dataFields property of the event's body, which updates the user’s profile data.
Batch size
This setting applies to custom events only.
Under Advanced Configuration, you can find the setting to change a sync’s batch size.
The default batch size is 1000 rows. You can increase this up to 2000 rows per batch in order to adjust the sync for increased speed, or you can lower it to correct “file too large” errors.