Computed Field Values | Yext Hitchhikers Platform
This doc references the Computed Field Values feature from the Spring ‘23 Release. To turn this feature on in your account, navigate to Account Settings > Account Features and select the following features:
- Preview Feature: Computed Field Values
- Improvements to Computed Fields
- Built-in Fields in the UI
Computed Field Values (aka Computed Values) allows businesses to configure an algorithm to automatically populate the value for a particular field on an entity.
In order for a field to have its value computed, a user must define a computation method for that field. This configuration is part of the field definition, in the same way that the display name, tooltip, and validation are a part of the field definition.
Computation methods can be defined for any built-in or custom field. Once a computation method has been defined for a field, the computation must be triggered in order for a new value to be computed. Today, a computation can be triggered via Entity Edit (by clicking the wand icon), or by changing the value of a field that the computation depends on.
By default, a field does not have any computation method, meaning that the field’s value must be populated explicitly for each entity.
Computation Methods
Yext Content offers a library of computation methods which can be selected to compute a field’s value. This list currently consists of a number of content generation-based methods. When configuring a computation method for a field, you will see the full list of supported methods included in the dropdown. More details on each method are provided.
Supported Field Types Per Method
Each method has a designated set of supported field types. A computation returns structured data, and this data must be compatible with the type of the field for which it is selected. As such, computation methods can only be selected for a given field if the field is of a type included in the method’s supported field types.
Supported Methods
There are a number of built-in computation methods with predefined algorithms and expected inputs. You have the option to provide additional instructions to these pre-defined computation methods to tailor it to your specific use case, although this is not required.
Method | Description | Supported Field Types |
---|---|---|
Write Web Page Body Content (Markdown) | Generates standard body content for a webpage given a set of input information, such as the topic, length, and structure details. Returns Markdown. | Rich-Text (v1), Markdown |
Write a Business Description | Generates a business description. Excludes URLs. Effective for locations. | Single-line Text, Multi-line Text, Rich-Text (v1), Markdown |
Write a Blog Post (Markdown) | Generates a blog post given inputs such as the topic and details about the structure. Returns Markdown. | Rich-Text (v1), Markdown |
Write a Bio for an Individual | Generates a biography for an individual. | Single-line Text, Multi-line Text, Rich-Text (v1), Markdown |
Write a Generic Description | Writes a description for any entity type. Flexible and effective for use cases such as product descriptions, feature descriptions, promotion descriptions, etc. | Single-line Text, Multi-line Text, Rich-Text (v1), Markdown |
Write a Web Page Meta Description | Writes a Meta Description for a Web Page. Intended to be used in the
<meta></meta> tags
tags for an HTML Web Page. |
Single-line Text, Multi-line Text, Rich-Text (v1), Markdown |
Summarize Content | Summarizes text, given a desired length as an input. | Single-line Text, Multi-line Text, Rich-Text (v1), Markdown |
Rewrite Content | Rewrites text using different prose. | Single-line Text, Multi-line Text, Rich-Text (v1), Markdown |
Custom Generative Prompt | Write a custom prompt for a generative model. Include any inputs you like. Allows users to write custom instructions to generate content. Include as much detail as is necessary to service your use case. | Single-line Text, Multi-line Text, Rich-Text (v1), Markdown, Date, Boolean, Number |
Inputs
When a computation is triggered for an entity, the execution of that computation will receive a set of parameters, known as inputs. You can think of inputs as the user-defined data that is passed to the program as it is executing.
For an example input configuration, visit the Leverage Computed Field Values guide.
Required vs. Optional Inputs
For each built-in computation method, there is a defined list of inputs that a user can provide during configuration. These inputs are either Required or Optional.
- Required Inputs: Users must provide values for these inputs in order to save the configuration. Additionally, the computation cannot be executed for a particular entity profile if the value of a required input is not populated.
- Optional Inputs: Users can choose to provide values for optional inputs. If a value is not provided, or the value for a field input is null when executing for a particular entity profile, the input will not be passed to the computation when it is executed.
Static vs. Dynamic Inputs
There are two categories of inputs:
- Static Inputs: These are defined statically as part of the computation method configuration. Every time the computation is executed, it will receive the exact value you have provided as a static input.
- Dynamic Inputs (aka Field Inputs): For a given input, users can reference a field using the embedded field syntax , making that input dynamic. When referencing a field as an input, the system will take the field value from the profile for which the computation is being executed and pass that value as part of the computation execution. Dynamic field inputs ensure that the data being passed to your computation is relevant to calculate the value for the entity in question.
Using Fields as Dynamic Computation Inputs
In order to reference fields in computation inputs, users specify the Field ID in the familiar double-bracketed notation, as they would when embedding fields on entities. However, the set of fields which can be used in computation inputs is a superset of what can be used on entities, and there are some other notable differences. This section will outline the specifics around using fields in computation inputs.
Supported and Non-Supported References
Input Field Embeds do support:
- All built-in and custom fields of a primitive type (e.g., strings, numbers, booleans)
- Fields using the Markdown type, using the following notation:
[[c_markdownField.markdown]]
- All list fields and list properties of objects containing primitive types, as a delimited list
- All properties of built-in and custom structured fields, to any depth (as long as each path contains a single item, and the final item is a primitive type or list of primitive types)
Certain meta properties, which can be referenced by prefixing the property with
meta
(e.g.,[[meta.entityType]]
). These properties include:accountId
countryCode
entityType
id
language
timestamp
uid
Input field embeds do not support:
Inputs from fields on entities referenced via Entity Relationships
- For example, if a Doctor entity has an Entity Reference field linking to a Location entity, you cannot embed any field data that’s stored on the linked Location to be used as an input to generate a field value on the Doctor entity.
Values from lists of structured objects
Fields using the Rich Text v2 type
Fields and properties which are themselves structured objects
- As covered above, you can reference the properties of these objects as long as the properties are of acceptable types.
Non-profile fields, including:
- Labels
- Folder ID
- Google Attributes
- Categories
- ECLs
Syntax and Default Display Values
Field inputs are accessed by including the Field ID in the familiar bracketed notation (i.e., [[address.line1]]
). The paths to each field match the Entities API format. Any field (including meta fields) available in the Entities API which matches the criteria above can be used as an input.
Rendered Value Options
The rendered value will generally appear in the same way as it appears in the API JSON format (not including the JSON-syntax-like quotes). However, for some value types, one or more additional “display” formats may be supported in order to better flow with natural language prose.
For example, the API format of a phone number is the non-localized E.164 format (e.g., +12125551234
) but the preferred display format for most use cases is the number’s national format, e.g., (212) 555-1234
in the US.
By default, the API format will be rendered. Note that this is different from profile field embed behavior, where most fields will return a localized format by default.
Certain value types for input field embeds support formatting cues that allow you designate a rendered format different from the default. These formatting cues are added as suffixes to the input embed syntax. As in the example above, adding the suffix $national
to the embed syntax [[mainPhone.$national]]
will render the value in the preferred display format.
Formatting cues supported by each type are summarized below.
Value Type | Cue | Description | Example Syntax | Example Value |
---|---|---|---|---|
Option Values (paymentOptions, c_optionField) | $display |
Localized option display name, rather than programmatic enum value | [[c_availableColors.$display]] |
Blue, Green |
Phone Numbers (mainPhone, etc.) | $national |
Country-dependent national format, rather than E.164 international format | [[mainPhone.$national]] |
(212) 555-1234 |
Country Codes (address.country, meta.countryCode) | $display |
Localized country display name rather than ISO country code | [[address.countryCode.$display]] |
United States |
Numeric Types (c_decimal, etc.) | $display |
Localized numeric display format (digit grouping and decimal point) rather than raw numeric value | [[c_bigNumber.$display]] |
100,456,211 |
Locale Code (meta.language) | $display |
Localized language name rather than locale code | [[meta.language.$display]] |
English |
Localization of Dynamic Inputs
Dynamic inputs are localized when a field value is computed on an alternate language profile. If the referenced field has a localized value for a given language profile, the localized value will be sent in the prompt when the computation is triggered.
For example, referencing the [[name]]
field as an input to compute the body of a blog post will localize the value for [[name]]
to the profile that is being computed.
Today, static inputs cannot be localized. Learn more below about the current possibilities and limitations for multilanguage profiles.
Input Validation
Each input has a set of validation defined by the system. When attempting to compute a value, if the value used for the input is invalid according to that validation, the computation will not be executed.
For example, for the Summarize Text Computation Method the Text to Summarize input has a maxLength of 5,000 characters. When configuring this method, I might choose to embed some field [[c_longTextBody]]
for this input. However, if the value for that [[c_longTextBody]]
field on a particular entity was >5,000 characters, the system would not compute the value, since that input field would be invalid according to the input constraints.
Computation Triggers
Once a computation method is configured for a field, the actual computation must be executed (or “triggered”) for a particular entity profile. Today, there are two supported mechanisms to trigger a computation:
Manually via Entity Edit
- For a single entity at a time, click the wand when editing a field with a Computation Method
Automatically, on an ongoing basis, when the value of a dependency ( Dynamic Field Input ) changes.
- In order to prevent unapproved or undesired computations from writing directly to the profile, all generated content will flow through Suggestions, by default.
For instructions on how to trigger a computation for a field, visit the Leverage Computed Fields guide.
We plan to support a number of additional triggers in future releases. Please see the Limitations & Future Improvement section for more details.
Ongoing Computations for Alternate Language Profiles
If the value of an input on a given language profile is changed, then a computation will be triggered for that profile.
This means that, for computed fields that are overridable or locale specific:
If the input field is also overridable or locale specific, the alternate language profile will only recompute if that language profile’s input field value changes, using the localized input value.
If the input field is primary only, a field update will also trigger a computation on alternate language profiles, and this value will not match that of the primary profile of the computed field, for non-deterministic computations (like Content Generation with AI). Even if the same input values are provided in the prompt for each language profile, separate computations are initiated for each profile and therefore subject to output varying responses.
System Controlled Setting
Optionally, a computation method can be set as “System Controlled.” This setting changes the behavior in that:
- When a computation is triggered automatically, the computed value will write directly to the entity profile.
- Users will not be able to edit the value of this field (nor manually trigger a computation).
Allowing the system to control the value of the field is not recommended for Content Generation, as it implies that the AI is entirely trusted to generate a value with no human approval or edits.
We recommend that all content generated with AI is reviewed by a human. For this reason, all automated computations (as triggered by a change in an input field value) will flow through the Suggestions workflow, by default. The content can be approved, modified, and/or rejected, as with any suggested content.
Access Controls and Required Subscriptions
There are a number of access controls to consider which may impact your access to computed field values, and associated functionality such as content generation.
Account Feature
In order to use Computed Field Values, the Preview Feature: Computed Field Values must be turned on in your account. This feature can be turned on via Account Settings > Account Features by any user with sufficient permission.
With this feature disabled, there will be no functionality related to computed field values available in an account.
Once the feature is set to be promoted from Preview, the Account Feature will be enabled at General Availability of the next release.
Subscription
The use of content generation in Yext requires the purchase of a Content Generation subscription, which grants a capacity of words generated to an account. Without purchasing this subscription, users will not be able to configure a computation method which relies on Content Generation; these computation methods will appear as locked in the Field Configuration UI.
At this time, all computation methods currently supported are based on Content Generation, so the current computed field values functionality will be unavailable without the purchase of a Content Generation subscription.
In the future, when we introduce computation methods which do not rely on Content Generation, accounts without a Content Generation subscription will still be able to leverage any methods which do not rely on Content Generation.
User Permissions
Any user with access to Manage Custom Fields will have permission to configure computed field values.
Any user with access to Edit Items With Approval or Edit for a field with a computation method defined will see the button to compute that field’s value in Entity Edit. The user’s ability to save the computed value will remain consistent with their permission on that field.
Configuration as Code
Computed field values are configured as part of the field definition. As such, computed field values can be configured via Configuration as Code, as part of the field resource .
Supported Computation Methods - Input Reference
The following tables detail the list of inputs for each supported computation method.
Write Markdown Web Page Body Content
Input Name | ID (CaC) | Type | Validation |
---|---|---|---|
Web Page Topic | topic | Single-line text | Maximum Length = 255 characters |
Desired Length | length | Single-line text | Maximum Length = 25 characters |
Number of Headers | numHeaders | Number | Maximum Value = 10 |
Number of Paragraphs per Header | numParasPerHeader | Number | Maximum Value = 5 |
Number of Sentences per Paragraph | numSentencesPerPara | Number | Maximum Value = 10 |
Additional Information | additionalInformation | Multi-line text | Maximum Length = 2,000 characters |
Additional Prompt Instructions | additionalInstructions | Multi-line text | Maximum Length = 2,000 characters |
Write a Business Description
Input Name | ID (CaC) | Type | Validation |
---|---|---|---|
Blog Post Topic | topic | Single-line text | Maximum Length = 100 characters |
Desired Length | length | Single-line text | Maximum Length = 25 characters |
Number of Headers | numHeaders | Number | Maximum Value = 10 |
Number of Paragraphs per Header | numParasPerHeader | Number | Maximum Value = 5 |
Number of Sentences per Paragraph | numSentencesPerPara | Number | Maximum Value = 10 |
Additional Information | additionalInformation | Multi-line text | Maximum Length = 2,000 characters |
Additional Prompt Instructions | additionalInstructions | Multi-line text | Maximum Length = 2,000 characters |
Write a Bio for an Individual
Input Name | ID (CaC) | Type | Validation |
---|---|---|---|
Occupation | occupation | Single-line text | Maximum Length = 255 characters |
Business Name | name | Single-line text | Maximum Length = 255 characters |
City | addressCity | Single-line text | Maximum Length = 255 characters |
Region | addressRegion | Single-line text | Maximum Length = 255 characters |
Country | addressCountry | Single-line text | Maximum Length = 255 characters |
Background | background | Single-line text | Maximum Length = 5,000 characters |
Certifications | certifications | Single-line text | Maximum Length = 1,000 characters |
Areas of Expertise | areasOfExpertise | Single-line text | Maximum Length = 1,000 characters |
Years of Experience | yearsOfExperience | Single-line text | Maximum Length = 255 characters |
Hobbies | hobbies | Single-line text | Maximum Length = 1,000 characters |
Interests | interests | Single-line text | Maximum Length = 1,000 characters |
Additional Information | additionalResumeInfo | Multi-line text | Maximum Length = 2,000 characters |
Additional Prompt Instructions | additionalInstructions | Multi-line text | Maximum Length = 2,000 characters |
Desired Maximum Length | maxLength | Single-line text | Maximum Length = 25 characters |
Write a Generic Description
Input Name | ID (CaC) | Type | Validation |
---|---|---|---|
Subject Type | subjectType | Single-line text | Maximum Length = 255 characters |
Subject Details | subjectDetails | Single-line text | Maximum Length = 20,00 characters |
Additional Prompt Instructions | additionalInstructions | Multi-line text | Maximum Length = 2,000 characters |
Desired Maximum Length | maxLength | Single-line text | Maximum Length = 25 characters |
Write a Web Page Meta Description
Input Name | ID (CaC) | Type | Validation |
---|---|---|---|
Web Page Topic | topic | Single-line text | Maximum Length = 255 characters |
Additional Information | additionalInfo | Multi-line text | Maximum Length = 2,000 characters |
Additional Prompt Instructions | additionalInstructions | Multi-line text | Maximum Length = 2,000 characters |
Summarize Content
Input Name | ID (CaC) | Type | Validation |
---|---|---|---|
Text to Summarize | textToSummarize | Single-line text | Maximum Length = 5,000 characters |
Desired Maximum Length | maxLength | Single-line text | Maximum Length = 25 characters |
Additional Prompt Instructions | additionalInstructions | Multi-line text | Maximum Length = 2,000 characters |
Rewrite Content
Input Name | ID (CaC) | Type | Validation |
---|---|---|---|
Text to Rewrite | textToRewrite | Single-line text | Maximum Length = 5,000 characters |
Output Format | outputFormat | Single-line text | Maximum Length = 100 characters |
Additional Prompt Instructions | additionalInstructions | Multi-line text | Maximum Length = 2,000 characters |
Custom Generative Computation
Input Name | ID (CaC) | Type | Validation |
---|---|---|---|
Prompt | prompt | Multi-line text | Maximum Length = 5,000 characters |
Maximum Tokens | maximumTokens | Number | Maximum Value = 2,000 |
Prefix | prefix | Multi-line text | Maximum Length = 2,000 characters |
Limitations & Future Improvements
As a Preview Feature, there are a number of known limitations with the computed field values system. If you think any of these features would be particularly useful for your use cases, or you have ideas for other improvements, feel free to submit to the Ideas board .
Usage Tracking Not Visible in Platform
Content generation capacity is tracked in terms of words generated. At this time, usage is not currently available in the Platform Usage UI. As such, accounts may see that their usage of content generation is temporarily 0, even after using some capacity.
Shortly following the release, we will begin surfacing usage in the Platform Usage UI. At this time, usage will be backfilled, so any existing usage will be counted towards allotted capacity.
Limited Trigger Support
The list of supported triggers is limited currently to Entity Edit. The implication of this limitation is that at this time, there is no mechanism to trigger computations across multiple entities at once, or on an ongoing basis.
In the future, we plan to expand the scope of supported triggers. We will be initially focusing on the following triggers:
- Ongoing: The system will automatically recompute the value for a field any time the value of an input field is modified.
- Bulk: The system will support re-computing the value for a field across multiple entities at once. This operation will be common when first configuring a computation method for a field, or when modifying the configuration, as a mechanism to backfill existing entities.
Limited Computation Method Support
The current list of supported computation methods is limited to only content generation-based methods.
In the future, we plan to extend the list of supported methods to include:
- Additional Content Generation based methods, based on common and popular customer use cases
- Built-in algorithmic methods which do not rely on Generative AI. Some examples include:
- Embedding and transforming strings
- Geocoding Addresses
- Fetching nearby entities in Content to populate relationships
- Invoking a Function: To support any use cases for which we do not have a pre-built solution, we will support customizing a method by writing a function on our Serverless Functions infrastructure.
Field Availability
Custom Fields Only
Currently, users can only configure a computation method for custom fields. The technical reason for this limitation is that the Computed Field Value Configuration is a part of a field’s definition. While custom fields are defined within the scope of an account, built-in fields are defined globally, meaning that their configuration is shared across all Yext Accounts. As such, there is currently no mechanism to define a computation method per account for built-in fields.
We realize this limitation is inconvenient for businesses leveraging Listings, since built-in fields sync to Listings. In the short-term, there are a few workarounds:
- Create a custom field to define your computed field value, and then embed that custom field into your built-in field. The drawback of this option is that it might be cumbersome to ensure that embeds are always properly populated across Yext Content.
- Modify your Publisher Configuration to map a custom field instead of the default built-in fields. Please note that customizable publisher configurations are only available for Google, Facebook, and Yelp, but we plan to continue to expand support to more publishers over time.
No Support for Lists or Objects
Currently, users can only leverage computed field values for fields which are not List or Object types. The full method-by-method list of supported types is included above.
In the future, we plan to support defining computation methods for List and Object field types. The data returned by the computation will still need to match the type of the selected field.
For Object field types, we also plan to support defining a computation method for each individual subfield. This functionality will ensure that businesses can leverage different logic for different properties of object fields.
Localization
Currently, the computed field values system is limited in its ability to support multiple different languages for a single Computed Field Value. Computations are optimized for English, though it is possible to configure a computation in another language.
When computing a value for a particular Entity Profile (also known as a language profile), any dynamic inputs will be resolved to the field values on the profile in question. For example, if the computation inputs include [[name]]
and [[description]]
:
- When a value is computed for an English profile, the name and description for that English profile will be passed to the computation
- When a value is computed for a Spanish profile, the the name and description for that Spanish profile will be passed to the computation
However, for any static inputs, the system only has access to the static string provided by a user. Thus, in order to support localized static inputs, the user needs to be able to provide these localized inputs (assuming the input value in question should be localized).
Additionally, all the existing computation methods have execution logic optimized for English. For content generation-based methods, through the additional prose instructions, a user could technically instruct the system to output content in a different language (even dynamically, based on the locale of the profile in question). However:
- The method might not perform as well as if the rest of the execution logic was optimized for that language
- Any static inputs will not be localized
In order to successfully support computing values for entities in many different languages, we therefore need to support:
- Localizable Inputs
- Language-specific computation execution logic
We plan to add support for these features in the future.
No Relationship Support in Inputs
The system does not currently support traversing across entity relationships for input values. This limitation means that only fields on the entity in question can be used as inputs. In a future release, we will support inputs from related entities, to maximize the flexibility of using existing content as inputs to computations.
No User-Facing Logs
At this time, we do not have computation logs included in the UI or API. In the future, we plan to surface logs for all computations, so a user can easily investigate each computation that is executed, including the inputs and response of the computation.