Migration From v6 to v7

The Runtime of enmeshed has recently been updated from version 6 to version 7. Accordingly, a new version of the Connector has also been released to make the updated Runtime available to Integrators of Connectors. The version update has resulted in some breaking changes. To support the migration of existing systems to the new version, the breaking changes made are listed and explained in this migration guide.

Step-by-Step Instructions

The step-by-step instructions can be consulted to start the migration to version 7 as an Integrator of a Connector directly. Runtime-specific breaking changes that do not need to be taken into account when updating the Connector from version 6 to version 7 can be found below.

Connector Setup

• Data persisted in the database by a previous version of the Connector is not compatible with version 7. For this reason, the old data must be deleted. Alternatively, the database can be deleted as a whole and set up again.
• The image used to run the Connector must be updated to version 7.
• Some changes must be made to the configuration of the Connector.
  • The database.dbNamePrefix field of the database configuration was removed. Before, it defaulted to acc-. If a database called acc-connector is to be accessed, the value of the database.dbName field must be set to acc-connector instead of connector only.
  • To support additional authentication methods beyond API key authentication, the apiKey field was replaced by the authentication.apiKey.keys.<key-id>.key parameter of the authentication configuration. The authentication.apiKey.keys.<key-id>.scopes field provides a convenient way to configure the permissions that apply when the API key identified by <key-id> is used.
  • Additionally, the support for the API_KEY environment variable has been removed, that could be used to define an API key using a short environment variable. As an alternative, the authentication.apiKey.keys.<key-id>.key configuration property can be set using an environment variable.
• It must be ensured that a Backbone is used which is compatible with version 7 of the Connector. Even though a Backbone of version 6 can still be used, it is recommended to update to version 7 of the Backbone due to the new features and bug fixes provided. Appropriate Backbone credentials can be specified in the fields transportLibrary.baseUrl, transportLibrary.platformClientId and transportLibrary.platformClientSecret of the Backbone configuration. The URL <baseUrl of Backbone>/api/v2/version can be accessed to validate the version of the Backbone. Please note that version 7 of the Backbone only supports version 2 of its API and no longer version 1.

Removed and Changed Data Structures

• The FreeTextRequestItem has been removed. It is no longer needed as the FormFieldRequestItem with StringFormFieldSettings as settings can be used instead. Of course, the associated AcceptFreeTextRequestItemParameters and the FreeTextAcceptResponseItem have been removed as well.
• The title property of most RequestItems has been removed, because in most cases the kind of RequestItem already clearly indicates its purpose. To be more precise, the title was only kept by the AuthenticationRequestItem and the FormFieldRequestItem to provide context.
• The title property of the AuthenticationRequestItem is now mandatory to always convey the subject of authentication.
• The requireManualDecision property of all RequestItems has been removed. Requests containing at least one AuthenticationRequestItem or ConsentRequestItem within their items property are no longer eligible for automatic acceptance or rejection by the Decider Module, yet proper configuration still enables automatic processing of Requests containing other RequestItems. Furthermore, the requiresInteraction property was added to the ConsentRequestItem to keep the ability to require an explicit action to grant consent, even though the requireManualDecision property was removed.
• The properties validFrom and validTo have been removed from the IdentityAttribute, the RelationshipAttribute, the IdentityAttributeQuery, the RelationshipAttributeQuery and the ThirdPartyRelationshipAttributeQuery. Specifying validity periods for Attributes is no longer supported as they were not enforced during Attribute processing so far.
• The template property of the Relationship was replaced by the templateId property in order to reduce data duplication by storing only the id of the RelationshipTemplate rather than the RelationshipTemplate itself within the Relationship.
• The truncatedReference property of the Token, the RelationshipTemplate and the File, which was already marked as deprecated, has been removed and replaced by the reference.truncated property. The property reference was introduced to group the property truncated with the additional property url, improving structure and better organizing related data.
• The title property of the File became optional and should no longer be relied upon to be set.
• The ownershipToken property of the TransferFileOwnershipRequestItem became mandatory. This ensures that the ownership of the original File on the Backbone is transferred instead of applying a copy-based workaround. If the ownership of a File ought to be transferred, that doesn’t have an ownershipToken yet, it will need to be regenerated.
• The properties approvedAt and approvedByDevice of the IdentityDeletionProcess have been removed. Furthermore, renaming "Approved" to "Active" resulted in a change of an IdentityDeletionProcess status.
• All data structures around the Attribute listener feature, including the LocalAttributeListener, the RegisterAttributeListenerRequestItem, and the RegisterAttributeListenerAcceptResponseItem, were removed.
• With the new LocalAttribute concept, an Attribute copy is no longer created when an Attribute is shared. Furthermore, LocalAttribute subtypes have been introduced to help distinguish between different kinds of LocalAttributes.
  • RepositoryAttributes were renamed to OwnIdentityAttributes. There are no own shared IdentityAttributes anymore. Instead, sharing an OwnIdentityAttribute leads to the creation of AttributeForwardingDetails.
  • The peer shared IdentityAttribute, the own shared RelationshipAttribute and the peer shared RelationshipAttribute have been replaced by the LocalAttribute subtypes PeerIdentityAttribute, OwnRelationshipAttribute and PeerRelationshipAttribute, respectively.
  • There are no emitted ThirdPartyRelationshipAttributes anymore. Instead, forwarding a RelationshipAttribute to a peer, which is not involved in the Relationship in which the RelationshipAttribute exists, leads to the creation of AttributeForwardingDetails. For this reason, the received ThirdPartyRelationshipAttribute is called ThirdPartyRelationshipAttribute from now on.
  • The shareInfo property of the LocalAttribute and the corresponding LocalAttributeShareInfo data object were removed. To track with which peer an Attribute was shared, AttributeForwardingDetails are now used and, in the case of PeerIdentityAttributes, OwnRelationshipAttributes, PeerRelationshipAttributes, and ThirdPartyRelationshipAttributes, the properties peer, sourceReference, and deletionInfo are utilized. For the ThirdPartyRelationshipAttributes, the initialAttributePeer property is additionally needed.
  • Some LocalAttribute subtypes may have a deletionInfo set, which has either EmittedAttributeDeletionInfo or ReceivedAttributeDeletionInfo as its type. The LocalAttributeDeletionInfo data object has been removed.
  • The introduction of the LocalAttribute subtypes has led to a renaming of the NotificationItems. The PeerAttributeSucceededNotificationItem replaces the PeerSharedAttributeSucceededNotificationItem. The OwnSharedAttributeDeletedByOwnerNotificationItem, the PeerSharedAttributeDeletedByPeerNotificationItem and the ThirdPartyRelationshipAttributeDeletedByPeerNotificationItem have been replaced by the OwnAttributeDeletedByOwnerNotificationItem, the PeerRelationshipAttributeDeletedByPeerNotificationItem and the ForwardedAttributeDeletedByPeerNotificationItem.
  • To better align with the initialAttributePeer property of the ThirdPartyRelationshipAttribute, the thirdPartyAddress property of the ShareAttributeRequestItem and the ReadAttributeAcceptResponseItem has been renamed to initialAttributePeer.
  • The parentId property of the LocalAttribute was removed as there is no child Attribute feature anymore. Sharing individual components of a complex IdentityAttribute will be possible again in future releases.

Changed Behavior of Known Features

• Stricter validation of tags of IdentityAttributes and Files have been added as documented in their description in the data model overview. An error with error code error.consumption.attributes.invalidTags will be thrown if an attempt is made to use invalid tags.
• For Attribute values, a character set is introduced. An error with error code error.consumption.attributes.forbiddenCharactersInAttribute will be thrown if an attempt is made to use characters outside of that character set in an Attribute value.

Removed and Changed Connector Routes

• For every Connector route originating from the Core HTTP API Module, the prefix has been changed from /api/v2 to /api/core/v1 to reflect its origin. The prefix syntax change led to the version being reset.
• The GET /api/v2/Attributes/Valid Connector route and its underlying use case for getting valid Attributes were removed, because the properties validFrom and validTo have been removed from the Attributes.
• For the same reason, the onlyValid parameter was removed from the use cases Get Attributes, Get own shared Attributes and Get peer shared Attributes. Accordingly, it was removed from the associated Connector routes as well.

TypeScript SDK Changes

With every version of the Connector, we ship a matching TypeScript SDK. With version 7 of the SDK, the deprecated field apiKey was removed. To access the Connector using an API key, you can configure the SDK now as follows:

import { ApiKeyAuthenticator, ConnectorClient } from "@nmshd/connector-sdk";

const connectorClient = ConnectorClient.create({
  baseUrl: "<insert-the-base-URL-of-your-Connector-here>",
  authenticator: new ApiKeyAuthenticator("<insert-your-valid-API-key-here>")
});

Removed and Changed Error Codes

An overview of the Error codes that may occur is given on the corresponding documentation page. The most important changes regarding the error codes due to the update from version 6 to version 7 are:

• With the new LocalAttribute concept, an Attribute copy is no longer created when an Attribute is shared. Therefore, there are no Attribute copies and source Attributes anymore. The error.consumption.attributes.successorSourceContentIsNotEqualToCopyContent error code and similar error codes could thus be removed.
• The error.consumption.attributes.successionMustNotChangePeer error code has been removed as the new LocalAttribute concept prevents some errors from occurring. Similarly, other error codes are no longer needed. However, a few new error codes, such as error.consumption.attributes.wrongTypeOfAttribute, had to be introduced.
• The error.runtime.attributes.isNotRepositoryAttribute error code has been renamed to error.runtime.attributes.isNotOwnIdentityAttribute as OwnIdentityAttributes now present those LocalAttributes that were previously known as RepositoryAttributes. Similarly, other error codes have been renamed.
• The error.consumption.attributes.cannotSucceedChildOfComplexAttribute error code has been removed as there is no child Attribute feature anymore.
• By renaming an IdentityDeletionProcess status from "Approved" to "Active", the error code error.runtime.identityDeletionProcess.noApprovedIdentityDeletionProcess has been replaced by error.runtime.identityDeletionProcess.noActiveIdentityDeletionProcess.

Runtime-Specific Breaking Changes

As an Integrator of a Connector, the following changes do not need to be taken into account during migration to version 7, as they are Runtime-specific breaking changes handled internally by the Connector.

Removed Use Cases

Some use cases of the Runtime that were previously marked as deprecated and replaced by new ones have now been removed. However, the Connector routes associated with these use cases are not affected by these replacements and can still be used.

• The nomenclature of ThirdPartyRelationshipAttributes has already changed in version 6. In particular, the term third party owned RelationshipAttribute has become obsolete. For this reason, the Delete a ThirdPartyRelationshipAttribute and notify peer use case was already added in version 6 and the use case of deleting a third party owned RelationshipAttribute and notifying the peer was marked as deprecated. It has now been deleted with the update to version 7.
• It will be possible to load items not only from truncated references, but also from other references. For this reason, the Load item from reference use case was already added in version 6 and the use case of loading an item from a truncated reference was marked as deprecated. It has now been deleted with the update to version 7.