Iterable identifies fields and events by name, which is a unique and case-sensitive string. Iterable displays the field’s name as a label in Iterable workspaces (journeys, segmentation, etc) as well as for data processing operations. Continue reading to learn more about Iterable’s validation rules for field and event names, as well as best practices for naming fields and events.
In this article
Why field and event names matter
Mistakes with event names, including case-sensitivity, can result in problems such as users not entering a journey or not being members of a dynamic list they should belong to.
For example, if an event with the name orderShipped is sent to Iterable with
the name OrderShipped, it is treated as an unrecognized event. A journey that
uses the event orderShipped doesn't interpret the inbound events with the
name OrderShipped as the same event. Users who had their event tracked with
incorrect event name do not enter the journey.
Field and event names cannot be changed. Because of this, it’s important to be intentional.
Field and event name validation
When you create an event or field from Data Schema Management, some validation rules apply to its name:
- Can’t be just numbers (like “54321”)
- Can’t begin with an underscore character (“_”)
- Can’t contain comma (“,”) or hashtag (“#”) characters
- May contain a period (“.”), but only when you’re adding a nested field to an object
These validation rules don’t apply when you create fields or events using Iterable’s API. If you need to bypass these rules, you can create fields and events using the API and then manage them later in Data Schema Management.
Best practices for naming fields and events
In addition to meeting Iterable’s validation criteria, consider these best practices when naming your fields and events:
Be consistent. Naming fields in the same pattern or set of rules creates predictability and ease of use. Understand what your company’s standard data practices are, and apply them consistently when creating new fields. Use a pattern that considers how to handle fields with one or more words, as well as whether to include non-alpha characters, like numbers or an underscore (“_“). To learn some common patterns for naming data fields, read Programming Naming Conventions (FreeCodeCamp).
-
Avoid creating duplicates. Once you create a field or event, you can’t change its name or delete it from Iterable. Search for an existing field before creating a new one.
To prevent confusion, avoid creating fields and events with the same names and/or the same purposes as system fields and events.
For example, shopping cart updates and purchase events are best tracked using Iterable's Commerce APIs rather than generating your own event name. To learn more, read Managing Commerce Events and Shopping Cart Items.
Don’t use periods as a space between words. Iterable uses periods to denote nested fields in Handlebars. Naming a field or event with a period creates ambiguity in your data and can lead to unpredictable results when accessing or updating data fields.
Avoid using spaces. Field names may contain a space (“ “), but this isn’t a best practice because it introduces complexity when it’s time to use the field. If a field or event name does contain a space, it needs special attention when creating Handlebars expressions. To learn more, read Personalizing Templates with Handlebars.
Don't give events the same name as an Iterable system event. If you do, you'll run into errors when you try to reference the custom event in a journey filter tile or segmentation query.