Managing Custom Events

Custom events are any events that you want to track and use in your marketing automations that aren't already captured by Iterable. You can send custom events to your project via API, Smart Ingest, or from an integration, and then you can use these events to trigger journeys, create audience segments, and more.

Custom events are useful for tracking user interactions with your brand that aren't captured by Iterable's system events. For example, you might want to track when a user searches for a key term on your website, or when a user adds an item to their favorites list.

# In this article

# Viewing custom events for a project

To view your custom events, go to Settings > Data Schema Management.

To access the Data Schema Management screen, you need the Manage Settings project permission.

# Custom event statuses

Custom events are organized in tabs based on their event status:

# Saved events

Saved events show in Iterable and are tracked on user profiles. You can use them in Iterable to trigger journeys, create audience segments, and more.

All events start as saved until the status is otherwise changed.

By default, saved events are stored indefinitely. You can set a retention period to delete them after a period of time.

# Discarded events

Discarded events are events that show in Iterable menus, but aren't stored when new events of that type are tracked. Historical data is preserved until the event is deleted by its retention policy.

Discarded events have these properties:

• Iterable usage:

  • They can trigger journeys with the Event Occurs entry source
  • You can reference fields from discarded events in messages sent in the Journey, by using Handlebars expressions.
  • Discarded events aren't available in any other Journey tiles (such as Hold Until).
  • Discarded events cannot be used in any other way in Iterable.

• User profile history: You can't view discarded events in a user's profile or export the data. Exception: You can export the data for discarded events that were tracked and saved to user profiles before the event became discarded.

• Aggregate field limits: Discarded events and their fields do count towards aggregate field limits for a project.

• Event volume: Discarded events that were tracked and saved to user profiles before the event became discarded do still count towards the aggregate volume of events in your project, until they are deleted by its retention policy.

• Event retention: Discarded events inherit the retention period that was set before it was changed to the discarded status. This applies to all events of that type which were tracked and saved to user profiles before the event became discarded. You can change the retention period for historical records of a discarded event at any time, and they are not deleted until the retention period is up.

# Deactivated events

Deactivated events are events that are hidden from view in Iterable and are not stored in Iterable when new events of that type are tracked. Historical data is preserved until the event is deleted by its retention policy.

Deactivated events have these properties:

• Iterable usage: Deactivated events cannot be used in any way in Iterable.

• Data export: Deactivated events are not saved and cannot be exported. Exception: Historical data for deactivated events can be exported from your project using the Export API endpoints.

• Aggregate field limits: Deactivated events and their fields do count towards aggregate field limits for a project.

• Event volume: Events that were tracked and saved to user profiles before the event became deactivated do still count towards the aggregate volume of events in your project, until they are deleted by its retention policy.

• Event retention: Deactivated events inherit the retention period that was set before it was changed to the deactivated status. This applies to all events of that type which were tracked and saved to user profiles before the event became deactivated. You can change the retention period for historical records of a deactivated event at any time, and they are not deleted until the retention period is up.

Custom events that trigger journeys or define a dynamic list can't be deactivated because they are still active in your project. To see the journeys and lists that reference you event, go to the overflow menu (three dots) and select View references. Use this information to update the journeys and lists so that they no longer use the event. Once you've done this, you can safely deactivate the event.

# Last seen

The Last seen column shows the most recent time that Iterable saved each event. This value is based on the last time that Iterable received an event with that name. If an event is discarded or deactivated, it does not impact this value.

# Volume

The Volume column shows the total number of times that an event was tracked in Iterable. The volume is based on the date range selected in the Volume date picker at the top of the page.

# References

References reveal where, in Iterable, an event is in use. This helps you locate existing templates and journeys that use the field. Iterable shows the number of lists and journeys that reference each event.

To view references to an event, go to Settings > Data Schema Management, find the name of the event or field, and then use the overflow menu to the right and choose View References. This option is only available when the event is referenced by journeys or lists.

# Trigger Journeys

This column shows a yes or no value indicating whether the event is used to trigger a journey.

If an event does trigger a journey, you can click on the reference count in the References column to view the journeys that reference the event.

# Retention period

By default, Iterable saves tracked events indefinitely. However, Iterable does have overall data storage limits. Event retention defines how long Iterable stores a tracked event before deleting it.

To learn more, read Managing Custom Event Retention.

# Viewing custom event fields

To view the fields for a custom event:

1. Go to Settings > Data Schema Management, and select the Custom Events tab.
2. Find the event you want to add a field to, and click on its name.

# Field types

Iterable supports the following data types for custom event fields:

• string: A text field.
• number: A numeric field that can store whole numbers (integers).
• double: A field that can store decimal numbers.
• boolean: A true/false field.
• date: A date field.
• geo_location: A field that stores latitude and longitude coordinates.
• object: A field that contains nested fields.
• array: A field that contains multiple values of any certain data type.

In the Custom Events tab, you can see the type of each field in the Type column.

For arrays, Iterable displays the data type of the array's elements. For example, an array of strings is classified as string. Any field that contains an array of objects is classified as object.

Important notes:

• A field's data type cannot be changed after it is created. If you need to change a field's data type, you must create a new one.
• Iterable does not support the nested data type for custom events. This field data type is only available for user profile fields.

To learn more about field data types in Iterable, read Field Data Types.

# Field descriptions and sample values

You can add descriptions and sample values to user profile fields to help you understand the data stored in each field. Descriptions and sample values are displayed in the Description and Sample Value columns in Data Schema Management.

To add a description or sample value to a field:

1. Go to Settings > Data Schema Management, and select the Custom Events tab.
2. Find the event you want to add a field description or sample value to, and click on its name.
3. Find the field you want to add a description or sample value to, and hover your cursor over the area where you want to add the text. You can click on Add a Description or Add a Sample Value (only shows if the cursor is hovering over the field).
4. Enter a description or sample value in the text box.
5. Click Save.

# Adding a new custom event

When you want to track a custom event, it needs to be added to your project.

To add a new custom event from the Iterable app:

1. Go to Settings > Data Schema Management and click Define New Event in the Custom Events tab.

2. Enter your desired event name in the Event Name field.

   The event name should be descriptive and easy to understand. For example, if you want to track when a user adds an item to their favorites list, you could name the event addToFavorites.

   To learn about field and event names, validation rules, and best practices, read Best Practices for Field Names and Event Names.

3. Select a Retention Period, which determines how long Iterable stores a tracked event before it is auto-deleted. To learn more about how this works, read Managing Custom Event Retention.

   If you are't ready to decide on a retention period, you can leave it as unlimited and update it later.

4. Click Create Event.

When you create a custom event, Iterable automatically adds a field for the unique user identifier for your project (email or userId), because it’s a required event field.

# Adding fields to a custom event

To add a custom field to a custom event:

1. Go to Settings > Data Schema Management, and select the Custom Events tab.
2. Find the event you want to add a field to, and click on its name.
3. Click New Field.
4. Enter details for the field you're adding:
   • Name: The name of the custom field. To learn about field names, validation rules, and best practices, read Best Practices for Field Names and Event Names.
   • Type: The data type of the custom field. To learn about field data types available in this menu, read Field Data Types.
   • Description: A description of the custom field. For display in Iterable. (optional)
   • Sample Value: An example value for the field. For display in Iterable. (optional)
5. Click Save.

# Adding a nested field to an object in a custom event

Nested fields are data fields specific to a given parent field (object), allowing for deeper levels of data.

For example, you could have a user profile field called address with an object data type and nested fields for street, city, state, country, and zip.

In Data Schema Management, it’s possible to create nested fields in two ways: by adding the nested field directly to the parent field, or by manually entering the nested field by referencing it's parent field name.

You can only add nested fields to parent fields that already exist and have a data type of object.

# Method 1 - Adding directly to the parent field

1. Go to Settings > Data Schema Management, and select the Custom Events tab.
2. Find the event that you want to add a nested field to, and click on its name.
3. Find or create the parent field. It must have a data type of object.
4. On the far right side of the parent field's row, click New Field.
5. Enter the new field's details.
   • Name: The name of the custom field. To learn about field names, validation rules, and best practices, read Best Practices for Field Names and Event Names.
   • Type: The data type of the custom field. To learn about field data types available in this menu, read Field Data Types.
   • Description: A description of the nested field. (optional)
   • Sample Value: An example value for the nested field. (optional)
6. Click Save.

# Method 2 - Adding a nested field with dot notation

You can quickly add nested fields by entering the parent field name followed by a period (.) as a delimiter, and then the new field name, like this: address.city.

1. Go to Settings > Data Schema Management, and select the Custom Events tab.
2. Find the event that you want to add a nested field to, and click on its name.
3. Click New Field.
4. Enter the new field's details.
   • Name: Enter the parent field name followed by a period (.), and
     then the new field name. Example: address.city. To learn about field names, validation rules, and best practices, read Best Practices for Field Names and Event Names.
   • Type: The data type of the custom field. To learn about field data types available in this menu, read Field Data Types.
   • Description: A description of the nested field. (optional)
   • Sample Value: An example value for the nested field. (optional)
5. Click Save.

# Handling unrecognized events and event fields

Sometimes you may need to send a new event definition through API calls or from an integration. This is especially helpful during times when you're developing new marketing solutions.

However, at other times, you may not want new event definitions to be added to your project to avoid clutter and excessive data. You can set your project to drop unrecognized events, or to drop unrecognized events and unrecognized event fields.

To learn more about these settings, read Data Schema Management.

# Creating new event definitions via API

When you send an API call with an unrecognized event name, there are two levels of permission that determine whether the unrecognized event is added to the project or dropped:

• The project must allow unrecognized events to be saved.
• The API key must have permission-it must either be a server-side key, or a client-side key with the Event creation permission. Learn more about this permission in our API Keys guide.

# Deleting tracked events after a period of time

By default, Iterable stores tracked events indefinitely. Over time, this could result in excess data aggregation that can take your account over data storage limits.

You can set a retention period for your custom events that dictates how long Iterable stores tracked event data. When you do this, Iterable automatically deletes events that age out of their retention periods.

To learn more about this setting, read Managing Custom Event Retention.

# Managing event status

By default, every new custom event is a saved event. However, you may decide later that you need different behavior for an event.

You may want to change an event status for various reasons, such as:

• You no longer need to track the event and it doesn't carry any value for your marketing efforts.
• You want to use the event in a journey but don't need to store the data in user profiles for access later.
• You want to keep past event data for historical purposes, but no longer need to track new events with that name.

To keep your workspaces tidy and to make it easy for your marketing team to find the events they’re looking for when setting up segmentation, journeys, or other event-related features, carefully consider the custom events you include in a project and how you make existing events available to your marketing team in Iterable.

Iterable provides several ways to manage events when they are no longer needed:

• Discarding an event stops data collection of new events but keeps historical data.
• Deactivating an event stops data collection and hides the event from view.
• Using retention periods to delete tracked events after a period of time limits the amount of aggregate data stored in your account.

To change an event status:

1. Go to Settings > Data Schema Management, and select the Custom Events tab (if it isn't already selected).
2. Find the event you want to change the status of.
3. Go to the overflow menu (three dots), and select the event status you want to change to.
4. Click the confirmation button to complete the change.

To learn about using retention periods to delete tracked events after a period of time, read Managing Custom Event Retention.

# Want to learn more?

For more information about some of the topics in this article, check out this Iterable Academy course. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

• Product Bite: Data Schema Management Tools