Skip to main content

External IDs

External IDs explain how SyncHive represents and correlates the same business record across multiple external systems (for example, Shopify and SAP S/4HANA), while maintaining a single canonical identifier internally.

Core Concepts​

Hive ID​

  • Every record stored in SyncHive is assigned exactly one internal identifier, called hiveId

  • hiveId is stable and system‑wide

External ID (externalId)​

  • External systems identify records using their own identifiers

  • SyncHive stores these identifiers in the externalId field

  • a single SyncHive record may have multiple external IDs coming from one or more external systems

  • Each external ID is always associated with a specific integration (identified by integrationKey)

Data in Different Systems​

Consider the following product message produced by a Shopify integration:

{
  "meta": {
    "integrationKey": "shopify_nz_integration",
    "shape": "Product"
  },
  "data": {
    "externalId": ["90la078s93498"],
    "sales order": "123-456",
    "description": "Test Product 20250101 Toaster version 2",
    "name": "Test Product 20250101"
  }
  //...
}

This means:

  • The product record has been stored in the external system connected via the integration with key shopify_nz_integration

  • Shopify identifies this product using the external ID `90la078s93498'

Now consider a message for the same product coming from SAP S/4HANA:

{
  "meta": {
    "integrationKey": "SapS4",
    "shape": "Product"
  },
  "data": {
    "externalId": ["MAT-47110823"],
    "sapMaterialNumber": "47110823",
    "sapMaterialDescription": "Electric Toaster - Stainless Steel",
    "sapMaterialGroup": "APPLIANCES_SMALL"
  }
  //...
}

This means:

  • The product record has been stored in the external system connected via the integration with key SapS4

  • SAP identifies this product using the external ID MAT-47110823

Single Product, Multiple External IDs​

Although the Shopify and SAP messages originate from different systems and use different identifiers, SyncHive can resolve both messages to the same product record.

Internally, SyncHive assigns a single hiveId to that product, for example:

"hiveId": "D6BFA0AB71A1"

How Records Appear in Explorer​

The SyncHive Explorer always shows external IDs in the context of the currently selected integration.

Filtered by shopify_nz_integration

{
  "meta": {
    "integrationKey": "shopify_nz_integration",
    "shape": "Product"
  },
  "data": {
    "hiveId": "D6BFA0AB71A1",
    "externalId": ["90la078s93498"],
    "description": "Test Product 20250101 Toaster version 2",
    "name": "Test Product 20250101"
  }
  //...
}

Filtered by SapS4

{
  "meta": {
    "integrationKey": "SapS4",
    "shape": "Product"
  },
  "data": {
    "hiveId": "D6BFA0AB71A1",
    "externalId": ["MAT-47110823"],
    "sapMaterialNumber": "47110823",
    "sapMaterialDescription": "Electric Toaster - Stainless Steel",
    "sapMaterialGroup": "APPLIANCES_SMALL"
  }
  //...
}

Identity Correspondence​

The relationship between the various identifiers can be summarised as follows:

The correspondence between the various IDs is as follows:

SyncHive (hiveId)ShopifySAP
D6BFA0AB71A190la078s93498MAT-47110823

External IDs are a mechanism SyncHive uses to track the same logical record across multiple external systems.

Collecting External IDs​

An external ID is added to a record whenever either of the following occurs:

  • A record is created in SyncHive by an integration for the first time (the document does not yet exist in SyncHive), or

  • A record is published from SyncHive into an external system for the first time by an integration

Each integration is responsible for reporting the external identifier assigned by its system.

Example Lifecycle​

  1. A sales order is created in SAP with primary key 30009396.

  2. The SAP integration detects the order creation in SAP, and creates a record, D, which includes the SAP external ID:

{
  "meta": {
    "integrationKey": "SapS4",
    "shape": "Product"
  },
  "data": {
    "externalId": ["MAT-47110823"],
    "sapMaterialNumber": "47110823",
    "sapMaterialDescription": "Electric Toaster - Stainless Steel",
    "sapMaterialGroup": "APPLIANCES_SMALL"
  }
  //...
}

  1. SyncHive stores D and assigns it a hiveId of D6BFA0AB71A1.

  2. SyncHive publishes D to Shopify.

  3. Shopify creates the corresponding record with ID 123-456.

  4. The Shopify integration reports this new external ID back to SyncHive.

At this point, D has:

  • One hiveId

  • Multiple external IDs (one per external system)

Key Rules​

  • A record has exactly one hiveId

  • A record may have many externalId values

  • Each external ID is always scoped to a specific integration

  • External IDs allow SyncHive to reconcile, publish, and re‑ingest data across systems without duplication