Skip to main content

The Anatomy of a Message

The atomic unit of data transfer within SyncHive. Messages contain structured payloads that represent records or changes moving between systems. They can be logged, tracked, inspected, and retried.

Overview of a Message​

A Message consists of two 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. Metadata: Identifies the integration source and the schema (shape) of the Message, enabling SyncHive to correctly interpret, validate, and route the payload.

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.

Shapes​

SyncHive uses Shapes to define the structured data payload for a given integration scenario, specifying which properties from an entity and its related entities are included. A Shape, such as "shape": "Product", determines the exact structure of the Message body and ensures the payload conforms to the intended SyncHive schema for that context.

Message Example​

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

Transaction Data​

{
  "data": {
  "hiveId": "TOAST-1001",
  "gtin": "5037891234501",
  "name": "Mini Toaster 2S",
  "sku": "MT-2S-01",
  "description": "Two-slice compact toaster.",
  "price": "49.99",
  "cost": "22.00",
  "sourceSystemCode": "SRC01",
  "sourceSystemId": "TOASTSYS",
  "createdOn": "2025-01-12T00:00:00Z",
  "lastUpdatedOn": "2025-01-14T00:00:00Z",
  "productStatus_code": "ACTIVE",
  "productStatus_description": "Active",
  "taxType_code": "GST_NZ",
  "taxType_description": "NZ GST",
  "billOfMaterials": [
    {
      "hiveId": "BOM-T1",
      "alternateId": "BOM-01",
      "baseQuantity": "1",
      "productPlant_code": "PLANT_A",
      "productPlant_description": "Assembly A",
      "billOfMaterialsItem": [
        {
          "hiveId": "BOMITEM-01",
          "lineNumber": "10",
          "quantity": "1",
          "catalogItem_hiveId": "674AFG67256",
          "catalogItem_name": "Heating Element",
        }
      ]
    }
  ],
  "inventoryCosting": [
    {
      "hiveId": "IC-01",
      "plannedPrice": "30.00",
      "plannedPriceCurrency_code": "NZD",
      "inventoryCostingItem": [
        {
          "hiveId": "ICITEM-01",
          "cost": "20.00",
          "costUnit": "NZD per EA",
          "costCurrency_code": "NZD"
        }
      ]
    }
  ],
  "productPlant": [
    {
      "hiveId": "PP-01",
      "plantCode": "AKL01",
      "profitCenter": "PC01",
      "productPlant_code": "PLANT_A",
      "productStorageLocation": [
        {
          "hiveId": "LOC-01",
          "storageLocation_hiveId": "LOC-AKL-01"
        }
      ]
    }
  ],

  "salesChannel": [
    {
      "hiveId": "SC-01",
      "distributionChannelCode": "ONLINE",
      "salesOrganizationCode": "NZ_RETAIL"
    }
  ]
}

Metadata​

{
  "meta": {
    "integrationKey": "shopify",
    "shape": "Product"
  }
  //...
}

Complete Product Message Example​

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

{
  "meta": {
    "integrationKey": "shopify",
    "shape": "Product"
  },
  //...
}
  // Transaction Data
  {
  "data": {
  "hiveId": "TOAST-1001",
  "gtin": "5037891234501",
  "name": "Mini Toaster 2S",
  "sku": "MT-2S-01",
  "description": "Two-slice compact toaster.",
  "price": "49.99",
  "cost": "22.00",
  "sourceSystemCode": "SRC01",
  "sourceSystemId": "TOASTSYS",
  "createdOn": "2025-01-12T00:00:00Z",
  "lastUpdatedOn": "2025-01-14T00:00:00Z",
  "productStatus_code": "ACTIVE",
  "productStatus_description": "Active",
  "taxType_code": "GST_NZ",
  "taxType_description": "NZ GST",
  "billOfMaterials": [
    {
      "hiveId": "BOM-T1",
      "alternateId": "BOM-01",
    }
  ]
  }
    //...
  }
  }