External Identities

External identities 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 the hiveId.

• The 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 Identities

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)	Shopify	SAP
D6BFA0AB71A1	90la078s93498	MAT-47110823

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

Collecting External Identities

An external identity 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 identity:

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

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

4. SyncHive publishes D to Shopify.

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

6. The Shopify integration reports this new external identity back to SyncHive.

At this point, D has:

• One hiveId

• Multiple external identities (one per external system)

Key Rules

• A record has exactly one hiveId.

• A record may have many externalId values.

• Each external identity is always scoped to a specific integration.

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