From 02e5e20e021097a1c4c645594a44e6f6eb34bdee Mon Sep 17 00:00:00 2001 From: Britta Stallknecht <146106656+britsta@users.noreply.github.com> Date: Mon, 16 Dec 2024 16:59:29 +0100 Subject: [PATCH] Notifications can be sent in case of terminated Relationships (#286) * fix: broken links * feat: mention that Notifications can be sent on terminated Relationships * refactor: place related sentences next to each other * feat: mention in other scenarios queuing of Notifications * fix: missing peerIdentity property of RelationshipDTO * fix: wrong remark about Backbone * feat: incorporate review comments * feat: incorporate review comments --- _docs_integrate/attribute-introduction.md | 2 +- _docs_integrate/data-model-overview.md | 7 ++++--- _docs_integrate/delete-attributes.md | 8 ++++++++ _docs_integrate/terminate-relationships.md | 11 ++++++++++- _docs_integrate/update-attributes-by-succession.md | 8 ++++++++ 5 files changed, 31 insertions(+), 5 deletions(-) diff --git a/_docs_integrate/attribute-introduction.md b/_docs_integrate/attribute-introduction.md index 32766b872..f6dbd99b0 100644 --- a/_docs_integrate/attribute-introduction.md +++ b/_docs_integrate/attribute-introduction.md @@ -67,7 +67,7 @@ This can be done by using a suitable [Request]({% link _docs_integrate/data-mode #### Own shared and peer shared IdentityAttributes -When [exchanging the underlying IdentityAttribute of a RepositoryAttribute with a peer](#exchange-attributes-with-peers), two corresponding copies of the RepositoryAttribute, the own shared IdentityAttribute and the peer shared IdentityAttribute, are created. This makes it possible to record with whom an IdentityAttribute has been shared or from whom an IdentityAttribute has been received. When an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) is shared by its `owner`, an own shared IdentityAttribute is created as a copy of the associated RepositoryAttribute in the wallet of the `owner`. An own shared IdentityAttribute is a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) for which, in contrast to the RepositoryAttribute, the `shareInfo` property is set. The `content` of the own shared IdentityAttribute is the same as that of the RepositoryAttribute. The `address` of the peer with whom the IdentityAttribute is shared is contained within its `shareInfo.peer` property. Furthermore, the `id` of the RepositoryAttribute used as the source is stored in its `shareInfo.sourceAttribute` property. This is the case as long as the RepositoryAttribute used as the source has not been [deleted]({% link _docs_integrate/delete-attributes.md %}#delete-repositoryattributes). If an IdentityAttribute is shared by its `owner` with several peers, a corresponding number of own shared IdentityAttributes are generated. +When [exchanging the underlying IdentityAttribute of a RepositoryAttribute with a peer](#attribute-management-options), two corresponding copies of the RepositoryAttribute, the own shared IdentityAttribute and the peer shared IdentityAttribute, are created. This makes it possible to record with whom an IdentityAttribute has been shared or from whom an IdentityAttribute has been received. When an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) is shared by its `owner`, an own shared IdentityAttribute is created as a copy of the associated RepositoryAttribute in the wallet of the `owner`. An own shared IdentityAttribute is a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) for which, in contrast to the RepositoryAttribute, the `shareInfo` property is set. The `content` of the own shared IdentityAttribute is the same as that of the RepositoryAttribute. The `address` of the peer with whom the IdentityAttribute is shared is contained within its `shareInfo.peer` property. Furthermore, the `id` of the RepositoryAttribute used as the source is stored in its `shareInfo.sourceAttribute` property. This is the case as long as the RepositoryAttribute used as the source has not been [deleted]({% link _docs_integrate/delete-attributes.md %}#delete-repositoryattributes). If an IdentityAttribute is shared by its `owner` with several peers, a corresponding number of own shared IdentityAttributes are generated.
diff --git a/_docs_integrate/data-model-overview.md b/_docs_integrate/data-model-overview.md index 626c8518f..1b69d5356 100644 --- a/_docs_integrate/data-model-overview.md +++ b/_docs_integrate/data-model-overview.md @@ -93,8 +93,9 @@ A Relationship between two Identities is the prerequisite for them to exchange M | template | [`RelationshipTemplate`](#relationshiptemplate) | The RelationshipTemplate that was used to establish this Relationship. | | | status | `"Pending"` \| `"Active"` \| `"Rejected"` \| `"Revoked"` \| `"Terminated"` \| `"DeletionProposed"` | The status of this Relationship.
{::nomarkdown}{:/} | | | creationContent | [`RelationshipCreationContent`](#relationshipcreationcontent) \| [`ArbitraryRelationshipCreationContent`](#arbitraryrelationshipcreationcontent) | The content sent along when the Relationship is initiated. If the `template` contains a [RelationshipTemplateContent](#relationshiptemplatecontent), `RelationshipCreationContent` has to be used. Otherwise, an `ArbitraryRelationshipCreationContent` is used, which can be filled with anything. | will be encrypted before sent to the Backbone | -| peer | `string` | The `address` of the [Identity](#identity) with which you have this Relationship. | saved only locally | -| peerDeletionInfo | [`PeerDeletionInfo`](#peerdeletioninfo) \| `undefined` | Information about whether the Identity with which you have this Relationship is to be deleted or was deleted, as well as the point in time of that deletion. | saved only locally | +| peer | `string` | The `address` of the [Identity](#identity) with which you have this Relationship. | | +| peerIdentity | [`Identity`](#identity) | The [Identity](#identity) with which you have this Relationship. | | +| peerDeletionInfo | [`PeerDeletionInfo`](#peerdeletioninfo) \| `undefined` | Information about whether the Identity with which you have this Relationship is to be deleted or was deleted, as well as the point in time of that deletion. | | | auditLog | [`RelationshipAuditLogEntry`](#relationshipauditlogentry)`[]` | A log of Relationship operations like creating or accepting a pending Relationship. | | ### PeerDeletionInfo @@ -342,7 +343,7 @@ With the information in this type you can clearly identify the Transport object A LocalAttribute stores the local metadata for an [Attribute](#attributes). This is contained within the `content` property of the LocalAttribute. The Attribute can be an [IdentityAttribute](#identityattribute) or a [RelationshipAttribute](#relationshipattribute). In the case of IdentityAttributes, there are three situations in which a LocalAttribute is created in the database: - The Identity [creates an IdentityAttribute for itself]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-an-identityattribute-for-yourself) (e.g. sets its first name). In particular, it is the `owner` of the IdentityAttribute. Its `shareInfo` property is undefined. Such an unshared LocalAttribute is called a **RepositoryAttribute**. -- The Identity shares an IdentityAttribute of itself with another Identity (e.g. by [exchanging]({% link _docs_integrate/attribute-introduction.md %}#exchange-attributes-with-peers) it using a suitable [Request]({% link _docs_integrate/data-model-overview.md %}#request)). In that case, a _copy_ of the RepositoryAttribute used as the source is created for which the `shareInfo` property is set. This LocalAttribute is referred to as an **own shared IdentityAttribute**. +- The Identity shares an IdentityAttribute of itself with another Identity (e.g. by [exchanging]({% link _docs_integrate/attribute-introduction.md %}#attribute-management-options) it using a suitable [Request]({% link _docs_integrate/data-model-overview.md %}#request)). In that case, a _copy_ of the RepositoryAttribute used as the source is created for which the `shareInfo` property is set. This LocalAttribute is referred to as an **own shared IdentityAttribute**. - The Identity receives an IdentityAttribute from another Identity (e.g. receives it via a [Request]({% link _docs_integrate/data-model-overview.md %}#request)). In that case a _new_ LocalAttribute is created for which the `shareInfo` property is set. This LocalAttribute is called a **peer shared IdentityAttribute**. In contrast, [RelationshipAttributes](#relationshipattribute) always exist in the context of a [Relationship](#relationship). diff --git a/_docs_integrate/delete-attributes.md b/_docs_integrate/delete-attributes.md index ae998f35e..c7a5486d6 100644 --- a/_docs_integrate/delete-attributes.md +++ b/_docs_integrate/delete-attributes.md @@ -111,6 +111,10 @@ Moreover, if the peer shared Attribute had a successor, its `succeeds` property Then, a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) with a [PeerSharedAttributeDeletedByPeerNotificationItem]({% link _docs_integrate/data-model-overview.md %}#peersharedattributedeletedbypeernotificationitem) is generated and sent to the owner of the peer shared Attribute, informing them that you deleted the Attribute they shared with you. Consequently, the `deletionInfo` of their corresponding own shared Attribute and of all potential predecessors is updated with `deletionStatus` `"DeletedByPeer"` and the time of receiving the Notification as `deletionDate`. In case the owner already [deleted their own shared Attribute](#delete-own-shared-attributes), nothing happens. +Please further note that the Notification is queued if the [Relationship is currently terminated]({% link _docs_integrate/terminate-relationships.md %}#terminate-an-active-relationship) but not yet [decomposed]({% link _docs_integrate/terminate-relationships.md %}#decompose-a-relationship). +It can then only be received and processed if the [Relationship is reactivated]({% link _docs_integrate/terminate-relationships.md %}#reactivate-a-terminated-relationship). +The Notification is also queued if the [peer is currently in deletion]({% link _docs_integrate/delete-identities.md %}#effects-of-identity-deletion-on-relationships) but not yet deleted. +It can then only be received and processed if the peer [cancels its deletion]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}).
@@ -132,6 +136,10 @@ Then, a Notification with an [OwnSharedAttributeDeletedByOwnerNotificationItem]( If they already deleted their corresponding peer shared Attribute or marked it for deletion, nothing will change. However, if the `deletionInfo` of their peer shared Attribute was undefined before, since you didn't send a Request for Attribute deletion or the Request was rejected, a `deletionInfo` will be set. Its `deletionStatus` will be set to `"DeletedByOwner"` and the `deletionDate` will be the time of receiving the Notification. +Please note that the Notification is queued if the [Relationship is currently terminated]({% link _docs_integrate/terminate-relationships.md %}#terminate-an-active-relationship) but not yet [decomposed]({% link _docs_integrate/terminate-relationships.md %}#decompose-a-relationship). +It can then only be received and processed if the [Relationship is reactivated]({% link _docs_integrate/terminate-relationships.md %}#reactivate-a-terminated-relationship). +Furthermore, the Notification is also queued if the [peer is currently in deletion]({% link _docs_integrate/delete-identities.md %}#effects-of-identity-deletion-on-relationships) but not yet deleted. +It can then only be received and processed if the peer [cancels its deletion]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}).
diff --git a/_docs_integrate/terminate-relationships.md b/_docs_integrate/terminate-relationships.md index 9cfa4a491..e900b6db4 100644 --- a/_docs_integrate/terminate-relationships.md +++ b/_docs_integrate/terminate-relationships.md @@ -33,7 +33,15 @@ It is then no longer possible to reactivate the Relationship. ## Terminate an active Relationship -Terminate an active Relationship with the use case [Terminate Relationship]({% link _docs_use-cases/use-case-transport-terminate-relationship.md %}) with the `relationshipId` as input. The `status` of the Relationship is changed to `"Terminated"`. You receive a `transport.relationshipChanged` [event]({% link _docs_integrate/connector-events.md %}), and the peer as well if they use a Connector. Then no Messages can be sent from either side, this includes Requests, Notifications and sharing Attributes. The peer cannot prevent the termination. +An active Relationship can be terminated by executing the use case [Terminate Relationship]({% link _docs_use-cases/use-case-transport-terminate-relationship.md %}) providing the `relationshipId` as input. +The termination of the Relationship does not require the permission of the peer. +After the Relationship has been terminated, its `status` changes to `"Terminated"`. +The Identity which terminated the Relationship and its peer receive a `transport.relationshipChanged` [event]({% link _docs_integrate/connector-events.md %}). +Then no [Messages]({% link _docs_integrate/data-model-overview.md %}#message) can be sent from either side. This includes [sending or responding to Requests]({% link _docs_integrate/requests-via-messages.md %}) and [exchanging Attributes]({% link _docs_integrate/attribute-introduction.md %}#attribute-management-options). +However, please note that Messages whose `content` is a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) are still sent on terminated Relationships. +Such Notifications cannot be received directly, but they are queued in case the Relationship is [reactivated](#reactivate-a-terminated-relationship). +For example, if certain [Attributes were deleted]({% link _docs_integrate/attribute-introduction.md %}#delete-attributes) or [Attributes were updated by succession]({% link _docs_integrate/attribute-introduction.md %}#update-attributes-by-succession) while the Relationship was terminated, the associated Notifications are transmitted after the reactivation. +Therefore, the loss of relevant information is prevented. ## Reactivate a terminated Relationship @@ -41,6 +49,7 @@ At any time, you or your peer can request the reactivation of the terminated Rel If your peer requests the reactivation, you will receive a `transport.relationshipReactivationRequested` [event]({% link _docs_integrate/connector-events.md %}) in addition to a `transport.relationshipChanged` event, which the peer also receives if they use a Connector. If you then wish to return the Relationship to an active status, you accept the reactivation with the use case [Accept Relationship reactivation]({% link _docs_use-cases/use-case-transport-accept-relationship-reactivation.md %}). +In this case, all Notifications that were sent while the Relationship was terminated are transmitted. If you want to keep the Relationship terminated, you reject the reactivation with the use case [Reject Relationship reactivation]({% link _docs_use-cases/use-case-transport-reject-relationship-reactivation.md %}). If you have requested the reactivation and changed your mind, you revoke it with the use case [Revoke Relationship reactivation]({% link _docs_use-cases/use-case-transport-revoke-relationship-reactivation.md %}). diff --git a/_docs_integrate/update-attributes-by-succession.md b/_docs_integrate/update-attributes-by-succession.md index 72eed397a..aab748133 100644 --- a/_docs_integrate/update-attributes-by-succession.md +++ b/_docs_integrate/update-attributes-by-succession.md @@ -85,6 +85,10 @@ After succeeding a RepositoryAttribute, you can check [with which of your peers Your own shared IdentityAttributes associated with the peers chosen will be succeeded in the same manner as your RepositoryAttribute before. Then, a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) is sent to the peers, containing a [PeerSharedAttributeSucceededNotificationItem]({% link _docs_integrate/data-model-overview.md %}#peersharedattributesucceedednotificationitem). In the `successorContent` property of the latter the updated IdentityAttribute is transmitted and automatically a likewise succession at the peers' side will be triggered, such that their LocalAttribute versions replicate the succession chain at your side. +Please note that the Notification is queued if the [Relationship is currently terminated]({% link _docs_integrate/terminate-relationships.md %}#terminate-an-active-relationship) but not yet [decomposed]({% link _docs_integrate/terminate-relationships.md %}#decompose-a-relationship). +It can then only be received and processed if the [Relationship is reactivated]({% link _docs_integrate/terminate-relationships.md %}#reactivate-a-terminated-relationship). +The Notification is also queued if the [peer is currently in deletion]({% link _docs_integrate/delete-identities.md %}#effects-of-identity-deletion-on-relationships) but not yet deleted. +It can then only be received and processed if the peer [cancels its deletion]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}).
@@ -110,6 +114,10 @@ Equally to IdentityAttributes, again only the `owner` can [succeed a Relationshi Doing so, a new version of the own shared RelationshipAttribute will be created at your side. The `succeeds` property of this LocalAttribute links to the old version, whose `succeededBy` property in turn is updated to the `id` of the newly created successor. Then, a Notification is sent automatically to the peer, which triggers the creation of a new peer shared RelationshipAttribute at their side, such that their LocalAttribute versions replicate the succession chain at your side. +Please note that the Notification is queued if the [Relationship is currently terminated]({% link _docs_integrate/terminate-relationships.md %}#terminate-an-active-relationship) but not yet [decomposed]({% link _docs_integrate/terminate-relationships.md %}#decompose-a-relationship). +It can then only be received and processed if the [Relationship is reactivated]({% link _docs_integrate/terminate-relationships.md %}#reactivate-a-terminated-relationship). +Furthermore, the Notification is also queued if the [peer is currently in deletion]({% link _docs_integrate/delete-identities.md %}#effects-of-identity-deletion-on-relationships) but not yet deleted. +It can then only be received and processed if the peer [cancels its deletion]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}).