Remote Identifiers

Remote Identifiers are used to link records or individual data fields from external systems to our entities.
They allow tracing the origin of an entire entity or specific pieces of data back to their source.
By using Remote Identifiers, it remains possible to track from which external system a dataset was imported and under which ID it is referenced there.

Use Case

Remote Identifiers are especially valuable when importing data from external systems. During import, records are transferred into our system and assigned one or more Remote Identifiers. Since the external system typically has no knowledge of our internal entity IDs, the Remote Identifier enables a reliable later assignment: using the combination of Source (system name) and ID (record identifier), an imported record can be identified without requiring internal knowledge. For example, when synchronizing or updating data, the external ID can be used to locate and update the corresponding entity — even if the internal ID is unknown.

Structure

Each Remote Identifier consists of two components:
"source": string (required) The name of the external system from which the data was imported.

"id": string (required) The unique identifier of the record in the external system.
An entity can have multiple Remote Identifiers. Each identifier represents an independent linkage to a specific record in a specific system.

warning

Each source must be unique per entity. An entity cannot have multiple Remote Identifiers with the same source.

Using remote identifiers

Remote Identifiers can be assigned directly when creating a new entity or can be added, updated, removed later via the described Endpoint below.

Request

PATCH 
/:id/remote-identifiers

{
  "remoteIdentifiers": [
    {
      "source": "CRM-System-X",
      "id": "abc-123"
    },
    {
      "source": "ERP-System-Y",
      "id": "erp-456"
    },
    {
      "source": "Legacy-DB",
      "remove": true
    }
  ]
}

remoteIdentifiers (remoteIdentifiers)

"source": string (required) The name of the external system from which the data originates.

"id": string (optional) The ID of the record in the external system.

"remove": boolean (optional) If set to true, the specified remote identifier will be removed.

Response

• If the entity does not exist, the Gateway returns a 404 Not Found.
• If a remote identifier has a source but no ID (and is not marked for removal), the Gateway returns a 400 Bad Request.
  "The identifier <source> has no id"
• If the provided import definition no longer exists, the Gateway returns a 400 Bad Request.
  "The import definition <definition> does not exist anymore. Please delete the remote identifier with the source <source>."

Querying by remote identifier

In some cases, you may want to query entities based on their remote identifiers.
For example, if you imported data from your system, and now want to update the corresponding entity in our system but don't know the internal ID of the entity.
Than you can use the remote identifiers to search for the entity in our system.
To do this, you can use the dsl filter in a search query.

Request

POST 
/api/v1/entities/search

{
  "filter": {
    "type": "dsl",
    "content": {
      "query": {
        "nested": {
          "path": "remoteIdentifiers",
          "query": {
            "bool": {
              "must": [
                { "match": { "remoteIdentifiers.source": "CRM-System-X" } }, // replace with your source
                { "match": { "remoteIdentifiers.id": "abc-123" } } // replace with your id
              ]
            }
          }
        }
      }
    }
  },
  "result": {
    "format": "json"
  },
  "options": {
    "showDeleted": true, // if you want to include deleted entities
    "showExpired": true, // if you want to include expired entities
    "size": 10
  }
}

Response

The response will contain the entity that match the provided remote identifier.

info

Sometimes it can happen that you have multiple entities with the same remote identifier.
For example, if you don't have a restriction on a specific project. In this case, the response will contain all entities that match the provided remote identifier.

{
    "status": "success",
    "meta": {
        "took": 27,
        "total": 1,
        "pagination": {
            "size": 10,
            "page": 1,
            "pages": 1
        }
    },
    "data": [
        {
            "_id": "0908f2377f8a45e7b7b9377418ffb045",
            ...
            "remoteIdentifiers": [
                {
                    "source": "CRM-System-X",
                    "id": "abc-123"
                }
            ],
            ...
        }
    ]
}