In Experience Data Model (XDM), a string field can be given a predefined set of accepted or suggested values to better control what values are ingested into that field or how it will behave in segmentation.
Enums constrain the values that can be ingested for a string field to a predefined set. If you attempt to ingest data to an enum field and the value does not match any of those defined in its configuration, ingestion will be denied.
In contrast to enums, the Suggested values option allows to to denote a set of recommended values for a string field that do not constrain the values that it can ingest. Instead, suggested values affect what predefined values are available in the Segmentation UI when including the string field as an attribute.
This document covers how to define enums and suggested values in the Schemas UI workspace. For a quick overview on enums and suggested values, including how to configure them in the UI and their downstream effects, watch the following video:
With the September release there will be an enhanced enum and suggested value workflow. Enumerated fields are used when you want to restrict data values coming in on ingestion. For example, if I want to bring in only male, female, or unspecified on a gender field, I could use an enumerated field to restrict data coming in to just those three values. Suggested value fields are used either in conjunction with enumerated fields or as a standalone configuration. Suggested values allow you to build a list of possible values that the data may or may not adhere to, but will surface as a friendly dropdown list in the segmentation UI. Let’s take a look at the capabilities in action.
Here I am in my experience event billing information schema. I can now see the suggested values that are included on the standard event type field. I select event type and see all the event types that are included.
I also have the flexibility to add additional suggested values, which will show in my segmentation dropdown. I want the marketer to be able to segment on billing complete, so I will add that to my list of event types.
I want to track payment setup, whether it’s automatic or manual by the user. On my custom payment setup method field, I will add a suggested value to capture these two options. I will add suggested value and add automatic and manual.
Downstream, the marketer will be able to easily segment by manual or automatic payment setup method. Last, I want to add a suggested value list on a standard field. I want to track whether login status is not started, pending or complete. I’ll go to the login status field and I have the option to add a suggested value. I will add not started, pending and complete as options that the marketer will be able to segment on. Let’s take a look at what it looks like downstream for the marketer. Now you can see when the marketer goes to build a segment, they can add that login status field to a segment and easily segment on the values we added to the suggested value in the schema UI. They have the option to choose complete, pending or not started, but they can also just type in an additional value and use that as well. These are just suggested values, they’re not locked into just those three. Thanks for watching this demo. -
Select Enums and Suggested Values, then select Enums. Additional controls appear, allowing you to specify the value constraints for the enum. To add a constraint, select Add row.
Under the Value column, you must provide the exact value you want to constrain the field to. You can optionally provide a human-friendly Display Name for the constraint as well, which affects how the value will be represented in segmentation.
Continue to use Add row to add the desired constraints and optional labels to the enum, or select the delete icon () next to a previously added row to remove it. When finished, select Apply to apply the changes to the schema.
The canvas updates to reflect the changes. When you explore this schema in the future, you can view and edit the constraints for the enum field within the right rail.
Select Enums and Suggested Values, then select Suggested Values to make additional controls appear. From here, select Add row to start adding suggested values.
Under the Display Name column, provide a human-friendly name for the value as you want it to appear in the Segmentation UI. To add more suggested values, select Add row again and repeat the process as needed. To remove a previously added row, select next to the row in question.
When finished, select Apply to apply the changes to the schema.
There is an approximate five-minute delay for a field’s updated suggested values to be reflected in the Segmentation UI.
Some fields from standard XDM components contain their own suggested values, such as
eventType from the XDM ExperienceEvent class. While you can create additional suggested values for a standard field, you cannot modify or remove any suggested values that are not defined by your organization. When viewing a standard field in the UI, its suggested values are displayed but are read-only.
To add new suggested values for a standard field, select Add row. To remove a suggested value that was previously added by your organization, select next to the row in question.
After a schema with an enum field has been used to ingest data into Platform, any further changes made to the schema definition must comply with the data already in the system. In general, changes made to an existing field can only make that field less restrictive. An field cannot be made more restrictive than it already is.
When it comes to enums and suggested values, the following rules apply post-ingestion:
If multiple schemas use the same enum field with different configurations, and those schemas are included in a union, certain rules apply when it comes to how enum differences are reconciled. The exact rules depend on whether the schemas referencing the same standard field (like
eventType) or if they’re referencing the same custom field path in different field groups.
If referencing the same standard field:
If referencing the same custom field path in different field groups:
Due to current system limitations, there are two cases where an enum is not validated by the system during ingestion:
This guide covered how to define enums and suggested values for string fields in the UI. For information on how to manage enums and suggested values using the Schema Registry API, refer to the following tutorial.
To learn how to define other XDM field types in the Schema Editor, see the overview on defining fields in the UI.