CMS - HyGraph

This guide is designed to take you through the process to set up Hygraph to work in tandem with Horizon. This unlocks the potential for manipulating your site into the perfect fit for your requirements whilst taking advantage of the sophicated networks of THG offerings such as our product information management and logistics.

Requirements

This guide assumes you have the following:

Hygraph

The assumption for this guide is that you have a Hygraph project set up (this can be with incumbent data or a new project). For more information on Hygraph, see here.

Horizon

For this guide, you already need to have a Horizon URL set up for your site. For more information on Horizon, see here.

Step By Step

Connecting the CMS and Delivery System

In this guide, we use Hygraph as the CMS. We want to use THG’s delivery system though to fetch the data. For this to work, we need to set up a webhook on Hygraph so that any change made in Hygraph can be passed on.

We have an application which sets up this connection for you which is being released imminently. Currently however, please contact Altitude to set the connection up.

Connecting Horizon to the System

We now need to connect our CMS system to Horizon. Horizon requires the following information:

Hygraph Project ID
- This is the Project ID specified on the Horizon page found by going to Project Settings.
Hygraph Management Token
- This token needs to be created. To create this token go to Project Settings -> Permanent Auth Tokens -> Add Token.
- Create a name and description for this token and make a note of the value specified on the following page.
- We now need to give it management access to read the models of Horizon. Scroll to the Management API section and click No, I'll configure custom permissions. Then the following permissions need selecting:
  - Read existing environments
  - Read existing models
  - Read existing enumerations
  - Read existing fields
  - Read existing components
  - Read locales
  - Read stages
  - Read remote sources
  - Can see schema view

Once we have these variables, please contact Altitude to add these to your site configuration.

Connecting Hygraph to THG’s Stack

Once the cache has cleared, we should now start seeing the entities created in Hygraph show up in Horizon’s self documenting schema. The Hygraph models created should be inside the Horizon schema with the suffix Entity. For example for a model named Outfit, the related Hygraph entity will be called OutfitEntity.

There is one special entity needed to connect Hygraph to the full product definition on Horizon. For the connection to occur, we need to create a Hygraph Model with the name Product. This needs one special field with the API ID of productId. This should be a required field and it should be unique. From here you can add any product enrichments you need to this model.

If you want to reference the Horizon product from another model, you should create a relation field from that model to the product model. This can be a one-to-many relation or a many-to-many relation.

As mentioned in the limitations, this model cannot be referenced from a component currently. This improvement is planed for the future.

Querying CMS Entities

We should now be able to see the custom entities within the Horizon schema as well as any time the product model is referenced, the fields inside the entity should show the THG product definition. For the following examples our Hygraph Models are the following:

Model 1: Outfit
- Name: Single Line Text - String
- Products: Two Way Reference with Product
Model 2: Product:
- ProductId: Number - Integer
- ExtraInformation:: Rich Text
- Outfits: Two Way Reference with Outfit

Top Level Entities Query

# Get all outfits stored in Algolia as well as product information related to the relevant products associated with the outfits.
query ProductRelations {
  entities(type: "Outfit", limit: 10, offset: 0) {
    total
    hasMore
    entities {
      ... on OutfitEntity {
        name
        products {
          # For master products
          product {
            sku
            title
          }
          # For child products
          productVariant {
            sku
            title
          }
        }
      }
    }
  }
}

Product Relations Query

# This will get all outfits which contain the product with sku 1234.
query ProductRelations {
  product(sku: 1234, strict: false) {
    sku
    title
    entities(type: "Outfit") {
      total
      hasMore
      entities {
        ... on OutfitEntity {
          name
        }
      }
    }
  }
}

Product Enrichment Query

# Using the dynamic entity field, we can get the additional product info stored in the CMS system
query ProductEnrichment {
  product(sku: 1234, strict: false) {
    sku
    title
    dynamicEntity {
      ... on ProductEntity {
        extraInformation {
          content {
            content
            type
          }
        }
      }
    }
  }
}

Limitations

To improve performance, we have a refresh cache in place on the requests for dynamic entities. The outcome of this is that a change to Hygraph will take a maximum of 5 minutes to propagate through to the Horizon queries. Given that this is a refresh cache, the first call after 5 minutes might also be stale but the following calls will be upto date.
We currently do not support all Hygraph types. If you use these unsupported types, the fields will not be shown on the Horizon schema. The current list of support and unsupported types are:

Type Supported?
String ✅
Rich Text ✅
Integer ✅
Float ✅
Boolean ✅
Date ✅
Date and Time ❌
JSON ❌
Color ❌
Map ❌
Enumerations ❌
Components ✅
Relations ✅
External Data ❌
Currently the connection between THG’s product system and Hygraph is limited. The special Product model can only be referenced by other models, not by components.

Type	Supported?
String	✅
Rich Text	✅
Integer	✅
Float	✅
Boolean	✅
Date	✅
Date and Time	❌
JSON	❌
Color	❌
Map	❌
Enumerations	❌
Components	✅
Relations	✅
External Data	❌