Computed Field Values | Yext Hitchhikers Platform

hitchhiker's thumb
New Release Feature

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

book
Note
Aside from the computation methods which specify “Markdown” in the name, the expected behavior will be that the method returns plain text. These methods are available for Rich-Text (v1) and Markdown field types since plain text is allowed in those fields, but leveraging one of these methods for a formatted field will not return formatted content (without additional instructions to do so).

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:

  1. Manually via Entity Edit

    • For a single entity at a time, click the wand when editing a field with a Computation Method
  2. 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:

  1. When a computation is triggered automatically, the computed value will write directly to the entity profile.
  2. 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.

Feedback