Directory Management | Yext Hitchhikers Platform

The Directory Manager (DM) helps you create a directory website by generating and grouping Knowledge Graph entities into a tree of parent-child relationships. Conceptually, the Knowledge Graph for a U.S.-based location directory could look something like this:

Once you have a directory tree set up in your Knowledge Graph, it’s really easy to develop a Pages site!

Note

If you want to get started building a directory site, check out this module .

Directory Manager Terminology

Before we dive in, here is a list of common Directory Manager terms used throughout the documentation:

Directory Manager Schema

The Directory Manager is powered by a JSON configuration file. Here is the full list of available properties that can be configured in your file:

Updating a Directory Manager Configuration

After reading our advanced use cases section, you may have decided you want to add a new feature to your existing directory. Don’t worry, upgrading your DM configuration is easy!

Follow the steps below to upgrade your configuration:

1. Go to your Yext account, and open up Admin Console.
   • You can find this in the Developer section of your left-nav bar, or by using Quick Find.
2. On the left-side of your page, open up pages > directory-manager, and click on your desired DM configuration file.
3. Update your file with the desired configuration updates.
4. Click the “Apply” button in the top-right corner of your window and follow the prompts to apply the resources.

5. Open up your terminal and enter the following command:

   yext init

6. Enter the following command to run your updated DM configuration:

   yext dm run --cacId="[REPLACE_ME]"

7. Navigate back to your Knowledge Graph. You should see the updated configuration changes reflected in your data!

Directory Manager Execution Process

Once the Directory Manager has been executed, there’s a lot that happens under the hood. Specifically, the Directory Manager:

1. Adds the following custom fields to the entity types in your Yext account:

   • Directory Parents (dm_directoryParents)
   • Directory Children (dm_directoryChildren)
   • Directory Children Count (dm_directoryChildrenCount)
   • Directory Manager ID (dm_directoryManagerId)
   • Child Entity IDs (dm_childEntityIds)

2. Generates your directory entities.

3. Creates a saved filter for each level of your directory.

Saved Filters

The Directory Manager creates a saved filter for each level of your tree, which includes all entities that were created at that level. These filters are generated automatically to help you configure Streams for Pages development.

Importantly, part of the criteria for these filters is to only include entities that have directory children.

Field Updates

Critically, the Directory Manager is also responsible for creating directory-specific fields and adding them to your entities. It will also populate the built-in slug field for each level of your tree. These include:

• Slug (slug)
• Directory Parents (list of entities related to an entity one-level up the directory tree)
• Directory Children (list of entities related to an entity one-level down the directory tree)
• Directory Children Count (the count of base entities related to an entity)
• Child Entity IDs (a list used by the Directory Manager to help power the Directory Children Count)
• Directory Manager ID (the DM resource ID associated with the creation of an entity)

Ongoing Directory Maintenance

The Directory Manager’s work isn’t finished after initialization. The DM will remain active in your account and actively listen for ongoing CRUD operations involving the set of base entities.

Entity Creation

For example, imagine your business has expanded to a new location - Chicago, Illinois - so you add a new location entity to your graph. You don’t need to re-run the Directory Manager in order to update your directory; the new entities are generated automatically!

In the example below:

• The user adds location 5 - based in Chicago, IL, a city and state that aren’t in the directory yet.
• As such, the DM creates all of the following:
  • Chicago city entity
  • Illinois state entity
  • Relationships pointing to and from them
• The directory children count for the root entity changes from four to five. It is set to one for both the Illinois state entity and the Chicago city entity.

Entity Updates

The same is true for updates to existing entities as well.

In the example below:

• The user moves location 2 from New York, NY to Brooklyn, NY.
• As such, the DM creates a new Brooklyn city entity and relates it to the NY state entity.
• The DM changes the related city entity for location 2 from New York (city) to Brooklyn.
• The directory children count is still two for NY state is still two, changes from two to one for New York (city), and it is set to one for Brooklyn.

Entity Deletions

The same is true for entity deletions. For example, if you were to delete a location from your directory, the DM will ensure any relevant directory entities are no longer related to it. Observe the example below:

In the example below:

• The user deletes location 1 in Brooklyn, NY.
• After deletion, the Brooklyn city entity no longer has any related children entities.
• Because Brooklyn has no children, the DM removes it as a child of NY state.
• The directory children count changes for NY state from three to two and changes for the root entity from four to three.

Advanced Configuration Use Cases

Entity Templates

An entity template is a Knowledge Graph tool that allows you to define a “template” of field values and apply it to a set of entities. Templates are extremely useful for applying standardized content at scale, and can save you a ton of time (refer to our module to learn more).

The Directory Manager extends this functionality by allowing you to apply specific templates any time a directory entity is generated! To accomplish this, use the entityTemplateId property.

Let’s look at a concrete use case to see why this is useful:

Example DM Configuration

Per the configuration below, there are two entity templates in use by the DM:

1. stateTemplate (applied to each state entity)

2. cityTemplate (applied to each city entity)

   {
     "$id": "us-directory",
     "$schema": "https://schema.yext.com/config/pages/directory-manager/v1",
     "name": "US Directory",
     "baseEntities": {
       "entityTypes": ["location"],
       "savedFilterIds": ["685381454"]
     },
     "root": {
       "entityType": "ce_root",
       "slug": "index.html"
     },
     "localization": {
       "locales": ["en"]
     },
     "levels": [
       {
         "entityType": "ce_state",
         "field": "address.region",
         "slug": "{{address.region}}",
         "entityTemplateId": "stateTemplate",
         "fieldMappings": {
           "c_addressRegionDisplayName": "{{#regionDisplayName}}",
           "c_addressCountryDisplayName": "{{#countryDisplayName}}"
         }
       },
       {
         "entityType": "ce_city",
         "field": "address.city",
         "slug": "{{address.region}}/{{address.city}}",
         "entityTemplateId": "cityTemplate",
         "fieldMappings": {
           "c_addressRegionDisplayName": "{{#regionDisplayName}}"
         }
       }
     ]
   }

Templates

Now, let’s look at what each entity template does:

1. stateTemplate - Sets the description field to “Welcome to [[name]], located in the great nation of [[c_addressCountryDisplayName]]!”

   

2. cityTemplate - Sets the description field is set to “Welcome to [[name]], located in the great state of [[c_addressRegionDisplayName]]!”

   

Note

These examples leverage embedded fields to make the descriptions dynamic per entity. Learn more about how embedded fields work in this module .

Tying it All Together

Once the Directory Manager runs, it will apply the relevant template to each entity that it generates. As a result, you can observe how the description field is automatically populated for both the New York (state) and New York (city) entities below:

Putting this all together, these dynamic description fields can then easily power your Pages frontend!

Multi-Language Directories

For each base entity, the DM will generate equivalent language profiles for each entity in its parent ancestry. Refer to the screenshot below:

Location 1, based in New York, NY, has language profiles defined for [“en”, “es”]. This language profile cardinality is respected across its parent ancestry - meaning the DM creates an “en” and “es” profile for the New York city, New York state, and root entities.

By contrast, Location 3 does not have an “es” profile, meaning its ancestry only has “en” profiles generated for it. Furthermore, when it comes to entity relationships, Streams respects language profile cardinality - meaning that the “es” language profile for the root entity will not have “California” as a child entity (because it does not exist).

Advanced Configuration Example

Tying all the above use cases together, here is an example configuration file that uses all possible features:

{
  "$id": "us-directory",
  "$schema": "https://schema.yext.com/config/pages/directory-manager/v1",
  "name": "US Diretory",
  "baseEntities": {
    "entityTypes": [
      "location"
    ]
  },
  "localization": {
    "locales": ["en", "es", "fr"]
  },
  "root": {
    "entityType": "ce_root",
    "slug": "index.html",
    "entityTemplateId": "rootTemplate",
    "localeOverrides": {
      "es": {
        "entityTemplateId": "rootTemplate-spanish",
        "slug": "index/{{localeCode}}"
      },
      "fr": {
        "entityTemplateId": "rootTemplate-french",
        "slug": "index/{{localeCode}}"
      }
    }
  },
  "levels": [
    {
      "entityType": "ce_state",
      "field": "address.region",
      "slug": "{{address.region}}",
      "entityTemplateId": "stateTemplate",
      "fieldMappings": {
        "c_addressRegionName": "{{#regionDisplayName}}",
        "c_addressCountryDisplayName": "{{#countryDisplayName}}"
      },
      "fieldsToCopyFromBase": [
        "email",
        "instagram",
        "labels",
      ],
      "localeOverrides": {
        "es": {
          "entityTemplateId": "stateTemplate-spanish",
          "slug": "{{localeCode}}/{{address.region}}",
          "c_addressRegionName": "{{#regionDisplayName}}",
          "c_addressCountryDisplayName": "{{#countryDisplayName}}"
        },
        "fr": {
          "entityTemplateId": "stateTemplate-french",
          "slug": "{{localeCode}}/{{address.region}}",
          "c_addressRegionName": "{{#regionDisplayName}}",
          "c_addressCountryDisplayName": "{{#countryDisplayName}}"
        }
      }
    },
    {
      "entityType": "ce_city",
      "field": "address.city",
      "slug": "{{address.region}}/{{address.city}}",
      "entityTemplateId": "cityTemplate",
      "fieldMappings": {
        "c_addressRegionName": "{{#regionDisplayName}}"
      },
      "fieldsToCopyFromBase": [
        "email",
        "instagram",
        "labels",
      ],
      "localeOverrides": {
        "es": {
          "entityTemplateId": "cityTemplate-spanish",
          "slug": "{{localeCode}}/{{address.region}}/{{address.city}}",
          "fieldMappings": {
            "c_addressRegionName": "{{#regionDisplayName}}"
          }
        },
        "fr": {
          "entityTemplateId": "cityTemplate-french",
          "slug": "{{localeCode}}/{{address.region}}/{{address.city}}",
          "fieldMappings": {
            "c_addressRegionName": "{{#regionDisplayName}}"
          }
        }
      }
    }
  ]
}