Syncing content between OMS and CMS

Introduction

Chord can sync product content and data between your order management system (OMS) and your content management system (CMS).

Terms

Syncing content between OMS and CMS is a service in your stack with product-related content that can be synced. This integration can be both an origin and a destination of content changes.

When acting as an origin, the integration will emit a change event when relevant content changes.

When acting as a destination, an integration may receive changes to its content.

A change event can be a creation, mutation (update), or deletion event triggered in the origin integration.

How does it work?

When a change is detected in the origin integration, a webhook will trigger a sync event in the Sync Service. Once the service has authorized the event, it will fetch content for the impacted content entity on origin and destination integrations.

It will then compare them and determine if a change needs to be synced at the destination.

If no mutation is needed, the flow is stopped. For example, this can happen if a product attribute is updated at the origin but is not supported as a syncable attribute.

If a mutation is needed, the service will sync content at the destination and trigger a notification to advertise the change.

What is synced exactly?

Each integration is a pre-determined set of attributes that will map to the corresponding attribute on the syncing content between OMS and CMS will map to the other integration corresponding attribute.

For example, a Contentful product slug will map to the Sync Product's slug attribute. For Shopify, the product handle will correspond to that slug.

Getting Started

Environments

The Sync Service can support multiple OMS and CMS pairs.

This is typically how we create multiple environments.

We highly recommend having at least 2 environments: production and staging.

Configuration & Options

Here's a list of the configuration and options needed for all integrations:

Notes

Supported Integrations

Contentful

Configuration & Options

Setup

How to model your content

Contentful has various data models that make up a product. This includes the product, variants, product types, and option values. Please take a moment to read over the Content Models portion of this documentation to familiarize yourself with these data models.

How to set up your webhook

Once you have all the necessary configurations, you must create a webhook in Contentful for each environment in your stack.

Here is the specific configuration you will need to use:

• URL: https://sync.api.chord.co/sync
• Content events:
  • Entry publish
  • Entry unpublish
• Filters:
  • Environment ID equals the Contentful environment ID for that environment.
  • Content Type ID in product, variant
• Headers:
  • x-api-key: the API key given to you by Chord
  • x-chord-tenant-name: your tenant name for that environment
• Payload: use the default payload

Usage

How to sync content from Contentful

If a Contentful product or variant is published (or unpublished), the sync service will attempt to publish it (and its related objects) to the destination.

Data Mapping

Notes

The Sync Service does not currently support syncing multiple locales in Contentful. Only content attached to the default locale will be synced (usually en-US).

Shopify

Setup

How to authorize the Sync Service in Shopify

The Sync Service needs some authorization in Shopify to change your content. This authorization is granted via a custom app. Required permission scopes are write_product_listings, read_product_listings, write_products, and read_products.

How to add a webhook in Shopify

Your Shopify store will need two webhooks to be created for the service, for the Product update and Product creation events.

The callback URL is https://sync.api.chord.co/sync.

Usage

How to sync content from Shopify

If a Shopify product or variant is saved (or updated), the sync service will attempt to publish it (and its related objects) to the destination.

How to use the allowlist/denylist feature

The Sync Service allows you to prevent or allow Shopify products to sync depending on the sync mode enabled.

There are two sync modes:

• denylist(default): When this mode is enabled, all Shopify products will sync unless they have the chord-no-sync tag.
• allowlist: When this mode is enabled, Shopify products will only be synced if they have the chord-sync tag.

You can read more about adding tags in Shopify here.

Data Mapping

Notes

Images

We currently only sync product and variant images to Shopify and not from Shopify.

Slugs for Product Type, Option Type, and Option Value data models

The sync service creates a slugified version of the Product Type, Option Type, or Option Value. We include a slug field for our Product Type, Option Type, and Option Value data models. However, Shopify has no such field. This means that we need to generate this automatically.

For example, if we create a product in Shopify with a Product Type of "Pants and Shorts," if there is not already a Product Type with a title of "Pants and Shorts" in the CMS, it will be created with a title of "Pants and Shorts" and a slug of "pants-and-shorts."

Slugs for Product Type, Option Type, and Option Value data models are written over.

Since we've stated above that Shopify does not have a slug field for Product Type, Option Type, and Option Value data models and that the slug is auto-generated, this also brings up the fact that Shopify will not override these slugs.

For example, if a product has a Product Type of "Pants" and a slug of "pants" and the Product Type is changed to "Shorts" in Shopify, the slug will not be affected. To change the slug, you must do this in the CMS itself.

A variant name is only set in CMS if not already selected.

Our data model includes a Variant Name field, but Shopify has no such field. Because of this, the sync service will populate the Variant Name field with a unique name only if the Variant doesn't already have a Name set in the CMS. This prevents custom Variant Names from being overwritten if you decide to create a custom name for it.

Create products as gift cards.

Due to a Shopify limitation, a Gift Card product (GCP) can only be marked as such at product creation. In other words, you can only create a GCP from a CMS if you keep it as such (using the giftCard attribute) before publishing it for the first time.

Notifications

Slack

We'd like you to provide a Slack webhook to get notified about successful or failed sync events produced by the Sync Service.

Add an Incoming Webhooks app to your space and provide the Chord team with the generated URL.

In-Depth

Change Detection Flow

sequenceDiagram
  participant CMS as CMS
  participant SS as Sync Service
  participant OMS as OMS
  
  Note over CMS,OMS: A change happens in the origin
  CMS->>SS: Product updated

  Note over CMS,OMS: Content is fetched on origin and destination and compared
  SS->>CMS: Request product
  CMS->>SS: 
  SS->>OMS: Request product
  OMS->>SS: 
  
  Note over CMS,OMS: If a change is needed, the Sync Service applies that change at destination
  SS->>OMS: Product modified or created

Difference Detection Logic

flowchart LR
    A(Sync Product)
    A2(Sync Product)
    B(Origin Product)
    C(Destination Product)
    D{Difference?}
    E(Destination Product)
    B --> A
    C --> A2
    A & A2 -.-> D -- Yes --> E

Sync Product Schema

Here's the shape of the Sync Product we use to map changes in between the various integrations we support:

Product

Variant

Image

Option Type & Value