Skip to main content

Linking External IDs

When integrating with SyncHive, external IDs can be helpful for accurately identifying records. To ensure that SyncHive updates the correct records and that Connectors receive the correct IDs, it is important to link the correct IDs to their corresponding records.

Linking IDs when a Connector Publishes Data to SyncHive​

When publishing data to SyncHive, the data needs to contain some IDs to facilitate ID resolution. These can be any of (or a combination of):

  1. Hive ID
  2. External ID
  3. Alternate ID

Data will be rejected if none of the above is provided. These IDs are crucial to prevent duplicate records from being created in SyncHive (and then published to other Integrations). The IDs published are "linked" once SyncHive stores the record.

Example of a Product message which contains an external ID of 632910392:

{
  "meta": {
    "integrationKey": "shopify_nz_integration",
    "shape": "Product"
  },
  "data": {
    "externalId": ["632910392"],
    "name": "Toaster",
    "description": "Four slice toaster.",
    "price": "100.00",
    "sku": "8082STAINLESS",
    "productStatus_code": "active"
  }
  //...
}

Linking IDs when a Connector Receives Data​

When a record is integrated across multiple systems, the record will have different identifiers in each system. By maintaining these external IDs in SyncHive, we can support updating records across multiple systems using their external IDs.

There are two ways to link identities: by responding to the Publish Request or by calling a separate API.

Linking IDs via the Publish Response​

To link these IDs via the Publish Response, the Connector needs to provide the appropriate response when receiving data from SyncHive.

{
  "meta": {
    "integrationKey": "SapS4",
    "shape": "SalesOrder",
    "correlationId": "25CB2660-FC17-4DDA-88BD-995CF08D479E"
  },
  "data": {
    "hiveId": "4CC12B037FC4",
    "externalId": ["53629"]
  }
}
  1. An HTTP status code of 200. (or 500 if encountering an error after an external ID is available. See: Error Handling)
  2. The property linkIdentities holds the integration key and a list of external IDs to link or unlink.

Unlinking IDs​

When data from an external system is deleted, the associated ID needs to be unlinked. This is achieved by using the deleteLink attribute in the response. Setting deleteLink to true indicates the removal of the ID link.

{
  "meta": {
    "integrationKey": "SapS4",
    "shape": "SalesOrder",
    "correlationId": "25CB2660-FC17-4DDA-88BD-995CF08D479E"
  },
  "unlink": {
    "hiveId": "4CC12B037FC4",
    "externalId": ["30009396"]
  }
}

The above says that for the SalesOrder with hiveId 4CC12B037FC4, the externalId 30009396 should be deleted.

Linking IDs via the API​

In scenarios when the external ID needs to be linked outside the publish response, an API is available for linking IDs.

PUThttps://{region}.synchive.com/data-service/v1/hives/{hiveIdentifier}/data/link

Example link payload:

{
  "meta": {
    "shape": "Customer",
    "integrationKey": "SAPS4HANA",
    "integrationVersion": "1.0.0",
    "integrationBuildNumber": 245
  },
  "data": {
    "hiveId": "4CC12B037FC4",
    "externalId": ["53629"]
  }
}

Example unlink payload:

{
  "meta": {
    "integrationKey": "SapS4",
    "shape": "SalesOrder",
    "correlationId": "25CB2660-FC17-4DDA-88BD-995CF08D479E"
  },
  "unlink": {
    "hiveId": "4CC12B037FC4",
    "externalId": ["53629"]
  }
}

Considerations for Using the API​

When linking via the Publish Response, SyncHive ensures the ID is linked before publishing another message. However, when using the API, it is important to ensure that your Connector can handle the interim state where a record has been created but not yet linked, and SyncHive publishes another message before processing the link request.