Special Field and Field Type Behavior | Yext Hitchhikers Platform
Certain fields and field types that expect a certain input format in order to correctly map to field values. This behavior is outlined below.
Field Type Behaviors
Entity Relationship
Mapping to an Entity Relationship field requires the value to be that of an existing, valid Entity ID.
If the referenced Entity ID does not exist in your account, the field update will be ignored, but any other updates to the same entity will still be processed This will be displayed as a warning diagnostic in the etl_diagnostics.csv file.
If the referenced Entity ID matches an entity that is not a valid reference (i.e., the Enitty ID is that of a Restaurant entity type, but only Product Entity Types are valid on the field), the entire entity update will fail. This will be displayed as an error in the entity_diagnostics.csv file.
List
Mapping to a List field assumes that the contents of the list are a comprehensive data set.
The connector data will overwrite the entire list. We do not yet support appending items to the end of a list. For example, if there are five items in the existing list field, and only one single item is mapped to the list, that item will be ingested as the comprehensive list value, with the prior existing items all removed.
If any item in the list is considered invalid, the entire entity update will fail.
There are two ways to map a column to a list field: as an entire list or as an individual list item.
Mapping to an entire list: If mapping to the entire list, all items must be comma separated.
Mapping to an individual list item: If mapping to an individual list item, any commas within the value will not be interpreted as a separator. The entire value will be considered a single list item.
This behavior can be thought of as allowing the connector to construct a list using items in multiple columns. Mapping columns to individual list items works well for:
- List items that might contain commas.
- Data sources that return each list item as a separate column via the connector.
When mapping to a List field, you must map to the API name of the field (as opposed to the display name) in order to correctly pass data to the field.
Option (Multi- or Single-Option Select)
You must always use the External ID when ingesting data via the connector. Using a display name will result in an invalid type option. To find out the External ID of your options, navigate to Field Settings and view the name in parentheses under Validation > Available Options.
Yes/No (Boolean)
You must use values of the following format:
TRUEortrueFALSEorfalse
Categories
Categories can be mapped to either the Base Category List (e.g., Yext) or to a publisher as overrides. In order to successfully map your Categories, you must provide the correct API/ID as stored in our system.
- To map to Yext categories, you must provide the numerical Yext ID.
- To map to a publisher’s categories, you must provide their API name (e.g., for Google Business Profile, you must use the GBP ID, such as
gcid:accountant. See the Google Business Profile reference for a list of Google categories).
To transform ingested Publisher IDs to correct Yext IDs in order to map to the Base (Yext) list, use the Map Publisher Categories Transform .
For more information on Category behavior in Connectors, see the Categories reference .
Country Codes
When creating a new entity, the Country Code can be set by mapping to either Country Code or Address > Country Code.
- If both Address and Country Code are provided, the values must match.
- If neither are provided, the country code of the new entity will default to the country of the Yext account.
If the Country Code field is mapped on an entity that already exists:
- The Country Code mapping is not required.
- The value(s) for
Country Codeand/orAddress > Country Codemust match the value for Country Code that is already on the entity already. This means the Country Code cannot be updated once the entity is created.
Folders
In order to map to folders, you can use the folder’s display name. There are two ways to map to a specific folder:
- Folder Name (e.g.,
TestFolder1) - Folder Path (e.g.,
Parent Folder > Folder1 > TestFolder1)
If there are multiple subfolders in your account with the same name, you must use the Folder Path option. Otherwise, the update will fail as our system will not know which subfolder to map to.
You cannot currently create a new folder via the connector flow. You must map to a folder that already exists in the account.
Labels
Map to new or existing labels using a label display name. Just as with List fields, the entire list of labels provided in the mapping will be assumed to be comprehensive, and will overwrite any existing labels on the entity.
If an item in the list does not match that of the display name of an existing label, a new label will be added to the account and applied to the entities with that label.
If an item in the list matches the display name of an existing label, that existing label will be applied.