Syncing content between OMS and CMS

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

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.

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.

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.

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.

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

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:

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.

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).

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

In your Shopify store admin, navigate to "Settings" > "Notifications". Under "Webhooks", create a new webhook with these settings:

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:

You can read more about adding tags in Shopify here.

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.

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

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