Integrate enmeshed

An organization needs the option to easily store arbitrary auxiliary metadata about familiar persons for its self-administration. This metadata must be differentiated from the IdentityAttributes provided by enmeshed, which are created for the purpose of exchanging with other Identities. From a technical point of view, an Integrator of a Connector should be able to store metadata related to an Identity within the Connector. The Identity about which metadata is to be stored must be sufficiently familiar to them, which means that it must be a peer of a Relationship or their own Identity.

For information on how to establish Relationships, refer to the Establish Relationships scenario documentation.

Storage of IdentityMetadata

Metadata about an Identity is stored in a data object of type IdentityMetadata. It has the properties id, reference, key and value. It is possible to create or update IdentityMetadata about an Identity by proceeding as described in the Upsert IdentityMetadata use case documentation and specifying its address as reference and the metadata to be stored as value. If the referenced Identity is neither the own Identity nor a peer of a Relationship and is therefore not sufficiently familiar, an error with error code error.runtime.identityMetadata.unfamiliarReferencedIdentity is thrown. The optional key property can be used as an additional identifier to store multiple IdentityMetadata about a single Identity. If there is no IdentityMetadata for a given reference and key combination, a new IdentityMetadata will be created by the use case. Otherwise, the existing IdentityMetadata is updated inplace with the new value provided. Therefore, there can be at most one IdentityMetadata per reference and key combination. In particular, there can be at most one IdentityMetadata without a key for each Identity. For this reason, IdentityMetadata can be queried by specifying a combination of reference and key using the Get IdentityMetadata use case with a uniquely determined return value. If no matching IdentityMetadata can be found for the specified parameters, an error with error code error.runtime.identityMetadata.notFound is thrown.

Removal of IdentityMetadata

If an Integrator of a Connector wants to delete IdentityMetadata manually, they must utilize the Delete IdentityMetadata use case providing the combination of reference and key of the IdentityMetadata to be deleted. An error with error code error.runtime.identityMetadata.notFound is thrown if no matching IdentityMetadata can be found for the specified parameters. When decomposing a Relationship, all IdentityMetadata that have the peer of the Relationship as their reference is deleted automatically.

Differentiation from IdentityAttributes

In addition to the IdentityMetadata presented in this guide, enmeshed provides IdentityAttributes for storing data of an Identity. These two types of data objects are different from each other and are used for entirely different purposes. In contrast to IdentityAttributes, IdentityMetadata can only be managed by Integrators of Connectors and not by App users. This is because IdentityMetadata is intended as a separate option for Integrators of Connectors to store arbitrary auxiliary metadata of their peers. IdentityAttributes are strongly interwoven into enmeshed and its features and the value of an IdentityAttribute is therefore more strictly typed. The following table provides an overview of the differences between IdentityAttributes and IdentityMetadata.

Aspect IdentityAttribute IdentityMetadata
Managing Identity It can be managed by both an Integrator of a Connector or an App user. It can only be managed by an Integrator of a Connector.
Possible types of value There is a predefined list of permitted IdentityAttribute value types. It must only be compatible with the JSON data types string, number, boolean, object, array and null.
Kind of storage Local storage within the content property of a LocalAttribute. The LocalAttribute can be identified by its id, which has ATT as prefix. Local storage within an IdentityMetadata data object. It can be identified by its id, which has IDM as prefix, or alternatively by its combination of reference and key.
Storability for own Identity Stored as a RepositoryAttribute. When sharing a RepositoryAttribute, an own shared IdentityAttribute is created as a copy. Stored as an IdentityMetadata that has the address of the own Identity as its reference.
Storability for peer of Relationship Stored as a peer shared IdentityAttribute. Cannot be created manually, but is created automatically if the peer of the Relationship has shared their RepositoryAttribute. Stored as an IdentityMetadata that has the peer of the Relationship as its reference.
Set of features Comprehensive feature set which, in addition to creating, updating, getting and deleting an IdentityAttribute, also includes sharing with peer, reading from peer, creating for peer and proposing to peer. Minimal feature set that includes creating and updating, getting and deleting IdentityMetadata.
Kind of update of value The value is updated by succession and the history of changes is preserved. The value is updated inplace and the history of changes is lost.

What’s next?

As already mentioned in the section on the differentiation from IdentityAttributes, IdentityAttributes are the classic means of choice provided by enmeshed to describe an Identity. To find out more about IdentityAttributes and the options for managing them, the IdentityAttribute introduction can be consulted.