Entities

Devices that are stored in DIS are called entities. Every kind of device, be it something small like a meter, something large, like a feeder, or even non-physical like an account are entities from the perspective of DIS.

Entities are mainly identified by their entity class (what kind of device they represent, like service point, meter, substation, and so on) and their ID. No two devices may have the same entity class and the same ID. Entities may also have secondary identifiers, these can be MAC address, serial number, electronic serial number, or utility ID. Not all entity classes may have all of the mentioned alternative identifiers.

Entities have no lifespan. Once they are created, it is assumed that they have always existed and always will, unless explicitly deleted. It is possible to delete entities either by soft deleting them (the entity record remains in the database but is marked as deleted) or by hard deleting (the entity record is removed from the database).

An entity record carries no addition information other than the type of the device, its ID, and its alternate identifiers.

The entity class of an entity may not be changed after creation. Its IDs may be changed, except for the integration key.

Every entity is assigned an integration key upon its creation. This key has no business meaning. It is the internal identifier of the entity which will never change. It can be used to unambiguously identify an entity within DIS. The integration key cannot be set from the outside. It is generated by DIS. Integration keys are never reused. An integration key that has been assigned to an entity that was later deleted will never be assigned to another entity.

Structure of an entity

  • Business ID. The external identifier (stable, but not necessarily permanent).

  • Integration Key. The permanent surrogate key issued by DIS.

  • Last modified date. The date that the entity was last modified.

  • Last modifier.

  • Correlation ID. The external correlation ID passed through DIS.

  • Entity class. The type of the entity (for example, service point, electric meter, transformer, and so on).

  • History of attribute sets.

  • History of links.

IDs

  • Business ID

    Entities can be identified by multiple attributes depending on their entity class. All entities, however, have an identifier that is unique to only them within their entity class and since DIS is a multi-tenant system, their tenant ID. This means that there can only be one entity having a given ID, entity class, and tenant ID. This ID generally has a business meaning but it is not a requirement. The ID of an entity may change, but its entity class cannot. The ID and entity class must be part of the payload during entity creation.

  • Alternate keys

    Entities can have alternate keys that unambigously identify them. Alternate keys are not specified directly. Only the entity numbers are specified in attribute sets. Alternate keys can also be changed.

    • Name. Unique with entity class and tenant ID.

    • Serial number. Unique with tenant ID.

    • Electronic serial number. Unique with tenant ID.

    • Utility ID. Unique with tenant ID.

    • Equipment serial number. Unique with tenant ID.

    • Long form device identifier. Unique with tenant ID.

Surrogate key

All entities are assigned an integration key upon their creation. This key is the next number in an increasing sequence. This key cannot be set in the payload and cannot be changed. It remains the same after it has been assigned and is never reused. The integration key is useful for consumers of DIS, as it provides a way of entity identification that cannot be influenced by third parties. The integration key is globally unique. There is no repetition even across tenant boundaries.

Last modification

Entities hold information about when they were last modified (and by whom or what system). This information is made available to consumers, making it easier for them to determine if an entity has changed since the time they have last received information about it.

Ambiguity checks

As explained in the previous sections, entities can have multiple identifiers. This may lead to a situation where an incoming entity has multiple keys specified in it. These keys may not point to an existing entity and a new entity is created. Or they may all point to the same, existing entity and that entity is updated. Or some of them may point to the same existing entity while some of them not point to any existing entity. In this case, the keys that had no target are updated on the entity the rest of the keys are pointed at and the entity is updated. It is also possible that some keys target one existing entity while others target a different one. This is an ambiguity, since there is no way to tell exactly which entity the caller intends to update. Update requests that exhibit this ambiguity are rejected by DIS.

Updating keys

To update the key of an existing entity, it has to have at least one other key defined. The update payload should contain at least one key that has not changed and the key that is being changed with its new value. The new value cannot be the ID of another entity since that would cause an ambiguity. In this way, DIS identifies the entity in question by the unchanged key and sets the changed key to the new value. Any key in an entity can be changed using this method except the integration key. The integration key cannot be used as the unchanged key as it cannot be set from the outside.

Entity lifetime

After an entity is created it continues to exist forever, it has no expiration date. Entities may be soft deleted. When entities are soft deleted they are not physically removed but all of their links and attribute sets and other associated information about them are physically deleted. They do, however, keep on existing in a deleted state. All of their keys are set to empty (NULL) except for their last ID (business ID), and their integration key.

It is possible to delete everything that exists inside a given tenant. When this happens, even entities are physically removed. Their integration key will not be assigned to any new entities.

Entity groups

Entity groups are entities that serve a special purpose. They can be used to collect entities in a cluster and to query the state of these entities. Groups can contain any type of entities, including other groups. There are two main kinds of groups:

  • Generic entity group. A group with static membership. Its members can be added or removed using the API.

  • Dynamic groups. Groups whose members are not directly assigned. Instead, entity criteria are specified for them. Members of such groups are entities that satisfy the criteria which is repeatedly evaluated so that the membership always accurately reflects the entity state.