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 events are organized in tabs based on their event handling options:

• Saved - Events that show in Iterable and are tracked on user profiles.
• Discarded - Historical events that show in Iterable, but are not saved on user profiles.
• Deactivated - Events that are hidden from view and not saved in Iterable.

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

# 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.
• nested: A field that contains nested objects that are indexed in a specific way.
• 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.

Note that Iterable doesn't have a function for changing a field's data type.

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.

# Managing events that are no longer relevant

To keep your workspaces tidy and to make it easy for users to find the values 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 users 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.
• Deleting tracked events after a period of time limits the amount of aggregate data stored in your account.

# Discarding an event

A discarded event displays in your Iterable workspaces, but Iterable stops tracking new events with that name.

Discarded events are still processed in Iterable's backend. This means that you can use them in journeys, but you can't view them in a user's profile or export them.

Discarded events and discarded event fields count towards aggregate field limits (8000 for custom event fields). Events that were tracked and saved to user profiles before the event became discarded are still counted towards the aggregate volume of events in your project.

To discard an event, go to the field in Data Schema Management, go to the overflow menu (three dots) and select Discard.

To view all of your discarded events, go to the Custom Events > Discarded tab in the Data Schema Management screen.

# Deactivating an event

When you're done using an event in your project and you no longer need to collect new data, you can deactivate the event. This removes it from view in Iterable and stops collecting event data in your project.

Deactivated events and their event fields count towards aggregate field limits (8000 for custom event fields). 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.

To view all of your deactivated events, go to the Custom Events > Deactivated tab in the Data Schema Management screen.

To deactivate an event, go to the overflow menu (three dots) and select Deactivate event.

Custom events that are used to trigger journeys or to define a dynamic list can't be deactivated. 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.

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

# 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