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? chord only supports syncing content between a single cms and a single oms chord does not support syncing between cmss, or one to many or many to many syncing 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 configurations are currently only editable by the chord team please reach out if you need to make any changes 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 default description sync service api key the api key given to you by chord tenant name the tenant slug given to you by chord for a given environment allowed origins \['contentful'] the list of allowed origins description false if the description should sync or not tags false if the tags should sync or not debug mode false if debug mode is enabled, the service will run but will not sync content notes the tags the feature can keep tags between the origin and destination in sync if tags already exist on either integration when that feature is turned on, it will override the tags at the destination for the first sync of content from the origin the tags will stay in sync once that first tag sync is achieved supported integrations contentful available as an origin and a destination configuration & options default description space id your contentful space id environment id master your contentful environment id management token false your contentful management token 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 docid\ mgeiekmhy5liz9 kq6j2e 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 product contentful notes status status name name slug slug vendor vendor producttype name producttype name producttype slug producttype slug shortdescription shortdescription longdescription longdescription note that we only support string or markdown like syncing we do not support syncing rich text content types mainimage mainimage (see below) images images (see below) optiontypes optiontypes (see below) tags metadata tags $ sys id in contentful, the tags are a system object we map the strings from the sync product to the corresponding id variants variant\[] (see below) isgiftcard giftcard variant contentful notes name nam sku sku this is required to be a unique value in contentful globaltradeitemnumber globaltradeitemnumber shopifyid shopifyid this value gets synced from shopify to contentful when the variant is created in shopify (to be deprecated) price price regularprice regularprice mainimage mainimage (see below) images images (see below) optionvalues optionvalues (see below) weight weight image contentful notes alt title filetype contenttype filename filename url url option type contentful notes name name slug slug presentation presentation optionvalues optionvalues (see below) option value contentful notes name name slug slug presentation presentation 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 available as an origin and a destination default description admin token the shopify admin api password shop name the shopify shop name (get this from the shop url before the myshopify com ) your contentful environment id your contentful environment id sync mode denylist your contentful environment id determine how a product is synced from shopify to the destination if denylist , all products are synced unless they have a chord no sync tag if allowlist , only products that have a chord sync tag will be synced 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 in your shopify store admin, navigate to "settings" > "notifications" under "webhooks", create a new webhook with these settings event product update format json url https //sync api chord co/sync webhook api version latest 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 shopify sync mode is not user configurable please contact chord if you'd like to change the sync mode 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 product shopify notes status status name name slug slug vendor vendor producttype name producttype producttype slug shortdescription longdescription descriptionhtml note that we only support string or markdown like syncing we do not support syncing rich text or html values mainimage variants $ mainimage $ file url images each mainimage of the variant will populate the images array in shopify and be referenced back on the shopify variant so that you know, images will only sync to shopify and not from shopify optiontypes $ name options tags tags variants variants (see below) isgiftcard giftcard variant shopify notes name nam sku sku this is required to be a unique value in contentful globaltradeitemnumber globaltradeitemnumber shopifyid shopifyid this value gets synced from shopify to contentful when the variant is created in shopify (to be deprecated) price price regularprice regularprice mainimage mainimage (see below) images images (see below) optionvalues optionvalues (see below) weight weight size (not supported) image shopify notes alt title filetype contenttype filename filename url url option type shopify notes name name slug slug presentation presentation optionvalues optionvalues (see below) option value shopify notes name name slug slug presentation presentation 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 product type notes status string the status of the product at origin name string the name of the product slug string the slug of the product vendor string the vendor name producttype name string the name of the product type producttype slug string the slug of the product type shortdescription string a short description of the product longdescription string a long description of the product mainimage image (see below) images image\[] (see below) optiontypes optiontypes (see below) tags string\[] a list of tags variants variant\[] (see below) isgiftcard boolean true if the product is a gift card variant variant type notes name string the name of the variant sku string the unique sku for the variant globaltradeitemnumber string the gtin number shopifyid string the id of the variant in shopify (to be deprecated) price string the current price (can be lower than the regular price) regularprice string the regular price mainimage image (see below) images image\[] (see below) optionvalues optionvalue\[] (see below) weight string a string representing the weight image image type notes alt string the alt string value filetype string the type of image (ex image/jpeg ) filename string the filename of the image url string the absolute url of the image option type & value option type type notes name string the name of the option type (ex color ) slug string the slug of the option type presentation string the presentation string of the option type optionvalues optionvalue\[] (see below) option value type notes name string the name of the option value (ex red ) slug string the slug of the option value presentation string the presentation string of the option type the presentation string of the option type the presentation string of the option type the presentation string of the option type