Skip to main content

Linking External Identities

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 Identities 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:

{
    "dataAction": "CREATE",
    "integrationKey": "shopify_nz_integration",
    "schemaName": "limber",
    "schemaVersion": "2.1.0",
    "shapeName": "Product",
    "storeKey": "limber",
    "mode": "LIVE",
    "dataId": {
        "@type": "DataReference",
        "schemaName": "limber",
        "shapeName": "Product",
        "externalIdentities": [
            {
                "integrationKey": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ]
    },
    "data": {
        "@type": "Product",
        "name": "Toaster",
        "sku": "8082STAINLESS",
        "externalIdentity": [
            {
                "@type": "ExternalID",
                "internalType": "Product",
                "externalSystemCode": "shopify_nz_integration",
                "externalId": "632910392"
            }
        ]
}

Linking Identities 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 identifiers via the Publish Response, the Connector needs to provide the appropriate response when receiving data from SyncHive.

Example Format
{
  "linkIdentities": {
    "integrationKey": "SapS4",
    "linkIdentities": [
      {
        "iri": "https://schema.limbergraph.com/limber/Product#048c6e55-e210-4a20-8616-f94d93e00e8c",
        "externalId": "30009396"
      }
    ]
  },
  "publishStatus": "SUCCESS"
}
  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.

Format of linkIdentities​

The iri property needs to be populated with an IRI, which is constructed by concatenating the constant https://schema.limbergraph.com/limber/ with the type of the object, followed by a hash (#) and the Hive ID.

The type of an object is determined by the value provided by the @type property on objects supplied by SyncHive.

For example, given a Product with the Hive ID 048c6e55-e210-4a20-8616-f94d93e00e8c, the IRI would be: https://schema.limbergraph.com/limber/Product#048c6e55-e210-4a20-8616-f94d93e00e8c.

Unlinking Identities​

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

Example
{
  "linkIdentities": {
    "integrationKey": "SapS4",
    "linkIdentities": [
      {
        "iri": "https://schema.limbergraph.com/limber/Product#048c6e55-e210-4a20-8616-f94d93e00e8c",
        "externalId": "30009396",
        "deleteLink": true
      }
    ]
  },
  "publishStatus": "SUCCESS"
}

Example of Linking IDs via the Publish Response​

Here's how a Publish Response could look when a product is created in an external system with the integration key SapS4.

{
  "linkIdentities": {
    "integrationKey": "SapS4",
    "linkIdentities": [
      {
        "iri": "https://schema.limbergraph.com/limber/Product#048c6e55-e210-4a20-8616-f94d93e00e8c",
        "externalId": "30009396"
      }
    ]
  },
  "publishStatus": "SUCCESS"
}

The iri is used to identify the record to link in SyncHive, and the externalId of 30009396 is the value to store against SyncHive.

Example of Unlinking IDs via the Publish Response​

{
  "linkIdentities": {
    "integrationKey": "SapS4",
    "linkIdentities": [
      {
        "iri": "https://schema.limbergraph.com/limber/Product#048c6e55-e210-4a20-8616-f94d93e00e8c",
        "externalId": "30009396",
        "deleteLink": true
      }
    ]
  },
  "publishStatus": "SUCCESS"
}

The above says that for the Product with Hive ID 048c6e55-e210-4a20-8616-f94d93e00e8c, the external ID 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 publishing IDs.

PUThttps://{synchive_url}/data-service/v1/data/link
Example
{
  "dataId": {
    "@type": "DataReference",
    "schemaName": "limber",
    "shapeName": "Product",
    "iri": "https://schema.limbergraph.com/limber/Product#048c6e55-e210-4a20-8616-f94d93e00e8c"
  },
  "mode": "LIVE",
  "linkIdentities": {
    "integrationKey": "SapS4",
    "linkIdentities": [
      {
        "iri": "https://schema.limbergraph.com/limber/Product#048c6e55-e210-4a20-8616-f94d93e00e8c",
        "externalId": "30009396"
      }
    ]
  }
}
  1. The property dataId is a data reference to an instance of a Shape in SyncHive.
  2. The property mode is whether this ID is for the LIVE instance or the SANDBOX instance of SyncHive.
  3. The property linkIdentities is the same as the above Publish Response format.

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.