Identifiers and references

Introduction

The concept of id’s and references are key to understand when it comes to matching records between the Integration Platform and remote systems. These must be handled with care in order to not end up in situations where duplicate records start to unexpectedly happen or record mix ups where records start to point to wrong corresponding records, and so on. Make sure to understand this concept before doing any integrations in production.

The id family of fields

The localId field

All records within the Integration Platform are denoted by a unique identifier called localId. The localId is always generated upon record creation by the Integration Platform and has a hexadecimal format and 32 characters in length. This identifier can be used to interact with a single specific record, since they are always stable and never changed in any way by any entity once the record has been created.

Example: localId: "0008820cafb66fc67eb4768563fa69d0"

The remoteId field

There exists a remoteId field dedicated to be used by the current API Connection. This value can be changed by the API user, however it must be a unique value per connectionId and recordType.

The remoteId that belongs to the API Connection can be used when accessing the record through the API. Assume that an Order has been created through the API with the remoteId: "myRemoteId". The endpoint /order/by-remote-id?remoteId=myRemoteId can be used to access that specific order.

The alternative approach is to save the localId for the Order and access the order through the endpoint /order/{localId}.

The remoteIdMap field (read only)

All records within the Integration Platform that have been exchanged (imported and/or exported) with a remote system through a Connection will have one or more remoteId’s stored in a map called remoteIdMap.

This field provides a map of all remoteId’s in the respective remote system for that particular record. The id is keyed by the connectionId of the connection that provided them. Thus this is a stable identifier connecting a record in the Integration Platform and the equivalent record in the remote system(s).

This means you can access and read this data, but you can’t in any way modify any other connections remoteId through the API, only your own remoteId. See remoteId section below.

Example scenario showcasing the usage of id fields

Let’s consider the example below. The localId is the unique id of this record on the Tenant within the Integration Platform. The remoteId is the corresponding unique id of this record in the remote system, as you can see it is also available as one of several fields within the remoteIdMap, more on that below.

Furthermore, there are several records within the remoteIdMap since there are a total of three remote systems where this record is referenced. For example if it is a Product and it has been imported and/or exported with two sales channels as well as our API Connection, that add up to a total of three touchpoints and thus references.

External System references (scenario)

• Sales channel 1. Let’s say an E-commerce Connection and the corresponding unique id in that system.
• Sales channel 2. Let’s say a Marketplace Connection and the corresponding unique id in that system.
• Our API Connection and our unique id.

External system references (JSON)

{
  "localId":"0008820cafb66fc67eb4768563fa69d0",
  "remoteId":"92345237462347865",
  "remoteIdMap":{
    "5377568eb7e165e3b38af6eece4a0001":{
      "connectionId":"5377568eb7e165e3b38af6eece4a0001",
      "remoteId":"/product/26/variant/46"
    },
    "2cd2568eb7e165e3b38b30b3e8c40003":{
      "connectionId":"2cd2568eb7e165e3b38b30b3e8c40003",
      "remoteId":"wrench"
    },
    "4485568eb7e165e3b1bcbb4cc57b0001":{
      "connectionId":"4485568eb7e165e3b1bcbb4cc57b0001",
      "remoteId":"92345237462347865"
  }
}

That showcases a real world scenario of a record and its references to remote systems.

The ref family of fields

The remoteRef field

The remoteRef field can contain a human-readable version of the remote systems reference.

Let’s consider the following scenario:

You create an Order in the Integration Platform where the order has a unique id in your system, as well as a human-readable identifier. Let’s say the unique id of the order is 2345 and the order number recognized to humans is 100001234 for the same order.

In such case the following separation is logical to have: remoteId: "2345" and remoteRef: "100001234".

The remoteRefMap field (read only)

The behavior of remoteRefMap is just like remoteIdMap, but for ref:s.