Step 9: Managing Downstream Integrations

Downstream integrations are any system that reads data from a field. If any downstream integrations reference a Legacy Rich Text field, you will need to update it so that it references the new forked field.

Content Delivery API

Your Content API is configured via your Content Endpoint. On your Content Endpoint, you will have defined a Stream which determines how the data will be indexed. We now will add your new field to your Stream configuration and thus it’ll be delivered via your Content Endpoint.

If you have many content endpoints and aren’t sure which of those reference your Legacy Rich Text fields, it may be easier to edit your Stream configuration via the Admin Console or the Yext CLI.

Content Endpoints

To edit your Stream configuration from within the Yext platform:

1. Navigate to Developer > Content Endpoints.

2. To add a field, click Configure on the Stream you want to add the field to. Then, click Add Fields and enter the name of the new field.

3. If you are adding a Markdown field, choose one of the following:

   • If you are planning to receive this content as Markdown, select {fieldID}.markdown.
   • If you are planning to receive this content as HTML, select {fieldID}.html.

4. If you are adding a Rich Text (v2) field, choose one of the following:

   • If you are planning to update your application to process the JSON AST directly, select {fieldID}.json.

   • If you are planning to receive this content as HTML, select {fieldID}.html.

   • Note you can’t include both the top level field and subfields of that field in the same stream. If you want to use the HTML of a field, only include {fieldID}.html and not {fieldID}.

5. Click Add Fields, and then Save.

Entities Management API and Content Delivery API

By default, the Entities Management API and Entities Content Delivery API will return the native storage format of the field, which is the JSON AST. If you wish to begin processing this AST directly, you will need to update your application to handle this new field and data format.

If you do not wish to handle the AST directly in your application, you can use the convertRichTextTo query parameter in your API request. To do this, pass convertRichTextToHTML=true to receive the data converted to HTML.

Pages

Your next steps will vary based on whether you are using a Markdown or Rich Text (v2) field and what kind of Pages experience you are leveraging.

Pages v2 - React

1. Update your Stream definition to include the new field.

2. Install the @yext/pages-components library (npm i @yext/pages-components) if you haven’t already. Import the LexicalRichText component:

   import { LexicalRichText } from "@yext/pages-components";

   Here is a simple example of the component:

   <LexicalRichText serializedAST={JSON.stringify(c_richTextDescriptionV2.json)} />

3. Remove the reference to the old field.

Pages v2 - Handlebars

1. Update your Stream definition to include the new field.
2. Add in a transform to your Stream definition to ensure that the JSON AST is converted to HTML.
3. Replace the reference in your code to the new field.

4. Remove the helper that converts Yext-flavored Markdown to HTML.

   {
     ...
     "transform": {
       "richTextToHTML": [
         "field3"
       ]
     }
   }

Search

Your next steps will vary based on whether you are using a Markdown or Rich Text (v2) field and what kind of Search experience you are leveraging.

Backend Configuration

1. Navigate to Search > [[Your Experience]] > Edit as JSON.

2. Add a top-level config property to convert rich text to HTML.

   • For Rich Text v2 fields, the richTextV2ToHTML property needs to be set to true.

   • For Markdown fields, the markdownToHTML property needs to be set to true.

     {
     "$schema": "https://schema.yext.com/config/answers/answers-config/v1",
     "$id": "test",
     "name": "test",
     "verticals": {},
     "richTextV2ToHTML": true,
     "markdownToHTML": true
     }

3. If you are already using the display fields property, add the new custom field to the displayFields array.

   {
    "verticals": {
      "products": {
        "displayFields": [
          "photoGallery",
          "name",
          "c_testRTDescription",
          "c_testMarkdown"
        ]
      }
    },
    "richTextV2ToHTML": true,
    "markdownToHTML": true
   }

Theme

Note

To use a markdown or rich text (v2) field, you must be on Hitchhiker Theme v1.32 or higher and Search UI SDK v1.16 or higher. Check out the Upgrade the Theme and SDK module for more info and the Theme Upgrade guide for step-by-step instructions on upgrading.

To render the field in the Code Editor, use the html subfield of the field you just added when mapping profile fields to properties in the card component.js file. Both rich text and markdown fields will be converted to HTML.

dataForRender(profile) {
  return {
    title: profile.name,
    details: profile.c_testRTDescription ? profile.c_testRTDescription['html'] : null
  }
}

React

1. In order to render the fields in the frontend, take a look at the example cards in the following repo:

   • HTML Example Card: this will be used to render Rich Text and Markdown fields that have been converted to HTML.
   • Markdown Example Card: this will be used to render Markdown fields that have not been converted to HTML.

2. For Markdown fields that haven’t been converted to HTML, you will need to do the additional following steps:

   • Make sure the markdownToHTML config property is set to false: "markdownToHTML": false, in the backend config.
   • Run this command in your terminal: npm i @uiw/react-md-editor

Check out the Update a Result Card to Support Rich Text help article for step-by-step instructions on display rich text on a result card.