External Ids

Entities can either have a single or multiple external IDs in order to be referenced by Third Parties

External IDs associate facilioo entities with their identifiers in an external system, such as an ERP system.
They are mostly used for imports and exports, either to ERP systems or to other products of facilioo, such as the Hybride Eigentümerversammlung.

Meaning of an External Id

The external ID always refers to the system an entity was imported from.

  • externalId is null: the entity was created in facilioo.
  • externalId is set: the entity was imported into facilioo from the external system it identifies.

An integration that links an existing entity to an entry in its own system must not overwrite the external ID.
For example, if a process was imported from one system and another integration links it to an entry in its own system, the process keeps the external ID of the system it was imported from.
If a process was created in facilioo, its external ID stays null, even if integrations link it to their own systems.
Such integrations have to keep the mapping to their own entries themselves.

Entities with Single External Id

Most entities, such as properties, units or conferences, have a single externalId attribute.
It is created, updated and deleted by applying the corresponding operation to the main entity, e.g.:

PATCH /conferences/42

{
  "externalId": "0733b38d-3270-4b76-80e1-464d60e03b9c"
}

Uniqueness

Some entities require the external ID to be unique within a certain context.
The same value can still appear on other entities or in other contexts.
A null external ID is never checked for uniqueness, so any number of entities created in facilioo can exist side by side.

EntityUnique within
TenantThe tenants of the owner party
Property and EntranceThe properties and entrances of the creator party, sharing a context
UnitThe units of the creator party
Unit ContractThe unit contracts of the creator party
AccountThe accounts of the same party
PartyThe parties of the same type with the same owner, see below

The external IDs of all other entities aren't unique yet, e.g. of attributes, booking accounts, consumption meters, documents, files, processes, feed entries, work orders or conference entities.
A lookup by such an external ID can therefore return more than one entity.

Deprecated Old External Ids

Properties (externalOldId) and units (externalIdOld) have an additional attribute for a previous external ID, e.g. from an ERP system used before.
These attributes are deprecated and will be removed, use externalId instead.

Entities with Multiple External Ids

Entities, such as parties, which are shared across multiple tenants of facilioo can have multiple external ids with different owners (property management companies / tenants).
Besides, it's possible that the entity has multiple External IDs naturally, as well.

Example: Party
Parties are not bound to tenants, and therefore different tenants can reference them in their ERP.
Property management company CasaPerfect Verwaltung might work with janitor Jean-Pierre Berger as well as property management company HuG Berlin.
Therefore, the janitor, which is a company, has one external id for CasaPerfect Verwaltung and one for HuG Berlin.
In addition, facilioo does support to deduplicate entries.
Incorrect management of master data leads to duplicated entries of parties, such as owners, in facilioo.
When merging these entities, facilioo does assign all external ids of the duplicated entries to the main entity, therefore, resulting in multiple external ids for that party, as well.

Implementation
In order to fetch external ids of an entity with multiple external ids, there is another endpoint: GET /<entities>/{id}/external-ids which will return a paginated list of strings.
It only returns the external IDs owned by the requesting party.

In order to replace the list of external ids of an entity with multiple external ids, there is another endpoint: PUT /<entities>/{id}/external-ids which takes an array of strings as their body parameter ["A123", "B123"].
It only replaces the external IDs owned by the requesting party, external IDs of other owners stay untouched.
Each external ID has to be unique among the parties of the same type owned by the requesting party.