External Identities and Data References

Inbound

When publishing documents into SyncHive an integration should usually only use its own external identities as data references.

For example, if the SAP connector (with integration key SapS4) publishes a data envelope containing a product document, (a fragment of) it should have the form:

{
    "dataId":
    {
        "@type": "DataReference",
        "schemaName": "limber",
        "shapeName": "Product",
        "externalIdentities":
        [
            {
                "integrationKey": "SapS4",
                "externalId": "30008412"
            }
        ]
    },

    "data":
    {
        "@type": "Product",
        "externalIdentity":
        [
            {
                "@type": "ExternalID",
                "internalType": "Product",
                "externalSystemCode": SF
                "externalId": "K02482QM"
            },
            {
                "@type": "ExternalID",
                "internalType": "Product",
                "externalSystemCode": "SapS4",
                "externalId": "30008412"
            }
        ],

        "name": "My Super Comfy Mattress"
    }
}

Note that the dataId field only uses the SapS4 external identity, even though the product document itself (in the data field) has other external identities.

Similarly, suppose the SAP connector (with integration key SapS4) publishes a data envelope containing a product document, where:

the product contains a bill of materials
the bill of materials contains (line) items
each line item refers to a product

Then a fragment of the document for this product should look as follows:

{
    "@type": "Product",
    ...,

    "billOfMaterials":
    [
        {
            "@type": "BillOfMaterials",

            "billOfMaterialsItem":
            [
                {
                    "@type": "BillOfMaterialsItem",

                    "catalogItem":
                    {
                        "@type": "Product",
                        "externalIdentity":
                        [
                            {
                                "@type": "ExternalID",
                                "internalType": "Product",
                                "externalSystemCode": "SapS4",
                                "externalId": "30008412"
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Note that the BillOfMaterialsItem contains a catalogItem which is a data reference to a product which is identified by an external identity for the SapS4 integration.

The inbound side of a onnector can use SyncHive ids to identify documents but shouldn't, because:

it's unlikely the connector knows the SyncHive id of a document
if a document has never been published into SyncHive before, then it won't even have a SyncHive id

The exception to this rule is "built-in", or "global", SyncHive documents like currencies, units of measure, etc.

To refer to these documents connectors should almost always use SyncHive ids. For example, the IRI

https://schema.limbergraph.com/limber/CurrencyUnit#NZD

identifies the "built-in" document for the NZD currency unit, so a connector should use the following to refer to this document:

{
  "@type": "DataReference",

  "schemaName": "limber",

  "shapeName": "CurrencyUnit",

  "iri": "https://schema.limbergraph.com/limber/CurrencyUnit#NZD"
}

Outbound

When receiving documents from SyncHive the situation is slightly different, because:

a received document always has a SyncHive id
any document that a received document refers to, will also always have a SyncHive id

Using SyncHive ids as data references on the outbound side of a connector does not therefore have the same issues as it does on the inbound side.

Having said that, the outbound side of a connector should, wherever possible, still only use its own external identities to identify documents, with the usual exception for "built-in" SyncHive documents.

External Identities and Data References

Inbound​

Outbound​

Inbound

Outbound