Skip to main content

The Anatomy of a Message

A Message is a structured JSON payload that streamlines communication between SyncHive and Connectors. Adhering to the SyncHive Schema, Messages encapsulate data for various transactions, such as the creation of sales orders, updates to customer profiles, or deletion of products. Once evaluated, Messages contents are stored within SyncHive’s data store or, for Connector-specific transactions, transformed and sent to an external application.

Overview of a Message​

A Message consists of three components:

  1. Transaction Data: This is the heart of the Message, containing the foundational information necessary for processing a transaction. For instance, a Product Message transaction might include details such as the product's name, SKU, description, and price.
  2. Data ID: Vital for Connectors, this enables them to accurately resolve IDs as they process and send Message data to external applications. Further documentation is available in ID Resolution.
  3. Metadata: Essential for contextualizing the Message, this component aids SyncHive in processing, storing, and forwarding of the Message to a Connector. It specifies the transaction type (CREATE, UPDATE, DELETE), details about the Integration, Schema, operational mode (LIVE or SANDBOX), and other relevant information.

Schema Compliance​

Messages adhere to the SyncHive Schema to ensure standardized communication. This schema mandates a specific format for Messages, which is validated upon receipt by SyncHive. The SyncHive Schema supports many use cases beyond Product Messages, detailed further in Schema.

Shapes​

SyncHive uses Shapes to create Message structures for real-world transactions, following the SyncHive Schema. An example is the Product Shape, indicated by "@type": "Product" and "shapeName": "Product", which contains data specific to a product transaction. All available Shapes, including Sales Order, and Customer Account are documented in Schema.

Message Example​

To illustrate, consider the following example of a Product Message, broken down by components.

Transaction Data​

{
    "data": {
        "@type": "Product",
        "name": "Toaster",
        "sku": "8082STAINLESS",
        "description": "Stainless steel four-slice toaster",
        "externalIdentity": [
            {
                "@type": "ExternalID",
                "internalType": "Product",
                "externalSystemCode": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ],
        "price": {
            "@type": "Monetary",
            "decimalValue": 100.00,
            "currency": {
                "@type": "DataReference",
                "schemaName": "limber",
                "shapeName": "CurrencyUnit",
                "iri": "https://schema.limbergraph.com/limber/CurrencyUnit#NZD",
                "keys": [
                    {
                        "code": "NZD",
                    }
                ]
            }
        }
    }
}

Data ID​

{
    "dataId": {
        "@type": "DataReference",
        "schemaName": "limber",
        "shapeName": "Product",
        "externalIdentities": [
            {
                "integrationKey": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ]
    },
}

Metadata​

{
    "dataAction": "CREATE",
    "integrationKey": "shopify_nz_integration",
    "schemaName": "limber",
    "schemaVersion": "2.1.0",
    "shapeName": "Product",
    "storeKey": "limber",
    "mode": "LIVE",
}

Complete Product Message Example​

A complete Product Message, including all aforementioned components, is depicted below:

{
    // Metadata
    "dataAction": "CREATE",
    "integrationKey": "shopify_nz_integration",
    "schemaName": "limber",
    "schemaVersion": "2.1.0",
    "shapeName": "Product",
    "storeKey": "limber",
    "mode": "LIVE",

    // Data ID
    "dataId": {
        "@type": "DataReference",
        "schemaName": "limber",
        "shapeName": "Product",
        "externalIdentities": [
            {
                "integrationKey": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ],
        "label": "632910392"
    },

    // Transaction Data
    "data": {
        "@type": "Product",
        "name": "Toaster",
        "sku": "8082STAINLESS",
        "description": "Stainless steel four-slice toaster",
        "externalIdentity": [
            {
                "@type": "ExternalID",
                "internalType": "Product",
                "externalSystemCode": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ],
        "price": {
            "@type": "Monetary",
            "decimalValue": 100.00,
            "currency": {
                "@type": "DataReference",
                "schemaName": "limber",
                "shapeName": "CurrencyUnit",
                "iri": "https://schema.limbergraph.com/limber/CurrencyUnit#NZD",
                "keys": [
                    {
                        "code": "NZD"
                    }
                ]
            }
        }
    }
}
note

Use the following static values for these Metadata fields:

  • "storeKey": "limber"
  • "schemaName": "limber"
  • "schemaVersion": "2.1.0"