diff --git a/_data/navigation.yml b/_data/navigation.yml index 74e972179..2a39f4b4f 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -83,7 +83,7 @@ docs_integrate: url: /integrate/integration-example - title: "Event introduction" url: /integrate/event-introduction - - title: Relationships between Identities + - title: Identities and Relationships children: - title: "Establish Relationships" url: integrate/establish-relationships @@ -91,7 +91,9 @@ docs_integrate: url: /integrate/exchange-messages - title: "Terminate Relationships" url: integrate/terminate-relationships - - title: Working with Requests + - title: "Delete Identities" + url: integrate/delete-identities + - title: Working With Requests children: - title: "Request and Response introduction" url: /integrate/request-and-response-introduction @@ -117,7 +119,7 @@ docs_integrate: url: /integrate/update-attributes-by-succession - title: "Delete Attributes" url: /integrate/delete-attributes - - title: Request consent + - title: Request Consent children: - title: "Request persistent consent of peer" url: /integrate/request-persistent-consent-of-peer diff --git a/_docs_integrate/01-integrate-scenarios.md b/_docs_integrate/01-integrate-scenarios.md index f99308007..72f455216 100644 --- a/_docs_integrate/01-integrate-scenarios.md +++ b/_docs_integrate/01-integrate-scenarios.md @@ -17,9 +17,9 @@ Here you'll find everything you need to seamlessly dive into the world of enmesh Begin your integration journey by familiarizing yourself with the [Connector REST API]({% link _docs_integrate/access-the-connector.md %}) and exploring the fundamental steps for integration. Gain insights into effectively utilizing the [Connector SDKs]({% link _docs_integrate/access-the-connector.md %}#accessing-the-connector-by-software-development-kits-sdk) to streamline and optimize your integration. To get a first impression of certain integration processes, take a look at our [Integration example]({% link _docs_integrate/integration-example.md %}). Discover how events work and how you can leverage them in your application in the [Event introduction]({% link _docs_integrate/event-introduction.md %}). -## Relationships Between Identities +## Identities and Relationships -Learn how to [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}) to another Identity in order to be able to communicate and exchange information with it. Furthermore, explore how to [exchange Messages]({% link _docs_integrate/exchange-messages.md %}) using enmeshed to communicate simply and securely with your peers. +Learn how to [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}) to another Identity in order to be able to communicate and exchange information with it. Explore how to [exchange Messages]({% link _docs_integrate/exchange-messages.md %}) using enmeshed to communicate simply and securely with your peers. Furthermore, discover how to [terminate Relationships]({% link _docs_integrate/terminate-relationships.md %}) and [delete Identities]({% link _docs_integrate/delete-identities.md %}). ## Working With Requests diff --git a/_docs_integrate/connector-events.md b/_docs_integrate/connector-events.md index 6672c1b8b..4c3bb7882 100644 --- a/_docs_integrate/connector-events.md +++ b/_docs_integrate/connector-events.md @@ -23,28 +23,32 @@ required_by: # End automatic generation --- -| Event | Data | Description (This event is triggered when ...) | -| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| consumption.attributeCreated | [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#LocalAttribute) | ... an Attribute was created manually or through a Request. | -| consumption.attributeDeleted | [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#LocalAttribute) | ... an Attribute was deleted manually or through a Request. | -| consumption.attributeSucceeded | [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#LocalAttribute) | ... an Attribute was succeeded manually or through a Request. | -| consumption.attributeUpdated | [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#LocalAttribute) | ... an Attribute was updated manually or through a Request. | -| consumption.incomingRequestReceived | [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#LocalRequest) | ... an incoming Request was received either by loading a RelationshipTemplate or by receiving a Message | -| consumption.incomingRequestStatusChanged | [RequestStatusChangedEventData](#requeststatuschangedeventdata) | ... the status of an incoming Request has changed. | -| consumption.messageProcessed | [MessageProcessedEventData](#messageprocessedeventdata) | ... a Message was processed by Modules like the `RequestModule` or `DeciderModule`. | -| consumption.outgoingRequestCreated | [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#LocalRequest) | ... any outgoing Request was created by the Connector API or Connector Module. | -| consumption.outgoingRequestCreatedAndCompleted | [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#LocalRequest) | ... any outgoing Request was transferred via a RelationshipTemplate.
This event could either be triggered:
• by an incoming pending Relationship using the `onNewRelationship` property within the RelationshipTemplate
Content
• by an incoming Message using the `onExistingRelationship` property within the RelationshipTemplate
Content, if the user already has a Relationship with the RelationshipTemplate creator | -| consumption.
outgoingRequestFromRelationshipCreation
CreatedAndCompleted | [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#LocalRequest) | ... a `consumption.`
`outgoingRequest`
`CreatedAndCompleted` event is fired and it was fired due to an incoming pending Relationship. This convenience event is useful to act on incoming pending Relationships. | -| consumption.outgoingRequestStatusChanged | [RequestStatusChangedEventData](#requeststatuschangedeventdata) | ... the status of an outgoing Request has changed. | -| consumption.relationshipTemplateProcessed | [RelationshipTemplateProcessedEventData](#relationshiptemplateprocessedeventdata) | ... a RelationshipTemplate was processed by Modules like the `RequestModule` or `DeciderModule`. | -| consumption.sharedAttributeCopyCreated | [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#LocalAttribute) | ... an Attribute is copied for sharing with another Identity. | -| transport.messageReceived | [Message]({% link _docs_integrate/data-model-overview.md %}#Message) | ... a Message is received during synchronization. | -| transport.messageSent | [Message]({% link _docs_integrate/data-model-overview.md %}#Message) | ... a Message was sent. | -| transport.peerRelationshipTemplateLoaded | [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#RelationshipTemplate) | ... a RelationshipTemplate was loaded that belongs to another Identity. | -| transport.relationshipChanged | [Relationship]({% link _docs_integrate/data-model-overview.md %}#Relationship) | ... a Relationship has changed. This can be due to one of the following cases:
• you create a Relationship
• you accept, reject or revoke a pending Relationship
• you terminate an active Relationship
• you request the reactivation of a terminated Relationship or accept, reject or revoke such a reactivation request
• a new Relationship is received or an existing one changed during synchronization | -| transport.relationshipReactivationRequested | [Relationship]({% link _docs_integrate/data-model-overview.md %}#Relationship) | ... the reactivation of a terminated Relationship has been requested by you or the peer. | -| transport.relationshipReactivationCompleted | [Relationship]({% link _docs_integrate/data-model-overview.md %}#Relationship) | ... the reactivation of a terminated Relationship has been accepted, rejected or revoked by you or the peer. | -| transport.relationshipDecomposedBySelf | [Relationship]({% link _docs_integrate/data-model-overview.md %}#Relationship) | ... you have decomposed a terminated Relationship. | +| Event | Data | Description (This event is triggered when ...) | +| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| consumption.attributeCreated | [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#LocalAttribute) | ... an Attribute was created manually or through a Request. | +| consumption.attributeDeleted | [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#LocalAttribute) | ... an Attribute was deleted manually or through a Request. | +| consumption.attributeSucceeded | [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#LocalAttribute) | ... an Attribute was succeeded manually or through a Request. | +| consumption.attributeUpdated | [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#LocalAttribute) | ... an Attribute was updated manually or through a Request. | +| consumption.incomingRequestReceived | [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#LocalRequest) | ... an incoming Request was received either by loading a RelationshipTemplate or by receiving a Message | +| consumption.incomingRequestStatusChanged | [RequestStatusChangedEventData](#requeststatuschangedeventdata) | ... the status of an incoming Request has changed. | +| consumption.messageProcessed | [MessageProcessedEventData](#messageprocessedeventdata) | ... a Message was processed by Modules like the `RequestModule` or `DeciderModule`. | +| consumption.outgoingRequestCreated | [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#LocalRequest) | ... any outgoing Request was created by the Connector API or Connector Module. | +| consumption.outgoingRequestCreatedAndCompleted | [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#LocalRequest) | ... any outgoing Request was transferred via a RelationshipTemplate.
This event could either be triggered:
• by an incoming pending Relationship using the `onNewRelationship` property within the RelationshipTemplate
Content
• by an incoming Message using the `onExistingRelationship` property within the RelationshipTemplate
Content, if the user already has a Relationship with the RelationshipTemplate creator | +| consumption.
outgoingRequestFromRelationshipCreation
CreatedAndCompleted | [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#LocalRequest) | ... a `consumption.`
`outgoingRequest`
`CreatedAndCompleted` event is fired and it was fired due to an incoming pending Relationship. This convenience event is useful to act on incoming pending Relationships. | +| consumption.outgoingRequestStatusChanged | [RequestStatusChangedEventData](#requeststatuschangedeventdata) | ... the status of an outgoing Request has changed. | +| consumption.relationshipTemplateProcessed | [RelationshipTemplateProcessedEventData](#relationshiptemplateprocessedeventdata) | ... a RelationshipTemplate was processed by Modules like the `RequestModule` or `DeciderModule`. | +| consumption.sharedAttributeCopyCreated | [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#LocalAttribute) | ... an Attribute is copied for sharing with another Identity. | +| transport.identityDeletionProcessStatusChanged | [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) | ... a new IdentityDeletionProcess has been created or the status of an existing IdentityDeletionProcess has changed. | +| transport.messageReceived | [Message]({% link _docs_integrate/data-model-overview.md %}#Message) | ... a Message is received during synchronization. | +| transport.messageSent | [Message]({% link _docs_integrate/data-model-overview.md %}#Message) | ... a Message was sent. | +| transport.peerRelationshipTemplateLoaded | [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#RelationshipTemplate) | ... a RelationshipTemplate was loaded that belongs to another Identity. | +| transport.relationshipChanged | [Relationship]({% link _docs_integrate/data-model-overview.md %}#Relationship) | ... a Relationship has changed. This can be due to one of the following cases:
• you create a Relationship
• you accept, reject or revoke a pending Relationship
• you terminate an active Relationship
• you request the reactivation of a terminated Relationship or accept, reject or revoke such a reactivation request
• a new Relationship is received or an existing one changed during synchronization | +| transport.relationshipReactivationRequested | [Relationship]({% link _docs_integrate/data-model-overview.md %}#Relationship) | ... the reactivation of a terminated Relationship has been requested by you or the peer. | +| transport.relationshipReactivationCompleted | [Relationship]({% link _docs_integrate/data-model-overview.md %}#Relationship) | ... the reactivation of a terminated Relationship has been accepted, rejected or revoked by you or the peer. | +| transport.relationshipDecomposedBySelf | [Relationship]({% link _docs_integrate/data-model-overview.md %}#Relationship) | ... you have decomposed a terminated Relationship. | +| transport.peerToBeDeleted | [Relationship]({% link _docs_integrate/data-model-overview.md %}#Relationship) | ... your Relationship's peer triggered their deletion. | +| transport.peerDeleted | [Relationship]({% link _docs_integrate/data-model-overview.md %}#Relationship) | ... your Relationship's peer was deleted. | +| transport.peerDeletionCancelled | [Relationship]({% link _docs_integrate/data-model-overview.md %}#Relationship) | ... your Relationship's peer cancelled their deletion. | ## Event structure diff --git a/_docs_integrate/data-model-overview.md b/_docs_integrate/data-model-overview.md index 3c07b22c0..626c8518f 100644 --- a/_docs_integrate/data-model-overview.md +++ b/_docs_integrate/data-model-overview.md @@ -87,27 +87,38 @@ A RelationshipTemplate serves two purposes: A Relationship between two Identities is the prerequisite for them to exchange Messages. If there is no Relationship, the Backbone blocks all Messages that are tried to be sent. This ensures that you only receive Messages from Identities you know, so you are protected from any harmful Messages like spam or phishing mails. -| Name | Type | Description | Remarks | -| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -| id | `string` | {% include descr_id class="Relationship" prefix="REL" %} | | -| 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 | -| auditLog | [`RelationshipAuditLogEntry`](#relationshipauditlogentry)`[]` | A log of Relationship operations like creating or accepting a pending Relationship. | | +| Name | Type | Description | Remarks | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| id | `string` | {% include descr_id class="Relationship" prefix="REL" %} | | +| 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 | +| auditLog | [`RelationshipAuditLogEntry`](#relationshipauditlogentry)`[]` | A log of Relationship operations like creating or accepting a pending Relationship. | | + +### PeerDeletionInfo + +The initiation of the [deletion of an Identity]({% link _docs_integrate/delete-identities.md %}) as well as the actual deletion of an [Identity](#identity) logically have [side effects for the peers of their Relationships]({% link _docs_integrate/delete-identities.md %}#effects-of-identity-deletion-on-relationships). +Whether the Identity with which you have a Relationship is to be deleted or has already been deleted is therefore recorded in the `peerDeletionInfo` property of the [Relationship](#relationship) by a data object of type PeerDeletionInfo. + +| Name | Type | Description | Remarks | +| -------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------- | +| deletionStatus | `"ToBeDeleted"` \| `"Deleted"` | A status that describes whether the Identity with which you have the Relationship is to be deleted or has already been deleted. | | +| deletionDate | `string` | The point in time the Identity with which you have the Relationship is to be deleted or was deleted. | | ### RelationshipAuditLogEntry The audit log records Relationship operations starting with the creation of the Relationship in status `Pending`. For the full list of tracked operations see the property `reason`. Each entry of the log is timestamped and states who executed the operation. -| Name | Type | Description | Remarks | -| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -| createdAt | `string` | A timestamp that describes when the Relationship operation was executed. | | -| createdBy | `string` | The `address` of the [Identity](#identity) that executed the Relationship operation. | | -| createdByDevice | `string` | The ID of the Device that executed the Relationship operation. You can use this information to track back who exactly did it. | | -| reason | `"Creation"` \| `"AcceptanceOfCreation"` \| `"RejectionOfCreation"` \| `"RevocationOfCreation"` \| `"Termination"` \| `"ReactivationRequested"` \| `"AcceptanceOfReactivation"` \| `"RejectionOfReactivation"` \| `"RevocationOfReactivation"` \| `"Decomposition"` | The type of the Relationship operation.
{::nomarkdown}{:/} | | -| oldStatus | `"Pending"` \| `"Active"` \| `"Terminated"` \| `undefined` | The status of the Relationship before the operation, it's `undefined` if the operation is the Relationship's creation. | | -| newStatus | `"Pending"` \| `"Active"` \| `"Rejected"` \| `"Revoked"` \| `"Terminated"` \| `"DeletionProposed"` | The status of the Relationship after the operation. | | +| Name | Type | Description | Remarks | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| createdAt | `string` | A timestamp that describes when the Relationship operation was executed. | | +| createdBy | `string` | The `address` of the [Identity](#identity) that executed the Relationship operation. | | +| createdByDevice | `string` | The ID of the Device that executed the Relationship operation. You can use this information to track back who exactly did it. | | +| reason | `"Creation"` \| `"AcceptanceOfCreation"` \| `"RejectionOfCreation"` \| `"RevocationOfCreation"` \| `"Termination"` \| `"ReactivationRequested"` \| `"AcceptanceOfReactivation"` \| `"RejectionOfReactivation"` \| `"RevocationOfReactivation"` \| `"Decomposition"` \| `"DecompositionDueToIdentityDeletion"` | The type of the Relationship operation.
{::nomarkdown}{:/} | | +| oldStatus | `"Pending"` \| `"Active"` \| `"Terminated"` \| `undefined` | The status of the Relationship before the operation, it's `undefined` if the operation is the Relationship's creation. | | +| newStatus | `"Pending"` \| `"Active"` \| `"Rejected"` \| `"Revoked"` \| `"Terminated"` \| `"DeletionProposed"` | The status of the Relationship after the operation. | | ## Message @@ -173,29 +184,32 @@ A File further has its content, of course. But since this is not a JSON property ## IdentityDeletionProcess -If you want to delete your [Identity](#identity), the actual deletion of all data associated with that Identity will only take place after a certain grace period has ended. +Please note that the feature of triggering the deletion of an Identity via the Backbone Admin UI is currently disabled. For this reason, an IdentityDeletionProcess currently cannot have `"WaitingForApproval"` as `status`. In addition, the use cases for [approving]({% link _docs_use-cases/use-case-transport-approve-identitydeletionprocess.md %}) and [rejecting]({% link _docs_use-cases/use-case-transport-reject-identitydeletionprocess.md %}) IdentityDeletionProcesses are not needed for the time being. +{: .notice--warning} + +If you want to [delete your Identity]({% link _docs_integrate/delete-identities.md %}), the actual deletion of all data associated with that [Identity](#identity) will only take place after a certain grace period has ended. Up until then, the data about the deletion process is stored in an object called IdentityDeletionProcess. It is possible to [cancel an IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}) that hasn't reached the end of its grace period, yet. -Furthermore, the deletion of an Identity can be initiated by the Backbone Admin UI. +Furthermore, the deletion of an Identity can be triggered via the Backbone Admin UI. In this case, the Identity has to [approve the IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-approve-identitydeletionprocess.md %}) in order to start the grace period. -The IdentityDeletionProcess can also be [rejected]({% link _docs_use-cases/use-case-transport-reject-identitydeletionprocess.md %}) if an Identity does not agree with its deletion initiated by the Backbone Admin UI. +The IdentityDeletionProcess can also be [rejected]({% link _docs_use-cases/use-case-transport-reject-identitydeletionprocess.md %}) if an Identity does not agree with its deletion triggered via the Backbone Admin UI. Since rejected and cancelled IdentityDeletionProcesses are stored, you can reach a situation in which there are multiple IdentityDeletionProcesses associated with the same Identity. -Note, however, that at all times there can only be at most one active IdentityDeletionProcess, i.e. with `status` `"WaitingForApproval"` or `"Approved"`, per Identity. - -| Name | Type | Description | Remarks | -| -------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -| id | `string` | {% include descr_id class="IdentityDeletionProcess" prefix="IDP" %} | | -| status | `"WaitingForApproval"` \| `"Rejected"` \| `"Approved"` \| `"Cancelled"` | The status of the IdentityDeletionProcess.
{::nomarkdown}{:/} | | -| createdAt | `string` \| `undefined` | {% include descr_createdAt class="IdentityDeletionProcess" %} | | -| createdByDevice | `string` \| `undefined` | {% include descr_createdByDevice class="IdentityDeletionProcess" %} | | -| approvalPeriodEndsAt | `string` \| `undefined` | A timestamp that describes up until when it is possible to approve or reject the IdentityDeletionProcess. If it is reached without the user having made their decision, the IdentityDeletionProcess will be cancelled. | | -| approvedAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was approved. | | -| approvedByDevice | `string` \| `undefined` | The ID of the Device that approved the IdentityDeletionProcess. | | -| rejectedAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was rejected. | | -| rejectedByDevice | `string` \| `undefined` | The ID of the Device that rejected the IdentityDeletionProcess. | | -| gracePeriodEndsAt | `string` \| `undefined` | A timestamp that describes when the Identity will be permanently deleted. Up until this moment, it is possible to cancel the IdentityDeletionProcess. | | -| cancelledAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was cancelled. | | -| cancelledByDevice | `string` \| `undefined` | The ID of the Device that cancelled the IdentityDeletionProcess. | | +Note, however, that at all times there can only be at most one **active IdentityDeletionProcess**, i.e. with `status` `"WaitingForApproval"` or `"Approved"`, per Identity. + +| Name | Type | Description | Remarks | +| -------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| id | `string` | {% include descr_id class="IdentityDeletionProcess" prefix="IDP" %} | | +| status | `"WaitingForApproval"` \| `"Rejected"` \| `"Approved"` \| `"Cancelled"` | The status of the IdentityDeletionProcess.
{::nomarkdown}{:/} | | +| createdAt | `string` \| `undefined` | {% include descr_createdAt class="IdentityDeletionProcess" %} | | +| createdByDevice | `string` \| `undefined` | {% include descr_createdByDevice class="IdentityDeletionProcess" %} | | +| approvalPeriodEndsAt | `string` \| `undefined` | A timestamp that describes up until when it is possible to approve or reject the IdentityDeletionProcess. If it is reached without the user having made their decision, the IdentityDeletionProcess will be cancelled. | | +| approvedAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was approved. | | +| approvedByDevice | `string` \| `undefined` | The ID of the Device that approved the IdentityDeletionProcess. | | +| rejectedAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was rejected. | | +| rejectedByDevice | `string` \| `undefined` | The ID of the Device that rejected the IdentityDeletionProcess. | | +| gracePeriodEndsAt | `string` \| `undefined` | A timestamp that describes when the Identity will be permanently deleted. Up until this moment, it is possible to cancel the IdentityDeletionProcess. | | +| cancelledAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was cancelled. | | +| cancelledByDevice | `string` \| `undefined` | The ID of the Device that cancelled the IdentityDeletionProcess. | | # Local Types diff --git a/_docs_integrate/delete-identities.md b/_docs_integrate/delete-identities.md new file mode 100644 index 000000000..9da962c5f --- /dev/null +++ b/_docs_integrate/delete-identities.md @@ -0,0 +1,98 @@ +--- +# Start automatic generation +permalink: integrate/delete-identities +redirect_from: + - /integrate/delete-identity-from-enmeshed +published: true +title: "Delete Identities" +type: scenario +toc: true +properties: + - id: SC061 + - category: Identities and Relationships + - description: + - customer: All + - component: integrate + - level: Beginner + - implementation status: DONE + - documentation status: DONE + - published: true + - link: delete-identities +require: +required_by: + - integrate/exchange-messages +# End automatic generation +--- + +It is not yet possible to utilize the use cases regarding the [IdentityDeletionProcesses]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) mentioned below as an Integrator of a Connector. Instead, these functionalities are currently only offered to App users in order to be able to delete their [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). Even if some use cases still have to be provided to the Integrators of Connectors for deleting their Identity, they benefit from the description of the process of Identity deletion given in this guide. Indeed, if an App user with whom a Connector has established a Relationship deletes their Identity, it is affected by [side effects on this Relationship](#effects-of-identity-deletion-on-relationships). +{: .notice--warning} + +Regardless of whether an [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) is an App user or a Connector, it is stored on the Backbone. +This guide describes the different [options for Identity deletion](#options-for-identity-deletion) from the Backbone. +There is usually a predefined grace period in each process of Identity deletion, during which the Identity can cancel its deletion if it no longer wants to be deleted. +Please note that an Identity can never trigger the process of deletion of another Identity. + +## IdentityDeletionProcesses + +From a technical perspective, the process of Identity deletion is described by a data object of type [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess). It can be uniquely identified by its `id`. +An IdentityDeletionProcess can have `"WaitingForApproval"`, `"Rejected"`, `"Approved"` or `"Cancelled"` as its `status`. + +Please note that the feature of triggering the deletion of an Identity via the Backbone Admin UI is currently disabled. For this reason, an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) currently cannot have `"WaitingForApproval"` as `status`. In addition, the use cases for [approving]({% link _docs_use-cases/use-case-transport-approve-identitydeletionprocess.md %}) and [rejecting]({% link _docs_use-cases/use-case-transport-reject-identitydeletionprocess.md %}) IdentityDeletionProcesses are not needed for the time being. +{: .notice--warning} + +If an IdentityDeletionProcess has `"WaitingForApproval"` or `"Approved"` as `status`, it is also referred to as an **active IdentityDeletionProcess**. +There can be at most one active IdentityDeletionProcess per Identity. +There are three [use cases]({% link _docs_integrate/use-cases.md %}) for getting one or more already existing [IdentityDeletionProcesses]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess): + +- If the `id` of an IdentityDeletionProcess is known, it can be viewed by calling the [Get IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-get-identitydeletionprocess.md %}) use case. +- All IdentityDeletionProcesses of an Identity can be viewed by utilizing the [Get IdentityDeletionProcesses]({% link _docs_use-cases/use-case-transport-get-identitydeletionprocesses.md %}) use case. This includes IdentityDeletionProcesses with `"Cancelled"` or `"Rejected"` as `status` in particular. +- The [Get active IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md %}) use case can be executed to view the currently active IdentityDeletionProcess if one exists. If none exists, the [error code]({% link _docs_integrate/error-codes.md %}) `error.runtime.identityDeletionProcess.noActiveIdentityDeletionProcess` will arise if an attempt is made to apply the use case anyway. + +## Options for Identity Deletion + +In principle, there are several options for deleting an Identity from the Backbone. +For example, depending on the Backbone environment, it is conceivable to set up automatic Identity deletion after a long period of Identity inactivity. +More essential is the option of [actively initiating the process of Identity deletion from the Backbone by the Identity itself](#self-initiated-identity-deletion). +Whenever a new [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) has been created or the `status` of an existing IdentityDeletionProcess has changed, the [Connector event]({% link _docs_integrate/connector-events.md %}) `transport.identityDeletionProcessStatusChanged` is raised. + +### Self-Initiated Identity Deletion + +An Identity can actively trigger its own process of deletion by executing the [Initiate IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md %}) use case. +Successful execution leads to the creation of an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) with `"Approved"` as `status`. +No further approval of the Identity is required. +Instead, the Identity is immediately in deletion and will be irreversibly deleted from the Backbone once the end of the associated grace period of the IdentityDeletionProcess specified within its `gracePeriodEndsAt` property has been reached. +Within the grace period, the [Cancel IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}) use case can be applied by the Identity if it no longer wants to be deleted. +In this case, the `status` of the IdentityDeletionProcess changes to `"Cancelled"`. +Trying to cancel an IdentityDeletionProcess that does not have `"Approved"` as `status` causes an error with `error.runtime.identityDeletionProcess.noApprovedIdentityDeletionProcess` as [error code]({% link _docs_integrate/error-codes.md %}) to be thrown. +Furthermore, please note that the use of the [Initiate IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md %}) use case is not permitted if there is already an active IdentityDeletionProcess. +The corresponding [error code]({% link _docs_integrate/error-codes.md %}) is given by `error.runtime.identityDeletionProcess.activeIdentityDeletionProcessAlreadyExists`. + +## Effects of Identity Deletion on Relationships + +The initiation of the deletion of an Identity as well as the actual deletion logically have an impact on the peers who have [established a Relationship]({% link _docs_integrate/establish-relationships.md %}) with it. +All peers of the Identity that is currently in deletion are informed that the deletion of the Identity has been initiated. +This is done via the `transport.peerToBeDeleted` [Connector event]({% link _docs_integrate/connector-events.md %}). +In addition, it is stored within the `peerDeletionInfo` property of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) that the Identity currently has `"ToBeDeleted"` as `deletionStatus`. +The `status` of the Relationship remains `"Active"` for the time being. +If the Identity is finally deleted, the `deletionStatus` will change to `"Deleted"` and the Connector event `transport.peerDeleted` can be received. +Since the deletion of an Identity leads to the [decomposition of its Relationships]({% link _docs_integrate/terminate-relationships.md %}#decompose-a-relationship), the `status` of the Relationship is changed to `"DeletionProposed"` and `"DecompositionDueToIdentityDeletion"` is specified as the `reason` of the associated [RelationshipAuditLogEntry]({% link _docs_integrate/data-model-overview.md %}#relationshipauditlogentry). +Otherwise, if the Identity decides against its deletion within the grace period, the `peerDeletionInfo` of the Relationship is set back to `undefined` and the `transport.peerDeletionCancelled` Connector event is triggered. +The deletion of an Identity has effects on [creating a new Relationship](#creation-of-new-relationships) to it, [sending Messages](#sending-messages) to it, [sending Requests to it and responding to Requests from it](#sending-and-responding-to-requests). + +### Creation of New Relationships + +To [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}), an Identity must first create a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate), which is then used by its peer to create a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status`. +However, if the creator of the RelationshipTemplate is meanwhile in deletion or has already deleted itself, the peer will receive an error with [error code]({% link _docs_integrate/error-codes.md %}) `error.transport.relationships.activeIdentityDeletionProcessOfOwnerOfRelationshipTemplate` or `error.transport.relationships.deletedOwnerOfRelationshipTemplate`, respectively, when trying to create a new Relationship using the RelationshipTemplate. + +### Sending Messages + +An Identity is not permitted to [send a Message]({% link _docs_use-cases/use-case-transport-send-message-to-recipients.md %}) to a peer with which a Relationship has been established if the peer has already been deleted. +As long as the `content` of a [Message]({% link _docs_integrate/data-model-overview.md %}#message) is not a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification), this also applies to a peer in deletion. +If the Identity tries to send a Message anyway to such a peer, an error with [error code]({% link _docs_integrate/error-codes.md %}) `error.runtime.messages.peerIsInDeletion` or `error.transport.messages.peerIsDeleted` is thrown. +Sent Messages whose `content` is a Notification cannot be received by a peer which is in deletion, but they are queued in case the peer cancels its deletion. After the peer has cancelled its deletion, it receives the queued Notifications. + +### Sending and Responding to Requests + +An incoming [Request]({% link _docs_integrate/data-model-overview.md %}#request) sent by an Identity with which a Relationship has been established cannot be responded to if the Identity is in deletion or has already been deleted. +If an attempt is nevertheless made to [accept]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) or [reject]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) the incoming Request, an error with [code]({% link _docs_integrate/error-codes.md %}) `error.consumption.requests.peerIsInDeletion` or `error.consumption.requests.peerIsDeleted`, respectively, is thrown. +Similarly, it is not possible to [create an outgoing Request]({% link _docs_use-cases/use-case-consumption-create-outgoing-request.md %}) to be sent to an Identity with which a Relationship has been established and which is in deletion or has already been deleted. diff --git a/_docs_integrate/delete-identity-from-enmeshed.md b/_docs_integrate/delete-identity-from-enmeshed.md deleted file mode 100644 index 5bc764832..000000000 --- a/_docs_integrate/delete-identity-from-enmeshed.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -# Start automatic generation -permalink: integrate/delete-identity-from-enmeshed -published: false -title: "Delete Identity from enmeshed" -type: scenario -toc: true -properties: - - id: SC061 - - category: Identity Basics - - description: - - customer: All - - component: integrate - - level: Beginner - - implementation status: OPEN - - documentation status: OPEN - - published: - - link: delete-identity-from-enmeshed -require: -required_by: - - integrate/exchange-messages -# End automatic generation ---- - -{% include warnings/feature-work-in-progress %} - -# Flow - -Every Identity has the option of deleting itself from the Backbone. There are three options to delete the Identity: - -- Actively trigger the deletion process by use of the App or the Connector. There is no further approval of the Identity required with this option. -- Actively trigger the deletion process by use of support tickets/e-mails to the Backbone operator (as required by GDPR). An active approval of the Identity is required with this option, as the Backbone must ensure, that the support ticket creator is the owner of the Identity. As there is the need of a push notification channel for this, the Connector does not have the ability to trigger the Identity deletion over the Backbone. -- Be inactive for a long period of time: Depending on the Backbone environment, deleting inactive Identities is possible. - -All peers of the to-be-deleted Identity are informed about this deletion, otherwise they will end up getting Backbone errors that the Identity is no longer available. - -Usually Identity deletion takes place with a grace period in which the owner of the Identity can revoke the decision to be deleted. The Identity deletion can be triggered by the runtime. diff --git a/_docs_integrate/error-codes.md b/_docs_integrate/error-codes.md index 90b7ee4a4..db7000f7e 100644 --- a/_docs_integrate/error-codes.md +++ b/_docs_integrate/error-codes.md @@ -91,6 +91,8 @@ Please find a list of enmeshed error codes below. Most often the errors occur on | {% include anchor a="error.consumption.requests.invalidAcceptParameters" %} | An attempt was made to accept the [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems) with invalid [AcceptRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptrequestitemparameters). | | {% include anchor a="error.consumption.requests.invalidRequestItem" %} | The given [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems) is invalid. Check the error message or the stack trace to learn more. | | {% include anchor a="error.consumption.requests.missingRelationship" %} | You need a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to send/decide that [Request]({% link _docs_integrate/data-model-overview.md %}#request). | +| {% include anchor a="error.consumption.requests.peerIsInDeletion" %} | The [Request]({% link _docs_integrate/data-model-overview.md %}#request) cannot be created or decided, because the `peer` of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to which the Request belongs has `"ToBeDeleted"` as `peerDeletionInfo.deletionStatus`. | +| {% include anchor a="error.consumption.requests.peerIsDeleted" %} | The [Request]({% link _docs_integrate/data-model-overview.md %}#request) cannot be created or decided, because the `peer` of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to which the Request belongs has `"Deleted"` as `peerDeletionInfo.deletionStatus`. | | {% include anchor a="error.consumption.requests.servalErrorDuringRequestItemProcessing" %} | A serialization / validation error occurred during the [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems) processing. Check the type definitions of your used types. | | {% include anchor a="error.consumption.requests.unexpectedErrorDuringRequestItemProcessing" %} | An unexpected error occurred during the [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems) processing. | | {% include anchor a="error.consumption.requests.validation.inheritedFromItem" %} | Some child items have errors. If this error occurred during the specification of a [Request]({% link _docs_integrate/data-model-overview.md %}#request), [call 'validate' to get more information]({% link _docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md %}). | @@ -114,6 +116,8 @@ Please find a list of enmeshed error codes below. Most often the errors occur on | {% include anchor a="error.runtime.identityDeletionProcess.noApprovedIdentityDeletionProcess" %} | [No approved IdentityDeletionProcess was found]({% link _docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md %}). | | {% include anchor a="error.runtime.identityDeletionProcess.noWaitingForApprovalIdentityDeletionProcess" %} | No [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) waiting for decision was found. | | {% include anchor a="error.runtime.invalidTokenContent" %} | The given [Token]({% link _docs_integrate/data-model-overview.md %}#token) has an invalid `content` for this [route]({% link _docs_use-cases/use-case-transport-create-own-token.md %}). | +| {% include anchor a="error.runtime.messages.hasNoActiveRelationship" %} | The [Message]({% link _docs_integrate/data-model-overview.md %}#message) cannot be sent, because there is no active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to one or more of its `recipients`. However, please note that Messages whose `content` is a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) can still be sent on terminated Relationships. | +| {% include anchor a="error.runtime.messages.peerIsInDeletion" %} | The [Message]({% link _docs_integrate/data-model-overview.md %}#message) cannot be sent, because one or more of its `recipients` to which [Relationships]({% link _docs_integrate/data-model-overview.md %}#relationship) exist have `"ToBeDeleted"` as `peerDeletionInfo.deletionStatus` and the `content` of the Message is not a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification). | | {% include anchor a="error.runtime.messages.fileNotFoundInMessage" %} | The requested [File]({% link _docs_integrate/data-model-overview.md %}#file) was not found in the given [Message]({% link _docs_integrate/data-model-overview.md %}#message). | | {% include anchor a="error.runtime.notifications.cannotReceiveNotificationFromOwnMessage" %} | It is not possible to receive a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) from an own [Message]({% link _docs_integrate/data-model-overview.md %}#message). | | {% include anchor a="error.runtime.notifications.cannotSaveSentNotificationFromPeerMessage" %} | The given [Message]({% link _docs_integrate/data-model-overview.md %}#message) was received from a peer, but an own Message is expected here to save its [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) `content`. | @@ -149,14 +153,16 @@ Please find a list of enmeshed error codes below. Most often the errors occur on | {% include anchor a="error.transport.general.platformClientIdNotSet" %} | [The `platformClientId` was not set.]({% link _docs_operate/configuration.md %}#configuration-options). | | {% include anchor a="error.transport.general.platformClientInvalid" %} | [The combination of `platformClientId` and `platformClientSecret` is invalid.]({% link _docs_operate/configuration.md %}#configuration-options) | | {% include anchor a="error.transport.general.platformClientSecretNotSet" %} | [The `platformClientSecret` was not set.]({% link _docs_operate/configuration.md %}#configuration-options) | -| {% include anchor a="error.transport.messages.missingOrInactiveRelationship" %} | An active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with the given `address` does not exist, consider ['Get Relationship']({% link _docs_use-cases/use-case-transport-get-relationship-by-address.md %}). | +| {% include anchor a="error.transport.messages.hasNeitherActiveNorTerminatedRelationship" %} | The [Message]({% link _docs_integrate/data-model-overview.md %}#message) cannot be sent, because there is neither an active nor a terminated [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to one or more of its `recipients`. | +| {% include anchor a="error.transport.messages.peerIsDeleted" %} | The [Message]({% link _docs_integrate/data-model-overview.md %}#message) cannot be sent, because one or more of its `recipients` to which [Relationships]({% link _docs_integrate/data-model-overview.md %}#relationship) exist have `"Deleted"` as `peerDeletionInfo.deletionStatus`. | | {% include anchor a="error.transport.messages.ownAddressNotInList" %} | The `recipients` list of a [Message]({% link _docs_integrate/data-model-overview.md %}#message) didn't contain an entry for the own `address`. This Message should not have been received. | | {% include anchor a="error.transport.messages.plaintextMismatch" %} | The own `address` was not named as a `recipient` within the signed MessagePlaintext. For example this can be caused by a replay attack. | | {% include anchor a="error.transport.messages.signatureListMismatch" %} | The `signature` list didn't contain an entry for a given `address`. | | {% include anchor a="error.transport.messages.signatureNotValid" %} | The digital signature on a [Message]({% link _docs_integrate/data-model-overview.md %}#message) for a peer `key` is invalid. An impersonation attack might be the cause of this. | | {% include anchor a="error.transport.notSupported" %} | The requested method is not yet supported. | | {% include anchor a="error.transport.recordNotFound" %} | The requested record was not found. | -| {% include anchor a="error.transport.relationships.
activeIdentityDeletionProcessOfOwnerOfRelationshipTemplate" %} | The [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) who created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is currently in the process of deleting itself. Thus, it is not possible to establish a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to it. | +| {% include anchor a="error.transport.relationships.
activeIdentityDeletionProcessOfOwnerOfRelationshipTemplate" %} | The [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is currently in the process of deleting itself. Thus, it is not possible to establish a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to it. | +| {% include anchor a="error.transport.relationships.deletedOwnerOfRelationshipTemplate" %} | The [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) has been deleted in the meantime. Thus, it is not possible to establish a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to it. | | {% include anchor a="error.transport.relationships.operationOnlyAllowedForPeer" %} | Only your peer may run the requested operation. | | {% include anchor a="error.transport.relationships.reactivationAlreadyRequested" %} | The reactivation of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) was requested already. | | {% include anchor a="error.transport.relationships.reactivationNotRequested" %} | There's no [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) reactivation [Request]({% link _docs_integrate/data-model-overview.md %}#request) to respond to. | diff --git a/_docs_use-cases/use-case-device-get-profiles.md b/_docs_use-cases/use-case-device-get-profiles.md index a171b0e8c..f2af926b7 100644 --- a/_docs_use-cases/use-case-device-get-profiles.md +++ b/_docs_use-cases/use-case-device-get-profiles.md @@ -43,10 +43,6 @@ required_by: This use case retrieves all LocalAccounts available on this Device. -## Parameters - ---- - ## On Success - A list of LocalAccounts. diff --git a/_docs_use-cases/use-case-transport-approve-identitydeletionprocess.md b/_docs_use-cases/use-case-transport-approve-identitydeletionprocess.md index e83e4ce5b..84a196c88 100644 --- a/_docs_use-cases/use-case-transport-approve-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-approve-identitydeletionprocess.md @@ -41,14 +41,18 @@ required_by: {% include properties_list.html %} -This use case allows you to approve an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) that was started via the Backbone Admin UI for your Identity. -The respective IdentityDeletionProcess has the `status` `"WaitingForApproval"` and can either be approved or [rejected]({% link _docs_use-cases/use-case-transport-reject-identitydeletionprocess.md %}). +Please note that the feature of triggering the deletion of an Identity via the Backbone Admin UI is currently disabled. For this reason, an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) currently cannot have `"WaitingForApproval"` as `status`. In addition, this use case for approving and the use case for [rejecting IdentityDeletionProcesses]({% link _docs_use-cases/use-case-transport-reject-identitydeletionprocess.md %}) are not needed for the time being. +{: .notice--warning} + +In the case of [Identity deletion]({% link _docs_integrate/delete-identities.md %}) triggered via the Backbone Admin UI, an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) with `"WaitingForApproval"` as `status` is created for your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) via the Backbone Admin UI. +This use case can be utilized to approve this IdentityDeletionProcess. +Alternatively, the [IdentityDeletionProcess can be rejected]({% link _docs_use-cases/use-case-transport-reject-identitydeletionprocess.md %}). ## On Success -- Changes the `status` of the IdentityDeletionProcess from `"WaitingForApproval"` to `"Approved"` -- Returns the approved IdentityDeletionProcess +- Changes the `status` of the IdentityDeletionProcess from `"WaitingForApproval"` to `"Approved"`. +- Returns the approved IdentityDeletionProcess. ## On Failure -- No IdentityDeletionProcess can be approved if none was started via the Backbone Admin UI, i.e. no IdentityDeletionProcess in `status` `"WaitingForApproval"` exists for this Identity. +- No IdentityDeletionProcess can be approved if none was started via the Backbone Admin UI, i.e. no IdentityDeletionProcess with `"WaitingForApproval"` as `status` exists for this Identity. diff --git a/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md b/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md index 36eeff78c..9f064b2d9 100644 --- a/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md @@ -41,13 +41,16 @@ required_by: {% include properties_list.html %} -This use case allows you to cancel an approved [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) for your own Identity. +The process of [Identity deletion]({% link _docs_integrate/delete-identities.md %}) leads to the creation of an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) with `"Approved"` as `status`. +It can be cancelled if the Identity no longer wants to be deleted. +This is only possible as long as the end of the associated grace period of the IdentityDeletionProcess specified within its `gracePeriodEndsAt` property has not yet been reached. +This use case allows you to cancel an approved IdentityDeletionProcess for your Identity within the grace period. ## On Success -- Changes the `status` of the IdentityDeletionProcess from `"Approved"` to `"Cancelled"` -- Returns the cancelled IdentityDeletionProcess +- Changes the `status` of the IdentityDeletionProcess from `"Approved"` to `"Cancelled"`. +- Returns the cancelled IdentityDeletionProcess. ## On Failure -- No IdentityDeletionProcess can be cancelled if none was in `status` `"Approved"` for this Identity. +- No IdentityDeletionProcess can be cancelled if none has `"Approved"` as `status` for this Identity. diff --git a/_docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md b/_docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md index 5bde509c3..3d2705113 100644 --- a/_docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md @@ -41,13 +41,14 @@ required_by: {% include properties_list.html %} -This use case will return the active [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) for your own Identity if one exists. -An IdentityDeletionProcess is active if it is in `status` `"WaitingForApproval"` or `"Approved"`. +From a technical perspective, the process of [Identity deletion]({% link _docs_integrate/delete-identities.md %}) is described by a data object of type [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess). +An IdentityDeletionProcess is active if it has `"WaitingForApproval"` or `"Approved"` as `status`. +This use case returns the active IdentityDeletionProcess for your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) if one exists. At all times, there can only be at most one active IdentityDeletionProcess per Identity. ## On Success -- Returns the active IdentityDeletionProcess +- Returns the active IdentityDeletionProcess. ## On Failure diff --git a/_docs_use-cases/use-case-transport-get-identitydeletionprocess.md b/_docs_use-cases/use-case-transport-get-identitydeletionprocess.md index 282b84a3a..5e00f0ecb 100644 --- a/_docs_use-cases/use-case-transport-get-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-get-identitydeletionprocess.md @@ -41,15 +41,17 @@ required_by: {% include properties_list.html %} -This use case allows you to query an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) for your own Identity by its `id`. +From a technical perspective, the process of [Identity deletion]({% link _docs_integrate/delete-identities.md %}) is described by a data object of type [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess). +An IdentityDeletionProcess can be uniquely identified by its `id`. +This use case allows you to query an IdentityDeletionProcess for your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) by its `id`. ## Parameters -- `id` of the IdentityDeletionProcess +- `id` of the [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess). ## On Success -- Returns the IdentityDeletionProcess corresponding to the provided `id` +- Returns the IdentityDeletionProcess corresponding to the provided `id`. ## On Failure diff --git a/_docs_use-cases/use-case-transport-get-identitydeletionprocesses.md b/_docs_use-cases/use-case-transport-get-identitydeletionprocesses.md index df90ef383..769acd2cb 100644 --- a/_docs_use-cases/use-case-transport-get-identitydeletionprocesses.md +++ b/_docs_use-cases/use-case-transport-get-identitydeletionprocesses.md @@ -41,8 +41,9 @@ required_by: {% include properties_list.html %} -This use case will return all [IdentityDeletionProcesses]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) for your own Identity. +From a technical perspective, the process of [Identity deletion]({% link _docs_integrate/delete-identities.md %}) is described by a data object of type [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess). +This use case will return all IdentityDeletionProcesses for your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). ## On Success -- Returns a list with all IdentityDeletionProcesses of your Identity +- Returns a list with all IdentityDeletionProcesses of your Identity. diff --git a/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md b/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md index c27ede9cc..ec484ca12 100644 --- a/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md @@ -41,13 +41,14 @@ required_by: {% include properties_list.html %} -This use case is intended to initiate an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) for your Identity. +Regarding [self-initiated Identity deletion]({% link _docs_integrate/delete-identities.md %}#self-initiated-identity-deletion), this use case can be utilized to initiate an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) for your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). +The generated IdentityDeletionProcess immediately has `"Approved"` as its `status` and describes that the Identity will be deleted after the grace period ends unless the [IdentityDeletionProcess is cancelled]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}) by the Identity by then. ## On Success -- Creates an IdentityDeletionProcess with status `"Approved"` -- Returns the initiated IdentityDeletionProcess +- Creates an IdentityDeletionProcess with `"Approved"` as `status`. +- Returns the initiated IdentityDeletionProcess. ## On Failure -- No IdentityDeletionProcess can be initiated if there is already an active IdentityDeletionProcess, i.e. an IdentityDeletionProcess in `status` `"Approved"` or `"WaitingForApproval"`, for this Identity. +- No IdentityDeletionProcess can be initiated if there is already an active IdentityDeletionProcess, i.e. an IdentityDeletionProcess with `"Approved"` or `"WaitingForApproval"` as `status`, for this Identity. Please note that an IdentityDeletionProcess with `"WaitingForApproval"` as `status` is never created by the self-initiated Identity deletion, but only by the process of Identity deletion triggered via the Backbone Admin UI. However, the latter feature is currently disabled. diff --git a/_docs_use-cases/use-case-transport-reject-identitydeletionprocess.md b/_docs_use-cases/use-case-transport-reject-identitydeletionprocess.md index dfe8dc4de..9e890afd7 100644 --- a/_docs_use-cases/use-case-transport-reject-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-reject-identitydeletionprocess.md @@ -41,14 +41,18 @@ required_by: {% include properties_list.html %} -This use case allows you to reject an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) that was started via the Backbone Admin UI for your own Identity. -The respective IdentityDeletionProcess has the `status` `"WaitingForApproval"` and can either be [approved]({% link _docs_use-cases/use-case-transport-approve-identitydeletionprocess.md %}) or rejected. +Please note that the feature of triggering the deletion of an Identity via the Backbone Admin UI is currently disabled. For this reason, an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) currently cannot have `"WaitingForApproval"` as `status`. In addition, this use case for rejecting and the use case for [approving IdentityDeletionProcesses]({% link _docs_use-cases/use-case-transport-approve-identitydeletionprocess.md %}) are not needed for the time being. +{: .notice--warning} + +In the case of [Identity deletion]({% link _docs_integrate/delete-identities.md %}) triggered via the Backbone Admin UI, an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) with `"WaitingForApproval"` as `status` for your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) is created via the Backbone Admin UI. +This use case allows you to reject this IdentityDeletionProcess. +Alternatively, the [IdentityDeletionProcess can be approved]({% link _docs_use-cases/use-case-transport-approve-identitydeletionprocess.md %}). ## On Success -- Changes the `status` of the IdentityDeletionProcess from `"WaitingForApproval"` to `"Rejected"` -- Returns the rejected IdentityDeletionProcess +- Changes the `status` of the IdentityDeletionProcess from `"WaitingForApproval"` to `"Rejected"`. +- Returns the rejected IdentityDeletionProcess. ## On Failure -- No IdentityDeletionProcess can be rejected if none was started via the Backbone Admin UI, i.e. no IdentityDeletionProcess in `status` `"WaitingForApproval"` exists for this Identity. +- No IdentityDeletionProcess can be rejected if none was started via the Backbone Admin UI, i.e. no IdentityDeletionProcess with `"WaitingForApproval"` as `status` exists for this Identity.