diff --git a/_data/navigation.yml b/_data/navigation.yml index aad9537b2..559966a71 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -147,6 +147,8 @@ docs_integrate: url: /integrate/migration-from-v4-to-v5 - title: "Migration From v5 to v6" url: /integrate/migration-from-v5-to-v6 + - title: "Migration From v6 to v7" + url: /integrate/migration-from-v6-to-v7 - title: Troubleshooting children: - title: "Error codes" diff --git a/_docs_explore/42-transport-layer.md b/_docs_explore/42-transport-layer.md index 37976b3d2..317f70397 100644 --- a/_docs_explore/42-transport-layer.md +++ b/_docs_explore/42-transport-layer.md @@ -15,7 +15,7 @@ The transport layer is located between the Backbone layer and the consumption la ## Data Handling -The transport layer introduces a local storage based on a document database. In this database all relevant data is persisted or cached. In addition to the database, the transport layer takes care of serializing and deserializing data structures. +The transport layer introduces a local storage based on a document database. In this database all relevant data is persisted. In addition to the database, the transport layer takes care of serializing and deserializing data structures. ## Syntactical validation of plaintext data @@ -121,7 +121,6 @@ The actual file is then shared by a file reference to a recipient. Files can be - expiresAt: ISO String when the file expires - mimetype: Mimetype of the file's payload - isOwn: Whether or not the file was uploaded by the current Identity -- truncatedReference: The truncated reference of the file - reference: The reference of the file - deletedAt: ISO String when the file has been deleted - deletedBy: Address of the Identity which deleted the file @@ -163,7 +162,7 @@ Relationships are usually used as the technical term, whereas contact is used as ### Relationship Structure - id -- RelationshipTemplate +- templateId - status - peer - peerIdentity @@ -264,7 +263,6 @@ A company has no customer system where customers can log in but would still like - content - forIdentity - passwordProtection -- truncatedReference - reference ## Tokens @@ -290,5 +288,4 @@ The token id and the generated secret key are then the only two properties which - content - forIdentity - passwordProtection -- truncatedReference - reference diff --git a/_docs_explore/61-runtime.md b/_docs_explore/61-runtime.md index bc8f23e10..c7571aed9 100644 --- a/_docs_explore/61-runtime.md +++ b/_docs_explore/61-runtime.md @@ -103,7 +103,7 @@ The Decider Module can be configured to automatically decide incoming Requests. For this to work, each RequestItem must match a form that was previously configured. The configuration also states how the RequestItem is processed, i.e. if it is rejected or accepted and in the latter case which parameters are used to do so. -If there is no suitable configuration for every [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitem) of a Request or at least one RequestItem has `requireManualDecision` set, the Decider Module will not be able to automatically decide the Request. +If there is no suitable configuration for every [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitem) of a Request or at least one RequestItem is an [AuthenticationRequestItem]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem) or a [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem), the Decider Module will not be able to automatically decide the Request. In this case, the `status` of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) is moved from `DecisionRequired` to `ManualDecisionRequired` and the user must manually decide the Request. ### Message Module diff --git a/_docs_integrate/01-integrate-scenarios.md b/_docs_integrate/01-integrate-scenarios.md index 9338456fd..9b52b036d 100644 --- a/_docs_integrate/01-integrate-scenarios.md +++ b/_docs_integrate/01-integrate-scenarios.md @@ -7,27 +7,40 @@ sidebar: nav: "docs_integrate" --- -You want to seamlessly use enmeshed with your processes, solutions and software components? No worries, you are good to go! +You want to seamlessly use enmeshed with your processes, solutions and software components? +No worries, you are good to go! We've built the enmeshed Connector exactly for this scenario: to integrate existing systems with the enmeshed approach with as little effort as possible. -Here you'll find everything you need to seamlessly dive into the world of enmeshed and integrate it into your applications and systems. Whether you're just starting out or are already familiar with enmeshed, our comprehensive guide and resources are at your disposal. +Here you'll find everything you need to seamlessly dive into the world of enmeshed and integrate it into your applications and systems. +Whether you're just starting out or are already familiar with enmeshed, our comprehensive guide and resources are at your disposal. ## Getting Started -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 %}). +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 %}). ## 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. 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 %}), [delete Identities]({% link _docs_integrate/delete-identities.md %}) and [manage IdentityMetadata]({% link _docs_integrate/manage-identitymetadata.md %}). +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 %}), [delete Identities]({% link _docs_integrate/delete-identities.md %}) and [manage IdentityMetadata]({% link _docs_integrate/manage-identitymetadata.md %}). ## Working With Requests -Learn how to create and manage Requests. Check out the [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) and the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) and [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) guides. +Learn how to create and manage Requests. +Check out the [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) and the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) and [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) guides. ## Manage Attributes -The [Attribute introduction]({% link _docs_integrate/attribute-introduction.md %}) provides an overview of the different kinds of Attributes and the Attribute management options. Next, explore how to [create Attributes for yourself]({% link _docs_integrate/create-attributes-for-yourself.md %}) and how to [share Attributes]({% link _docs_integrate/share-attributes-with-peer.md %}) with a peer. Also, discover how to [read Attributes]({% link _docs_integrate/read-attributes-from-peer.md %}) from a peer and how to store Attributes in a peer's Wallet for them. The latter can be realized by [creating Attributes]({% link _docs_integrate/create-attributes-for-peer.md %}) for them or by [proposing Attributes]({% link _docs_integrate/propose-attributes-to-peer.md %}) to them. The peer must give you their permission for this. Furthermore, learn how to [update Attributes by succession]({% link _docs_integrate/update-attributes-by-succession.md %}) or how to [delete Attributes]({% link _docs_integrate/delete-attributes.md %}). +The [Attribute introduction]({% link _docs_integrate/attribute-introduction.md %}) provides an overview of the different kinds of Attributes and the Attribute management options. +Next, explore how to [create Attributes for yourself]({% link _docs_integrate/create-attributes-for-yourself.md %}) and how to [share Attributes]({% link _docs_integrate/share-attributes-with-peer.md %}) with a peer. +Also, discover how to [read Attributes]({% link _docs_integrate/read-attributes-from-peer.md %}) from a peer and how to store Attributes in a peer's Wallet for them. +The latter can be realized by [creating Attributes]({% link _docs_integrate/create-attributes-for-peer.md %}) for them or by [proposing Attributes]({% link _docs_integrate/propose-attributes-to-peer.md %}) to them. +The peer must give you their permission for this. +Furthermore, learn how to [update Attributes by succession]({% link _docs_integrate/update-attributes-by-succession.md %}) or how to [delete Attributes]({% link _docs_integrate/delete-attributes.md %}). ## Request Consent @@ -35,11 +48,12 @@ Discover how to request [persistent consent]({% link _docs_integrate/request-per ## Data Model -Understand the [Data Model]({% link _docs_integrate/data-model-overview.md %}) of enmeshed and how it fits into your integration. Also get an overview of the [Attribute Values]({% link _docs_integrate/attribute-values.md %}), the [Connector Events]({% link _docs_integrate/connector-events.md %}) and our [Use Cases]({% link _docs_integrate/use-cases.md %}). +Understand the [Data Model]({% link _docs_integrate/data-model-overview.md %}) of enmeshed and how it fits into your integration. +Also get an overview of the [Attribute Values]({% link _docs_integrate/attribute-values.md %}), the [Connector Events]({% link _docs_integrate/connector-events.md %}) and our [Use Cases]({% link _docs_integrate/use-cases.md %}). ## Migration Guides -Get support for the migration of an existing system to a new version, for example when [migrating from version 4 to version 5]({% link _docs_integrate/migration-from-v4-to-v5.md %}) or [from version 5 to version 6]({% link _docs_integrate/migration-from-v5-to-v6.md %}) of the enmeshed Runtime and Connector, respectively. +Get support for the migration of an existing system to a new version, for example when [migrating from version 5 to version 6]({% link _docs_integrate/migration-from-v5-to-v6.md %}) or [from version 6 to version 7]({% link _docs_integrate/migration-from-v6-to-v7.md %}) of the enmeshed Runtime and Connector, respectively. ## Troubleshooting diff --git a/_docs_integrate/access-the-connector.md b/_docs_integrate/access-the-connector.md index 6bdcaa7c1..4df6a9756 100644 --- a/_docs_integrate/access-the-connector.md +++ b/_docs_integrate/access-the-connector.md @@ -23,14 +23,17 @@ required_by: # End automatic generation --- -The primary integration capability of the Connector is the REST API. In order to use it, you should have received an API-Key for the respective Connector. An API-Key so far has all authorizations for accessing the API. +The primary integration capability of the Connector is the REST API. +In order to use it, you should have received an API-Key for the respective Connector. +An API-Key so far has all authorizations for accessing the API. # Hosted API tooling by the (development) Connector In order to use the hosted api tooling, it must be activated in the [Connector configuration]({% link _docs_operate/setup-with-docker-compose.md %}#hosted-api-tooling-by-the-development-connector). {: .notice--warning} -You can access the REST API documentation through the Connector's designated HTTP endpoints. Swagger and Rapidoc serve as interactive platforms hosted on the Connector, enabling you to explore and experiment with the various APIs interactively. +You can access the REST API documentation through the Connector's designated HTTP endpoints. +Swagger and Rapidoc serve as interactive platforms hosted on the Connector, enabling you to explore and experiment with the various APIs interactively. ## Swagger @@ -57,11 +60,14 @@ You can view these files with the [Swagger Editor](https://editor.swagger.io/) o # Accessing the Connector by Software Development Kits (SDK) -To achieve a better developer experience and type safety, preferably a Software Development Kit (SDK) should be used. The following SDKs are available for this purpose: +To achieve a better developer experience and type safety, preferably a Software Development Kit (SDK) should be used. +The following SDKs are available for this purpose: -We work on keeping this list as updated as possible. Please let us know, if some SDKs are outdated or new SDKs are available for the community. +We work on keeping this list as updated as possible. +Please let us know, if some SDKs are outdated or new SDKs are available for the community. {: .notice--info} ## TypeScript SDK -We offer an SDK developed in TypeScript that facilitates communication with your Connector from your TypeScript or JavaScript application. You can find it readily available on [npmjs](https://www.npmjs.com/package/@nmshd/connector-sdk). +We offer an SDK developed in TypeScript that facilitates communication with your Connector from your TypeScript or JavaScript application. +You can find it readily available on [npmjs](https://www.npmjs.com/package/@nmshd/connector-sdk). diff --git a/_docs_integrate/attribute-introduction.md b/_docs_integrate/attribute-introduction.md index f6dbd99b0..584744c0c 100644 --- a/_docs_integrate/attribute-introduction.md +++ b/_docs_integrate/attribute-introduction.md @@ -22,135 +22,175 @@ required_by: # End automatic generation --- -This guide provides an introduction to [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes) in the enmeshed context. Attributes are used to store information about Identities or data that is relevant in a Relationship between Identities. There are therefore two types of Attributes, the [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) and the [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), which are designed for these different purposes. Both have in common that they have a `value` property that contains the actual value of the Attribute, whereby it is possible to select from a long list of possible [Attribute value types]({% link _docs_integrate/attribute-values.md %}). They define the format, the validation rules and the information display for the stored data. Furthermore, an Attribute is technically stored as the `content` of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute), in whose other properties metadata can be found. +This guide provides an introduction to [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes) in the enmeshed context. +Attributes are used to store information about Identities or data that is relevant in a Relationship between Identities. +There are therefore two types of Attributes, the [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) and the [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), which are designed for these different purposes. +Both have in common that they have a `value` property that contains the actual value of the Attribute, whereby it is possible to select from a long list of possible [Attribute value types]({% link _docs_integrate/attribute-values.md %}). +They define the format, the validation rules and the information display for the stored data. +Furthermore, an Attribute is technically stored as the `content` of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute), in whose other properties metadata can be found.
## IdentityAttributes -[IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) play a pivotal role in the management and exchange of information within the networked ecosystem. An IdentityAttribute stores specific information about an Identity, which can be a person or an organization. The semantic meaning of an IdentityAttribute is determined by its [IdentityAttribute value type]({% link _docs_integrate/attribute-values.md %}#identity-attributes). +[IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) play a pivotal role in the management and exchange of information within the networked ecosystem. +An IdentityAttribute stores specific information about an Identity, which can be a person or an organization. +The semantic meaning of an IdentityAttribute is determined by its [IdentityAttribute value type]({% link _docs_integrate/attribute-values.md %}#identity-attributes). ### IdentityAttribute value types -The [IdentityAttribute value types]({% link _docs_integrate/attribute-values.md %}#identity-attributes) are used to define the type of the `value` property of an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute). In order to fulfill various purposes, many such IdentityAttribute value types are provided. If the IdentityAttribute value type used is not sufficient to clearly characterize the IdentityAttribute, `tags` can be used for a more precise description of its meaning. +The [IdentityAttribute value types]({% link _docs_integrate/attribute-values.md %}#identity-attributes) are used to define the type of the `value` property of an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute). +In order to fulfill various purposes, many such IdentityAttribute value types are provided. +If the IdentityAttribute value type used is not sufficient to clearly characterize the IdentityAttribute, `tags` can be used for a more precise description of its meaning. +Apart from custom `tags`, which must have the prefix `x:` or `X:`, Backbone-defined `tags` may be used, which can be queried using the [Get AttributeTagCollection]({% link _docs_use-cases/use-case-consumption-get-attributetagcollection.md %}) use case and which must start with the prefix `bkb:`. +Moreover, the prefixes `urn:`, `language:` and `mimetype:` are supported, and `language:` must be followed by a valid ISO 639 language code and `mimetype:` by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$`. -The storage of multiple IdentityAttributes of the same value type is possible. If an Identity receives a [Request for an IdentityAttribute of a certain value type]({% link _docs_integrate/read-attributes-from-peer.md %}#example-of-reading-an-identityattribute), it can choose which of the matching IdentityAttributes it wants to provide for its [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the [Request]({% link _docs_integrate/data-model-overview.md %}#request). For example, storing multiple IdentityAttributes of the same value type is beneficial if an Identity has more than one residential address. Using `tags` helps to distinguish such IdentityAttributes from each other. +The storage of multiple IdentityAttributes of the same value type is possible. +If an Identity receives a [Request for an IdentityAttribute of a certain value type]({% link _docs_integrate/read-attributes-from-peer.md %}#example-of-reading-an-identityattribute), it can choose which of the matching IdentityAttributes it wants to provide for its [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the [Request]({% link _docs_integrate/data-model-overview.md %}#request). +For example, storing multiple IdentityAttributes of the same value type is beneficial if an Identity has more than one residential address. +Using `tags` helps to distinguish such IdentityAttributes from each other. {: .notice--info} Depending on what IdentityAttribute value type is used, the associated IdentityAttribute is either a simple IdentityAttribute or a complex IdentityAttribute. #### Simple IdentityAttributes -A simple IdentityAttribute is an IdentityAttribute with an [IdentityAttribute value type]({% link _docs_integrate/attribute-values.md %}#identity-attributes) for which none of its properties correspond to another IdentityAttribute value type. In most cases, the IdentityAttribute value type then only has a single property, which often also has the name `value`. This property stores the actual value of the IdentityAttribute. From a technical point of view, it can be stated that the `id` of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) whose `content` is given by a simple IdentityAttribute cannot be the `parentId` of another LocalAttribute. In other words, it could be said that simple IdentityAttributes are not composite of other IdentityAttributes. Examples of simple IdentityAttributes are IdentityAttributes with IdentityAttribute value type [DisplayName]({% link _docs_integrate/attribute-values.md %}#displayname) or [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress). +A simple IdentityAttribute is an IdentityAttribute with an [IdentityAttribute value type]({% link _docs_integrate/attribute-values.md %}#identity-attributes) which only has a single property with the name `value`. +This property stores the actual value of the IdentityAttribute. +Examples of simple IdentityAttributes are IdentityAttributes with IdentityAttribute value type [DisplayName]({% link _docs_integrate/attribute-values.md %}#displayname) or [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress). #### Complex IdentityAttributes -A complex IdentityAttribute is an IdentityAttribute with an [IdentityAttribute value type]({% link _docs_integrate/attribute-values.md %}#identity-attributes) for which at least one property corresponds to another IdentityAttribute value type. An IdentityAttribute value type that contains such a property can be recognized by whether another IdentityAttribute value type is mentioned in its table in the [documentation]({% link _docs_integrate/attribute-values.md %}#identity-attributes) with regard to the validation of the property. Examples of complex IdentityAttributes are IdentityAttributes with IdentityAttribute value type [BirthDate]({% link _docs_integrate/attribute-values.md %}#birthdate) or [StreetAddress]({% link _docs_integrate/attribute-values.md %}#streetaddress). When [creating a complex IdentityAttribute for yourself]({% link _docs_integrate/create-attributes-for-yourself.md %}#example-of-creating-a-complex-identityattribute), there is an important detail to note in contrast to the [creation of a simple IdentityAttribute for yourself]({% link _docs_integrate/create-attributes-for-yourself.md %}#example-of-creating-a-simple-identityattribute). Creating an IdentityAttribute for yourself always leads to the creation of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) whose `shareInfo` property is undefined and whose `content` is given by the IdentityAttribute owned by yourself. Such a LocalAttribute is also referred to as a RepositoryAttribute. If a RepositoryAttribute is created that contains a complex IdentityAttribute within its `content` property, additional RepositoryAttributes are automatically created for each property of its IdentityAttribute value type that corresponds to another IdentityAttribute value type. These RepositoryAttributes are also referred to as children of the RepositoryAttribute belonging to the complex IdentityAttribute. The `id` of their parent is contained within their `parentId` property. The creation of these RepositoryAttributes makes it possible to share individual components of a complex IdentityAttribute. For example, if an IdentityAttribute of type [BirthDate]({% link _docs_integrate/attribute-values.md %}#birthdate) has been created, it is possible to share only the `year` of birth with peers, instead of the full date of birth. The corresponding IdentityAttribute of type [BirthYear]({% link _docs_integrate/attribute-values.md %}#birthyear) does not have to be created manually, but is created automatically after the IdentityAttribute of type [BirthDate]({% link _docs_integrate/attribute-values.md %}#birthdate) has been created. - -Please note that when creating a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) that contains a complex IdentityAttribute in its `content` property, additional LocalAttributes are only created automatically if the LocalAttribute is a RepositoryAttribute. However, if the LocalAttribute is an own shared IdentityAttribute or a peer shared IdentityAttribute, no additional LocalAttributes are created. More details on the terminology related to [LocalAttributes and IdentityAttributes]({% link _docs_integrate/attribute-introduction.md %}#localattributes-and-identityattributes) can be found in the next section. -{: .notice--info} +A complex IdentityAttribute is an IdentityAttribute with an [IdentityAttribute value type]({% link _docs_integrate/attribute-values.md %}#identity-attributes) which has multiple properties instead of only one `value` property. +Examples of complex IdentityAttributes are IdentityAttributes with IdentityAttribute value type [BirthDate]({% link _docs_integrate/attribute-values.md %}#birthdate) or [StreetAddress]({% link _docs_integrate/attribute-values.md %}#streetaddress). ### LocalAttributes and IdentityAttributes -From a technical perspective, an IdentityAttribute is always stored as the `content` of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). Depending on the values of certain properties of the LocalAttribute, a LocalAttribute whose `content` is given by an IdentityAttribute is also referred to as a **RepositoryAttribute**, an **own shared IdentityAttribute** or a **peer shared IdentityAttribute**. +From a technical perspective, an IdentityAttribute is always stored as the `content` of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). +A LocalAttribute whose `content` is given by an IdentityAttribute can be an [OwnIdentityAttribute](#ownidentityattributes) or a [PeerIdentityAttribute](#peeridentityattributes). -#### RepositoryAttributes +#### OwnIdentityAttributes -As already mentioned in the section on [complex IdentityAttributes]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes), a RepositoryAttribute is a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) whose `content` is given by an IdentityAttribute owned by yourself and whose `shareInfo` property is undefined. +When an Identity [creates an IdentityAttribute for itself]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-an-identityattribute-for-yourself), an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) is created. +Its `content` is given by the IdentityAttribute owned by the Identity. -
+
-A RepositoryAttribute is created when an Identity [creates an IdentityAttribute for itself]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-an-identityattribute-for-yourself). -If the IdentityAttribute is a complex IdentityAttribute, RepositoryAttributes are also created for the properties of the IdentityAttribute value type that correspond to other IdentityAttribute value types. -An Identity may share the underlying IdentityAttribute of a RepositoryAttribute with a peer. +An Identity may share the underlying IdentityAttribute of an OwnIdentityAttribute with a peer. This can be done by using a suitable [Request]({% link _docs_integrate/data-model-overview.md %}#request). -#### Own shared and peer shared IdentityAttributes +#### PeerIdentityAttributes -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. +When an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) is shared by its `owner`, [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with the OwnIdentityAttribute are created in the wallet of the `owner`. +They make it possible to record with whom an IdentityAttribute has been shared as the `address` of the peer with whom the IdentityAttribute is shared is contained within their `peer` property. +If an IdentityAttribute is shared by its `owner` with several peers, a corresponding number of AttributeForwardingDetails is generated. +If the OwnIdentityAttribute is [deleted]({% link _docs_integrate/delete-attributes.md %}#delete-emitted-attributes), the associated AttributeForwardingDetails are deleted as well. -
+
-If an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) is shared by its `owner`, this not only leads to the creation of an own shared IdentityAttribute as a copy of the associated RepositoryAttribute for the `owner` of the IdentityAttribute, but also to the creation of a peer shared IdentityAttribute for the peer with whom the IdentityAttribute was shared. A peer shared IdentityAttribute is a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) for which the `shareInfo` property is set. The `address` of the `owner` of the IdentityAttribute is contained within its `shareInfo.peer` property. The `shareInfo.sourceAttribute` property of a peer shared IdentityAttribute is always undefined, as the RepositoryAttribute used as the source is only stored locally for the `owner` of the IdentityAttribute. Furthermore, note that the `id` of a peer shared IdentityAttribute is always the same as the `id` of the associated own shared IdentityAttribute. To ensure the privacy of an Identity's data, the IdentityAttribute shared by its `owner` with a peer cannot be shared by that peer with a third party. +If an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) is shared by its `owner`, this not only leads to the creation of associated AttributeForwardingDetails for the `owner` of the IdentityAttribute, but also to the creation of a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) for the peer with whom the IdentityAttribute was shared. +The `address` of the `owner` of the IdentityAttribute is contained within its `peer` property. +Furthermore, note that the `id` of a PeerIdentityAttribute is always the same as the `id` of the associated OwnIdentityAttribute. +To ensure the privacy of an Identity's data, the IdentityAttribute shared by its `owner` with a peer cannot be shared by that peer with a third party. ## RelationshipAttributes -A [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) is used to store data that is relevant in the context of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between two Identities. Both Identities involved in the Relationship must agree to its creation. +A [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) is used to store data that is relevant in the context of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between two Identities. +Both Identities involved in the Relationship must agree to its creation. In the context of a single Relationship, each RelationshipAttribute has its unique `key` for identification. RelationshipAttributes can be shared with peers who are not involved in the Relationship in which the RelationshipAttribute exists as long as their `confidentiality` is not `"private"`. -Such sharing leads to the creation of ThirdPartyRelationshipAttributes. +Such sharing leads to the creation of [ThirdPartyRelationshipAttributes](#thirdpartyrelationshipattributes). For information on how to establish Relationships, refer to the [Establish Relationships]({% link _docs_integrate/establish-relationships.md %}) scenario documentation. {: .notice--info} ### RelationshipAttribute value types -The [RelationshipAttribute value types]({% link _docs_integrate/attribute-values.md %}#relationship-attributes) are used to define the type of the `value` property of a RelationshipAttribute. In order to fulfill various purposes, many such RelationshipAttribute value types are provided. Examples of RelationshipAttribute value types are [ProprietaryString]({% link _docs_integrate/attribute-values.md %}#proprietarystring) and [ProprietaryEMailAddress]({% link _docs_integrate/attribute-values.md %}#proprietaryemailaddress). In contrast to IdentityAttributes, RelationshipAttributes are not divided into simple RelationshipAttributes and complex RelationshipAttributes depending on the value type. Nevertheless, the RelationshipAttribute value type [Consent]({% link _docs_integrate/attribute-values.md %}#consent) should be highlighted, as it differs slightly from the other RelationshipAttribute value types. Accordingly, with the [Request persistent consent of peer]({% link _docs_integrate/request-persistent-consent-of-peer.md %}) scenario documentation, there is a separate guide for creating RelationshipAttributes with Consent as RelationshipAttribute value type. +The [RelationshipAttribute value types]({% link _docs_integrate/attribute-values.md %}#relationship-attributes) are used to define the type of the `value` property of a RelationshipAttribute. +In order to fulfill various purposes, many such RelationshipAttribute value types are provided. +Examples of RelationshipAttribute value types are [ProprietaryString]({% link _docs_integrate/attribute-values.md %}#proprietarystring) and [ProprietaryEMailAddress]({% link _docs_integrate/attribute-values.md %}#proprietaryemailaddress). +In contrast to IdentityAttributes, RelationshipAttributes are not divided into simple RelationshipAttributes and complex RelationshipAttributes depending on the value type. +Nevertheless, the RelationshipAttribute value type [Consent]({% link _docs_integrate/attribute-values.md %}#consent) should be highlighted, as it differs slightly from the other RelationshipAttribute value types. +Accordingly, with the [Request persistent consent of peer]({% link _docs_integrate/request-persistent-consent-of-peer.md %}) scenario documentation, there is a separate guide for creating RelationshipAttributes with Consent as RelationshipAttribute value type. ### LocalAttributes and RelationshipAttributes -From a technical perspective, a RelationshipAttribute is always stored as the `content` of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). Depending on the values of certain properties of the LocalAttribute, a LocalAttribute whose `content` is given by a RelationshipAttribute is also referred to as an **own shared RelationshipAttribute**, a **peer shared RelationshipAttribute**, an **emitted ThirdPartyRelationshipAttribute** or a **received ThirdPartyRelationshipAttribute**. For the simple initial creation of a RelationshipAttribute within a given Relationship, the terms [own shared RelationshipAttribute and peer shared RelationshipAttribute](#own-shared-and-peer-shared-relationshipattributes) are relevant. The terms [emitted ThirdPartyRelationshipAttribute and received ThirdPartyRelationshipAttribute](#emitted-and-received-shared-thirdpartyrelationshipattributes) are used if an existing RelationshipAttribute from one Relationship is shared with a peer from another Relationship. +From a technical perspective, a RelationshipAttribute is always stored as the `content` of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). +A LocalAttribute whose `content` is given by a RelationshipAttribute can be an [OwnRelationshipAttribute](#ownrelationshipattributes-and-peerrelationshipattributes), a [PeerRelationshipAttribute](#ownrelationshipattributes-and-peerrelationshipattributes) or a [ThirdPartyRelationshipAttribute](#thirdpartyrelationshipattributes). +For the simple initial creation of a RelationshipAttribute within a given Relationship, the terms [OwnRelationshipAttribute and PeerRelationshipAttribute](#ownrelationshipattributes-and-peerrelationshipattributes) are relevant. +The term [ThirdPartyRelationshipAttribute](#thirdpartyrelationshipattributes) is used if an existing RelationshipAttribute from one Relationship is shared with a peer from another Relationship. -#### Own shared and peer shared RelationshipAttributes +#### OwnRelationshipAttributes and PeerRelationshipAttributes A [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) can only exist in the context of a Relationship and must therefore be stored locally for both Identities involved in the Relationship. Accordingly, the [creation of a RelationshipAttribute]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-a-relationshipattribute) corresponds to the creation of one [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) for its `owner` and one LocalAttribute for the peer with whom the `owner` has established the Relationship in whose context the RelationshipAttribute is to exist. -The own shared RelationshipAttribute is the LocalAttribute of the `owner` of the RelationshipAttribute and the peer's LocalAttribute is referred to as a peer shared RelationshipAttribute. +The [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) is the LocalAttribute of the `owner` of the RelationshipAttribute and the peer's LocalAttribute is referred to as a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute). -
+
-Of course, the `shareInfo` property of the own shared RelationshipAttribute is set. Within the `shareInfo.peer` property, the `address` of the peer to whom the RelationshipAttribute's `owner` has established the Relationship in whose context the RelationshipAttribute exists is specified. -If the RelationshipAttribute is initially created for a specific Relationship and does not originate from another RelationshipAttribute, the `shareInfo.sourceAttribute` property is undefined. -The peer shared RelationshipAttribute is the peer's [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) and forms the counterpart of the own shared RelationshipAttribute. The `id` of a peer shared RelationshipAttribute is always the same as the `id` of the associated own shared RelationshipAttribute. As with the own shared RelationshipAttribute, the `shareInfo` property of a peer shared RelationshipAttribute is of course set. -Within the `shareInfo.peer` property, the `address` of the `owner` of the RelationshipAttribute is specified. -Furthermore, the `shareInfo.sourceAttribute` property of a peer shared RelationshipAttribute is undefined. -Also, for both the own shared and peer shared RelationshipAttribute, the `shareInfo.thirdPartyAddress` property is undefined, as it is only used for ThirdPartyRelationshipAttributes. +Within the `peer` property of the OwnRelationshipAttribute, the `address` of the peer to whom the RelationshipAttribute's `owner` has established the Relationship in whose context the RelationshipAttribute exists is specified. +The PeerRelationshipAttribute is the peer's [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) and forms the counterpart of the OwnRelationshipAttribute. +The `id` of a PeerRelationshipAttribute is always the same as the `id` of the associated OwnRelationshipAttribute. +Within the `peer` property of the PeerRelationshipAttribute, the `address` of the `owner` of the RelationshipAttribute is specified. -#### Emitted and received ThirdPartyRelationshipAttributes +#### ThirdPartyRelationshipAttributes Note that it is possible to share a RelationshipAttribute with peers who are not involved in the Relationship in which the RelationshipAttribute exists, provided that the `confidentiality` of the RelationshipAttribute is not `"private"`. -The sharing of a RelationshipAttribute with such a peer leads to the creation of a so-called emitted ThirdPartyRelationshipAttribute in the wallet of the Identity who has the source RelationshipAttribute. -An emitted ThirdPartyRelationshipAttribute is a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) similar to an own shared RelationshipAttribute that contains the `address` of this peer within its `shareInfo.peer` property. -As it originates from another own shared RelationshipAttribute that exists in the context of a different Relationship, it contains the `id` of the source RelationshipAttribute within its `shareInfo.sourceAttribute` property. -This is the case as long as the own shared RelationshipAttribute used as the source has not been [deleted]({% link _docs_integrate/delete-attributes.md %}#delete-own-shared-attributes). -Furthermore, in the `shareInfo.thirdPartyAddress` the `address` of the peer of the source RelationshipAttribute is stored. +The sharing of a RelationshipAttribute with such a peer leads to the creation of associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) in the wallet of the Identity who has the source RelationshipAttribute. +They contain the `address` of this peer within their `peer` property. +If the source RelationshipAttribute is [deleted]({% link _docs_integrate/delete-attributes.md %}#delete-emitted-attributes), the associated AttributeForwardingDetails will be deleted as well. +The source RelationshipAttribute is either an [OwnRelationshipAttribute](#ownrelationshipattributes-and-peerrelationshipattributes) or a [PeerRelationshipAttribute](#ownrelationshipattributes-and-peerrelationshipattributes). -
+
-In the wallet of the peer with whom the underlying RelationshipAttribute of the source RelationshipAttribute was shared, a so-called received ThirdPartyRelationshipAttribute is created. -It is a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) similar to a peer shared RelationshipAttribute that can be interpreted as the counterpart of an emitted ThirdPartyRelationshipAttribute. -As for the emitted ThirdPartyRelationshipAttribute, the `shareInfo.thirdPartyAddress` property of the received ThirdPartyRelationshipAttribute is set to the peer of the source RelationshipAttribute. -Lastly, the `shareInfo.sourceAttribute` property of a received ThirdPartyRelationshipAttribute is always undefined, as the source RelationshipAttribute can only be available locally to the emitter of the ThirdPartyRelationshipAttribute. +In the wallet of the peer with whom the underlying RelationshipAttribute of the source RelationshipAttribute was shared, a so-called [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute) is created. +The `initialAttributePeer` property of the ThirdPartyRelationshipAttribute is set to the peer of the source RelationshipAttribute. +The `id` of a ThirdPartyRelationshipAttribute is always the same as the `id` of the associated source RelationshipAttribute. ## Attribute management options -The IdentityAttributes and RelationshipAttributes were previously introduced. Regardless of whether an Attribute is an IdentityAttribute or a RelationshipAttribute, various operations can be performed with Attributes. These are described on separate documentation pages. In the following, the Attribute management options are briefly described. +The IdentityAttributes and RelationshipAttributes were previously introduced. +Regardless of whether an Attribute is an IdentityAttribute or a RelationshipAttribute, various operations can be performed with Attributes. +These are described on separate documentation pages. +In the following, the Attribute management options are briefly described. ### Create Attributes for yourself -Obviously, it is not possible to work with Attributes that have not yet been created. Therefore, the most important feature is the [creation of Attributes for yourself]({% link _docs_integrate/create-attributes-for-yourself.md %}). +Obviously, it is not possible to work with Attributes that have not yet been created. +Therefore, the most important feature is the [creation of Attributes for yourself]({% link _docs_integrate/create-attributes-for-yourself.md %}). ### Share Attributes with peer -Attributes can not only be managed locally, but can also be [shared with peers]({% link _docs_integrate/share-attributes-with-peer.md %}). The Identity can either share [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) about itself or [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) from a Relationship with another peer, [provided the `confidentiality` allows for it]({% link _docs_integrate/share-attributes-with-peer.md %}#combinations-and-usage-scenarios-of-shareattributerequestitem). +Attributes can not only be managed locally, but can also be [shared with peers]({% link _docs_integrate/share-attributes-with-peer.md %}). +The Identity can either share [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) about itself or [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) from a Relationship with another peer, [provided the `confidentiality` allows for it]({% link _docs_integrate/share-attributes-with-peer.md %}#combinations-and-usage-scenarios-of-shareattributerequestitem). ### Read Attributes from peer -If an Identity is interested in Attributes from another Identity and wants to query them, it can send a Request to [read Attributes from the peer]({% link _docs_integrate/read-attributes-from-peer.md %}). In this case the recipient of the Request can determine the values of the requested Attributes. An example of a use case would be if a company needs additional information about a customer that it does not have yet. +If an Identity is interested in Attributes from another Identity and wants to query them, it can send a Request to [read Attributes from the peer]({% link _docs_integrate/read-attributes-from-peer.md %}). +In this case the recipient of the Request can determine the values of the requested Attributes. +An example of a use case would be if a company needs additional information about a customer that it does not have yet. ### Create Attributes for peer -Furthermore, it is possible to [create Attributes for another Identity]({% link _docs_integrate/create-attributes-for-peer.md %}). In this case, the sender of the Request determines the value of the Attributes. For example if a school sends the students their certificates, then it is necessary to use [Requests for creating Attributes]({% link _docs_integrate/create-attributes-for-peer.md %}#request-for-creating-attributes). +Furthermore, it is possible to [create Attributes for another Identity]({% link _docs_integrate/create-attributes-for-peer.md %}). +In this case, the sender of the Request determines the value of the Attributes. +For example if a school sends the students their certificates, then it is necessary to use [Requests for creating Attributes]({% link _docs_integrate/create-attributes-for-peer.md %}#request-for-creating-attributes). ### Propose Attributes to peer -Lastly, if an Identity wants to [propose an Attribute to a peer]({% link _docs_integrate/propose-attributes-to-peer.md %}), it can send a Request that looks similar to the case where it wants to create an Attribute for the peer. However, the recipient of the Request has the possibility to answer with an Attribute whose content is determined by itself, similar to the case where the sender requests to read an Attribute from the peer. -The difference to the ReadAttributeRequestItem is that an Identity already has information about a peer and wants them to be confirmed in order to use them. For example, a company may want to support a customer in setting up an enmeshed account by proposing Attributes derived from the company’s knowledge of the costumer. +Lastly, if an Identity wants to [propose an Attribute to a peer]({% link _docs_integrate/propose-attributes-to-peer.md %}), it can send a Request that looks similar to the case where it wants to create an Attribute for the peer. +However, the recipient of the Request has the possibility to answer with an Attribute whose content is determined by itself, similar to the case where the sender requests to read an Attribute from the peer. +The difference to the ReadAttributeRequestItem is that an Identity already has information about a peer and wants them to be confirmed in order to use them. +For example, a company may want to support a customer in setting up an enmeshed account by proposing Attributes derived from the company’s knowledge of the costumer. ### Update Attributes by succession -If an Identity has created an Attribute that is owned by itself and is no longer valid, it has the option of [updating the Attribute by succession]({% link _docs_integrate/update-attributes-by-succession.md %}). The peers with whom the Identity may have shared the Attribute can be notified about the update of the Attribute. +If an Identity has created an Attribute that is owned by itself and is no longer valid, it has the option of [updating the Attribute by succession]({% link _docs_integrate/update-attributes-by-succession.md %}). +The peers with whom the Identity may have shared the Attribute can be notified about the update of the Attribute. ### Delete Attributes -An Identity may have created an Attribute for itself or received an Attribute from a peer that it does not need any longer. In both cases, it can [delete the Attribute]({% link _docs_integrate/delete-attributes.md %}). If an Identity has shared an Attribute that is owned by itself with a peer, it can [request the deletion of this Attribute from the peer]({% link _docs_integrate/delete-attributes.md %}#request-the-deletion-of-own-attributes-from-peer) in order to withdraw their permission to use the Attribute. Of course, the associated [own shared Attribute can be deleted]({% link _docs_integrate/delete-attributes.md %}#delete-own-shared-attributes), too. +An Identity may have created an Attribute for itself or received an Attribute from a peer that it does not need any longer. +In both cases, it can [delete the Attribute]({% link _docs_integrate/delete-attributes.md %}). +If an Identity has shared an Attribute with a peer, it can [request the deletion of this Attribute from its recipient]({% link _docs_integrate/delete-attributes.md %}#request-the-deletion-of-emitted-attributes-from-recipient) in order to withdraw their permission to use the Attribute. +Of course, the associated [emitted Attribute can be deleted]({% link _docs_integrate/delete-attributes.md %}#delete-emitted-attributes), too. diff --git a/_docs_integrate/attribute-values.md b/_docs_integrate/attribute-values.md index eb455acd2..af71666eb 100644 --- a/_docs_integrate/attribute-values.md +++ b/_docs_integrate/attribute-values.md @@ -23,15 +23,27 @@ required_by: # End automatic generation --- -Each [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) contains an instance of an Attribute Value within its `value` property. There are different types of Attribute Values. The types define the value's structural definition, rendering information and validators. For example, an email address with the value `address@company.corp` is stored with the Attribute Value type [`EMailAddress`](#emailaddress), which defines +Each [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) contains an instance of an Attribute Value within its `value` property. +There are different types of Attribute Values. +The types define the value's structural definition, rendering information and validators. +For example, an email address with the value `address@company.corp` is stored with the Attribute Value type [`EMailAddress`](#emailaddress), which defines - the data type of the actual value (a String) - how it is validated (the pattern of an email address and a maximum length) - information about how it can be rendered on the UI -enmeshed defines a standard set of possible Attribute Value types for Identities within the enmeshed ecosystem and its meaning for the Identities. And every Identity can understand/use/fill/query these Attribute Value types of other Identities. +enmeshed defines a standard set of possible Attribute Value types for Identities within the enmeshed ecosystem and its meaning for the Identities. +And every Identity can understand/use/fill/query these Attribute Value types of other Identities. -Most Attribute Value types are atomic, which means that they have only one property called `value` (e.g. [`EMailAddress`](#emailaddress), [`DisplayName`](#displayname), [`PhoneNumber`](#phonenumber)). But there are also more complex Attribute Value types which consist of multiple properties with a strong correlation (e.g. [`StreetAddress`](#streetaddress), [`PersonName`](#personname)). These properties can (but don't have to) contain other Attribute Values. +Most Attribute Value types are atomic, which means that they have only one property called `value` (e.g. [`EMailAddress`](#emailaddress), [`DisplayName`](#displayname), [`PhoneNumber`](#phonenumber)). +But there are also more complex Attribute Value types which consist of multiple properties with a strong correlation (e.g. [`StreetAddress`](#streetaddress), [`PersonName`](#personname)). + +# Valid Characters in Attributes + +Characters in Attribute values are restricted to the [normative characters of DIN 91379](https://en.wikipedia.org/wiki/DIN_91379#Normative_part) which reduces validation efforts required from integrators. +This bans, for example, foreign scripts like Greek or Chinese, but transliterations are possible in that case. +Also banned are emojis, which deters joke entries. +See [a one-page overview of the characters](https://github.com/String-Latin/DIN-91379-Characters-and-Sequences/blob/e6eff1e/latin_letters_1.3.txt#L1-L40) (the allowed characters are highlighted) and the [regex used for validation](https://xoev.de/schemata/din/91379/2022-08/din-norm-91379-datatypes.xsd) - search for datatypeC. # Identity Attributes @@ -39,129 +51,36 @@ The Attribute Values in this chapter can only be used in an [Identity Attribute] ## Affiliation -A complex Attribute Value type which defines the affiliation of a person to an organization. Inside of the organization the person can have a role and it can be assigned to a specific unit inside of the organization. - -**Properties** - -| Name | Type | Required | Validation | -| -------------- | --------------- | :------: | --------------------------------------------------------- | -| `@type` | `"Affiliation"` | ✓ | | -| `role` | `string` | ✗ | see [`AffiliationRole`](#affiliationrole) | -| `organization` | `string` | ✓ | see [`AffiliationOrganization`](#affiliationorganization) | -| `unit` | `string` | ✗ | see [`AffiliationUnit`](#affiliationunit) | - -## AffiliationOrganization - -The organization the person is affiliated to. - -It is not recommended to send an AffiliationOrganization to another Identity by its own. Instead, send an [`Affiliation`](#affiliation) with the `organization` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | --------------------------- | :------: | ---------------- | -| `@type` | `"AffiliationOrganization"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -**Validation** - -## AffiliationRole - -The role the person has in the organization. - -It is not recommended to send an AffiliationRole to another Identity by its own. Instead, send an [`Affiliation`](#affiliation) with the `role` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------------- | :------: | ---------------- | -| `@type` | `"AffiliationRole"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## AffiliationUnit - -The organization unit the person is affiliated to. - -It is not recommended to send an AffiliationUnit to another Identity by its own. Instead, send an [`Affiliation`](#affiliation) with the `unit` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------------- | :------: | ---------------- | -| `@type` | `"AffiliationUnit"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## BirthCity - -The city of birth. - -It is not recommended to send a BirthCity to another Identity by its own. Instead, send a [`BirthPlace`](#birthplace) with the `city` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------- | :------: | ---------------- | -| `@type` | `"BirthCity"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## BirthCountry - -The country of birth. - -It is not recommended to send a BirthCountry to another Identity by its own. Instead, send a [`BirthPlace`](#birthplace) with the `country` property set. -{: .notice--warning} +A complex Attribute Value type which defines the affiliation of a person to an organization. +Inside of the organization the person can have a role and it can be assigned to a specific unit inside of the organization. **Properties** -| Name | Type | Required | Validation | -| ------- | ---------------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"BirthCountry"` | ✓ | | -| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | +| Name | Type | Required | Validation | +| -------------- | --------------- | :------: | ---------------- | +| `@type` | `"Affiliation"` | ✓ | | +| `role` | `string` | ✗ | max. length: 100 | +| `organization` | `string` | ✓ | max. length: 100 | +| `unit` | `string` | ✗ | max. length: 100 | ## BirthDate -The birth date of a natural person. +The birth date of a natural person in the Gregorian calendar. **Properties** -| Name | Type | Required | Validation | -| ------- | ------------- | :------: | ------------------------------- | -| `@type` | `"BirthDate"` | ✓ | | -| `day` | `number` | ✓ | see [`BirthDay`](#birthday) | -| `month` | `number` | ✓ | see [`BirthMonth`](#birthmonth) | -| `year` | `number` | ✓ | see [`BirthYear`](#birthyear) | - -## BirthDay - -The day of birth. - -It is not recommended to send a BirthDay to another Identity by its own. Instead, send a [`BirthDate`](#birthdate) with the `day` property set. -{: .notice--warning} - -| Name | Type | Required | Validation | -| ------- | ------------ | :------: | --------------------------------------- | -| `@type` | `"BirthDay"` | ✓ | | -| `value` | `number` | ✓ | min: 1
max: 31
must be an integer | - -## BirthMonth - -The month of birth. - -It is not recommended to send a BirthMonth to another Identity by its own. Instead, send a [`BirthDate`](#birthdate) with the `month` property set. -{: .notice--warning} - -| Name | Type | Required | Validation | -| ------- | -------------- | :------: | --------------------------------------- | -| `@type` | `"BirthMonth"` | ✓ | | -| `value` | `number` | ✓ | min: 1
max: 12
must be an integer | +| Name | Type | Required | Validation | +| ------- | ------------- | :------: | ----------------------------------------- | +| `@type` | `"BirthDate"` | ✓ | | +| `day` | `number` | ✓ | min: 1
max: 31
must be an integer | +| `month` | `number` | ✓ | min: 1
max: 12
must be an integer | +| `year` | `number` | ✓ | min: 1
max: 9999
must be an integer | ## BirthName -The BirthName is the surname of the person at birth. Some countries allow changing the surname, thus the BirthName is also used as the identification. The BirthName is innate depending on your surname at birth. +The BirthName is the surname of the person at birth. +Some countries allow changing the surname, thus the BirthName is also used as the identification. +The BirthName is innate depending on your surname at birth. If this value is set, there has been a change of the surname throughout the life of the person. @@ -174,46 +93,21 @@ If this value is set, there has been a change of the surname throughout the life ## BirthPlace -The BirthPlace consists of the BirthCity and BirthCountry and can optionally include a BirthState (e.g. if the BirthCity is ambiguous within the BirthCountry). +The BirthPlace consists of the birth city and birth country and can optionally include a birth state (e.g. if the birth city is ambiguous within the birth country). **Properties** -| Name | Type | Required | Validation | -| --------- | -------------- | :------: | ------------------------------- | -| `@type` | `"BirthPlace"` | ✓ | | -| `city` | `string` | ✓ see | [`BirthCity`](#birthcity) | -| `country` | `string` | ✓ see | [`BirthCountry`](#birthcountry) | -| `state` | `string` | ✗ see | [`BirthState`](#birthstate) | - -## BirthState - -The state of birth. - -It is not recommended to send a BirthState to another Identity by its own. Instead, send a [`BirthPlace`](#birthplace) with the `state` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | -------------- | :------: | ---------------- | -| `@type` | `"BirthState"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## BirthYear - -The year of birth in the Gregorian calendar. - -It is not recommended to send a BirthYear to another Identity by its own. Instead, send a [`BirthDate`](#birthdate) with the `year` property set. -{: .notice--warning} - -| Name | Type | Required | Validation | -| ------- | ------------- | :------: | ----------------------------------------- | -| `@type` | `"BirthYear"` | ✓ | | -| `value` | `number` | ✓ | min: 1
max: 9999
must be an integer | +| Name | Type | Required | Validation | +| --------- | -------------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"BirthPlace"` | ✓ | | +| `city` | `string` | ✓ | max. length: 100 | +| `country` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | +| `state` | `string` | ✗ | max. length: 100 | ## Citizenship -The Citizenship defines which country currently recognizes you as a citizen. Thus, the Citizenship usually refers to the country you have a passport from. +The Citizenship defines which country currently recognizes you as a citizen. +Thus, the Citizenship usually refers to the country you have a passport from. **Properties** @@ -222,20 +116,6 @@ The Citizenship defines which country currently recognizes you as a citizen. Thu | `@type` | `"Citizenship"` | ✓ | | | `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | -## City - -The name of a city. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). - -It is not recommended to send a City to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `city` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | -------- | :------: | ---------------- | -| `@type` | `"City"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - ## CommunicationLanguage The CommunicationLanguage is an officially recognized language the person can communicate with. @@ -247,41 +127,28 @@ The CommunicationLanguage is an officially recognized language the person can co | `@type` | `"CommunicationLanguage"` | ✓ | | | `value` | `string` | ✓ | only [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language codes | -## Country - -A country code according to the standard "ISO 3166-1 alpha-2". This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). - -It is not recommended to send a Country to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `country` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ----------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"Country"` | ✓ | | -| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | - ## DeliveryBoxAddress A complex Attribute Value defining the components of a delivery box address. **Properties** -| Name | Type | Required | Validation | -| --------------- | ---------------------- | :------: | --------------------------------- | -| `@type` | `"DeliveryBoxAddress"` | ✓ | | -| `recipient` | `string` | ✓ | max. length: 100 | -| `deliveryBoxId` | `string` | ✓ | max. length: 100 | -| `userId` | `string` | ✓ | max. length: 100 | -| `zipCode` | `string` | ✓ | see [`ZipCode`](#zipcode) | -| `city` | `string` | ✓ | see [`City`](#city) | -| `country` | `string` | ✓ | see [`Country`](#country) | -| `phoneNumber` | `string` | ✗ | see [`PhoneNumber`](#phonenumber) | -| `state` | `string` | ✗ | see [`State`](#state) | +| Name | Type | Required | Validation | +| --------------- | ---------------------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"DeliveryBoxAddress"` | ✓ | | +| `recipient` | `string` | ✓ | max. length: 100 | +| `deliveryBoxId` | `string` | ✓ | max. length: 100 | +| `userId` | `string` | ✓ | max. length: 100 | +| `zipCode` | `string` | ✓ | max. length: 100 | +| `city` | `string` | ✓ | max. length: 100 | +| `country` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | +| `phoneNumber` | `string` | ✗ | see [`PhoneNumber`](#phonenumber) | +| `state` | `string` | ✗ | max. length: 100 | ## DisplayName -The Display Name is the textual representation of the natural or legal person. It is usually combined out of titles, names or legal statuses. +The Display Name is the textual representation of the natural or legal person. +It is usually combined out of titles, names or legal statuses. **Properties** @@ -358,23 +225,9 @@ The honorific suffix of a person, e.g. 'PhD' | `@type` | `"HonorificSuffix"` | ✓ | | | `value` | `string` | ✓ | max. length: 100 | -## HouseNumber - -A house number. This is usually used as part of a [`StreetAddress`](#streetaddress). - -It is not recommended to send a HouseNumber to another Identity by its own. Instead, send a [`StreetAddress`](#streetaddress) with the `houseNumber` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | --------------- | :------: | ---------------- | -| `@type` | `"HouseNumber"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - ## JobTitle -A short phrase that describes the position an employee has within an organization. (e.g. "Senior Developer" in case of a software company). +A short phrase that describes the position an employee has within an organization, e.g. "Senior Developer" in case of a software company. **Properties** @@ -396,7 +249,9 @@ In various cultures, a middle name is a portion of a personal name that is writt ## Nationality -The Nationality is the citizenship of a person at birth. One cannot change the Nationality because it's innate. Thus, the Nationality refers usually to the country where you are born. +The Nationality is the citizenship of a person at birth. +One cannot change the Nationality because it's innate. +Thus, the Nationality refers usually to the country where you are born. **Properties** @@ -437,15 +292,15 @@ A complex Attribute Value defining the components of a post office box address. **Properties** -| Name | Type | Required | Validation | -| ----------- | ------------------------ | :------: | ------------------------- | -| `@type` | `"PostOfficeBoxAddress"` | ✓ | | -| `recipient` | `string` | ✓ | max. length: 100 | -| `boxId` | `string` | ✓ | max. length: 100 | -| `zipCode` | `string` | ✓ | see [`ZipCode`](#zipcode) | -| `city` | `string` | ✓ | see [`City`](#city) | -| `country` | `string` | ✓ | see [`Country`](#country) | -| `state` | `string` | ✗ | see [`State`](#state) | +| Name | Type | Required | Validation | +| ----------- | ------------------------ | :------: | --------------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"PostOfficeBoxAddress"` | ✓ | | +| `recipient` | `string` | ✓ | max. length: 100 | +| `boxId` | `string` | ✓ | max. length: 100 | +| `zipCode` | `string` | ✓ | max. length: 100 | +| `city` | `string` | ✓ | max. length: 100 | +| `country` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | +| `state` | `string` | ✗ | max. length: 100 | ## Pseudonym @@ -460,7 +315,8 @@ The officially registered pseudonym of a person. ## SchematizedXML -SchematizedXML can be used to exchange files in XML format. The exchange of XML files is also possible via [`IdentityFileReference`](#identityfilereference), but SchematizedXML has the advantage that it is possible to validate the XML and display the Attributes in the wallet. +SchematizedXML can be used to exchange files in XML format. +The exchange of XML files is also possible via [`IdentityFileReference`](#identityfilereference), but SchematizedXML has the advantage that it is possible to validate the XML and display the Attributes in the wallet. **Properties** @@ -486,170 +342,22 @@ The "Gender" Attribute Value type is currently being evaluated to ensure inclusi | `@type` | `"Sex"` | ✓ | | | `value` | `string` | ✓ | one of: `"intersex"`, `"female"`, `"male"` | -## State - -The name of a state. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). - -It is not recommended to send a State to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `state` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | --------- | :------: | ---------------- | -| `@type` | `"State"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## Statement - -The statement allows a very generic digital mapping of facts - -**Properties** - -| Name | Type | Required | Validation | -| ------------------ | ------------- | :------: | ----------------------------------------------------------------------- | -| `@type` | `"Statement"` | ✓ | | -| `value` | `string` | ✓ | see [`StatementSubject`](#statementsubject) | -| `predicate` | `string` | ✓ | see [`StatementPredicate`](#statementpredicate) | -| `object` | `string` | ✓ | see [`StatementObject`](#statementobject) | -| `issuer` | `string` | ✓ | see [`DigitalIdentityDescriptor`](#statement-digitalidentitydescriptor) | -| `issuerConditions` | `string` | ✓ | see [`StatementIssuerConditions`](#statementissuerconditions) | - -## Statement DigitalIdentityDescriptor - -The issuer of a [`statement`](#statement). - -It is not recommended to send a DigitalIdentityDescriptor to another Identity by its own. Instead, send a [`statement`](#statement) -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------------ | ----------------------------- | :------: | -------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"DigitalIdentityDescriptor"` | ✓ | | -| `address` | `string` | ✓ | The `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that owns the statement. | -| `attributes` | `string []` | ✗ | see [`Identity Attributes`](#identity-attributes) | - -## StatementAuthorityType - -The authority type in [`StatementIssuerConditions`](#statementissuerconditions) - -It is not recommended to send a StatementAuthorityType to another Identity by its own. Instead, send a [`statement`](#statement) -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"Statement"` | ✓ | | -| `value` | `string` | ✓ | one of: `"ownAuthority"`, `"trustedAuthority"`, `"publicAuthority"`,`"relayedOwnAuthority"`, `"relayedTrustedAuthority"`, `"relayedPublicAuthority"` | - -## StatementEvidence - -The evidence in [`StatementIssuerConditions`](#statementissuerconditions) - -It is not recommended to send a StatementEvidence to another Identity by its own. Instead, send a [`statement`](#statement) -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | --------------------- | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"StatementEvidence"` | ✓ | | -| `value` | `string` | ✓ | one of: `"ownFact"`, `"digitalPublicIDCard"`, `"digitalPublicDocument"`,`"digitalDocument"`, `"sightCheckOfPublicIDCard"`, `"sightCheckOfPublicDocument"`,`"sightCheckOfDocument"`, `"mediaOfPublicIDCard"`, `"mediaOfPublicDocument"`, `"mediaOfDocument"` | - -## StatementIssuerConditions - -The issuer conditions in a [`Statement`](#statement) - -It is not recommended to send a StatementIssuerConditions to another Identity by its own. Instead, send a [`statement`](#statement) -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| --------------- | ----------------------------- | :------: | ----------------------------------------------------------------------- | -| `@type` | `"StatementIssuerConditions"` | ✓ | | -| `validFrom` | `string` | ✓ | The date from which on the Attribute is valid. | -| `validTo` | `string` | ✓ | The date until this Attribute is valid | -| `evidence` | `string` | ✓ | see [`StatementEvidence`](#statementevidence) | -| `authorityType` | `string` | ✓ | see [`StatementAuthorityType`](#statementauthoritytype) | -| `relayedParty` | `string` | ✗ | see [`DigitalIdentityDescriptor`](#statement-digitalidentitydescriptor) | - -## StatementObject - -The object of a [`statement`](#statement). - -It is not recommended to send a object to another Identity by its own. Instead, send a [`statement`](#statement) -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------------ | ------------------- | :------: | -------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"StatementObject"` | ✓ | | -| `address` | `string` | ✓ | The `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that owns the statement. | -| `attributes` | `string []` | ✗ | see [`Identity Attributes`](#identity-attributes) | - -## StatementPredicate - -The predicate of a [`statement`](#statement). - -It is not recommended to send a predicate to another Identity by its own. Instead, send a [`statement`](#statement) -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ---------------------- | :------: | ----------------------------------------------------------------------------------------- | -| `@type` | `"StatementPredicate"` | ✓ | | -| `value` | `string` | ✓ | one of: `"hasAttribute"`, `"relatesTo"`, `"isRelatedTo"` or any string starting with "z-" | - -## StatementSubject - -The subject of a [`statement`](#statement). - -It is not recommended to send a subject to another Identity by its own. Instead, send a [`statement`](#statement) -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------------ | -------------------- | :------: | -------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"StatementSubject"` | ✓ | | -| `address` | `string` | ✓ | The `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that owns the statement. | -| `attributes` | `string []` | ✗ | see [`Identity Attributes`](#identity-attributes) | - -## Street - -A street name. This is usually used as part of a [`StreetAddress`](#streetaddress). - -It is not recommended to send a Street to another Identity by its own. Instead, send a [`StreetAddress`](#streetaddress) with the `street` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ---------- | :------: | ---------------- | -| `@type` | `"Street"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - ## StreetAddress A complex Attribute Value defining the components of a "normal" address. **Properties** -| Name | Type | Required | Validation | -| ----------- | ----------------------- | :------: | --------------------------------- | -| `@type` | `"StreetAddress"` | ✓ | | -| `recipient` | `string` | ✓ | max. length: 100 | -| `street` | `string` | ✓ | see [`Street`](#street) | -| `houseNo` | `string` | ✓ | see [`HouseNumber`](#housenumber) | -| `zipCode` | `string` | ✓ | see [`ZipCode`](#zipcode) | -| `city` | `string` | ✓ | see [`City`](#city) | -| `country` | `string` | ✓ | see [`Country`](#country) | -| `state` | `string` \| `undefined` | ✓ | see [`State`](#state) | +| Name | Type | Required | Validation | +| ----------- | ----------------------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"StreetAddress"` | ✓ | | +| `recipient` | `string` | ✓ | max. length: 100 | +| `street` | `string` | ✓ | max. length: 100 | +| `houseNo` | `string` | ✓ | max. length: 100 | +| `zipCode` | `string` | ✓ | max. length: 100 | +| `city` | `string` | ✓ | max. length: 100 | +| `country` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | +| `state` | `string` \| `undefined` | ✓ | max. length: 100 | ## Surname @@ -673,27 +381,18 @@ The website of the person which can be used to get more information about the pe | `@type` | `"Website"` | ✓ | | | `value` | `string` | ✓ | min. length: 3
max. length: 1024
must be a valid URL | -## ZipCode - -A zip code. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). - -It is not recommended to send a ZipCode to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `zipCode` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ----------- | :------: | ---------------- | -| `@type` | `"ZipCode"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - # Relationship Attributes -The Attribute Values in this chapter can only be used in a [Relationship Attribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute). Most of them are generic. You can recognize those by the prefix `Proprietary` (e.g. `ProprietaryInteger`, `ProprietaryString`, ...). In order to add some validation, you have the option to add [`valueHints`]({% link _docs_integrate/data-model-overview.md %}#valuehints). +The Attribute Values in this chapter can only be used in a [Relationship Attribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute). +Most of them are generic. +You can recognize those by the prefix `Proprietary` (e.g. `ProprietaryInteger`, `ProprietaryString`, ...). +In order to add some validation, you have the option to add [`valueHints`]({% link _docs_integrate/data-model-overview.md %}#valuehints). ## Consent -Represents the consent of an Identity to a specific topic. To obtain persistent consent from a peer, a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) can be sent, which contains a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), whose `owner` is the peer, with Consent as `value.@type` within its `attribute` property. For more details, refer to the documentation of the [Request persistent consent of peer]({% link _docs_integrate/request-persistent-consent-of-peer.md %}) scenario. +Represents the consent of an Identity to a specific topic. +To obtain persistent consent from a peer, a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) can be sent, which contains a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), whose `owner` is the peer, with Consent as `value.@type` within its `attribute` property. +For more details, refer to the documentation of the [Request persistent consent of peer]({% link _docs_integrate/request-persistent-consent-of-peer.md %}) scenario. **Properties** @@ -806,9 +505,11 @@ An arbitrary integer number. ## ProprietaryJSON -An arbitrary JSON value. The `value` property can contain any valid JSON structure (except `null`). +An arbitrary JSON value. +The `value` property can contain any valid JSON structure (except `null`). -For validation purposes, the `value` property is stringified using `JSON.stringify`. That string must not exceed the maximum length of 4096 characters. +For validation purposes, the `value` property is stringified using `JSON.stringify`. +That string must not exceed the maximum length of 4096 characters. **Properties** diff --git a/_docs_integrate/connector-events.md b/_docs_integrate/connector-events.md index 863045062..b2be4a0dd 100644 --- a/_docs_integrate/connector-events.md +++ b/_docs_integrate/connector-events.md @@ -37,7 +37,6 @@ required_by: | 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.fileOwnershipClaimed | [File]({% link _docs_integrate/data-model-overview.md %}#file) | ... the ownership of the File was claimed by another Identity. This happens when they accept a corresponding [TransferFileOwnershipRequestItem]({% link _docs_integrate/data-model-overview.md %}#transferfileownershiprequestitem). | | transport.fileOwnershipLocked | [File]({% link _docs_integrate/data-model-overview.md %}#file) | ... the ownership of the File is locked and can only be claimed once the [`ownershipToken` is regenerated]({% link _docs_use-cases/use-case-transport-regenerate-file-ownership-token.md %}). | | 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. | diff --git a/_docs_integrate/create-attributes-for-peer.md b/_docs_integrate/create-attributes-for-peer.md index 79ddbdda7..39ac5d24c 100644 --- a/_docs_integrate/create-attributes-for-peer.md +++ b/_docs_integrate/create-attributes-for-peer.md @@ -28,28 +28,46 @@ There are many situations in which an Identity wants to create an [IdentityAttri - A university wants to send a graduate their degree certificate. - A company wants to provide an employee with their business email address at the start of their employment. -We will now explain how a Connector, hereinafter referred to as the Sender, can create an Attribute for another Connector, the so-called Recipient. Since understanding this creation process requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) and how to use them in general, you should take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) before continuing reading this guide. +We will now explain how a Connector, hereinafter referred to as the Sender, can create an Attribute for another Connector, the so-called Recipient. +Since understanding this creation process requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) and how to use them in general, you should take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) before continuing reading this guide. -Please note that the general procedure is the same if the Connector wants to create an Attribute for an App user instead of another Connector. For reasons of clarity, this guide focuses on the creation process with two Connectors. +Please note that the general procedure is the same if the Connector wants to create an Attribute for an App user instead of another Connector. +For reasons of clarity, this guide focuses on the creation process with two Connectors. {: .notice--info} -The Sender has several options for requesting an Attribute creation. This guide covers how it can request the creation of an Attribute for the Recipient so that the [Attribute value]({% link _docs_integrate/attribute-values.md %}) is only set by the Sender itself and cannot be modified by the Recipient when accepting the Request. +The Sender has several options for requesting an Attribute creation. +This guide covers how it can request the creation of an Attribute for the Recipient so that the [Attribute value]({% link _docs_integrate/attribute-values.md %}) is only set by the Sender itself and cannot be modified by the Recipient when accepting the Request. -If the Recipient should be able to adjust the Attribute offered for creation, the [Propose Attributes to peer]({% link _docs_integrate/propose-attributes-to-peer.md %}) guide must be consulted instead. Also, it is possible for the Sender to ask the Recipient for an Attribute of a specific Attribute value type without offering an Attribute by following the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide. If the Recipient complies with this Request by using the `newAttribute` parameter of the [AcceptReadAttributeRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptreadattributerequestitemparameters), +If the Recipient should be able to adjust the Attribute offered for creation, the [Propose Attributes to peer]({% link _docs_integrate/propose-attributes-to-peer.md %}) guide must be consulted instead. +Also, it is possible for the Sender to ask the Recipient for an Attribute of a specific Attribute value type without offering an Attribute by following the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide. +If the Recipient complies with this Request by using the `newAttribute` parameter of the [AcceptReadAttributeRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptreadattributerequestitemparameters), this leads to the creation of an Attribute for the Recipient whose Attribute value was chosen completely freely by it. {: .notice--info} ## Request for creating Attributes -The Sender wants to create an Attribute for the Recipient. To do this, the Sender must first create a suitable Request, which it can then send to the Recipient. In the following subsections, we describe the general appearance of a Request for creating Attributes. +The Sender wants to create an Attribute for the Recipient. +To do this, the Sender must first create a suitable Request, which it can then send to the Recipient. +In the following subsections, we describe the general appearance of a Request for creating Attributes. ### Role of CreateAttributeRequestItem -For requesting the creation of a single Attribute for the Recipient, a single RequestItem of type [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) must be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request). It is possible to request the creation of an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) or a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), which must be inserted into the `attribute` property of the CreateAttributeRequestItem. Depending on whether an IdentityAttribute or a RelationshipAttribute is to be created for the Recipient, the Sender has a different number of input options when defining the prospective `owner` of the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes). In the case of IdentityAttributes, the Recipient must be the prospective `owner`. In contrast, the Sender is also permitted as the `owner` of RelationshipAttributes. More details on the various input options when creating a Request for creating Attributes and the corresponding application scenarios can be found in the table of the [Combinations and usage scenarios of the CreateAttributeRequestItem]({% link _docs_integrate/create-attributes-for-peer.md %}#combinations-and-usage-scenarios-of-createattributerequestitem). +For requesting the creation of a single Attribute for the Recipient, a single RequestItem of type [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) must be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request). +It is possible to request the creation of an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) or a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), which must be inserted into the `attribute` property of the CreateAttributeRequestItem. +Depending on whether an IdentityAttribute or a RelationshipAttribute is to be created for the Recipient, the Sender has a different number of input options when defining the prospective `owner` of the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes). +In the case of IdentityAttributes, the Recipient must be the prospective `owner`. +In contrast, the Sender is also permitted as the `owner` of RelationshipAttributes. +More details on the various input options when creating a Request for creating Attributes and the corresponding application scenarios can be found in the table of the [Combinations and usage scenarios of the CreateAttributeRequestItem]({% link _docs_integrate/create-attributes-for-peer.md %}#combinations-and-usage-scenarios-of-createattributerequestitem). ### Combinations and usage scenarios of CreateAttributeRequestItem -The following table provides an overview of the possible kinds of Attributes that the Sender can create for the Recipient using the CreateAttributeRequestItem. It must be taken into account whether the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) is an IdentityAttribute or a RelationshipAttribute and which Identity is its `owner`. Note that you can only explicitly specify the Recipient as the `owner` of the Attribute for [Requests that are sent via a Message]({% link _docs_integrate/create-attributes-for-peer.md %}#request-via-message). This is because when a Request is sent via a Message, the Identity that receives the Request is always known in advance. For [Requests that are sent via a RelationshipTemplate]({% link _docs_integrate/create-attributes-for-peer.md %}#request-via-relationshiptemplate), an empty string must be specified as the `owner` instead, as you do not know the Identity that will load your RelationshipTemplate beforehand. Specifying an empty string for the `owner` of the Attribute is equivalent to requesting the creation of an Attribute with the Recipient as its `owner`. Requesting the creation of a RelationshipAttribute using a CreateAttributeRequestItem is only possible if it should exist in the context of the Relationship between the Sender and the Recipient. +The following table provides an overview of the possible kinds of Attributes that the Sender can create for the Recipient using the CreateAttributeRequestItem. +It must be taken into account whether the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) is an IdentityAttribute or a RelationshipAttribute and which Identity is its `owner`. +Note that you can only explicitly specify the Recipient as the `owner` of the Attribute for [Requests that are sent via a Message]({% link _docs_integrate/create-attributes-for-peer.md %}#request-via-message). +This is because when a Request is sent via a Message, the Identity that receives the Request is always known in advance. +For [Requests that are sent via a RelationshipTemplate]({% link _docs_integrate/create-attributes-for-peer.md %}#request-via-relationshiptemplate), an empty string must be specified as the `owner` instead, as you do not know the Identity that will load your RelationshipTemplate beforehand. +Specifying an empty string for the `owner` of the Attribute is equivalent to requesting the creation of an Attribute with the Recipient as its `owner`. +Requesting the creation of a RelationshipAttribute using a CreateAttributeRequestItem is only possible if it should exist in the context of the Relationship between the Sender and the Recipient. | Type and context | Owner | Possible? | Automation | Remarks, reasons and examples | | --------------------------------------------------------------------------------------------------------- | --------- | :-------: | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -60,7 +78,12 @@ The following table provides an overview of the possible kinds of Attributes tha ### Example of creating an IdentityAttribute -We assume that the Integrator of the Sender wants to create an IdentityAttribute of type [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) for the Recipient. To request the creation of this IdentityAttribute, the Sender needs to insert it into the `attribute` property of the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for creating Attributes. As the IdentityAttribute should be owned by the Recipient, an empty string is specified for its `owner` property. If the Sender sends the corresponding [Request via a Message]({% link _docs_integrate/create-attributes-for-peer.md %}#request-via-message), the address of the Recipient could alternatively be specified explicitly. In our example, we have chosen to set the value of the `mustBeAccepted` property of the CreateAttributeRequestItem to `true`. Please note that the `<...>` notation is used as a placeholder for the actual data as usual. +We assume that the Integrator of the Sender wants to create an IdentityAttribute of type [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) for the Recipient. +To request the creation of this IdentityAttribute, the Sender needs to insert it into the `attribute` property of the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for creating Attributes. +As the IdentityAttribute should be owned by the Recipient, an empty string is specified for its `owner` property. +If the Sender sends the corresponding [Request via a Message]({% link _docs_integrate/create-attributes-for-peer.md %}#request-via-message), the address of the Recipient could alternatively be specified explicitly. +In our example, we have chosen to set the value of the `mustBeAccepted` property of the CreateAttributeRequestItem to `true`. +Please note that the `<...>` notation is used as a placeholder for the actual data as usual. ```jsonc { @@ -84,7 +107,9 @@ We assume that the Integrator of the Sender wants to create an IdentityAttribute ### Example of creating a RelationshipAttribute -We now consider the case in which the Sender has an active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with the Recipient and wants to create a RelationshipAttribute of type [ProprietaryString]({% link _docs_integrate/attribute-values.md %}#proprietarystring) for this Relationship that is owned by itself. The Sender can request the creation of this RelationshipAttribute by inserting it into the `attribute` property of the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) included in the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for creating Attributes. In our example, we have chosen to set the value of the `mustBeAccepted` property of the CreateAttributeRequestItem to `true` and the value of the `confidentiality` property of the RelationshipAttribute to `"public"`. +We now consider the case in which the Sender has an active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with the Recipient and wants to create a RelationshipAttribute of type [ProprietaryString]({% link _docs_integrate/attribute-values.md %}#proprietarystring) for this Relationship that is owned by itself. +The Sender can request the creation of this RelationshipAttribute by inserting it into the `attribute` property of the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) included in the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for creating Attributes. +In our example, we have chosen to set the value of the `mustBeAccepted` property of the CreateAttributeRequestItem to `true` and the value of the `confidentiality` property of the RelationshipAttribute to `"public"`. ```jsonc { @@ -114,47 +139,63 @@ It would also be possible to specify an empty string as the value for the `owner ### Create multiple Attributes -Requesting the creation of Attributes for a peer is not limited to just a single Attribute, but it is possible to request the creation of multiple Attributes at the same time. For this purpose, several CreateAttributeRequestItems or suitable [RequestItemGroups]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) can be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for creating Attributes. If you want to use a RequestItemGroup in order to create multiple Attributes for the Recipient at the same time, you must insert corresponding CreateAttributeRequestItems into the `items` property of it. +Requesting the creation of Attributes for a peer is not limited to just a single Attribute, but it is possible to request the creation of multiple Attributes at the same time. +For this purpose, several CreateAttributeRequestItems or suitable [RequestItemGroups]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) can be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for creating Attributes. +If you want to use a RequestItemGroup in order to create multiple Attributes for the Recipient at the same time, you must insert corresponding CreateAttributeRequestItems into the `items` property of it. ## Send and receive the Request -The Sender that wants to create an Attribute for the Recipient may or may not already have a Relationship with the Recipient. Depending on which is the case, a different method can be used to send the [Request for creating Attributes]({% link _docs_integrate/create-attributes-for-peer.md %}#request-for-creating-attributes). There are two ways to send the Request for creating Attributes created by the Sender to the Recipient. +The Sender that wants to create an Attribute for the Recipient may or may not already have a Relationship with the Recipient. +Depending on which is the case, a different method can be used to send the [Request for creating Attributes]({% link _docs_integrate/create-attributes-for-peer.md %}#request-for-creating-attributes). +There are two ways to send the Request for creating Attributes created by the Sender to the Recipient. ### Request via RelationshipTemplate -If there is currently no Relationship between the Sender and the Recipient, this approach must be used. However, it is also possible for the Sender to use a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) to send a Request to the Recipient if there is already an active Relationship between them. All details on how to send and receive a Request via a RelationshipTemplate in general can be found in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide. +If there is currently no Relationship between the Sender and the Recipient, this approach must be used. +However, it is also possible for the Sender to use a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) to send a Request to the Recipient if there is already an active Relationship between them. +All details on how to send and receive a Request via a RelationshipTemplate in general can be found in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide. ### Request via Message -The Sender only has the option of sending a Request to the Recipient via a [Message]({% link _docs_integrate/data-model-overview.md %}#message) if there is already an active Relationship between them. All information on how to send and receive a Request via a Message can be found in the [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) guide. +The Sender only has the option of sending a Request to the Recipient via a [Message]({% link _docs_integrate/data-model-overview.md %}#message) if there is already an active Relationship between them. +All information on how to send and receive a Request via a Message can be found in the [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) guide. ## Accept the Request and create the Attributes -After the Recipient has received the [Request for creating Attributes]({% link _docs_integrate/create-attributes-for-peer.md %}#request-for-creating-attributes), it can accept it to create all or some of the Attributes that were offered for creation by the Sender. To do this, proceed as described in the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case documentation and specify the `id` of the received [Request]({% link _docs_integrate/data-model-overview.md %}#request). Also, you need to decide and specify for each CreateAttributeRequestItem contained in the Request for creating Attributes whether you want to accept or reject it. +After the Recipient has received the [Request for creating Attributes]({% link _docs_integrate/create-attributes-for-peer.md %}#request-for-creating-attributes), it can accept it to create all or some of the Attributes that were offered for creation by the Sender. +To do this, proceed as described in the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case documentation and specify the `id` of the received [Request]({% link _docs_integrate/data-model-overview.md %}#request). +Also, you need to decide and specify for each CreateAttributeRequestItem contained in the Request for creating Attributes whether you want to accept or reject it. -If the Recipient does not want to create any of the Attributes offered by the Sender and, therefore, does not want to accept the Request for creating Attributes of the Sender, it can reject it as a whole as well. For that, follow the instructions of the [Reject incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) use case. +If the Recipient does not want to create any of the Attributes offered by the Sender and, therefore, does not want to accept the Request for creating Attributes of the Sender, it can reject it as a whole as well. +For that, follow the instructions of the [Reject incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) use case. {: .notice--info} -
+
### Accept a CreateAttributeRequestItem If the Recipient agrees to the creation of one of the Attributes offered by the Sender, it can accept the associated CreateAttributeRequestItem contained in the Request for creating Attributes. The [AcceptRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptrequestitemparameters) must be used for that. -The acceptance of a CreateAttributeRequestItem leads to the creation of a corresponding [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) with a [LocalAttributeShareInfo]({% link _docs_integrate/data-model-overview.md %}#localattributeshareinfo) contained within its `shareInfo` property. +The acceptance of a CreateAttributeRequestItem leads to the creation of a corresponding [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). The `content` of the LocalAttribute is the underlying `attribute` of the CreateAttributeRequestItem. -Depending on whether an IdentityAttribute or a RelationshipAttribute is created and the ownership, it is referred to as either an [own shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes), an [own shared RelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-relationshipattributes) or a [peer shared RelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-relationshipattributes). +Depending on whether an IdentityAttribute or a RelationshipAttribute is created and the ownership, it is referred to as either an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) or a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute). +If the underlying `attribute` of the accepted [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) is an IdentityAttribute, [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with the created OwnIdentityAttribute will additionally be created for the Recipient beforehand. Based on the created LocalAttribute, an appropriate AcceptResponseItem of type [CreateAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#createattributeacceptresponseitem) is generated, which incorporates the `id` of the LocalAttribute in its `attributeId` property. This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for creating Attributes that will be transferred to the Sender. -If the underlying `attribute` of the accepted [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) is an IdentityAttribute, a [RepositoryAttribute]({% link _docs_integrate/attribute-introduction.md %}#repositoryattributes) will additionally be created for the Recipient beforehand. ### Reject a CreateAttributeRequestItem -Even if the Recipient accepts the Request for creating Attributes as a whole, it may decide not to accept all of the Attributes offered by the Sender. To be more precise, the Recipient has the option of rejecting [CreateAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) that have the value `false` specified in their `mustBeAccepted` property. To reject a CreateAttributeRequestItem, use the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters). The rejection of a CreateAttributeRequestItem leads to the creation of a corresponding ResponseItem of type [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem). This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for creating Attributes. +Even if the Recipient accepts the Request for creating Attributes as a whole, it may decide not to accept all of the Attributes offered by the Sender. +To be more precise, the Recipient has the option of rejecting [CreateAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) that have the value `false` specified in their `mustBeAccepted` property. +To reject a CreateAttributeRequestItem, use the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters). +The rejection of a CreateAttributeRequestItem leads to the creation of a corresponding ResponseItem of type [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem). +This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for creating Attributes. ### Example of accepting a RequestItemGroup -Let's look at an example where the Sender wants to create an [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress), a [BirthDate]({% link _docs_integrate/attribute-values.md %}#birthdate) and a [BirthPlace]({% link _docs_integrate/attribute-values.md %}#birthplace) for the Recipient. For this purpose, the Sender creates a [Request]({% link _docs_integrate/data-model-overview.md %}#request) for creating Attributes, which contains a CreateAttributeRequestItem belonging to the EMailAddress and a RequestItemGroup belonging to the birth information in its `items` property. The [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) itself includes two CreateAttributeRequestItems in its `items` property, namely one for the BirthDate and one for the BirthPlace. +Let's look at an example where the Sender wants to create an [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress), a [BirthDate]({% link _docs_integrate/attribute-values.md %}#birthdate) and a [BirthPlace]({% link _docs_integrate/attribute-values.md %}#birthplace) for the Recipient. +For this purpose, the Sender creates a [Request]({% link _docs_integrate/data-model-overview.md %}#request) for creating Attributes, which contains a CreateAttributeRequestItem belonging to the EMailAddress and a RequestItemGroup belonging to the birth information in its `items` property. +The [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) itself includes two CreateAttributeRequestItems in its `items` property, namely one for the BirthDate and one for the BirthPlace. ```jsonc { @@ -208,12 +249,16 @@ Let's look at an example where the Sender wants to create an [EMailAddress]({% l } ``` -In our example, the Sender only requires the Recipient to accept the EMailAddress and the BirthDate, which is why the individual [CreateAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) within the Request have specified corresponding values in their `mustBeAccepted` property. We assume that the Recipient wants to accept the Request and all its CreateAttributeRequestItems with the exception of the BirthPlace. +In our example, the Sender only requires the Recipient to accept the EMailAddress and the BirthDate, which is why the individual [CreateAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) within the Request have specified corresponding values in their `mustBeAccepted` property. +We assume that the Recipient wants to accept the Request and all its CreateAttributeRequestItems with the exception of the BirthPlace. -If the Recipient wants to accept the Request for creating Attributes, it must accept all CreateAttributeRequestItems for which the `mustBeAccepted` property is set to `true`. It is therefore not permitted for the Recipient to refuse to accept the EMailAddress or the BirthDate offered by the Sender. +If the Recipient wants to accept the Request for creating Attributes, it must accept all CreateAttributeRequestItems for which the `mustBeAccepted` property is set to `true`. +It is therefore not permitted for the Recipient to refuse to accept the EMailAddress or the BirthDate offered by the Sender. {: .notice--info} -The Recipient accepts the EMailAddress of the Sender. Also, the Recipient accepts the BirthDate and rejects the BirthPlace of the Sender. It therefore responds to the Request for creating Attributes as follows: +The Recipient accepts the EMailAddress of the Sender. +Also, the Recipient accepts the BirthDate and rejects the BirthPlace of the Sender. +It therefore responds to the Request for creating Attributes as follows: ```jsonc { @@ -242,9 +287,11 @@ Note that it is important to respond to RequestItems, some of which may be conta ## Receive the Response to the Request -We now assume that the Recipient has accepted the [Request for creating Attributes]({% link _docs_integrate/create-attributes-for-peer.md %}#request-for-creating-attributes) of the Sender. In order for the Sender to receive the Response of the Recipient, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). Please note that this synchronization can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync). +We now assume that the Recipient has accepted the [Request for creating Attributes]({% link _docs_integrate/create-attributes-for-peer.md %}#request-for-creating-attributes) of the Sender. +In order for the Sender to receive the Response of the Recipient, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). +Please note that this synchronization can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync). -
+
To view the Response to the Request, proceed as described in the [Query outgoing Requests]({% link _docs_use-cases/use-case-consumption-query-outgoing-requests.md %}) use case documentation and use the following query parameter: @@ -253,13 +300,17 @@ To view the Response to the Request, proceed as described in the [Query outgoing The Integrator of the Sender can now get the Response of the Recipient from the `response.content` property of the result. In the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) is a [CreateAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#createattributeacceptresponseitem) for each accepted and a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) for each rejected CreateAttributeRequestItem included. -Note that each accepted CreateAttributeRequestItem leads to the creation of an appropriate LocalAttribute with a LocalAttributeShareInfo of the Sender. +Note that each accepted CreateAttributeRequestItem leads to the creation of an appropriate LocalAttribute of the Sender. The `content` of the [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) is the underlying `attribute` of the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem). -Depending on whether an IdentityAttribute or a RelationshipAttribute has been created and the ownership, it is referred to as either a [peer shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes), an [own shared RelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-relationshipattributes) or a [peer shared RelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-relationshipattributes). +Depending on whether an IdentityAttribute or a RelationshipAttribute has been created and the ownership, it is referred to as either a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute), an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) or a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute). -In case of an error, [ErrorResponseItems]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) can also be included in the Response. If the Request for creating Attributes contains a RequestItemGroup in its `items` property, the Response to this Request contains a corresponding [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) in its `items` property. +In case of an error, [ErrorResponseItems]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) can also be included in the Response. +If the Request for creating Attributes contains a RequestItemGroup in its `items` property, the Response to this Request contains a corresponding [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) in its `items` property. {: .notice--info} ## What's next? -As already mentioned, this guide covers how an Identity can request the creation of an Attribute for a peer so that the [Attribute value]({% link _docs_integrate/attribute-values.md %}) is only set by the Identity itself and cannot be modified by the peer when accepting the Request. For a typical example of an application of this procedure, refer to the documentation of the [Request persistent consent of peer]({% link _docs_integrate/request-persistent-consent-of-peer.md %}) scenario. In many cases, however, it makes more sense if the peer can adjust the Attribute that was offered for creation. For that, take a look at the [Propose Attributes to peer]({% link _docs_integrate/propose-attributes-to-peer.md %}) guide. +As already mentioned, this guide covers how an Identity can request the creation of an Attribute for a peer so that the [Attribute value]({% link _docs_integrate/attribute-values.md %}) is only set by the Identity itself and cannot be modified by the peer when accepting the Request. +For a typical example of an application of this procedure, refer to the documentation of the [Request persistent consent of peer]({% link _docs_integrate/request-persistent-consent-of-peer.md %}) scenario. +In many cases, however, it makes more sense if the peer can adjust the Attribute that was offered for creation. +For that, take a look at the [Propose Attributes to peer]({% link _docs_integrate/propose-attributes-to-peer.md %}) guide. diff --git a/_docs_integrate/create-attributes-for-yourself.md b/_docs_integrate/create-attributes-for-yourself.md index 40511d82c..4b0498597 100644 --- a/_docs_integrate/create-attributes-for-yourself.md +++ b/_docs_integrate/create-attributes-for-yourself.md @@ -25,24 +25,26 @@ required_by: # End automatic generation --- -This guide explains the end-to-end flow of creating an [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) for your own Connector as its Integrator. As there are two types of Attributes, [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) and [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), a distinction must be made between them when creating an Attribute for yourself. +This guide explains the end-to-end flow of creating an [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) for your own Connector as its Integrator. +As there are two types of Attributes, [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) and [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), a distinction must be made between them when creating an Attribute for yourself. ## Create an IdentityAttribute for yourself -This section is about how to create an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) for your own Connector that is not initially shared with any other Identity. From a technical point of view, this corresponds to the creation of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) whose `content` is given by the IdentityAttribute that is intended to be created and whose `shareInfo` is undefined. Such a LocalAttribute is referred to as a RepositoryAttribute. +This section is about how to create an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) for your own Connector that is not initially shared with any other Identity. +From a technical point of view, this corresponds to the creation of an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute). -Since knowledge about IdentityAttributes is required in the following, you should take a look at our [IdentityAttribute introduction]({% link _docs_integrate/attribute-introduction.md %}#identityattributes) before you continue reading this guide. In particular, a description of the two kinds of IdentityAttributes, the [simple IdentityAttributes]({% link _docs_integrate/attribute-introduction.md %}#simple-identityattributes) and the [complex IdentityAttributes]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes), can be found there. +Since knowledge about IdentityAttributes is required in the following, you should take a look at our [IdentityAttribute introduction]({% link _docs_integrate/attribute-introduction.md %}#identityattributes) before you continue reading this guide. +In particular, a description of the two kinds of IdentityAttributes, the [simple IdentityAttributes]({% link _docs_integrate/attribute-introduction.md %}#simple-identityattributes) and the [complex IdentityAttributes]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes), can be found there. {: .notice--info} -### Input for creating a RepositoryAttribute +### Input for creating an OwnIdentityAttribute -To create a RepositoryAttribute, proceed as described in the [Create a RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-create-a-repositoryattribute.md %}) use case documentation. As input for the creation of a RepositoryAttribute, the following `content` must be used: +To create an OwnIdentityAttribute, proceed as described in the [Create an OwnIdentityAttribute]({% link _docs_use-cases/use-case-consumption-create-an-ownidentityattribute.md %}) use case documentation. +As input for the creation of an OwnIdentityAttribute, the following `content` must be used: ```jsonc { "content": { - "validFrom": "", - "validTo": "", "value": { // IdentityAttribute value ... @@ -53,20 +55,25 @@ To create a RepositoryAttribute, proceed as described in the [Create a Repositor ``` You need to replace the placeholders marked with `<...>` appropriately. -Note that the properties `validFrom`, `validTo` and `tags` are optional, so you can omit them. +Note that the property `tags` is optional, so you can omit it. It is necessary that you insert one of the available [IdentityAttributeValues]({% link _docs_integrate/attribute-values.md %}#identity-attributes) into the `value` property. -If there is already an existing RepositoryAttribute with an undefined `succeededBy` property and which therefore represents the latest version, whose `content.value` exactly matches the specified `value` in the payload for creating a new RepositoryAttribute, an error with [error code]({% link _docs_integrate/error-codes.md %}) `error.runtime.attributes.cannotCreateDuplicateRepositoryAttribute` is thrown. -This is to prevent several latest RepositoryAttributes with the same `content.value` from existing in parallel. +If there is already an existing OwnIdentityAttribute with an undefined `succeededBy` property and which therefore represents the latest version, whose `content.value` exactly matches the specified `value` in the payload for creating a new OwnIdentityAttribute, an error with [error code]({% link _docs_integrate/error-codes.md %}) `error.runtime.attributes.cannotCreateDuplicateOwnIdentityAttribute` is thrown. +This is to prevent several latest OwnIdentityAttributes with the same `content.value` from existing in parallel. -### Process of creating a RepositoryAttribute +### Process of creating an OwnIdentityAttribute -As you can see from the diagram below, after you have entered the [input for creating a RepositoryAttribute]({% link _docs_integrate/create-attributes-for-yourself.md %}#input-for-creating-a-repositoryattribute), a check is performed whether the input values for the properties of the specified [IdentityAttributeValue]({% link _docs_integrate/attribute-values.md %}#identity-attributes) meet the validation criteria documented on the [Attribute Values]({% link _docs_integrate/attribute-values.md %}) page. If the validation is not successful, an [error message]({% link _docs_integrate/error-codes.md %}) is sent in response. Otherwise, a RepositoryAttribute is created that contains the IdentityAttribute in its `content` property. If it is a [simple IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#simple-identityattributes), a success response is sent directly. In the case of a [complex IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes), on the other hand, another RepositoryAttribute is created beforehand for each of its appropriate properties. These RepositoryAttributes for the properties are also referred to as children of the RepositoryAttribute belonging to the complex IdentityAttribute. The `id` of their parent is contained within their `parentId` property. Note that the successful creation of a LocalAttribute, and therefore in particular the creation of a RepositoryAttribute, triggers the `consumption.attributeCreated` [Connector event]({% link _docs_integrate/connector-events.md %}). +As you can see from the diagram below, after you have entered the [input for creating an OwnIdentityAttribute]({% link _docs_integrate/create-attributes-for-yourself.md %}#input-for-creating-an-ownidentityattribute), a check is performed whether the input values for the properties of the specified [IdentityAttributeValue]({% link _docs_integrate/attribute-values.md %}#identity-attributes) meet the validation criteria documented on the [Attribute Values]({% link _docs_integrate/attribute-values.md %}) page. +If the validation is not successful, an [error message]({% link _docs_integrate/error-codes.md %}) is sent in response. +Otherwise, an OwnIdentityAttribute is created that contains the IdentityAttribute in its `content` property. +Regardless of whether it is a [simple IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#simple-identityattributes) or a [complex IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes), a success response is sent directly. +Note that the successful creation of a LocalAttribute, and therefore in particular the creation of an OwnIdentityAttribute, triggers the `consumption.attributeCreated` [Connector event]({% link _docs_integrate/connector-events.md %}). -
+
### Example of creating a simple IdentityAttribute -An example of a [simple IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#simple-identityattributes) is one of type [DisplayName]({% link _docs_integrate/attribute-values.md %}#displayname). To create one for your own Connector without specifying optional parameters, the following `content` must be used: +An example of a [simple IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#simple-identityattributes) is one of type [DisplayName]({% link _docs_integrate/attribute-values.md %}#displayname). +To create one for your own Connector without specifying optional parameters, the following `content` must be used: ```jsonc { @@ -79,11 +86,12 @@ An example of a [simple IdentityAttribute]({% link _docs_integrate/attribute-int } ``` -Assuming that the input value for the Connector's display name specified in the `value.value` property meets the [validation criterion]({% link _docs_integrate/attribute-values.md %}#displayname), which means that the entered name does not have more than 100 characters, the IdentityAttribute is saved as a RepositoryAttribute and a success response is sent. +Assuming that the input value for the Connector's display name specified in the `value.value` property meets the [validation criterion]({% link _docs_integrate/attribute-values.md %}#displayname), which means that the entered name does not have more than 100 characters, the IdentityAttribute is saved as an OwnIdentityAttribute and a success response is sent. ### Example of creating a complex IdentityAttribute -An example of a [complex IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes) is one of type [BirthDate]({% link _docs_integrate/attribute-values.md %}#birthdate). To create one for your own Connector without specifying optional parameters, the following `content` must be used: +An example of a [complex IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes) is one of type [BirthDate]({% link _docs_integrate/attribute-values.md %}#birthdate). +To create one for your own Connector without specifying optional parameters, the following `content` must be used: ```jsonc { @@ -98,32 +106,48 @@ An example of a [complex IdentityAttribute]({% link _docs_integrate/attribute-in } ``` -Assuming that the input values ​​for the properties `value.day`, `value.month` and `value.year` meet the [validation criteria]({% link _docs_integrate/attribute-values.md %}#birthdate), which means, for example, that the input value for `value.month` is an integer between 1 and 12, the IdentityAttribute is saved as a RepositoryAttribute. The properties `value.day`, `value.month` and `value.year` can each be understood as an additional simple IdentityAttribute of type [BirthDay]({% link _docs_integrate/attribute-values.md %}#birthday), [BirthMonth]({% link _docs_integrate/attribute-values.md %}#birthmonth) and [BirthYear]({% link _docs_integrate/attribute-values.md %}#birthyear), respectively. For this reason, another RepositoryAttribute is created internally for each of these properties before a success response is sent. So for the RepositoryAttribute, which belongs to the complex IdentityAttribute of type BirthDate, a total of three children are created. +Assuming that the input values ​​for the properties `value.day`, `value.month` and `value.year` meet the [validation criteria]({% link _docs_integrate/attribute-values.md %}#birthdate), which means, for example, that the input value for `value.month` is an integer between 1 and 12, the IdentityAttribute is saved as an OwnIdentityAttribute. ### What's next? -When you have successfully created an IdentityAttribute for your own Connector, you will receive a success response. From the result, you can get the `id` of the corresponding RepositoryAttribute belonging to the IdentityAttribute. You will need this `id`, for example, if you want to share the underlying IdentityAttribute with other Identities later, as in the [Share Attributes with peer]({% link _docs_integrate/share-attributes-with-peer.md %}) scenario. +When you have successfully created an IdentityAttribute for your own Connector, you will receive a success response. +From the result, you can get the `id` of the corresponding OwnIdentityAttribute belonging to the IdentityAttribute. +You will need this `id`, for example, if you want to share the underlying IdentityAttribute with other Identities later, as in the [Share Attributes with peer]({% link _docs_integrate/share-attributes-with-peer.md %}) scenario. ## Create a RelationshipAttribute -If you want to create a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), you must proceed differently than when [creating an IdentityAttribute for yourself]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-an-identityattribute-for-yourself). This is because a RelationshipAttribute can only exist in the context of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with a peer, which means that they must also agree to the creation of it. This is achieved by sending a [Request]({% link _docs_integrate/data-model-overview.md %}#request) whose `items` property contains an appropriate [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems), which must be accepted by the peer. Depending on whether you or your peer should set the [RelationshipAttributeValue]({% link _docs_integrate/attribute-values.md %}#relationship-attributes) and depending on other factors, a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem), [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem), [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) or [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) should be used for this. +If you want to create a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), you must proceed differently than when [creating an IdentityAttribute for yourself]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-an-identityattribute-for-yourself). +This is because a RelationshipAttribute can only exist in the context of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with a peer, which means that they must also agree to the creation of it. +This is achieved by sending a [Request]({% link _docs_integrate/data-model-overview.md %}#request) whose `items` property contains an appropriate [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems), which must be accepted by the peer. +Depending on whether you or your peer should set the [RelationshipAttributeValue]({% link _docs_integrate/attribute-values.md %}#relationship-attributes) and depending on other factors, a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem), [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem), [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) or [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) should be used for this. -From a technical point of view, the creation of a RelationshipAttribute corresponds to the creation of one [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) for yourself and one LocalAttribute for your peer, whereby their `content` is given by the RelationshipAttribute that is intended to be created and the `shareInfo` of both LocalAttributes contains a correspondingly suitable [LocalAttributeShareInfo]({% link _docs_integrate/data-model-overview.md %}#localattributeshareinfo). -In terms of nomenclature, this pair of LocalAttributes consists of one own shared RelationshipAttribute and one peer shared RelationshipAttribute. +From a technical point of view, the creation of a RelationshipAttribute corresponds to the creation of one [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) for yourself and one LocalAttribute for your peer, whereby their `content` is given by the RelationshipAttribute that is intended to be created. +In terms of nomenclature, this pair of LocalAttributes consists of one [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) and one [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute). {: .notice--info} ### Utilization of a CreateAttributeRequestItem -You can use a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want the RelationshipAttributeValue to be set by yourself. Your peer can only accept or reject the creation of the RelationshipAttribute, but cannot modify the RelationshipAttributeValue. A RelationshipAttribute that you want to create using a CreateAttributeRequestItem can be owned by yourself or by your peer. For full details on how to create a RelationshipAttribute using a CreateAttributeRequestItem, please refer to the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. +You can use a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want the RelationshipAttributeValue to be set by yourself. +Your peer can only accept or reject the creation of the RelationshipAttribute, but cannot modify the RelationshipAttributeValue. +A RelationshipAttribute that you want to create using a CreateAttributeRequestItem can be owned by yourself or by your peer. +For full details on how to create a RelationshipAttribute using a CreateAttributeRequestItem, please refer to the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. ### Utilization of a ReadAttributeRequestItem -You can use a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem) to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want the RelationshipAttributeValue to be set by your peer. Even if it seems misleading to use a ReadAttributeRequestItem to create a RelationshipAttribute, this terminology makes sense insofar as the RelationshipAttributeValue should be read from the peer in order to be able to create the RelationshipAttribute. A RelationshipAttribute that you want to create using a ReadAttributeRequestItem can be owned by yourself, your peer or even a third party. For full details on how to create a RelationshipAttribute using a ReadAttributeRequestItem, please refer to the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide. +You can use a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem) to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want the RelationshipAttributeValue to be set by your peer. +Even if it seems misleading to use a ReadAttributeRequestItem to create a RelationshipAttribute, this terminology makes sense insofar as the RelationshipAttributeValue should be read from the peer in order to be able to create the RelationshipAttribute. +A RelationshipAttribute that you want to create using a ReadAttributeRequestItem can be owned by yourself, your peer or even a third party. +For full details on how to create a RelationshipAttribute using a ReadAttributeRequestItem, please refer to the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide. ### Utilization of a ProposeAttributeRequestItem -You can use a [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want to propose a potentially suitable RelationshipAttributeValue to your peer, but your peer has the option to modify it before the RelationshipAttribute is created. A RelationshipAttribute that you want to create using a ProposeAttributeRequestItem must be owned by your peer. All details on how to create a RelationshipAttribute using a ProposeAttributeRequestItem can be found in the [Propose Attributes to peer]({% link _docs_integrate/propose-attributes-to-peer.md %}) guide. +You can use a [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want to propose a potentially suitable RelationshipAttributeValue to your peer, but your peer has the option to modify it before the RelationshipAttribute is created. +A RelationshipAttribute that you want to create using a ProposeAttributeRequestItem must be owned by your peer. +All details on how to create a RelationshipAttribute using a ProposeAttributeRequestItem can be found in the [Propose Attributes to peer]({% link _docs_integrate/propose-attributes-to-peer.md %}) guide. ### Utilization of a ShareAttributeRequestItem -You can use a [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want to use an existing RelationshipAttribute between you and a third party as the source for creating the new RelationshipAttribute. Your peer can only accept or reject the creation of it, but cannot modify it. A RelationshipAttribute that you want to create using a ShareAttributeRequestItem can be owned by yourself or the third party, but not by your peer. All details on how to create a RelationshipAttribute using a ShareAttributeRequestItem can be found in the [Share Attributes with peer]({% link _docs_integrate/share-attributes-with-peer.md %}) guide. +You can use a [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) to create a RelationshipAttribute in the context of a Relationship between you and your peer if you want to use an existing RelationshipAttribute between you and a third party as the source for creating the new RelationshipAttribute. +Your peer can only accept or reject the creation of it, but cannot modify it. +A RelationshipAttribute that you want to create using a ShareAttributeRequestItem can be owned by yourself or the third party, but not by your peer. +All details on how to create a RelationshipAttribute using a ShareAttributeRequestItem can be found in the [Share Attributes with peer]({% link _docs_integrate/share-attributes-with-peer.md %}) guide. diff --git a/_docs_integrate/data-model-overview.md b/_docs_integrate/data-model-overview.md index c45d6b3de..003fe302d 100644 --- a/_docs_integrate/data-model-overview.md +++ b/_docs_integrate/data-model-overview.md @@ -29,42 +29,54 @@ The enmeshed data model can be divided into three parts: - Local types - Content types -The following diagram gives you an overview of all the existing types and how they are connected to each other. The subsequent chapters describe these types in more detail. +The following diagram gives you an overview of all the existing types and how they are connected to each other. +The subsequent chapters describe these types in more detail. -
+
(note that you can click on each type in order to navigate to the paragraph with the corresponding description) -At a first glance the amount of types is overwhelming. But in the following chapters all of them are explained in detail. +At a first glance the amount of types is overwhelming. +But in the following chapters all of them are explained in detail. # Transport Types -Transport types like `RelationshipTemplate`, `Token` or `File` are types that are "exchanged" between Identities via the Backbone. They are created and updated by the [Transport Layer]({% link _docs_explore/42-transport-layer.md %}). In most cases they have a `content` property, which contains the actual payload that should be transferred between the Identities. This payload is being encrypted when it is sent to the Backbone, and decrypted by the other Identity when it is received. The following sections describe the different Transport types and their properties. +Transport types like `RelationshipTemplate`, `Token` or `File` are types that are "exchanged" between Identities via the Backbone. +They are created and updated by the [Transport Layer]({% link _docs_explore/42-transport-layer.md %}). +In most cases they have a `content` property, which contains the actual payload that should be transferred between the Identities. +This payload is being encrypted when it is sent to the Backbone, and decrypted by the other Identity when it is received. +The following sections describe the different Transport types and their properties. -Note that the properties of the types are the ones that exist locally (aka on the Connector/in the App). The Backbone does not necessarily know about them. The properties that only exist locally are marked accordingly in the tables below. Further there are properties that are confidential and are therefore encrypted before sent to the Backbone, in order to enable end-to-end encryption. Both kinds of these properties are marked accordingly in the "Remarks" column of the property tables below. +Note that the properties of the types are the ones that exist locally (aka on the Connector/in the App). +The Backbone does not necessarily know about them. +The properties that only exist locally are marked accordingly in the tables below. +Further there are properties that are confidential and are therefore encrypted before sent to the Backbone, in order to enable end-to-end encryption. +Both kinds of these properties are marked accordingly in the "Remarks" column of the property tables below. ## Token -Tokens can be used to save arbitrary structured data on the Backbone, which is encrypted with a random symmetric key. You can then pass the ID of the Token, together with the random key, to another Identity, which can then retrieve the token and decrypt it, e.g. inside of a QR code, which you send to the recipient via letter. Tokens can be handy in a lot of scenarios, for example: +Tokens can be used to save arbitrary structured data on the Backbone, which is encrypted with a random symmetric key. +You can then pass the ID of the Token, together with the random key, to another Identity, which can then retrieve the token and decrypt it, e.g. inside of a QR code, which you send to the recipient via letter. +Tokens can be handy in a lot of scenarios, for example: - You want to share secret information with someone you don't have a Relationship with. -- The enmeshed App currently uses a Token to save a Backup of the Identity. The Token's `reference.url` is then encoded in a QR code, which the user can print out and scan later in order to restore the Identity on a new device. +- The enmeshed App currently uses a Token to save a Backup of the Identity. + The Token's `reference.url` is then encoded in a QR code, which the user can print out and scan later in order to restore the Identity on a new device. A Token has the following properties: -| Name | Type | Description | Remarks | -| ------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | -| id | `string` | {% include descr_id class="Token" prefix="TOK" %} | -| isOwn | `boolean` | {% include descr_isOwn class="Token" %} | saved only locally | -| createdBy | `string` | {% include descr_createdBy class="Token" %} | | -| createdByDevice | `string` | {% include descr_createdByDevice class="Token" %} | | -| content | `unknown` | The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone | -| createdAt | `string` | {% include descr_createdAt class="Token" %} | | -| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | | -| forIdentity | `string` \| `undefined` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the Token from the Backbone. | -| passwordProtection | [`PasswordProtection`](#passwordprotection) \| `undefined` | Information about whether or not the Token is protected by a password or pin. | | -| truncatedReference | `string` | A Base64 encoded string containing all information necessary for another Identity to load the Token. You can use it to share the Token with someone else. This property is deprecated and will be replaced by the `reference.truncated` property of the Token in future. | saved only locally | -| reference | [`ObjectReference`](#objectreference) | {% include descr_reference class="Token" %} | saved only locally | -| isEphemeral | `boolean` | If set to `true` the Token will not be cached in the database and only displayed once. You will not be able to fetch this Token unless you remember its reference. | +| Name | Type | Description | Remarks | +| ------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| id | `string` | {% include descr_id class="Token" prefix="TOK" %} | +| isOwn | `boolean` | {% include descr_isOwn class="Token" %} | saved only locally | +| createdBy | `string` | {% include descr_createdBy class="Token" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="Token" %} | | +| content | `unknown` | The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone | +| createdAt | `string` | {% include descr_createdAt class="Token" %} | | +| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | | +| forIdentity | `string` \| `undefined` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the Token from the Backbone. | +| passwordProtection | [`PasswordProtection`](#passwordprotection) \| `undefined` | Information about whether or not the Token is protected by a password or pin. | | +| reference | [`ObjectReference`](#objectreference) | {% include descr_reference class="Token" %} | saved only locally | +| isEphemeral | `boolean` | If set to `true` the Token will not be persisted in the database and only displayed once. You will not be able to fetch this Token unless you remember its reference. | ### PasswordProtection @@ -91,8 +103,12 @@ The data objects [Token](#token), [RelationshipTemplate](#relationshiptemplate) A RelationshipTemplate serves two purposes: -1. It represents the permission to establish a Relationship. When initiating a Relationship, the ID of a valid RelationshipTemplate must be attached. Otherwise the Backbone blocks the Relationship. And since the IDs are randomly generated, you can only obtain such an ID from the RelationshipTemplate's owner. -2. It can contain data which is of interest for the one who uses the RelationshipTemplate. The enmeshed App for example expects a RelationshipTemplate content which contains a `Request` which contains e.g. Attributes about the creator of the RelationshipTemplate as well as queries for Attributes that the RelationshipTemplate creator wants to receive together with the Relationship. +1. It represents the permission to establish a Relationship. + When initiating a Relationship, the ID of a valid RelationshipTemplate must be attached. + Otherwise the Backbone blocks the Relationship. + And since the IDs are randomly generated, you can only obtain such an ID from the RelationshipTemplate's owner. +2. It can contain data which is of interest for the one who uses the RelationshipTemplate. + The enmeshed App for example expects a RelationshipTemplate content which contains a `Request` which contains e.g. Attributes about the creator of the RelationshipTemplate as well as queries for Attributes that the RelationshipTemplate creator wants to receive together with the Relationship. | Name | Type | Description | Remarks | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | @@ -106,17 +122,18 @@ A RelationshipTemplate serves two purposes: | maxNumberOfAllocations | `number` \| `undefined` | Can be set to limit the number of allocations of this RelationshipTemplate. A RelationshipTemplate is allocated by another Identity when it is first retrieved by it from the Backbone. After this value is reached, the Backbone rejects each request of any new Identity that wants to retrieve it. Identities that already allocated it will still be able to retrieve it. | | | forIdentity | `string` \| `undefined` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the RelationshipTemplate from the Backbone. | | | passwordProtection | [`PasswordProtection`](#passwordprotection) \| `undefined` | Information about whether or not the RelationshipTemplate is protected by a password or pin. | | -| truncatedReference | `string` | A Base64 encoded string containing all information necessary for another Identity to load the RelationshipTemplate. You can use it to share the RelationshipTemplate with someone else. This property is deprecated and will be replaced by the `reference.truncated` property of the RelationshipTemplate in future. | saved only locally | | reference | [`ObjectReference`](#objectreference) | {% include descr_reference class="RelationshipTemplate" %} | saved only locally | ## Relationship -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. +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. | | +| templateId | `string` | The ID of 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. | | @@ -136,7 +153,9 @@ Whether the Identity with which you have a Relationship is to be deleted or has ### 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. +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 | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | @@ -149,7 +168,11 @@ The audit log records Relationship operations starting with the creation of the ## Message -A Message is a piece of data that can be sent to one or more recipients. The sender is completely free in what the content of the Message looks like. Though in order to enable a normalized communication, enmeshed defines some `content` structures for Messages, and in the future there will be more of those. Consider that the enmeshed App only supports Messages with such a normalized `content`. Currently there are: +A Message is a piece of data that can be sent to one or more recipients. +The sender is completely free in what the content of the Message looks like. +Though in order to enable a normalized communication, enmeshed defines some `content` structures for Messages, and in the future there will be more of those. +Consider that the enmeshed App only supports Messages with such a normalized `content`. +Currently there are: - [`Mail`](#mail) - [`Request`](#request) @@ -185,27 +208,27 @@ But if you are communicating with another Connector, you can use the [`Arbitrary The Backbone allows you to [upload a file]({% link _docs_use-cases/use-case-transport-upload-own-file.md %}) in encrypted form. Its metadata information is stored in a data object of type File. -A File further has its content, of course. But since this is not a JSON property, it is not included in the following table. +A File further has its content, of course. +But since this is not a JSON property, it is not included in the following table. The content of the File can be downloaded separately by executing the [Download File]({% link _docs_use-cases/use-case-transport-download-file.md %}) use case. -| Name | Type | Description | Remarks | -| ------------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -| id | `string` | {% include descr_id class="File" prefix="FIL" %} | | -| createdAt | `string` | {% include descr_createdAt class="File" %} | | -| createdBy | `string` | {% include descr_createdBy class="File" %} | | -| createdByDevice | `string` | {% include descr_createdByDevice class="File" %} | | -| expiresAt | `string` | {% include descr_expiresAt class="File" %} | | -| filename | `string` | The name of the file as it was on the device that uploaded it. | will be encrypted before sent to the Backbone | -| filesize | `number` | The size of the plaintext file in bytes. | will be encrypted before sent to the Backbone | -| tags | `string[]` \| `undefined` | To specify additional information. It is not possible to specify the same tag more than once. | will be encrypted before sent to the Backbone | -| mimetype | `string` | The [mimetype](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the file. | will be encrypted before sent to the Backbone | -| title | `string` | A human readable title of the file, which can be defined when uploading the File. | will be encrypted before sent to the Backbone | -| description | `string` \| `undefined` | A human readable description of the file, which can be defined when uploading the File. | will be encrypted before sent to the Backbone | -| isOwn | `boolean` | `true` if the File is owned by yourself, `false` if it is owned by someone else. | saved only locally | -| truncatedReference | `string` | A Base64 encoded string containing all information necessary for another Identity to load the File. You can use it to share the File with someone else. This property is deprecated and will be replaced by the `reference.truncated` property of the File in future. | saved only locally | -| reference | [`ObjectReference`](#objectreference) | {% include descr_reference class="File" %} | saved only locally | -| ownershipToken | `string` \| `undefined` | If the ownership of the File should be transferred to another Identity, the ownershipToken must be specified in the according [TransferFileOwnershipRequestItem](#transferfileownershiprequestitem). This property is only set for the owner of the File. | | -| ownershipIsLocked | `true` \| `undefined` | If an Identity tries to claim the ownership of the File with an incorrect `ownershipToken`, the File will be locked for further claims, which this property indicates. In order to unlock it, it is necessary to [regenerate the `ownershipToken`]({% link _docs_use-cases/use-case-transport-regenerate-file-ownership-token.md %}). This property can only be set for the owner of the File. | | +| Name | Type | Description | Remarks | +| ----------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| id | `string` | {% include descr_id class="File" prefix="FIL" %} | | +| createdAt | `string` | {% include descr_createdAt class="File" %} | | +| createdBy | `string` | {% include descr_createdBy class="File" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="File" %} | | +| expiresAt | `string` | {% include descr_expiresAt class="File" %} | | +| filename | `string` | The name of the file as it was on the device that uploaded it. | will be encrypted before sent to the Backbone | +| filesize | `number` | The size of the plaintext file in bytes. | will be encrypted before sent to the Backbone | +| tags | `string[]` \| `undefined` | To specify additional information. A tag is valid if it is contained in the [AttributeTagCollection](#attributetagcollection) for the [IdentityAttribute](#identityattribute) `value.@type` [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) and starts with the prefix `bkb:` or if it starts with the custom tag prefix `x:` or `X:`, the prefix `urn:`, the prefix `language:` followed by a valid ISO 639 language code or the prefix `mimetype:` followed by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$`. This validation is needed as an associated IdentityAttribute with IdentityFileReference as `value.@type` will have these `tags` as well if it is created for the File during [transferring its ownership to a peer]({% link _docs_integrate/exchange-files-using-attributes.md %}#transfer-the-ownership-of-a-file-to-a-peer). | will be encrypted before sent to the Backbone | +| mimetype | `string` | The [mimetype](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the file. | will be encrypted before sent to the Backbone | +| title | `string` | A human readable title of the file, which can be defined when uploading the File. | will be encrypted before sent to the Backbone | +| description | `string` \| `undefined` | A human readable description of the file, which can be defined when uploading the File. | will be encrypted before sent to the Backbone | +| isOwn | `boolean` | {% include descr_isOwn class="File" %} | saved only locally | +| reference | [`ObjectReference`](#objectreference) | {% include descr_reference class="File" %} | saved only locally | +| ownershipToken | `string` \| `undefined` | If the ownership of the File should be transferred to another Identity, the ownershipToken must be specified in the according [TransferFileOwnershipRequestItem](#transferfileownershiprequestitem). This property is only set for the owner of the File. | | +| ownershipIsLocked | `true` \| `undefined` | If an Identity tries to claim the ownership of the File with an incorrect `ownershipToken`, the File will be locked for further claims, which this property indicates. In order to unlock it, it is necessary to [regenerate the `ownershipToken`]({% link _docs_use-cases/use-case-transport-regenerate-file-ownership-token.md %}). This property can only be set for the owner of the File. | | ## Identity @@ -220,23 +243,23 @@ If you want to [delete your Identity]({% link _docs_integrate/delete-identities. 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. Since 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 `"Approved"` as `status`, per Identity. - -| Name | Type | Description | Remarks | -| ----------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -| id | `string` | {% include descr_id class="IdentityDeletionProcess" prefix="IDP" %} | | -| status | `"Approved"` \| `"Cancelled"` | The status of the IdentityDeletionProcess.
{::nomarkdown}{:/} | | -| createdAt | `string` \| `undefined` | {% include descr_createdAt class="IdentityDeletionProcess" %} | | -| createdByDevice | `string` \| `undefined` | {% include descr_createdByDevice class="IdentityDeletionProcess" %} | | -| approvedAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was approved. | | -| approvedByDevice | `string` \| `undefined` | The ID of the Device that approved 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 `"Active"` as `status`, per Identity. + +| Name | Type | Description | Remarks | +| ----------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| id | `string` | {% include descr_id class="IdentityDeletionProcess" prefix="IDP" %} | | +| status | `"Active"` \| `"Cancelled"` | The status of the IdentityDeletionProcess.
{::nomarkdown}{:/} | | +| createdAt | `string` \| `undefined` | {% include descr_createdAt class="IdentityDeletionProcess" %} | | +| createdByDevice | `string` \| `undefined` | {% include descr_createdByDevice class="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 -In addition to the types that are shared between Identities via the Backbone, there are certain types that only exist within one Identity. These types usually contain metadata about [Content types](#content-types) that should not be transferred to other Identities. They are created and updated by the [Consumption Layer]({% link _docs_explore/43-consumption-layer.md %}). +In addition to the types that are shared between Identities via the Backbone, there are certain types that only exist within one Identity. +These types usually contain metadata about [Content types](#content-types) that should not be transferred to other Identities. +They are created and updated by the [Consumption Layer]({% link _docs_explore/43-consumption-layer.md %}). Currently there are three main Local types: @@ -266,36 +289,47 @@ A LocalRequest contains the local metadata for a [Request](#request). ### LocalRequestStatus -Depending on whether it is an incoming or an outgoing Request, there can be different statuses. The following state diagram shows which status exists in both cases and when there are transitions from one state to another: +Depending on whether it is an incoming or an outgoing Request, there can be different statuses. +The following state diagram shows which status exists in both cases and when there are transitions from one state to another: ![State diagram for LocalRequest Status]( {{ '/assets/images/explore/RequestStatus%20-%20State%20Diagram.png' | relative_url }} ) Draft -: This status only exists for outgoing Requests. It means that the LocalRequest was created, but not yet sent. +: This status only exists for outgoing Requests. +It means that the LocalRequest was created, but not yet sent. Open -: In case of an outgoing Request, `Open` means that the Request was sent. The transition to `Open` happens automatically when you send the Request with a Message. +: In case of an outgoing Request, `Open` means that the Request was sent. +The transition to `Open` happens automatically when you send the Request with a Message. : In case of an incoming Request, `Open` means that the LocalRequest was received. DecisionRequired -: After the prerequisites of the Request and all of its RequestItems were checked, a decision can be made. At first, the [Decider Module]({% link _docs_explore/61-runtime.md %}#decider-module) tries to make an automatic decision. It therefore checks all LocalRequests in status `DecisionRequired`. +: After the prerequisites of the Request and all of its RequestItems were checked, a decision can be made. +At first, the [Decider Module]({% link _docs_explore/61-runtime.md %}#decider-module) tries to make an automatic decision. +It therefore checks all LocalRequests in status `DecisionRequired`. ManualDecisionRequired -: If the Decider Module cannot make a decision, it moves the LocalRequest to `ManualDecisionRequired`. When the LocalRequest is in this status, it's the User's turn to decide whether they want to accept or reject the Request. +: If the Decider Module cannot make a decision, it moves the LocalRequest to `ManualDecisionRequired`. +When the LocalRequest is in this status, it's the User's turn to decide whether they want to accept or reject the Request. Decided -: When the User or the Decider Module accepts or rejects the Request, the Response and ResponseItems are generated based on the passed parameters. This Response is saved in the `response` property of the `LocalRequest`, but not yet sent. +: When the User or the Decider Module accepts or rejects the Request, the Response and ResponseItems are generated based on the passed parameters. +This Response is saved in the `response` property of the `LocalRequest`, but not yet sent. Completed -: In case of an incoming Request, the Runtime Module listens to an Event saying that a Request moved to status `Decided`. It then checks on which way the Request was received (Message/RelationshipTemplate) and sends the Response on the corresponding way (by sending a Message or creating a Relationship). After the Response was successfully sent, it moves the LocalRequest to `Completed`. -: In case of an outgoing Request, the Runtime Module listens to the `MessageReceivedEvent` and checks the content of the sent Message for a Response. If there is one, it moves the corresponding LocalRequest to `Completed`. +: In case of an incoming Request, the Runtime Module listens to an Event saying that a Request moved to status `Decided`. +It then checks on which way the Request was received (Message/RelationshipTemplate) and sends the Response on the corresponding way (by sending a Message or creating a Relationship). +After the Response was successfully sent, it moves the LocalRequest to `Completed`. +: In case of an outgoing Request, the Runtime Module listens to the `MessageReceivedEvent` and checks the content of the sent Message for a Response. +If there is one, it moves the corresponding LocalRequest to `Completed`. Expired : When the timestamp in `expiresAt` of a Request is reached, the Request automatically moves to the status `Expired`. ### LocalRequestSource -With the information in this type you can clearly identify the Transport object the Request was sent/received in. Currently there are only two possibilities: Message and RelationshipTemplate. +With the information in this type you can clearly identify the Transport object the Request was sent/received in. +Currently there are only two possibilities: Message and RelationshipTemplate. | Name | Type | Description | | --------- | --------------------------------------- | ---------------------------------------------------------------- | @@ -314,7 +348,8 @@ When a LocalRequest is decided/received, a Local Response is generated, which co ### LocalResponseSource -With the information in this type you can clearly identify the Transport object the Response was sent/received in. Currently there are only two possibilities: Message and Relationship. +With the information in this type you can clearly identify the Transport object the Response was sent/received in. +Currently there are only two possibilities: Message and Relationship. | Name | Type | Description | | --------- | ------------------------------- | ----------------------------------------------------------------- | @@ -341,20 +376,23 @@ A LocalNotification contains the local metadata for a [Notification](#notificati Depending on whether it is an incoming or an outgoing Notification, there can be different statuses. Sent -: This is the only valid status on sender side. If a Notification is sent and, therefore, a LocalNotification is created, its status will be set to `Sent`. +: This is the only valid status on sender side. +If a Notification is sent and, therefore, a LocalNotification is created, its status will be set to `Sent`. Open : Receiving a Notification, a LocalNotification is created with status `Open`. Completed -: After receiving a Notification, its items will be processed internally. If all processes finish successfully, the status of the LocalNotification will be set to `Completed`. +: After receiving a Notification, its items will be processed internally. +If all processes finish successfully, the status of the LocalNotification will be set to `Completed`. Error : If an error occurs while processing the items of a received Notification, the status of the LocalNotification will be set to `Error`. ### LocalNotificationSource -With the information in this type you can clearly identify the Transport object the Notification was sent/received in. Currently, the only possibility for transmitting Notifications are Messages. +With the information in this type you can clearly identify the Transport object the Notification was sent/received in. +Currently, the only possibility for transmitting Notifications are Messages. | Name | Type | Description | | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | @@ -363,108 +401,176 @@ With the information in this type you can clearly identify the Transport object ## LocalAttribute -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 %}#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). +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). +To represent who the `owner` of an Attribute is and who shared or received an Attribute, there are different subtypes of LocalAttributes. +In the [Attribute introduction]({% link _docs_integrate/attribute-introduction.md %}), more details on the terminology related to LocalAttributes can be found. + +### OwnIdentityAttribute + +If an Identity [creates an IdentityAttribute for itself]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-an-identityattribute-for-yourself), it is referred to as an OwnIdentityAttribute. +The Identity can share an [IdentityAttribute](#identityattribute) of itself with another Identity 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, [AttributeForwardingDetails](#attributeforwardingdetails) associated with the OwnIdentityAttribute are created. + +| Name | Type | Description | +| ----------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | `string` | {% include descr_id class="LocalAttribute" prefix="ATT" %} | +| content | [`IdentityAttribute`](#identityattribute) | The actual Content object this LocalAttribute defines the metadata for. | +| createdAt | `string` | {% include descr_createdAt class="LocalAttribute" %} | +| succeeds | `string` \| `undefined` | The `id` of a possibly existing predecessor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. The value of its `succeeds` property is then the `id` of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no predecessor, its `succeeds` property is `undefined`. | +| succeededBy | `string` \| `undefined` | The `id` of a possibly existing successor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. Its `id` is then the value of the `succeededBy` property of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no successor, its `succeededBy` property is `undefined`. | +| wasViewedAt | `string` \| `undefined` | A timestamp indicating when the LocalAttribute was firstly viewed. | +| isDefault | `true` \| `undefined` | States whether the LocalAttribute is the default OwnIdentityAttribute for its Attribute value type. If setting default OwnIdentityAttributes is enabled, for every IdentityAttribute value type exactly one OwnIdentityAttribute will have `isDefault` set, given that at least one OwnIdentityAttribute of that value type exists. This property is only used for the UI of the App, e.g. to mark the Attribute that should be displayed firstly if multiple Attributes of the same value type exist. Thus, for a Connector it will always be `undefined`. | + +### PeerIdentityAttribute + +If an Identity shares an [OwnIdentityAttribute](#ownidentityattribute) with a peer, a PeerIdentityAttribute is created for the peer. +An [IdentityAttribute](#identityattribute) received from another Identity cannot be shared further. + +| Name | Type | Description | +| --------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | `string` | {% include descr_id class="LocalAttribute" prefix="ATT" %} | +| content | [`IdentityAttribute`](#identityattribute) | The actual Content object this LocalAttribute defines the metadata for. | +| createdAt | `string` | {% include descr_createdAt class="LocalAttribute" %} | +| succeeds | `string` \| `undefined` | The `id` of a possibly existing predecessor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. The value of its `succeeds` property is then the `id` of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no predecessor, its `succeeds` property is `undefined`. | +| succeededBy | `string` \| `undefined` | The `id` of a possibly existing successor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. Its `id` is then the value of the `succeededBy` property of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no successor, its `succeededBy` property is `undefined`. | +| wasViewedAt | `string` \| `undefined` | A timestamp indicating when the LocalAttribute was firstly viewed. | +| peer | `string` | The `address` of the [Identity](#identity) the LocalAttribute was received from. | +| sourceReference | `string` | The `id` of the [LocalRequest](#localrequest) or [LocalNotification](#localnotification) the LocalAttribute was received in. | +| deletionInfo | [`ReceivedAttributeDeletionInfo`](#receivedattributedeletioninfo) \| `undefined` | Information about whether the PeerIdentityAttribute is to be deleted or the OwnIdentityAttribute was deleted by the emitter, as well as the point in time of that deletion. | + +#### ReceivedAttributeDeletionInfo + +The ReceivedAttributeDeletionInfo holds information about the deletion status of the Attribute, as well as the point in time of that deletion. +If the Attribute's emitter requests the deletion of a shared Attribute via a [DeleteAttributeRequestItem](#deleteattributerequestitem) from the recipient, the recipient can accept or reject it. +If the recipient [accepts](#acceptdeleteattributerequestitemparameters) the DeleteAttributeRequestItem, the `deletionStatus` of the recipient's Attribute will be set to `"ToBeDeleted"` and its `deletionDate` will be set to the `deletionDate` the recipient sent with their [DeleteAttributeAcceptResponseItem](#deleteattributeacceptresponseitem). +Once the recipient's Attribute is deleted by the recipient, a [ForwardedAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#forwardedattributedeletedbypeernotificationitem) or a [PeerRelationshipAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#peerrelationshipattributedeletedbypeernotificationitem) is sent to the emitter, enabling it to update its corresponding [EmittedAttributeDeletionInfo](#emittedattributedeletioninfo). +If the emitter deletes their emitted Attribute, before the recipient deleted their Attribute, either an [OwnAttributeDeletedByOwnerNotificationItem](#ownattributedeletedbyownernotificationitem) or, in a special case, a [PeerRelationshipAttributeDeletedByPeerNotificationItem](#peerrelationshipattributedeletedbypeernotificationitem) is sent to the recipient. +If the `deletionInfo` of the recipient was undefined before, the `deletionStatus` will be set to `"DeletedByEmitter"` with the time of processing the [NotificationItem](#notificationitems) as `deletionDate`. +However, if the `deletionInfo` was defined before with `"ToBeDeleted"` as `deletionStatus`, it will remain unchanged, such that the recipient will be able to delete their Attribute as planned. + +| Name | Type | Description | +| -------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| deletionStatus | `"ToBeDeleted"` \| `"DeletedByEmitter"` | The deletion status of the Attribute. | +| deletionDate | `string` | The point in time
{::nomarkdown}{:/} | + +### OwnRelationshipAttribute + +[RelationshipAttributes](#relationshipattribute) always exist in the context of a [Relationship](#relationship). For this reason, it is not possible for an Identity to have an unshared RelationshipAttribute. -The [creation of a RelationshipAttribute]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-a-relationshipattribute) corresponds to the creation of one LocalAttribute for its `owner` and one LocalAttribute for the peer with whom the `owner` has established the Relationship in whose context the RelationshipAttribute is to exist. - -- We refer to the LocalAttribute of the `owner` as an **own shared RelationshipAttribute**. -- The peer’s LocalAttribute is referred to as a **peer shared RelationshipAttribute**. - -If a RelationshipAttribute is forwarded to a peer which is not involved in the Relationship in which the RelationshipAttribute exists, this will result in the creation of a pair of ThirdPartyRelationshipAttributes. -RelationshipAttributes can only be shared with third parties if their `confidentiality` is not set to `"private"`. - -- For the Identity which is in the Relationship in whose context the forwarded RelationshipAttribute exists, a LocalAttribute is created, whose `shareInfo.sourceAttribute` holds the `id` of the source RelationshipAttribute. It is referred to as an **emitted ThirdPartyRelationshipAttribute**. The property `shareInfo.thirdPartyAddress` stores the `address` of the peer to which the Relationship exists, in whose context the source RelationshipAttribute was created. -- For the Identity which received the forwarded RelationshipAttribute, a so-called **received ThirdPartyRelationshipAttribute** is created. It is a LocalAttribute whose property `shareInfo.thirdPartyAddress` is set equally to the one of the corresponding emitted ThirdPartyRelationshipAttribute. However, the property `shareInfo.sourceAttribute` is undefined, since the Identity doesn't have the source RelationshipAttribute. - -In the [Attribute introduction]({% link _docs_integrate/attribute-introduction.md %}) more details on the terminology related to LocalAttributes can be found. - -| Name | Type | Description | -| ------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| id | `string` | {% include descr_id class="LocalAttribute" prefix="ATT" %} | -| parentId | `string` \| `undefined` | If the Attribute referenced by this LocalAttribute is a component of a [complex Attribute]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes), the `parentId` property is set to the `id` of the complex Attribute. Example: if a LocalAttribute is created with the content `StreetAddress`, for each property of the `StreetAddress` an additional LocalAttribute is created. And each of these will have `parentId` set to the `id` of the LocalAttribute for the `StreetAddress`. | -| createdAt | `string` | {% include descr_createdAt class="LocalAttribute" %} | -| content | [`IdentityAttribute`](#identityattribute) \| [`RelationshipAttribute`](#relationshipattribute) | The actual Content object this LocalAttribute defines the metadata for. | -| succeeds | `string` \| `undefined` | The `id` of a possibly existing predecessor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. The value of its `succeeds` property is then the `id` of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no predecessor, its `succeeds` property is `undefined`. | -| succeededBy | `string` \| `undefined` | The `id` of a possibly existing successor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. Its `id` is then the value of the `succeededBy` property of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no successor, its `succeededBy` property is `undefined`. | -| shareInfo | [`LocalAttributeShareInfo`](#localattributeshareinfo) \| `undefined` | Information about the peer this LocalAttribute was received from/shared with, as well as via which LocalRequest it was received/sent. If the LocalAttribute refers to a RepositoryAttribute, this property is `undefined`. | -| deletionInfo | [`LocalAttributeDeletionInfo`](#localattributedeletioninfo) \| `undefined` | Information about whether the counterpart of a shared Attribute is to be deleted or was deleted by the peer of the Relationship, as well as the point in time of that deletion. | -| isDefault | `true` \| `undefined` | States whether the LocalAttribute is the default RepositoryAttribute for its Attribute value type. If setting default RepositoryAttributes is enabled, for every IdentityAttribute value type exactly one RepositoryAttribute will have `isDefault` set, given that at least one RepositoryAttribute of that value type exists. This property is only used for the UI of the App, e.g. to mark the Attribute that should be displayed firstly if multiple Attributes of the same value type exist. Thus, for a Connector it will always be `undefined`. | -| wasViewedAt | `string` \| `undefined` | A timestamp indicating when the LocalAttribute was firstly viewed. | - -### LocalAttributeShareInfo - -The LocalAttributeShareInfo helps to keep track of how the LocalAttribute was received/sent, from whom it was received/who sent it, as well as which LocalAttribute it was copied from. For example, this enables us to track back who we shared a certain IdentityAttribute with, so we are able to notify each of those peers when changing it. The Attribute can be either transmitted via Request or Notification. Hence, only one of `requestReference` and `notificationReference` can be set. - -| Name | Type | Description | -| --------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| peer | `string` | The `address` of the [Identity](#identity) the LocalAttribute was received from/shared with. | -| requestReference | `string` \| `undefined` | The `id` of the [LocalRequest](#localrequest) the LocalAttribute was received in/sent with. If this is set, `notificationReference` must be undefined. | -| notificationReference | `string` \| `undefined` | The `id` of the [LocalNotification](#localnotification) the LocalAttribute was received in/sent with. If this is set, `requestReference` must be undefined. | -| sourceAttribute | `string` \| `undefined` | If the [LocalAttribute](#localattribute) is an own shared IdentityAttribute, then this property contains the `id` of the RepositoryAttribute it was copied from. Also, if a RelationshipAttribute is shared with a third party, i.e. in the context of a Relationship that is different to the one the RelationshipAttribute was initially created in, this ThirdPartyRelationshipAttribute will link to the source RelationshipAttribute. Note that `sourceAttribute` is only defined for the peer who also has the Attribute this property links to. Regarding IdentityAttributes this is the owner. For ThirdPartyRelationshipAttributes it is the Identity who is in the Relationship the source RelationshipAttribute is copied from and who emitted the ThirdPartyRelationshipAttribute to the peer. | -| thirdPartyAddress | `string` \| `undefined` | If the [LocalAttribute](#localattribute) is a ThirdPartyRelationshipAttribute, this property will contain the `address` of the [Identity](#identity) with whom the emitter has the Relationship in which context the source RelationshipAttribute exists. | - -### LocalAttributeDeletionInfo - -The LocalAttributeDeletionInfo holds information about the deletion status of the counterpart of a shared Attribute, as well as the point in time of that deletion. -If the Attribute's `owner` requests the deletion of a shared Attribute via a [DeleteAttributeRequestItem](#deleteattributerequestitem) from the peer, their own shared Attribute will get `"DeletionRequestSent"` as `deletionStatus` and the time of sending the Request as `deletionDate`. -Should the peer reject the DeleteAttributeRequestItem, the own shared Attribute of the `owner` is given `"DeletionRequestRejected"` as `deletionStatus`. -The `deletionDate` then will be set to the time of receiving the [RejectResponseItem](#rejectresponseitem). -If they accept, however, using the [AcceptDeleteAttributeRequestItemParameters](#acceptdeleteattributerequestitemparameters), the `deletionStatus` of the peer shared Attribute of the peer will be set to `"ToBeDeleted"` and its `deletionDate` will be set to the `deletionDate` the peer sent in their Response. -Accordingly, the `deletionStatus` of the own shared Attribute of the owner will move to `"ToBeDeletedByPeer"` with the same `deletionDate`. -Once the peer shared Attribute is deleted by the peer, a [PeerSharedAttributeDeletedByPeerNotificationItem](#peersharedattributedeletedbypeernotificationitem) is sent to the owner, where the `deletionStatus` of the own shared Attribute is set to `"DeletedByPeer"` with the current time stamp as `deletionDate`. -Likewise, if the owner deletes their own shared Attribute, before the peer deleted their corresponding peer shared Attribute, an [OwnSharedAttributeDeletedByOwnerNotificationItem](#ownsharedattributedeletedbyownernotificationitem) is sent to the peer. -If the `deletionInfo` of the peer was undefined before, the `deletionStatus` will be set to `"DeletedByOwner"` with the current time stamp as `deletionDate`. -However, if the `deletionInfo` was defined before with `"ToBeDeleted"` as `deletionStatus`, it will remain unchanged, such that the peer will be able to delete their peer shared Attribute as planned. -This will be the case, if the peer already accepted the DeleteAttributeRequestItem for this particular Attribute. - -| Name | Type | Description | -| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| deletionStatus | `"DeletionRequestSent"` \| `"DeletionRequestRejected"` \| `"ToBeDeleted"` \| `"ToBeDeletedByPeer"` \| `"DeletedByOwner"` \| `"DeletedByPeer"` | The deletion status of the peer's counterpart of the shared Attribute. For own shared Attributes it may only be set to `"DeletionRequestSent"`, `"DeletionRequestRejected"`, `"ToBeDeletedByPeer"` or `"DeletedByPeer"`, whereas for peer shared Attributes only the values `"ToBeDeleted"` and `"DeletedByOwner"` are allowed. | -| deletionDate | `string` | The point in time
{::nomarkdown}{:/} | - -## LocalAttributeListener - -A LocalAttributeListener is created when you accept an incoming Request with a [`RegisterAttributeListenerRequestItem`](#registerattributelistenerrequestitem). It is used to keep track of which Attribute Listeners currently exist and what they are listening for. - -| Name | Type | Description | -| ----- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| id | `string` | {% include descr_id class="LocalAttributeListener" prefix="ATL" %} | -| query | [`IdentityAttributeQuery`](#identityattributequery) \| [`ThirdPartyRelationshipAttributeQuery`](#thirdpartyrelationshipattributequery) | The query the Attribute that is listened to must match. Note that you cannot send a [`RelationshipAttributeQuery`](#relationshipattributequery) here, because it doesn't make sense: by definition, both parties know about a RelationshipAttribute right from the beginning, because one party requests its creation, and the other one accepts it. | -| peer | `string` | The address of the peer that requested the Attribute Listener. | +The [creation of a RelationshipAttribute]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-a-relationshipattribute) corresponds to the creation of an OwnRelationshipAttribute for its `owner` and a [PeerRelationshipAttribute](#peerrelationshipattribute) for the peer with whom the `owner` has established the Relationship in whose context the RelationshipAttribute is to exist. + +| Name | Type | Description | +| --------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | `string` | {% include descr_id class="LocalAttribute" prefix="ATT" %} | +| content | [`RelationshipAttribute`](#relationshipattribute) | The actual Content object this LocalAttribute defines the metadata for. | +| createdAt | `string` | {% include descr_createdAt class="LocalAttribute" %} | +| succeeds | `string` \| `undefined` | The `id` of a possibly existing predecessor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. The value of its `succeeds` property is then the `id` of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no predecessor, its `succeeds` property is `undefined`. | +| succeededBy | `string` \| `undefined` | The `id` of a possibly existing successor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. Its `id` is then the value of the `succeededBy` property of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no successor, its `succeededBy` property is `undefined`. | +| wasViewedAt | `string` \| `undefined` | A timestamp indicating when the LocalAttribute was firstly viewed. | +| peer | `string` | The `address` of the [Identity](#identity) the LocalAttribute was shared with. | +| sourceReference | `string` | The `id` of the [LocalRequest](#localrequest) or [LocalNotification](#localnotification) the LocalAttribute was sent with. | +| deletionInfo | [`EmittedAttributeDeletionInfo`](#emittedattributedeletioninfo) \| `undefined` | Information about whether the [PeerRelationshipAttribute](#peerrelationshipattribute) of the peer of the Relationship is to be deleted or was deleted by the peer, as well as the point in time of that deletion. | + +#### EmittedAttributeDeletionInfo + +The EmittedAttributeDeletionInfo holds information about the deletion status of the Attribute, as well as the point in time of that deletion. +If the Attribute's emitter requests the deletion of a shared Attribute via a [DeleteAttributeRequestItem](#deleteattributerequestitem) from the recipient, the emitted Attribute will get `"DeletionRequestSent"` as `deletionStatus` and the time of sending the Request as `deletionDate`. +If the recipient rejects the DeleteAttributeRequestItem, the emitted Attribute will get `"DeletionRequestRejected"` as `deletionStatus` and the time of receiving the [RejectResponseItem](#rejectresponseitem) as `deletionDate`. +If the recipient [accepts](#acceptdeleteattributerequestitemparameters), however, the `deletionStatus` of the emitter's Attribute will change to `"ToBeDeletedByRecipient"` and the `deletionDate` will be the same as the `deletionDate` of the received [DeleteAttributeAcceptResponseItem](#deleteattributeacceptresponseitem). +Either a [ForwardedAttributeDeletedByPeerNotificationItem](#forwardedattributedeletedbypeernotificationitem) or a [PeerRelationshipAttributeDeletedByPeerNotificationItem](#peerrelationshipattributedeletedbypeernotificationitem) is sent to the emitter, once the recipient's Attribute is deleted. +Finally, the `deletionStatus` of the emitted Attribute is set to `"DeletedByRecipient"` with the time of processing the [NotificationItem](#notificationitems) as `deletionDate`. + +| Name | Type | Description | +| -------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| deletionStatus | `"DeletionRequestSent"` \| `"DeletionRequestRejected"` \| `"ToBeDeletedByRecipient"` \| `"DeletedByRecipient"` | The deletion status of the Attribute. | +| deletionDate | `string` | The point in time
{::nomarkdown}{:/} | + +### PeerRelationshipAttribute + +[RelationshipAttributes](#relationshipattribute) always exist in the context of a [Relationship](#relationship). +For this reason, it is not possible for an Identity to have an unshared RelationshipAttribute. +The [creation of a RelationshipAttribute]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-a-relationshipattribute) corresponds to the creation of an [OwnRelationshipAttribute](#ownrelationshipattribute) for its `owner` and a PeerRelationshipAttribute for the peer with whom the `owner` has established the Relationship in whose context the RelationshipAttribute is to exist. + +| Name | Type | Description | +| --------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | `string` | {% include descr_id class="LocalAttribute" prefix="ATT" %} | +| content | [`RelationshipAttribute`](#relationshipattribute) | The actual Content object this LocalAttribute defines the metadata for. | +| createdAt | `string` | {% include descr_createdAt class="LocalAttribute" %} | +| succeeds | `string` \| `undefined` | The `id` of a possibly existing predecessor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. The value of its `succeeds` property is then the `id` of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no predecessor, its `succeeds` property is `undefined`. | +| succeededBy | `string` \| `undefined` | The `id` of a possibly existing successor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. Its `id` is then the value of the `succeededBy` property of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no successor, its `succeededBy` property is `undefined`. | +| wasViewedAt | `string` \| `undefined` | A timestamp indicating when the LocalAttribute was firstly viewed. | +| peer | `string` | The `address` of the [Identity](#identity) the LocalAttribute was received from. | +| sourceReference | `string` | The `id` of the [LocalRequest](#localrequest) or [LocalNotification](#localnotification) the LocalAttribute was received in. | +| deletionInfo | [`ReceivedAttributeDeletionInfo`](#receivedattributedeletioninfo) \| `undefined` | Information about whether the PeerRelationshipAttribute is to be deleted or the OwnRelationshipAttribute is deleted by the emitter, as well as the point in time of that deletion. | + +### ThirdPartyRelationshipAttribute + +A [RelationshipAttribute](#relationshipattribute) can be forwarded to a peer which is not involved in the [Relationship](#relationship) in which the RelationshipAttribute exists if its `confidentiality` is not set to `"private"`. +For the Identity which forwards its [OwnRelationshipAttribute](#ownrelationshipattribute) or [PeerRelationshipAttribute](#peerrelationshipattribute) to a peer, [AttributeForwardingDetails](#attributeforwardingdetails) associated with the source RelationshipAttribute are created. +A ThirdPartyRelationshipAttribute is created for the Identity which received the forwarded RelationshipAttribute. + +| Name | Type | Description | +| -------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | `string` | {% include descr_id class="LocalAttribute" prefix="ATT" %} | +| content | [`RelationshipAttribute`](#relationshipattribute) | The actual Content object this LocalAttribute defines the metadata for. | +| createdAt | `string` | {% include descr_createdAt class="LocalAttribute" %} | +| succeeds | `string` \| `undefined` | The `id` of a possibly existing predecessor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. The value of its `succeeds` property is then the `id` of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no predecessor, its `succeeds` property is `undefined`. | +| succeededBy | `string` \| `undefined` | The `id` of a possibly existing successor of a LocalAttribute. It is possible to update the [Attribute](#attributes) contained in the `content` property of a LocalAttribute using [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). In this case, a new LocalAttribute, the so-called successor, is created. Its `id` is then the value of the `succeededBy` property of the old LocalAttribute, the so-called predecessor. If a LocalAttribute has no successor, its `succeededBy` property is `undefined`. | +| wasViewedAt | `string` \| `undefined` | A timestamp indicating when the LocalAttribute was firstly viewed. | +| peer | `string` | The `address` of the [Identity](#identity) the LocalAttribute was received from. | +| sourceReference | `string` | The `id` of the [LocalRequest](#localrequest) or [LocalNotification](#localnotification) the LocalAttribute was received in. | +| initialAttributePeer | `string` | This property contains the `address` of the [Identity](#identity) with whom the emitter has the Relationship in which context the source RelationshipAttribute exists. | +| deletionInfo | [`ReceivedAttributeDeletionInfo`](#receivedattributedeletioninfo) \| `undefined` | Information about whether the ThirdPartyRelationshipAttribute is to be deleted or the source RelationshipAttribute is deleted by the emitter, as well as the point in time of that deletion. | + +## AttributeForwardingDetails + +If an Identity has shared an [OwnIdentityAttribute](#ownidentityattribute) with a peer or forwarded an [OwnRelationshipAttribute](#ownrelationshipattribute) or a [PeerRelationshipAttribute](#peerrelationshipattribute) to a peer which is not involved in the Relationship in which the RelationshipAttribute exists, AttributeForwardingDetails are created. +These help track which peer a [LocalAttribute](#localattribute) was shared with and when it was shared. +This also makes it possible to notify that peer if the LocalAttribute changes. + +| Name | Type | Description | +| --------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| peer | `string` | The `address` of the [Identity](#identity) the LocalAttribute was shared with. | +| sourceReference | `string` | The `id` of the [LocalRequest](#localrequest) or [LocalNotification](#localnotification) the LocalAttribute was sent with. | +| sharedAt | `string` | A timestamp that describes when the corresponding Attribute was shared. | +| deletionInfo | [`EmittedAttributeDeletionInfo`](#emittedattributedeletioninfo) \| `undefined` | Information about whether the recipient's Attribute is to be deleted or was deleted by the recipient, as well as the point in time of that deletion. | ## AttributeTagCollection The AttributeTagCollection is defined by the Backbone and specifies which `tags` are allowed for which [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) `value.@type`. It can be queried from the Backbone by using the [Get AttributeTagCollection]({% link _docs_use-cases/use-case-consumption-get-attributetagcollection.md %}) use case. -Apart from the Backbone-defined `tags`, only `tags` starting with the custom tag prefix `x+%+` or `X+%+` will be allowed to use when working with IdentityAttributes. +Apart from the Backbone-defined `tags`, which must start with the prefix `bkb:`, only `tags` starting with the custom tag prefix `x:` or `X:`, the prefix `urn:`, the prefix `language:` followed by a valid ISO 639 language code or the prefix `mimetype:` followed by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$` are allowed to use when working with IdentityAttributes. -| Name | Type | Description | -| -------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| supportedLanguages | `string[]` | An array of all supported languages for which a translation must be specified within the `displayNames` mapping of any [AttributeTag](#attributetag) within the `tagsForAttributeValueTypes` mapping. | -| tagsForAttributeValueTypes | `Record>` | A mapping of certain [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) `value.@types` and allowed `tags`. These are represented by a mapping of their names and their specifications as [AttributeTags](#attributetag). If an IdentityAttribute `value.@type` does not occur in the mapping, IdentityAttributes of this `value.@type` will only be allowed to have `tags` that start with `x+%+` or `X+%+`. | +| Name | Type | Description | +| -------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| supportedLanguages | `string[]` | An array of all supported languages for which a translation must be specified within the `displayNames` mapping of any [AttributeTag](#attributetag) within the `tagsForAttributeValueTypes` mapping. | +| tagsForAttributeValueTypes | `Record>` | A mapping of certain [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) `value.@types` and allowed `tags`. These are represented by a mapping of their names and their specifications as [AttributeTags](#attributetag). If an IdentityAttribute `value.@type` does not occur in the mapping, IdentityAttributes of this `value.@type` will only be allowed to have `tags` that start with `x:` or `X:`, `urn:`, `language:` followed by a valid ISO 639 language code or `mimetype:` followed by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$`, and not with `bkb:`. | ### AttributeTag AttributeTags occur within the `tagsForAttributeValueTypes` mapping of the [AttributeTagCollection](#attributetagcollection). -| Name | Type | Description | -| ------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| displayNames | `Record` | A mapping of all `supportedLanguages` of the associated [AttributeTagCollection](#attributetagcollection) and the corresponding display names of the AttributeTag. | -| children | `Record` \| `undefined` | A mapping of the names of sub-AttributeTags of the AttributeTag and their specifications. If an AttributeTag has children, the allowed [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) `tags` will be the concatenations of the name of the AttributeTag itself with the name of any child separated by the tag separator `+%+`. | +| Name | Type | Description | +| ------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| displayNames | `Record` | A mapping of all `supportedLanguages` of the associated [AttributeTagCollection](#attributetagcollection) and the corresponding display names of the AttributeTag. | +| children | `Record` \| `undefined` | A mapping of the names of sub-AttributeTags of the AttributeTag and their specifications. If an AttributeTag has children, the allowed Backbone-defined [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) `tags` will be the concatenation of the prefix `bkb:` with any concatenation of the name of the AttributeTag itself with the name of any child separated by the tag separator `:`. | # Content Types -Content Types can be seen as a data contract between Identities. The medium through which this data is exchanged are the [Transport types](#transport-types) (e.g. Messages, Tokens, ...). This chapter shows all the Content types and describes their intended usage. +Content Types can be seen as a data contract between Identities. +The medium through which this data is exchanged are the [Transport types](#transport-types) (e.g. Messages, Tokens, ...). +This chapter shows all the Content types and describes their intended usage. ## Request -A Request allows you to ask another Identity to do something. What this "something" is depends on which of the so called [RequestItems](#requestitems) were added to the Request (e.g. [`CreateAttributeRequestItem`](}#createattributerequestitem), [`ReadAttributeRequestItem`](#readattributerequestitem), ...). The Request is then sent to the peer via Message or RelationshipTemplate. The peer can then review the Request and decide whether they want to accept or reject it. And if they accept it, they can even choose which of the Items they want to accept. You can also put multiple Items into a [RequestItemGroup](#requestitemgroup) in order to display them visually as a unit. +A Request allows you to ask another Identity to do something. +What this "something" is depends on which of the so called [RequestItems](#requestitems) were added to the Request (e.g. [`CreateAttributeRequestItem`](#createattributerequestitem), [`ReadAttributeRequestItem`](#readattributerequestitem), ...). +The Request is then sent to the peer via Message or RelationshipTemplate. +The peer can then review the Request and decide whether they want to accept or reject it. +And if they accept it, they can even choose which of the Items they want to accept. +You can also put multiple Items into a [RequestItemGroup](#requestitemgroup) in order to display them visually as a unit. | Name | Type | Description | | ----------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | @@ -478,78 +584,76 @@ A Request allows you to ask another Identity to do something. What this "somethi ### RequestItems -RequestItems can be sent inside of a [Request](#request) and specify what should be done when the [Request is accepted]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}). More information on how to use the individual [types of RequestItems]({% link _docs_integrate/request-and-response-introduction.md %}#types-of-requestitems) for your purposes can be found in the [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}). If you are interested in a brief overview of the various operations which can be performed with Attributes, take a look at our [Attribute management options]({% link _docs_integrate/attribute-introduction.md %}#attribute-management-options). +RequestItems can be sent inside of a [Request](#request) and specify what should be done when the [Request is accepted]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}). +More information on how to use the individual [types of RequestItems]({% link _docs_integrate/request-and-response-introduction.md %}#types-of-requestitems) for your purposes can be found in the [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}). +If you are interested in a brief overview of the various operations which can be performed with Attributes, take a look at our [Attribute management options]({% link _docs_integrate/attribute-introduction.md %}#attribute-management-options). #### AuthenticationRequestItem For more information you should check out the section [AuthenticationRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#authenticationrequestitem). -| Name | Type | Description | -| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| @type | `"AuthenticationRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| title | `string` \| `undefined` | An optional, human readable title for the RequestItem. | -| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | -| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | -| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | -| requireManualDecision | `boolean` \| `undefined` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step, the requireManualDecision property can be set to true. | +| Name | Type | Description | +| -------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| @type | `"AuthenticationRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| title | `string` | A human readable title for the AuthenticationRequestItem. This title should contain the topic of the authentication. | +| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | +| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | +| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | #### ConsentRequestItem -For more information you should check out the section [ConsentRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#consentrequestitem). Furthermore, all details on how to use the ConsentRequestItem and examples of use cases for it can be found in the [Request one-time consent of peer]({% link _docs_integrate/request-one-time-consent-of-peer.md %}) guide. +For more information you should check out the section [ConsentRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#consentrequestitem). +Furthermore, all details on how to use the ConsentRequestItem and examples of use cases for it can be found in the [Request one-time consent of peer]({% link _docs_integrate/request-one-time-consent-of-peer.md %}) guide. -| Name | Type | Description | -| --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| @type | `"ConsentRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| consent | `string` | The textual consent the user needs to give. This is different to the title and description of the RequestItem, as the consent would be the actual statement the user agrees to. | -| link | `string` \| `undefined` | A valid URL linking to a website which contains more information, like the EULA or privacy terms. | -| linkDisplayText | `string` \| `undefined` | If a link is specified, a display text, which is displayed in the App instead of the link's URL, can be specified for this link. | -| title | `string` \| `undefined` | An optional, human readable title for the RequestItem. | -| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | -| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | -| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | -| requireManualDecision | `boolean` \| `undefined` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step, the requireManualDecision property can be set to true. | +| Name | Type | Description | +| ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| @type | `"ConsentRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| consent | `string` | The textual consent the user needs to give. This is different to the description of the RequestItem, as the consent would be the actual statement the user agrees to, the description only provides a help text. | +| link | `string` \| `undefined` | A valid URL linking to a website which contains more information, like the EULA or privacy terms. | +| linkDisplayText | `string` \| `undefined` | If a link is specified, a display text, which is displayed in the App instead of the link's URL, can be specified for this link. | +| requiresInteraction | `boolean` \| `undefined` | If set to `true`, an explicit action to grant the consent is required, ensuring that it is given intentionally. In case of the enmeshed App, this results in the checkbox associated with the ConsentRequestItem not being preselected and requiring the App user to explicitly tick it. This may be necessary for legal reasons, for example, when the consent involves the processing of sensitive data. | +| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | +| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | +| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | #### CreateAttributeRequestItem -For more information you should check out the section [CreateAttributeRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#createattributerequestitem). Furthermore, all details on how to use the CreateAttributeRequestItem and examples of use cases for it can be found in the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. +For more information you should check out the section [CreateAttributeRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#createattributerequestitem). +Furthermore, all details on how to use the CreateAttributeRequestItem and examples of use cases for it can be found in the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. -| Name | Type | Description | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| @type | `"CreateAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| attribute | [`IdentityAttribute`]({% link _docs_integrate/data-model-overview.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to create for the peer within the Identity of the peer. | -| title | `string` \| `undefined` | An optional, human readable title for the RequestItem. | -| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | -| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | -| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | -| requireManualDecision | `boolean` \| `undefined` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step, the requireManualDecision property can be set to true. | +| Name | Type | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| @type | `"CreateAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| attribute | [`IdentityAttribute`]({% link _docs_integrate/data-model-overview.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to create for the peer within the Identity of the peer. | +| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | +| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | +| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | #### DeleteAttributeRequestItem -For more information you should check out the section [DeleteAttributeRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#deleteattributerequestitem). Furthermore, all details on how to use the DeleteAttributeRequestItem can be found in the [Delete Attributes]({% link _docs_integrate/delete-attributes.md %}) guide. +For more information you should check out the section [DeleteAttributeRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#deleteattributerequestitem). +Furthermore, all details on how to use the DeleteAttributeRequestItem can be found in the [Delete Attributes]({% link _docs_integrate/delete-attributes.md %}) guide. -| Name | Type | Description | -| --------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| @type | `"DeleteAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| attributeId | `string` | The `id` of the own shared Attribute you wish for the peer to delete. This will match the `id` of the corresponding peer shared Attribute at the peer's side. | -| title | `string` \| `undefined` | An optional, human readable title for the RequestItem. | -| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | -| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | -| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | -| requireManualDecision | `boolean` \| `undefined` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step, the requireManualDecision property can be set to true. | +| Name | Type | Description | +| -------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| @type | `"DeleteAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| attributeId | `string` | The `id` of the emitted Attribute you wish for the peer to delete. This will match the `id` of the corresponding peer Attribute at the peer's side. | +| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | +| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | +| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | #### FormFieldRequestItem For more information you should check out the section [FormFieldRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#formfieldrequestitem) or the [Form Fields Within Requests]({% link _docs_integrate/form-fields-within-requests.md %}) scenario documentation. -| Name | Type | Description | -| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| @type | `"FormFieldRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| settings | [`BooleanFormFieldSettings`](#booleanformfieldsettings) \| [`DateFormFieldSettings`](#dateformfieldsettings) \| [`DoubleFormFieldSettings`](#doubleformfieldsettings) \| [`IntegerFormFieldSettings`](#integerformfieldsettings) \| [`RatingFormFieldSettings`](#ratingformfieldsettings) \| [`SelectionFormFieldSettings`](#selectionformfieldsettings) \| [`StringFormFieldSettings`](#stringformfieldsettings) | The settings that determine the kind of form field. | -| title | `string` | A human readable title for the RequestItem. | -| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | -| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | -| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | -| requireManualDecision | `boolean` \| `undefined` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step, the requireManualDecision property can be set to true. | +| Name | Type | Description | +| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| @type | `"FormFieldRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| settings | [`BooleanFormFieldSettings`](#booleanformfieldsettings) \| [`DateFormFieldSettings`](#dateformfieldsettings) \| [`DoubleFormFieldSettings`](#doubleformfieldsettings) \| [`IntegerFormFieldSettings`](#integerformfieldsettings) \| [`RatingFormFieldSettings`](#ratingformfieldsettings) \| [`SelectionFormFieldSettings`](#selectionformfieldsettings) \| [`StringFormFieldSettings`](#stringformfieldsettings) | The settings that determine the kind of form field. | +| title | `string` | A human readable title for the RequestItem. | +| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | +| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | +| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | ##### BooleanFormFieldSettings @@ -622,93 +726,61 @@ If StringFormFieldSettings are used as `settings` of a [FormFieldRequestItem](#f | `min` | `number` \| `undefined` | A non-negative integer that serves as the lower limit for the length of the requested string. | | `max` | `number` \| `undefined` | A non-negative integer that serves as the upper limit for the length of the requested string. | -#### FreeTextRequestItem - -For more information you should check out the section [FreeTextRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#freetextrequestitem). - -| Name | Type | Description | -| --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| @type | `"FreeTextRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| freeText | `string` | The free text you want to send to the peer. | -| title | `string` \| `undefined` | An optional, human readable title for the RequestItem. | -| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | -| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | -| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | -| requireManualDecision | `boolean` \| `undefined` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step, the requireManualDecision property can be set to true. | - #### ProposeAttributeRequestItem -For more information you should check out the section [ProposeAttributeRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#proposeattributerequestitem). Furthermore, all details on how to use the ProposeAttributeRequestItem and examples of use cases for it can be found in the [Propose Attributes to peer]({% link _docs_integrate/propose-attributes-to-peer.md %}) guide. +For more information you should check out the section [ProposeAttributeRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#proposeattributerequestitem). +Furthermore, all details on how to use the ProposeAttributeRequestItem and examples of use cases for it can be found in the [Propose Attributes to peer]({% link _docs_integrate/propose-attributes-to-peer.md %}) guide. -| Name | Type | Description | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| @type | `"ProposeAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| attribute | [`IdentityAttribute`]({% link _docs_integrate/data-model-overview.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute. | -| query | [`IdentityAttributeQuery`](#identityattributequery) \| [`RelationshipAttributeQuery`](#relationshipattributequery) \| [`IQLQuery`](#iqlquery) | The structured query of the Attribute the sender would like to receive. | -| title | `string` \| `undefined` | An optional, human readable title for the RequestItem. | -| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | -| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | -| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | -| requireManualDecision | `boolean` \| `undefined` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step, the requireManualDecision property can be set to true. | +| Name | Type | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| @type | `"ProposeAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| attribute | [`IdentityAttribute`]({% link _docs_integrate/data-model-overview.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute. | +| query | [`IdentityAttributeQuery`](#identityattributequery) \| [`RelationshipAttributeQuery`](#relationshipattributequery) \| [`IQLQuery`](#iqlquery) | The structured query of the Attribute the sender would like to receive. | +| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | +| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | +| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | #### ReadAttributeRequestItem -For more information you should check out the section [ReadAttributeRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#readattributerequestitem). Furthermore, all details on how to use the ReadAttributeRequestItem and examples of use cases for it can be found in the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide. - -| Name | Type | Description | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| @type | `"ReadAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| query | [`IdentityAttributeQuery`](#identityattributequery) \| [`RelationshipAttributeQuery`](#relationshipattributequery) \| [`ThirdPartyRelationshipAttributeQuery`](#thirdpartyrelationshipattributequery) \| [`IQLQuery`](#iqlquery) | The structured query of the Attribute the sender would like to receive. | -| title | `string` \| `undefined` | An optional, human readable title for the RequestItem. | -| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | -| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | -| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | -| requireManualDecision | `boolean` \| `undefined` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step, the requireManualDecision property can be set to true. | - -#### RegisterAttributeListenerRequestItem +For more information you should check out the section [ReadAttributeRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#readattributerequestitem). +Furthermore, all details on how to use the ReadAttributeRequestItem and examples of use cases for it can be found in the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide. -For more information you should check out the section [RegisterAttributeListenerRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#registerattributelistenerrequestitem). - -| Name | Type | Description | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| @type | `"RegisterAttributeListenerRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| query | [`IdentityAttributeQuery`]({% link _docs_integrate/data-model-overview.md %}#identityattributequery) \| [`ThirdPartyRelationshipAttributeQuery`]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) | The structured query of the Attribute the sender would like to query. | -| title | `string` \| `undefined` | An optional, human readable title for the RequestItem. | -| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | -| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | -| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | -| requireManualDecision | `boolean` \| `undefined` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step, the requireManualDecision property can be set to true. | +| Name | Type | Description | +| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| @type | `"ReadAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| query | [`IdentityAttributeQuery`](#identityattributequery) \| [`RelationshipAttributeQuery`](#relationshipattributequery) \| [`ThirdPartyRelationshipAttributeQuery`](#thirdpartyrelationshipattributequery) \| [`IQLQuery`](#iqlquery) | The structured query of the Attribute the sender would like to receive. | +| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | +| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | +| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | #### ShareAttributeRequestItem -For more information you should check out the section [ShareAttributeRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#shareattributerequestitem). Furthermore, all details on how to use the ShareAttributeRequestItem and examples of use cases for it can be found in the [Share Attributes with peer]({% link _docs_integrate/share-attributes-with-peer.md %}) guide. +For more information you should check out the section [ShareAttributeRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#shareattributerequestitem). +Furthermore, all details on how to use the ShareAttributeRequestItem and examples of use cases for it can be found in the [Share Attributes with peer]({% link _docs_integrate/share-attributes-with-peer.md %}) guide. -| Name | Type | Description | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| @type | `"ShareAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| attribute | [`IdentityAttribute`]({% link _docs_integrate/data-model-overview.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) | The [Attribute](#attributes) to be shared can be an IdentityAttribute or a RelationshipAttribute. It is therefore not a [LocalAttribute](#localattribute) itself, but its `content`. An overview of the possible kinds of Attributes that can be shared is provided by the table of the [combinations and usage scenarios of the ShareAttributeRequestItem]({% link _docs_integrate/share-attributes-with-peer.md %}#combinations-and-usage-scenarios-of-shareattributerequestitem). | -| sourceAttributeId | `string` | The `id` of the [LocalAttribute](#localattribute) which is the source of the shared [Attribute](#attributes). This will be used later to reference the `sourceAttribute` from its shared copy. | -| thirdPartyAddress | `string` \| `undefined` | If the Attribute to be shared is a [RelationshipAttribute](#relationshipattribute), this property must contain the address of the `peer` with whom the sender of the Attribute has the [Relationship](#relationship) in which context the RelationshipAttribute exists. | -| title | `string` \| `undefined` | An optional, human readable title for the RequestItem. | -| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | -| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | -| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | -| requireManualDecision | `boolean` \| `undefined` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step, the requireManualDecision property can be set to true. | +| Name | Type | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| @type | `"ShareAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| attribute | [`IdentityAttribute`]({% link _docs_integrate/data-model-overview.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) | The [Attribute](#attributes) to be shared can be an IdentityAttribute or a RelationshipAttribute. It is therefore not a [LocalAttribute](#localattribute) itself, but its `content`. An overview of the possible kinds of Attributes that can be shared is provided by the table of the [combinations and usage scenarios of the ShareAttributeRequestItem]({% link _docs_integrate/share-attributes-with-peer.md %}#combinations-and-usage-scenarios-of-shareattributerequestitem). | +| attributeId | `string` | The `id` of the [LocalAttribute](#localattribute) which is the source of the shared [Attribute](#attributes). If the recipient [accepts]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) the ShareAttributeRequestItem, a LocalAttribute with the same `id` will be created for them. | +| initialAttributePeer | `string` \| `undefined` | If the Attribute to be shared is a [RelationshipAttribute](#relationshipattribute), this property must contain the address of the `peer` with whom the sender of the Attribute has the [Relationship](#relationship) in which context the RelationshipAttribute exists. | +| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | +| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | +| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | #### TransferFileOwnershipRequestItem -For more information you should check out the section [TransferFileOwnershipRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#transferfileownershiprequestitem). Furthermore, all details on how to use the TransferFileOwnershipRequestItem and examples of use cases for it can be found in the [Exchange Files using Attributes]({% link _docs_integrate/exchange-files-using-attributes.md %}#transfer-the-ownership-of-a-file-to-a-peer) guide. +For more information you should check out the section [TransferFileOwnershipRequestItem of the Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}#transferfileownershiprequestitem). +Furthermore, all details on how to use the TransferFileOwnershipRequestItem and examples of use cases for it can be found in the [Exchange Files using Attributes]({% link _docs_integrate/exchange-files-using-attributes.md %}#transfer-the-ownership-of-a-file-to-a-peer) guide. -| Name | Type | Description | -| --------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| @type | `"TransferFileOwnershipRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| fileReference | `string` | The value of `reference.truncated` of the [File](#file) whose ownership ought to be transferred. | -| ownershipToken | `string` \| `undefined` | The `ownershipToken` of the [File](#file) whose ownership ought to be transferred. | -| title | `string` \| `undefined` | An optional, human readable title for the RequestItem. | -| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | -| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | -| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | -| requireManualDecision | `boolean` \| `undefined` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step, the requireManualDecision property can be set to true. | +| Name | Type | Description | +| -------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| @type | `"TransferFileOwnershipRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| fileReference | `string` | The value of `reference.truncated` of the [File](#file) whose ownership ought to be transferred. | +| ownershipToken | `string` | The `ownershipToken` of the [File](#file) whose ownership ought to be transferred. | +| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | +| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the Request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the Request which helps you identify the correct internal process at the time of receiving the Response. | +| mustBeAccepted | `boolean` | The mandatory `mustBeAccepted` property is used to differentiate between required and optional RequestItems within the Request.
{::nomarkdown}
  • If mustBeAccepted is set to true, the peer cannot accept the Request without accepting this RequestItem.
  • If mustBeAccepted is set to false, the peer can accept the Request even though the RequestItem is rejected.
{:/} | ### RequestItemGroup @@ -739,7 +811,7 @@ For more information, please consult the respective chapter of the [Request and #### AcceptResponseItem -An AcceptResponseItem can be received as answer to an [AuthenticationRequestItem]({% link _docs_integrate/request-and-response-introduction.md %}#authenticationrequestitem) or [ConsentRequestItem]({% link _docs_integrate/request-and-response-introduction.md %}#consentrequestitem). +An AcceptResponseItem can be received as answer to an [AuthenticationRequestItem]({% link _docs_integrate/request-and-response-introduction.md %}#authenticationrequestitem) or a [ConsentRequestItem]({% link _docs_integrate/request-and-response-introduction.md %}#consentrequestitem). | Name | Type | Description | | ------ | ---------------------- | -------------------------------------------------------- | @@ -749,9 +821,10 @@ An AcceptResponseItem can be received as answer to an [AuthenticationRequestItem ##### AttributeAlreadySharedAcceptResponseItem An AttributeAlreadySharedAcceptResponseItem can be received as answer to a [ReadAttributeRequestItem]({% link _docs_integrate/request-and-response-introduction.md %}#readattributerequestitem) or [ProposeAttributeRequestItem]({% link _docs_integrate/request-and-response-introduction.md %}#proposeattributerequestitem). -It is generated if the Recipient of the RequestItem responds to it with an existing Attribute they already shared with the Sender in case the own shared [LocalAttribute](#localattribute) doesn't have `"DeletedByPeer"` or `"ToBeDeletedByPeer"` as `deletionInfo.deletionStatus`. -Instead of creating a further own shared/peer shared Attribute pair, the `id` of the already existing shared LocalAttributes is returned. -Note that the `id` of the own/peer shared Attribute of the Sender matches the `id` of the corresponding peer/own shared Attribute of the Recipient. +It is generated if the Recipient of the RequestItem responds to it with an existing Attribute they already shared with the Sender in case the corresponding [AttributeForwardingDetails](#attributeforwardingdetails) of the own [LocalAttribute](#localattribute) don't have `"DeletedByRecipient"` as `deletionInfo.deletionStatus`. +If `"ToBeDeletedByRecipient"` was previously the `deletionInfo.deletionStatus`, the `deletionInfo` will be reset to undefined. +Instead of creating further AttributeForwardingDetails, the `id` of the already existing shared LocalAttributes is returned. +Note that the `id` of the own/peer Attribute of the Sender matches the `id` of the corresponding peer/own Attribute of the Recipient. | Name | Type | Description | | ----------- | -------------------------------------------- | -------------------------------------------------------- | @@ -762,8 +835,8 @@ Note that the `id` of the own/peer shared Attribute of the Sender matches the `i ##### AttributeSuccessionAcceptResponseItem An AttributeSuccessionAcceptResponseItem can be received as answer to a [ReadAttributeRequestItem]({% link _docs_integrate/request-and-response-introduction.md %}#readattributerequestitem) or [ProposeAttributeRequestItem]({% link _docs_integrate/request-and-response-introduction.md %}#proposeattributerequestitem). -It is generated if the Recipient of the RequestItem responds to it with an existing Attribute that is a successor of an Attribute they already shared with the Sender in case the own shared [LocalAttribute](#localattribute) doesn't have `"DeletedByPeer"` or `"ToBeDeletedByPeer"` as `deletionInfo.deletionStatus`. -Instead of creating an independent own shared/peer shared Attribute pair, internally an [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) is performed. +It is generated if the Recipient of the RequestItem responds to it with an existing Attribute that is a successor of an Attribute they already shared with the Sender in case the corresponding [AttributeForwardingDetails](#attributeforwardingdetails) of the own [LocalAttribute](#localattribute) don't have `"DeletedByRecipient"` as `deletionInfo.deletionStatus`. +Instead of creating an independent peer Attribute, internally an [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) is performed. The `id` of the already existing shared LocalAttribute predecessor is returned, as well as the `id` and `content` of the newly created successor. Receiving an AttributeSuccessionAcceptResponseItem, the respective shared LocalAttribute of the Sender of the Request is automatically succeeded accordingly. @@ -799,14 +872,6 @@ Receiving an AttributeSuccessionAcceptResponseItem, the respective shared LocalA | result | `"Accepted"` | The only possible value here is the string `"Accepted"`. | | response | `string` \| `number` \| `boolean` \| `string[]` | The response that is used to fill out the form field. The expected type of response depends on the `settings` of the [FormFieldRequestItem]({% link _docs_integrate/data-model-overview.md %}#formfieldrequestitem). | -##### FreeTextAcceptResponseItem - -| Name | Type | Description | -| -------- | ------------------------------ | -------------------------------------------------------- | -| @type | `"FreeTextAcceptResponseItem"` | The type of the ResponseItem. | -| result | `"Accepted"` | The only possible value here is the string `"Accepted"`. | -| freeText | `string` | The free text that is used to answer the RequestItem. | - ##### ProposeAttributeAcceptResponseItem | Name | Type | Description | @@ -818,21 +883,13 @@ Receiving an AttributeSuccessionAcceptResponseItem, the respective shared LocalA ##### ReadAttributeAcceptResponseItem -| Name | Type | Description | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| @type | `"ReadAttributeAcceptResponseItem"` | The type of the ResponseItem. | -| result | `"Accepted"` | The only possible value here is the string `"Accepted"`. | -| attributeId | `string` | The `id` of the returned LocalAttribute. | -| attribute | [`IdentityAttribute`]({% link _docs_integrate/data-model-overview.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute that will be shared with the peer. | -| thirdPartyAddress | `string` \| `undefined` | If the Attribute to be shared is an already existing [RelationshipAttribute](#relationshipattribute) of another [Relationship](#relationship), this property must contain the address of the `peer` with whom the sender of the Attribute has the Relationship in which context the RelationshipAttribute exists. | - -##### RegisterAttributeListenerAcceptResponseItem - -| Name | Type | Description | -| ---------- | ----------------------------------------------- | -------------------------------------------------------- | -| @type | `"RegisterAttributeListenerAcceptResponseItem"` | The type of the ResponseItem. | -| result | `"Accepted"` | The only possible value here is the string `"Accepted"`. | -| listenerId | `string` | The id of the created AttributeListener. | +| Name | Type | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| @type | `"ReadAttributeAcceptResponseItem"` | The type of the ResponseItem. | +| result | `"Accepted"` | The only possible value here is the string `"Accepted"`. | +| attributeId | `string` | The `id` of the returned LocalAttribute. | +| attribute | [`IdentityAttribute`]({% link _docs_integrate/data-model-overview.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute that will be shared with the peer. | +| initialAttributePeer | `string` \| `undefined` | If the Attribute to be shared is an already existing [RelationshipAttribute](#relationshipattribute) of another [Relationship](#relationship), this property must contain the address of the `peer` with whom the sender of the Attribute has the Relationship in which context the RelationshipAttribute exists. | ##### ShareAttributeAcceptResponseItem @@ -862,7 +919,9 @@ Receiving an AttributeSuccessionAcceptResponseItem, the respective shared LocalA #### ErrorResponseItem -The `ErrorResponseItem` is only created by the enmeshed Runtime, in case something happens which hinders you from further processing of the RequestItem. It will never be created manually. The properties are: +The `ErrorResponseItem` is only created by the enmeshed Runtime, in case something happens which hinders you from further processing of the RequestItem. +It will never be created manually. +The properties are: | Name | Type | Description | | ------- | --------------------- | ----------------------------------------------------------------------- | @@ -880,7 +939,8 @@ The `ErrorResponseItem` is only created by the enmeshed Runtime, in case somethi ## ResponseWrapper -The ResponseWrapper is a wrapper around the Response that is sent by the recipient of the Request. It contains the Response itself, but also some additional information that is required for the Request to be processed correctly. +The ResponseWrapper is a wrapper around the Response that is sent by the recipient of the Request. +It contains the Response itself, but also some additional information that is required for the Request to be processed correctly. | Name | Type | Description | | ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | @@ -906,75 +966,75 @@ In the example of Attribute succession, the peer can not decide to accept or rej NotificationItems are sent inside a Notification and specify which processes should be triggered when receiving the Notification. -#### OwnSharedAttributeDeletedByOwnerNotificationItem +#### ForwardedAttributeDeletedByPeerNotificationItem -If a peer has shared one of their Attributes with you and deletes their own shared Attribute, an OwnSharedAttributeDeletedByOwnerNotificationItem will be sent to you. -Internally, for your corresponding peer shared Attribute the `deletionInfo.deletionStatus` will be set to `"DeletedByOwner"` if it wasn't set to `"ToBeDeleted` before. +If an Identity has shared an [OwnIdentityAttribute](#ownidentityattribute) with a peer or forwarded an [OwnRelationshipAttribute](#ownrelationshipattribute) or a [PeerRelationshipAttribute](#peerrelationshipattribute) to a peer which is not involved in the [Relationship](#relationship) in which the [RelationshipAttribute](#relationshipattribute) exists, a ForwardedAttributeDeletedByPeerNotificationItem will be sent to the Identity if the peer deletes their forwarded Attribute. +Internally, for the corresponding [AttributeForwardingDetails](#attributeforwardingdetails) of the Identity's Attribute, the `deletionInfo.deletionStatus` will be set to `"DeletedByRecipient"`. -| Name | Type | Description | -| ----------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| @type | `"OwnSharedAttributeDeletedByOwnerNotificationItem"` | | -| attributeId | `string` | The `id` of the own shared Attribute that was deleted by the owner. It matches the `id` of the corresponding peer shared Attributes of the recipient. | +| Name | Type | Description | +| ----------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| @type | `"ForwardedAttributeDeletedByPeerNotificationItem"` | | +| attributeId | `string` | The `id` of the forwarded Attribute that was deleted by the peer. It matches the `id` of the corresponding Attribute of the Identity. | -#### PeerSharedAttributeDeletedByPeerNotificationItem +#### OwnAttributeDeletedByOwnerNotificationItem -If you have shared one of your Attributes with a peer and they delete their peer shared Attribute, a PeerSharedAttributeDeletedByPeerNotificationItem will be sent to you. -Internally, for your corresponding own shared Attribute the `deletionInfo.deletionStatus` will be set to `"DeletedByPeer"` . +If an Identity has shared an [OwnIdentityAttribute](#ownidentityattribute) or an [OwnRelationshipAttribute](#ownrelationshipattribute) with a peer and deletes it, an OwnAttributeDeletedByOwnerNotificationItem will be sent to the peer. +Internally, for the corresponding Attribute of the peer, the `deletionInfo.deletionStatus` will be set to `"DeletedByEmitter"` if it wasn't set to `"ToBeDeleted` before. -| Name | Type | Description | -| ----------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| @type | `"PeerSharedAttributeDeletedByPeerNotificationItem"` | | -| attributeId | `string` | The `id` of the peer shared Attribute that was deleted by the peer. It matches the `id` of the corresponding own shared Attributes of the recipient. | +| Name | Type | Description | +| ----------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| @type | `"OwnAttributeDeletedByOwnerNotificationItem"` | | +| attributeId | `string` | The `id` of the own Attribute that was deleted by the owner. It matches the `id` of the corresponding Attribute of the peer. | -#### PeerSharedAttributeSucceededNotificationItem +#### PeerRelationshipAttributeDeletedByPeerNotificationItem -A PeerSharedAttributeSucceededNotificationItem will be sent, if an Attribute, a peer shared with you, was succeeded by them and they choose to notify you about it. -Internally, the succeeded version will then be created at your side as successor for your previously received Attribute. +If an Identity has shared a [PeerRelationshipAttribute](#peerrelationshipattribute) with a peer and deletes it, a PeerRelationshipAttributeDeletedByPeerNotificationItem will be sent to the peer. +Internally, for the corresponding [OwnRelationshipAttribute](#ownrelationshipattribute) or [ThirdPartyRelationshipAttribute](#thirdpartyrelationshipattribute) of the peer, the `deletionInfo.deletionStatus` will be set to `"DeletedByRecipient"` or `"DeletedByEmitter"`, respectively. -| Name | Type | Description | -| ---------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- | -| @type | `"PeerSharedAttributeSucceededNotificationItem"` | | -| predecessorId | `string` | The `id` of the LocalAttribute that was succeeded | -| successorId | `string` | The `id` of the LocalAttribute it was succeeded by | -| successorContent | [`IdentityAttribute`](#identityattribute) \| [`RelationshipAttribute`](#relationshipattribute) | The updated `content` of the LocalAttribute | +| Name | Type | Description | +| ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| @type | `"PeerRelationshipAttributeDeletedByPeerNotificationItem"` | | +| attributeId | `string` | The `id` of the PeerRelationshipAttribute that was deleted by the Identity. It matches the `id` of the OwnRelationshipAttribute or ThirdPartyRelationshipAttribute of the peer. | -#### ThirdPartyRelationshipAttributeDeletedByPeerNotificationItem +#### PeerAttributeSucceededNotificationItem -If your peer deletes an [emitted or received ThirdPartyRelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#emitted-and-received-thirdpartyrelationshipattributes), a ThirdPartyRelationshipAttributeDeletedByPeerNotificationItem will be sent to you. -Internally, for your corresponding ThirdPartyRelationshipAttribute the `deletionInfo.deletionStatus` will be set to `"DeletedByPeer"`. +A PeerAttributeSucceededNotificationItem will be sent if an Attribute, an Identity has shared with a peer, was succeeded by the Identity and they choose to notify the peer about it. +Internally, the succeeded version will then be created at the peer's side as successor for the previously received Attribute. -| Name | Type | Description | -| ----------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| @type | `"ThirdPartyRelationshipAttributeDeletedByPeerNotificationItem"` | | -| attributeId | `string` | The `id` of the ThirdPartyRelationshipAttribute that was deleted by the peer. The `id` of the ThirdPartyRelationshipAttribute of the sender of the NotificationItem matches the one of the recipient. | +| Name | Type | Description | +| ---------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| @type | `"PeerAttributeSucceededNotificationItem"` | | +| predecessorId | `string` | The `id` of the [LocalAttribute](#localattribute) that was succeeded. | +| successorId | `string` | The `id` of the [LocalAttribute](#localattribute) it was succeeded by. | +| successorContent | [`IdentityAttribute`](#identityattribute) \| [`RelationshipAttribute`](#relationshipattribute) | The updated `content` of the [LocalAttribute](#localattribute). | ## Attributes -An Attribute is some piece of information about an Identity itself (e.g. its name, address, birth date, etc.) or about an Identity in the context of a Relationship (e.g. the customer id the of the user the Relationship). Since the two scenarios differ quite a lot, there are two different types for them: IdentityAttribute and RelationshipAttribute. +An Attribute is some piece of information about an Identity itself (e.g. its name, address, birth date, etc.) or about an Identity in the context of a Relationship (e.g. the customer id the of the user the Relationship). +Since the two scenarios differ quite a lot, there are two different types for them: IdentityAttribute and RelationshipAttribute. ### IdentityAttribute -IdentityAttributes describe an Identity itself. Their values are strongly normalized. There is a list of available values [here]({% link _docs_integrate/attribute-values.md %}). +IdentityAttributes describe an Identity itself. +Their values are strongly normalized. +There is a list of available values [here]({% link _docs_integrate/attribute-values.md %}). -| Name | Type | Description | -| --------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -| @type | `"IdentityAttribute"` | | -| owner | `string` | The Identity that owns this Attribute. Only the owner of an Attribute is allowed to change it after its creation. | -| validFrom | `string` \| `undefined` | The date from which on the Attribute is valid. Could be in the future if the Attribute is not yet valid. | -| validTo | `string` \| `undefined` | The date until this Attribute is valid. Could be in the past if the Attribute is already expired. | -| value | [`IdentityAttributeValue`]({% link _docs_integrate/attribute-values.md %}#identity-attributes) | The Attribute's value. | -| tags | `string[]` \| `undefined` | To specify additional information. It is not possible to specify the same tag more than once. | +| Name | Type | Description | +| ----- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| @type | `"IdentityAttribute"` | | +| owner | `string` | The Identity that owns this Attribute. Only the owner of an Attribute is allowed to change it after its creation. | +| value | [`IdentityAttributeValue`]({% link _docs_integrate/attribute-values.md %}#identity-attributes) | The Attribute's value. | +| tags | `string[]` \| `undefined` | To specify additional information. A tag is valid if it is contained in the [AttributeTagCollection](#attributetagcollection) and starts with the prefix `bkb:` or if it starts with the custom tag prefix `x:` or `X:`, the prefix `urn:`, the prefix `language:` followed by a valid ISO 639 language code or the prefix `mimetype:` followed by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$`. | ### RelationshipAttribute -RelationshipAttributes describe an Identity in the context of a Relationship. While there are some types that can be used as a value for a RelationshipAttribute, these types are rather generic (e.g. `ProprietaryString`, `ProprietaryInteger`, ...). +RelationshipAttributes describe an Identity in the context of a Relationship. +While there are some types that can be used as a value for a RelationshipAttribute, these types are rather generic (e.g. `ProprietaryString`, `ProprietaryInteger`, ...). | Name | Type | Description | | --------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | | @type | `"RelationshipAttribute"` | | | owner | `string` | The Identity that owns this Attribute. Only the owner of an Attribute is allowed to change it after its creation. | -| validFrom | `string` \| `undefined` | The date from which on the Attribute is valid. Could be in the future if the Attribute is not yet valid. | -| validTo | `string` \| `undefined` | The date until this Attribute is valid. Could be in the past if the Attribute is already expired. | | key | `string` | An arbitrary key that is set by the creator of this Attribute. It is used to identify the Attribute in a query, especially by a third party. Example: you could set something like `customerId` in case of a customer id. | | isTechnical | `boolean` \| `undefined` | Defines whether the RelationshipAttribute contains data that is actually relevant for the user (`isTechnical=false`) or whether it should be hidden in the UI (`isTechnical=true`). | | value | [`RelationshipAttributeValue`]({% link _docs_integrate/attribute-values.md %}#relationship-attributes) | The Attribute's value. | @@ -982,31 +1042,36 @@ RelationshipAttributes describe an Identity in the context of a Relationship. Wh ## AttributeQueries -One of the main features of enmeshed is sharing Attributes. For this, an Identity either proactively sends its Attributes to a peer. Or, if let's say a company wants to know the birth date of its customer, it can ask for it. Depending on the exact use case, the latter can be achieved with one of a bunch of RequestItems, like for example a [`ReadAttributeRequestItem`](#readattributerequestitem), or a [`CreateAttributeRequestItem`](#createattributerequestitem). All of them have in common that they define a `query` property, which contains either an [`IdentityAttributeQuery`](#identityattributequery) or a [`RelationshipAttributeQuery`](#relationshipattributequery). +One of the main features of enmeshed is sharing Attributes. +For this, an Identity either proactively sends its Attributes to a peer. +Or, if let's say a company wants to know the birth date of its customer, it can ask for it. +Depending on the exact use case, the latter can be achieved with one of a bunch of RequestItems, like for example a [`ReadAttributeRequestItem`](#readattributerequestitem), or a [`CreateAttributeRequestItem`](#createattributerequestitem). +All of them have in common that they define a `query` property, which contains either an [`IdentityAttributeQuery`](#identityattributequery) or a [`RelationshipAttributeQuery`](#relationshipattributequery). ### IdentityAttributeQuery -An `IdentityAttributeQuery` is used to query for IdentityAttributes. For that, it defines the following properties: +An `IdentityAttributeQuery` is used to query for IdentityAttributes. +For that, it defines the following properties: -| Name | Type | Description | -| --------- | -------------------------- | --------------------------------------------------------------------------------------------------- | -| @type | `"IdentityAttributeQuery"` | | -| validFrom | `string` \| `undefined` | The start date of the time frame the returned Attribute should be valid in. | -| validTo | `string` \| `undefined` | The end date of the time frame the returned Attribute should be valid in. | -| valueType | `string` | The type of value that should be queried, e.g. `"StreetAddress"`, `"BirthDate"` or `"Nationality"`. | -| tags | `string[]` \| `undefined` | To specify additional information. | +| Name | Type | Description | +| --------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| @type | `"IdentityAttributeQuery"` | | +| valueType | `string` | The type of value that should be queried, e.g. `"StreetAddress"`, `"BirthDate"` or `"Nationality"`. | +| tags | `string[]` \| `undefined` | To specify additional information. A tag is valid if it is contained in the [AttributeTagCollection](#attributetagcollection) and starts with the prefix `bkb:` or if it starts with the custom tag prefix `x:` or `X:`, the prefix `urn:`, the prefix `language:` followed by a valid ISO 639 language code or the prefix `mimetype:` followed by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$`. | You can only query IdentityAttributes owned by the recipient of the query. ### RelationshipAttributeQuery -There are cases in which you want to query some data from your peer that is not an IdentityAttribute. An example for this is when an electricity provider asks for the electric meter number of a new customer. Since this information is only relevant in the context of the Relationship, an IdentityAttribute wouldn't make any sense here. That's why you would send a `RelationshipAttributeQuery`. Its properties are: +There are cases in which you want to query some data from your peer that is not an IdentityAttribute. +An example for this is when an electricity provider asks for the electric meter number of a new customer. +Since this information is only relevant in the context of the Relationship, an IdentityAttribute wouldn't make any sense here. +That's why you would send a `RelationshipAttributeQuery`. +Its properties are: | Name | Type | Description | | ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | @type | `"RelationshipAttributeQuery"` | | -| validFrom | `string` \| `undefined` | The start date of the time frame the returned Attribute should be valid in. | -| validTo | `string` \| `undefined` | The end date of the time frame the returned Attribute should be valid in. | | key | `string` | The key of the RelationshipAttribute that should be queried. | | owner | `string` | The owner of the queried RelationshipAttribute. | | attributeCreationHints | [`RelationshipAttributeCreationHints`](#relationshipattributecreationhints) | Contains information about the value that will be created, like the value type or its confidentiality. | @@ -1036,7 +1101,8 @@ There are cases in which you want to query some data from your peer that is not #### ValueHintsOverride -`ValueHintsOverride` has the same properties as [`ValueHints`](#valuehints), except that all of them are optional. This type is used for some [RelationshipAttribute values]({% link _docs_integrate/attribute-values.md %}#relationship-attributes) +`ValueHintsOverride` has the same properties as [`ValueHints`](#valuehints), except that all of them are optional. +This type is used for some [RelationshipAttribute values]({% link _docs_integrate/attribute-values.md %}#relationship-attributes) #### ValueHintsValue @@ -1047,20 +1113,24 @@ There are cases in which you want to query some data from your peer that is not ### ThirdPartyRelationshipAttributeQuery -If you want to query RelationshipAttributes the Recipient has in the context of a Relationship with a third party, you can use the `ThirdPartyRelationshipAttributeQuery`. An example would be the query for the number of a bonus card managed by another company (like Payback). A ThirdPartyRelationshipAttributeQuery has the following properties: +If you want to query RelationshipAttributes the Recipient has in the context of a Relationship with a third party, you can use the `ThirdPartyRelationshipAttributeQuery`. +An example would be the query for the number of a bonus card managed by another company (like Payback). +A ThirdPartyRelationshipAttributeQuery has the following properties: | Name | Type | Description | | ---------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | @type | `"ThirdPartyRelationshipAttributeQuery"` | | -| validFrom | `string` \| `undefined` | The start date of the time frame the returned RelationshipAttribute should be valid in. | -| validTo | `string` \| `undefined` | The end date of the time frame the returned RelationshipAttribute should be valid in. | | key | `string` | The `key` of the RelationshipAttribute that should be queried. | | owner | `"recipient"` \| `"thirdParty"` \| `""` | The `owner` of the queried RelationshipAttribute. Specify the string `"recipient"` if the Recipient should be the `owner` of the queried RelationshipAttribute. Use the string `"thirdParty"` if any of the third parties specified in the array string `thirdParty` should be the `owner`. If both the Recipient and each of the given third parties may be the `owner`, an empty string `""` must be specified. Using this option is useful if the `owner` of the queried RelationshipAttribute is not known in advance. | -| thirdParty | `string[]` | The third parties the RelationshipAttribute should be queried from. An `address` from this array will match the `shareInfo.thirdPartyAddress` property of a [ThirdPartyRelationshipAttribute](#localattribute). | +| thirdParty | `string[]` | The third parties the RelationshipAttribute should be queried from. An `address` from this array will match the `initialAttributePeer` property of a [ThirdPartyRelationshipAttribute](#thirdpartyrelationshipattribute). | ### IQLQuery -If you want to query IdentityAttributes by their content, you can use the `IQLQuery` which is based on the IQL language, a simple and accessible yet powerful query language for IdentityAttributes. It allows you to specify conditions the IdentityAttribute must match and which may be chained using binary operations. Every property of the IdentityAttribute's content may be queried. For a full explanation of the IQL syntax, see its [dedicated documentation page]({% link _docs_integrate/iql-syntax.md %}) which also includes an interactive demo for you to try out different queries. If no IdentityAttribute corresponding to the IQLQuery exists at the peer's side, you are given the possibility to add `attributeCreationHints`, suggesting to create an IdentityAttribute which matches a specific `valueType` and optionally `tags`. +If you want to query IdentityAttributes by their content, you can use the `IQLQuery` which is based on the IQL language, a simple and accessible yet powerful query language for IdentityAttributes. +It allows you to specify conditions the IdentityAttribute must match and which may be chained using binary operations. +Every property of the IdentityAttribute's content may be queried. +For a full explanation of the IQL syntax, see its [dedicated documentation page]({% link _docs_integrate/iql-syntax.md %}) which also includes an interactive demo for you to try out different queries. +If no IdentityAttribute corresponding to the IQLQuery exists at the peer's side, you are given the possibility to add `attributeCreationHints`, suggesting to create an IdentityAttribute which matches a specific `valueType` and optionally `tags`. | Name | Type | Description | | ---------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -1070,14 +1140,15 @@ If you want to query IdentityAttributes by their content, you can use the `IQLQu #### IQLQueryCreationHints -| Name | Type | Description | -| --------- | ----------------------------------- | -------------------------------------------------------------------- | -| valueType | `AttributeValues.Identity.TypeName` | The `value.@type` of the IdentityAttribute, which should be created. | -| tags | `string[]` \| `undefined` | The `tags` for the IdentityAttribute, which should be created. | +| Name | Type | Description | +| --------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| valueType | `AttributeValues.Identity.TypeName` | The `value.@type` of the IdentityAttribute, which should be created. | +| tags | `string[]` \| `undefined` | The `tags` for the IdentityAttribute, which should be created. A tag is valid if it is contained in the [AttributeTagCollection](#attributetagcollection) and starts with the prefix `bkb:` or if it starts with the custom tag prefix `x:` or `X:`, the prefix `urn:`, the prefix `language:` followed by a valid ISO 639 language code or the prefix `mimetype:` followed by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$`. | ## RelationshipTemplateContent -Theoretically you can send any kind of data in a RelationshipTemplate. However, if your peer uses the enmeshed App, it will only be able to process RelationshipTemplates that contain a `RelationshipTemplateContent`, which looks like this: +Theoretically you can send any kind of data in a RelationshipTemplate. +However, if your peer uses the enmeshed App, it will only be able to process RelationshipTemplates that contain a `RelationshipTemplateContent`, which looks like this: | Name | Type | Description | | ---------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -1098,7 +1169,8 @@ When communicating with a Connector, you can send any kind of data in a [Relatio ## RelationshipCreationContent -Theoretically you can send any kind of data in a [Relationship's](#relationship) `creationContent`. However, if the [RelationshipTemplate's](#relationshiptemplate) `content` was of type `RelationshipTemplateContent`, the `creationContent` must be of type `RelationshipCreationContent`, containing the Response to the [Request](#request) contained within the [RelationshipTemplateContent's](#relationshiptemplatecontent) `onNewRelationship` property. +Theoretically you can send any kind of data in a [Relationship's](#relationship) `creationContent`. +However, if the [RelationshipTemplate's](#relationshiptemplate) `content` was of type `RelationshipTemplateContent`, the `creationContent` must be of type `RelationshipCreationContent`, containing the Response to the [Request](#request) contained within the [RelationshipTemplateContent's](#relationshiptemplatecontent) `onNewRelationship` property. | Name | Type | Description | | -------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -1116,7 +1188,8 @@ When receiving a [RelationshipTemplate](#relationshiptemplate) with an [Arbitrar ## Mail -A Mail can be sent as the content of a [Message](#message). It is comparable with the classic email, so its properties should be familiar. +A Mail can be sent as the content of a [Message](#message). +It is comparable with the classic email, so its properties should be familiar. | Name | Type | Description | | ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -1143,7 +1216,7 @@ In order to answer a Request, the Response must be formulated appropriately. As an easier interface to do so various `DecideRequestItemParameters` are provided. If you want to reject any RequestItem, you must use the `RejectRequestItemParameters`. If you want to accept a RequestItem, however, depending on its kind you might need different parameters. -For example, an AuthenticationRequestItem can be accepted using the AcceptRequestItemParameters, but for a FreeTextRequestItem `AcceptFreeTextRequestItemParameters` are required. +For example, an AuthenticationRequestItem can be accepted using the AcceptRequestItemParameters, but for a FormFieldRequestItem `AcceptFormFieldRequestItemParameters` are required. ### RejectRequestItemParameters @@ -1177,13 +1250,6 @@ For example, when using [BooleanFormFieldSettings](#booleanformfieldsettings), a | accept | `"true"` | The only possible value here is the string "true". | | response | `string` \| `number` \| `boolean` \| `string[]` | The response that is used to fill out the form field. | -#### AcceptFreeTextRequestItemParameters - -| Name | Type | Description | -| -------- | -------- | ----------------------------------------------------- | -| accept | `"true"` | The only possible value here is the string "true". | -| freeText | `string` | The free text that is used to answer the RequestItem. | - #### AcceptProposeAttributeRequestItemParameters The parameters to accept a ProposeAttributeRequestItem with an existing Attribute. @@ -1204,11 +1270,11 @@ The parameters to accept a ProposeAttributeRequestItem with a new Attribute. The parameters to accept a ReadAttributeRequestItem with an existing Attribute. -| Name | Type | Description | -| ------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| accept | `"true"` | The only possible value here is the string "true". | -| existingAttributeId | `string` | The `id` of the existing LocalAttribute. | -| tags | `string[]` \| `undefined` | If additional `tags` are requested, that the exsiting Attibute doesn't have, yet, they can be specified using this property. | +| Name | Type | Description | +| ------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| accept | `"true"` | The only possible value here is the string "true". | +| existingAttributeId | `string` | The `id` of the existing LocalAttribute. | +| tags | `string[]` \| `undefined` | If additional `tags` are requested, that the exsiting Attibute doesn't have, yet, they can be specified using this property. A tag is valid if it is contained in the [AttributeTagCollection](#attributetagcollection) and starts with the prefix `bkb:` or if it starts with the custom tag prefix `x:` or `X:`, the prefix `urn:`, the prefix `language:` followed by a valid ISO 639 language code or the prefix `mimetype:` followed by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$`. | The parameters to accept a ReadAttributeRequestItem with a new Attribute. diff --git a/_docs_integrate/delete-attributes.md b/_docs_integrate/delete-attributes.md index c7a5486d6..edb125a58 100644 --- a/_docs_integrate/delete-attributes.md +++ b/_docs_integrate/delete-attributes.md @@ -25,27 +25,29 @@ required_by: The exact process of deleting an Attribute depends on the kind of Attribute at hand. [Creating an Attribute]({% link _docs_integrate/create-attributes-for-yourself.md %}), we must distinguish between [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) and [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute). -In the former case, a so-called RepositoryAttribute is created, which is a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) without `shareInfo`, that you are the `owner` of. -Afterwards, you may [share it]({% link _docs_integrate/share-attributes-with-peer.md %}) with a peer, which yields the creation of an own shared IdentityAttribute. -This is a LocalAttribute with the copied `content` of the RepositoryAttribute, but an additional `shareInfo` property. -Doing so, also a LocalAttribute with the same `content` and a respective `shareInfo` is created for the peer, which is referred to as peer shared Attribute. -In the case of RelationshipAttributes we have own shared and peer shared RelationshipAttributes analogeously, however, no unshared LocalAttributes like we have in the case of IdentityAttributes with RepositoryAttributes. +In the former case, a so-called [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) is created. +Afterwards, you may [share it]({% link _docs_integrate/share-attributes-with-peer.md %}) with a peer, which yields the creation of associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails). +Doing so, also a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) with the same `content` is created for the peer. +In the case of RelationshipAttributes we have [OwnRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) and [PeerRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute). +Analogeously, sharing an OwnRelationshipAttribute or a PeerRelationshipAttribute with a third party leads to the the creation of associated AttributeForwardingDetails for the emitter and a [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute) for the third party. These different kinds of Attributes have different demands that need to be taken into account, wanting to delete them. +For example, it is straightforward to delete an OwnIdentityAttribute that has not been shared with a peer. +To [delete such an Attribute]({% link _docs_use-cases/use-case-consumption-delete-an-attribute-and-notify.md %}), simply specify its `attributeId`. -
+
In general, you can only delete data from your own wallet and never from the peer's. So, for example you can delete Attributes a peer shared with you from your wallet, but you can't delete Attributes you shared with a peer from their wallet. Wanting to do so, you need to send a Request to the peer, asking them to delete the respective Attribute. Note that this doesn't automatically delete their Attribute, since the peer may have a valid reason to still keep it for a certain amount of time. -## Request the deletion of own Attributes from peer +## Request the deletion of emitted Attributes from recipient -Wanting to delete a peer shared Attribute owned by you from the peer technically describes the endeavor of withdrawing the permission you gave them to use your Attribute. +Wanting to delete an emitted Attribute from its recipient technically describes the endeavor of withdrawing the permission you gave them to use your Attribute. To this end, a [Request]({% link _docs_integrate/data-model-overview.md %}#request) must be used with a [DeleteAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#deleteattributerequestitem). -As a parameter, the `attributeId` of the peer shared Attribute you would like the peer to delete must be provided. -Note, that the peer shared Attribute at the peer's side has the same `id` like the own shared Attribute at your side. -A possible Request for deleting a peer shared Attribute from a peer could look as follows: +As a parameter, the `attributeId` of the Attribute you would like the recipient to delete must be provided. +Note, that the Attribute at the recipient's side has the same `id` like the emitted Attribute at your side. +A possible Request for deleting an Attribute could look as follows: ```json { @@ -54,27 +56,27 @@ A possible Request for deleting a peer shared Attribute from a peer could look a { "@type": "DeleteAttributeRequestItem", "mustBeAccepted": true, - "attributeId": "" + "attributeId": "" } ] } ``` -Of course, it is also possible to request the deletion of multiple peer shared Attributes within a single Request. +Of course, it is also possible to request the deletion of multiple Attributes within a single Request. For this purpose, several DeleteAttributeRequestItems or suitable [RequestItemGroups]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) can be inserted into the `items` property of the Request. Before sending the Request, we recommend to [validate its content]({% link _docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md %}), since this will give you additional information in case of an error. {: .notice--info} -Next, send the Request to the peer. +Next, send the Request to the Attribute recipient. You can either do so by [Message]({% link _docs_integrate/data-model-overview.md %}#message) or by a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate), using the `onExistingRelationship` property of a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). For a detailed explanation check out our guides on how to send [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) and [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}). -Once the Request is sent, the according own shared Attribute of the Sender gets a [LocalAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#localattributedeletioninfo). +Once the Request is sent, the [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with the emitted Attribute of the Sender or the emitted Attribute itself, in case it is an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) and the deletion of the [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) is requested from the `peer`, get an [EmittedAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#emittedattributedeletioninfo). There, `"DeletionRequestSent"` is set as `deletionStatus` and the time of sending the Request is stored as `deletionDate`. -When the peer receives the Request, they can accept or reject it. +When the recipient receives the Request, they can accept or reject it. If they want to [accept it]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}), they must use the [AcceptDeleteAttributeRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptdeleteattributerequestitemparameters). -Doing so, they specify a `deletionDate` on which they plan to delete the peer shared Attribute. +Doing so, they specify a `deletionDate` on which they plan to delete the received Attribute. In the given example, the payload would look like the following: ```json @@ -82,75 +84,59 @@ In the given example, the payload would look like the following: "items": [ { "accept": true, - "deletionDate": "" + "deletionDate": "" } ] } ``` -Now, the [enmeshed Runtime]({% link _docs_explore/61-runtime.md %}) sets the `deletionInfo` of the corresponding peer shared Attribute of the peer with `deletionStatus` `"ToBeDeleted"` and the specified `deletionDate`. -The same is done for all predecessors of the peer shared Attribute. +Now, the [enmeshed Runtime]({% link _docs_explore/61-runtime.md %}) sets the `deletionInfo` of the corresponding Attribute of the recipient with `deletionStatus` `"ToBeDeleted"` and the specified `deletionDate`. +The same is done for all predecessors of the received Attribute. Then, the appropriate [DeleteAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#deleteattributeacceptresponseitem) is generated and sent back in the [Reponse]({% link _docs_integrate/data-model-overview.md %}#response) to the Sender of the Request. -There, the `deletionInfo` of the corresponding own shared Attribute and its predecessors is set with `deletionStatus` `"ToBeDeletedByPeer"` and the `deletionDate` received in the Response. +There, the `deletionInfo` of the corresponding emitted Attribute and its predecessors, in case it is an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) and the deletion of the [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) was requested from the `peer`, or of the associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) is set with `deletionStatus` `"ToBeDeletedByRecipient"` and the `deletionDate` received in the Response. -
+
-It is also possible for the peer to reject the DeleteAttributeRequestItem, if its `mustBeAccepted` property is set `false`, or to [reject the Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) for deleting a peer shared Attribute as a whole, if they have a valid reason for keeping the respective peer shared Attribute. -In this case, the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters) must be used and it is advised to provide a `message`, informing the Sender of the Request about the reason not to delete the peer shared Attribute. -Receiving the Response with the [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem), the own shared Attribute of the `owner` is given `"DeletionRequestRejected"` as `deletionStatus` and the receiving time is stored in the property `deletionDate`. +It is also possible for the recipient to reject the DeleteAttributeRequestItem, if its `mustBeAccepted` property is set `false`, or to [reject the Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) for deleting a received Attribute as a whole, if they have a valid reason for keeping the respective received Attribute. +In this case, the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters) must be used and it is advised to provide a `message`, informing the Sender of the Request about the reason not to delete the received Attribute. +Receiving the Response with the [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem), the emitted Attribute of the Sender, in case it is an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) and the deletion of the [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) was requested from the `peer`, or the associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) are given `"DeletionRequestRejected"` as `deletionStatus` and the receiving time is stored in the property `deletionDate`. {: .notice--info} -## Delete peer shared Attributes +## Delete received Attributes -The actual deletion of a peer shared Attribute happens in a separate step. -This can either be triggered if the `deletionInfo.deletionDate` is reached, in case the deletion was requested by the owner of the peer shared Attribute, or if the peer decides they no longer need it. +The actual deletion of a received Attribute happens in a separate step. +This can either be triggered if the `deletionInfo.deletionDate` is reached, in case the deletion was requested by the emitter of the Attribute, or if the recipient decides they no longer need it. -To [delete a peer shared Attribute]({% link _docs_use-cases/use-case-consumption-delete-a-peer-shared-attribute-and-notify-peer.md %}), only its `attributeId` must be specified. -Internally, not just the given peer shared Attribute is deleted, but also all its predecessors, in case there were any. -Moreover, if the peer shared Attribute had a successor, its `succeeds` property will be set to undefined, as the corresponding predecessor no longer exists. -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. +To [delete a received Attribute]({% link _docs_use-cases/use-case-consumption-delete-an-attribute-and-notify.md %}), only its `attributeId` must be specified. +Internally, not just the given Attribute is deleted, but also all its predecessors, in case there were any. +Moreover, if the received Attribute had a successor, its `succeeds` property will be set to undefined, as the corresponding predecessor no longer exists. +Then, a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) with a [ForwardedAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#forwardedattributedeletedbypeernotificationitem) or a [PeerRelationshipAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#peerrelationshipattributedeletedbypeernotificationitem) is generated and sent to the emitter of the Attribute, informing them that you deleted the Attribute they shared with you. +Consequently, the `deletionInfo` of their corresponding emitted Attribute and of all potential predecessors, in case it is an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) and the [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) was deleted by the `peer`, or of the associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) is updated with `deletionStatus` `"DeletedByRecipient"` and the time of receiving the Notification as `deletionDate`. +In case the emitter already [deleted their Attribute](#delete-emitted-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 %}). +The Notification is also queued if the [Attribute recipient 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 Attribute recipient [cancels its deletion]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}). -
+
-If you want to [delete a ThirdPartyRelationshipAttribute]({% link _docs_use-cases/use-case-consumption-delete-a-thirdpartyrelationshipattribute-and-notify-peer.md %}), the process will work analogously. -In this case, a [ThirdPartyRelationshipAttributeDeletedByPeerNotificationItem]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributedeletedbypeernotificationitem) will be sent. -{: .notice--info} - -## Delete own shared Attributes +## Delete emitted Attributes -The `owner` can always delete their LocalAttributes without having to ask for consent, even if there are shared copies of it. -Hence, it is always possible to delete own shared Attributes. -Doing so before the [peer deleted their copy of the shared Attribute](#delete-peer-shared-attributes), however, you lose the information of having shared the Attribute with them and whether they keep their peer shared Attribute or delete it. -Thus, we recommend to [request the deletion of own Attributes from the peer](#request-the-deletion-of-own-attributes-from-peer) before deleting them yourself. +The emitter can always delete their [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) without having to ask for consent. +Then, associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) are deleted as well. +Doing so before the [recipient deleted their copy of the shared Attribute](#delete-received-attributes), however, you lose the information of having shared the Attribute with them and whether they keep their Attribute or delete it. +Thus, we recommend to [request the deletion of emitted Attributes from their recipients](#request-the-deletion-of-emitted-attributes-from-recipient) before deleting them yourself. -If you decide to [delete an own shared Attribute]({% link _docs_use-cases/use-case-consumption-delete-an-own-shared-attribute-and-notify-peer.md %}), you must specifiy its `attributeId`. -Then, in addition to the own shared Attribute itself, also all its predecessors will be deleted, given there were any. -Moreover, if the own shared Attribute had a successor, its `succeeds` property will be set to undefined, as the corresponding predecessor no longer exists. -Then, a Notification with an [OwnSharedAttributeDeletedByOwnerNotificationItem]({% link _docs_integrate/data-model-overview.md %}#ownsharedattributedeletedbyownernotificationitem) is generated and sent to the peer you shared the Attribute with, informing them that you deleted that own shared Attribute. -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. +If you decide to [delete an emitted Attribute]({% link _docs_use-cases/use-case-consumption-delete-an-attribute-and-notify.md %}), you must specifiy its `attributeId`. +Then, in addition to the emitted Attribute itself, also all its predecessors will be deleted, given there were any. +Moreover, if the emitted Attribute had a successor, its `succeeds` property will be set to undefined, as the corresponding predecessor no longer exists. +Then, a Notification with an [OwnAttributeDeletedByOwnerNotificationItem]({% link _docs_integrate/data-model-overview.md %}#ownattributedeletedbyownernotificationitem) or a [PeerRelationshipAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#peerrelationshipattributedeletedbypeernotificationitem) is generated and sent to the recipient you shared the Attribute with, informing them that you deleted that Attribute. +If they already deleted their corresponding Attribute or marked it for deletion, nothing will change. +However, if the `deletionInfo` of their 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 `"DeletedByEmitter"` 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 %}). - -
- -## Delete RepositoryAttributes - -Lastly, you can also [delete RepositoryAttributes]({% link _docs_use-cases/use-case-consumption-delete-a-repositoryattribute.md %}), i.e. LocalAttributes that are owned by yourself and whose `shareInfo` property is undefined. -Analogously to the cases above, also all predecessors of the RepositoryAttribute with specified `attributeId` will be deleted. -Additionally, the `succeeds` property of the successor will be removed in case of [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}). -If the RepositoryAttribute has [child Attributes]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes), the same will hold true for all its children. +Furthermore, the Notification is also queued if the [Attribute recipient 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 Attribute recipient [cancels its deletion]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}). -Furthermore, if there are any shared copies of the RepositoryAttribute, their `shareInfo` will be updated such that `sourceAttribute` doesn't link to the deleted RepositoryAttribute anymore. -As a consequence, the [get shared versions of an Attribute use case]({% link _docs_use-cases/use-case-consumption-get-shared-versions-of-an-attribute.md %}) will no longer return those shared versions. -Now, in case you shared a RepositoryAttribute with a peer, succeeded it without notifying the peer and then delete the source Attribute of the predecessor, you won't be able to [notify the peer about the succession]({% link _docs_use-cases/use-case-consumption-notify-peer-about-repositoryattribute-succession.md %}) of this no longer existing RepositoryAttribute anymore. -Instead, if you want to inform them about a newer version of this RepositoryAttribute, you must [share that version]({% link _docs_use-cases/use-case-consumption-share-a-repositoryattribute.md %}) again. +
diff --git a/_docs_integrate/delete-identities.md b/_docs_integrate/delete-identities.md index 5e7ff1301..dd4efbd77 100644 --- a/_docs_integrate/delete-identities.md +++ b/_docs_integrate/delete-identities.md @@ -35,15 +35,18 @@ However, Integrators of Connectors can still delete their Identity by using [Con ## 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 `"Approved"` or `"Cancelled"` as its `status`. -If an IdentityDeletionProcess has `"Approved"` as `status`, it is also referred to as an **active IdentityDeletionProcess**. +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 `"Active"` or `"Cancelled"` as its `status`. +If an IdentityDeletionProcess has `"Active"` 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"` 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. +- 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"` 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 @@ -55,11 +58,11 @@ Whenever a new [IdentityDeletionProcess]({% link _docs_integrate/data-model-over ### 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`. +Successful execution leads to the creation of an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) with `"Active"` as `status`. 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. +Trying to cancel an IdentityDeletionProcess that does not have `"Active"` as `status` causes an error with `error.runtime.identityDeletionProcess.noActiveIdentityDeletionProcess` 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`. @@ -85,7 +88,8 @@ However, if the creator of the RelationshipTemplate is meanwhile in deletion or 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. +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 diff --git a/_docs_integrate/error-codes.md b/_docs_integrate/error-codes.md index 9de39452b..2b67b0b28 100644 --- a/_docs_integrate/error-codes.md +++ b/_docs_integrate/error-codes.md @@ -23,180 +23,149 @@ required_by: # End automatic generation --- -Please find a list of enmeshed error codes below. Most often the errors occur on invalid input or actions. If you happen to find unexpected errors while using enmeshed or cannot deduce the reason for your error, please report it in the [enmeshed Issue Tracker](https://github.com/nmshd/feedback/issues). +Please find a list of enmeshed error codes below. +Most often the errors occur on invalid input or actions. +If you happen to find unexpected errors while using enmeshed or cannot deduce the reason for your error, please report it in the [enmeshed Issue Tracker](https://github.com/nmshd/feedback/issues). -| ErrorCode | Description | -| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {% include anchor a="error.connector.errorInErrorHandler" %} | The error handler ran into an error. Check the error message and the stack trace and [report this to a Connector developer](https://github.com/nmshd/feedback/issues), because this should not happen. | -| {% include anchor a="error.connector.http.methodNotAllowed" %} | This method is not supported for the requested resource. | -| {% include anchor a="error.connector.http.notAcceptable" %} | The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request. | -| {% include anchor a="error.connector.http.routeDoesNotExist" %} | The requested route does not exist. | -| {% include anchor a="error.connector.unauthorized" %} | The Connector is unauthorized, because the [API key]({% link _docs_integrate/access-the-connector.md %}) is not set or incorrect. | -| {% include anchor a="error.connector.unexpected" %} | An unexpected error occurred. | -| {% include anchor a="error.connector.validation.invalidJsonInPayload" %} | The given payload is not a valid JSON object. | -| {% include anchor a="error.consumption.attributes.cannotSetDeletionInfoOfRepositoryAttributes" %} | [RepositoryAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) cannot have a `deletionInfo`, since they are not shared with a peer and can be deleted directly. | -| {% include anchor a="error.consumption.attributes.cannotSucceedAttributesWithASuccessor" %} | It isn't possible to [succeed Attributes]({% link _docs_integrate/update-attributes-by-succession.md %}) which have already a successor. Instead, the successor has to be succeeded. | -| {% include anchor a="error.consumption.attributes.cannotSucceedAttributesWithDeletionInfo" %} | Attributes with a `deletionInfo` cannot be [succeeded]({% link _docs_integrate/update-attributes-by-succession.md %}), since the peer may have already deleted it or marked it for deletion. | -| {% include anchor a="error.consumption.attributes.cannotSucceedChildOfComplexAttribute" %} | The Attribute is a child Attribute of a [complex IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes) and cannot be succeeded on its own. Instead, succeed the parent which will implicitly succeed all its children. | -| {% include anchor a="error.consumption.attributes.invalidDeletionInfoOfOwnSharedAttribute" %} | The only valid values of the property [`deletionStatus` for own shared Attributes]({% link _docs_integrate/delete-attributes.md %}#delete-own-shared-attributes) are `"DeletionRequestSent"`, `"DeletionRequestRejected"`, `"DeletedByPeer"` or `"ToBeDeletedByPeer"`. | -| {% include anchor a="error.consumption.attributes.invalidDeletionInfoOfPeerSharedAttribute" %} | The only valid values of the property [`deletionStatus` for peer shared Attributes]({% link _docs_integrate/delete-attributes.md %}#delete-peer-shared-attributes) are `"DeletedByOwner"` or `"ToBeDeleted"`. | -| {% include anchor a="error.consumption.attributes.
invalidDeletionInfoOfThirdPartyRelationshipAttribute" %} | The only valid `deletionStatus` for [ThirdPartyRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) is `"DeletedByPeer"`, see ['Delete a ThirdPartyRelationshipAttribute']({% link _docs_use-cases/use-case-consumption-delete-a-thirdpartyrelationshipattribute-and-notify-peer.md %}) for more details. | -| {% include anchor a="error.consumption.attributes.invalidParentSuccessor" %} | The [complex parent successor of this Attribute]({% link _docs_integrate/update-attributes-by-succession.md %}#succeeding-a-repositoryattribute) does not exist. | -| {% include anchor a="error.consumption.attributes.isNotOwnSharedAttribute" %} | The Attribute is not an [own shared Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.isNotPeerSharedAttribute" %} | The Attribute is not a [peer shared Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.isNotRepositoryAttribute" %} | The given Attribute is not a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.isNotSharedAttribute" %} | The Attribute is not a shared [Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.isNotThirdPartyRelationshipAttribute" %} | The Attribute is not a [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.predecessorDoesNotExist" %} | The predecessor does not exist. | -| {% include anchor a="error.consumption.attributes.predecessorIsNotOwnSharedIdentityAttribute" %} | The predecessor is not an [own shared IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.predecessorIsNotOwnSharedRelationshipAttribute" %} | The predecessor is not an [own shared RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.predecessorIsNotPeerSharedIdentityAttribute" %} | The predecessor is not a [peer shared IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.predecessorIsNotPeerSharedRelationshipAttribute" %} | The predecessor is not a [peer shared RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.predecessorIsNotRepositoryAttribute" %} | The predecessor is not a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.
predecessorIsNotThirdPartyRelationshipAttribute" %} | The predecessor is not a [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.predecessorSourceAttributeIsNotRepositoryAttribute" %} | The predecessor sourceAttribute is not a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.predecessorSourceContentIsNotEqualToCopyContent" %} | The predecessor sourceAttribute `content` doesn't match the `content` of the predecessor [shared Attribute copy]({% link _docs_integrate/update-attributes-by-succession.md %}#sharing-a-repositoryattribute). | -| {% include anchor a="error.consumption.attributes.senderIsNotPeerOfSharedAttribute" %} | The Sender of the [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) is not the peer you shared the Attribute with. | -| {% include anchor a="error.consumption.attributes.setPredecessorIdDoesNotMatchActualPredecessorId" %} | The predecessor's `id` and the explicitly set value for the successor's `succeeds` field don't match. | -| {% include anchor a="error.consumption.attributes.setDefaultRepositoryAttributesIsDisabled" %} | Setting default RepositoryAttributes is disabled for this Account. | -| {% include anchor a="error.consumption.attributes.successionMustChangeContent" %} | An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must change the Attribute's `content`. | -| {% include anchor a="error.consumption.attributes.successionMustNotChangeContentType" %} | The successor Attribute's `content` type does not match that of the predecessor. An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must not change the Attribute's `content` type, i.e. an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) must not be succeeded by a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) and v.v. | -| {% include anchor a="error.consumption.attributes.successionMustNotChangeKey" %} | The predecessor [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute)'s `key` does not match that of the successor. The [succession of a RelationshipAttribute]({% link _docs_integrate/update-attributes-by-succession.md %}#succeeding-a-relationshipattribute-and-notifying-the-peer) must not change the `key`. | -| {% include anchor a="error.consumption.attributes.successionPeerIsNotOwner" %} | The peer of the succeeded Attribute is not its `owner`. This may be an attempt of spoofing. | -| {% include anchor a="error.consumption.attributes.successionMustNotChangeOwner" %} | The successor Attribute's `owner` does not match that of the predecessor. An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must not change the Attribute's `owner`. | -| {% include anchor a="error.consumption.attributes.successionMustNotChangePeer" %} | The peer of the [shared Attribute]({% link _docs_integrate/update-attributes-by-succession.md %}#sharing-a-repositoryattribute) must not change. | -| {% include anchor a="error.consumption.attributes.successionMustNotChangeThirdParty" %} | The `thirdPartyAddress` of the [shared Attribute]({% link _docs_integrate/update-attributes-by-succession.md %}#sharing-a-repositoryattribute) must not change. | -| {% include anchor a="error.consumption.attributes.successionMustNotChangeValueType" %} | The successor Attribute's `value.@type` does not match that of the predecessor. An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must not change the Attribute's `value.@type`. | -| {% include anchor a="error.consumption.attributes.successorDoesNotExist" %} | The successor does not exist. | -| {% include anchor a="error.consumption.attributes.successorIsNotAValidAttribute" %} | During the [creation of the successor]({% link _docs_integrate/update-attributes-by-succession.md %}#succeeding-a-repositoryattribute) the validation failed. | -| {% include anchor a="error.consumption.attributes.successorIsNotOwnSharedIdentityAttribute" %} | The successor is not an [own shared IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.successorIsNotOwnSharedRelationshipAttribute" %} | The successor is not an [own shared RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.successorIsNotPeerSharedIdentityAttribute" %} | The successor is not a [peer shared IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.successorIsNotPeerSharedRelationshipAttribute" %} | The successor is not a [peer shared RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.successorIsNotRepositoryAttribute" %} | The successor is not a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.successorIsNotThirdPartyRelationshipAttribute" %} | The successor is not a [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.successorMustNotHaveASuccessor" %} | The successor must not have a successor itself. That means the property `succeededBy` must be undefined. | -| {% include anchor a="error.consumption.attributes.successorMustNotYetExist" %} | The predecessor Attribute's successor must not exist. It will be created by the succession handlers and must not be created manually. | -| {% include anchor a="error.consumption.attributes.successorSourceAttributeDoesNotExist" %} | The successor `sourceAttribute` does not exist. | -| {% include anchor a="error.consumption.attributes.successorSourceAttributeIsNotRepositoryAttribute" %} | The successor `sourceAttribute` is not a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.consumption.attributes.successorSourceAttributeIsNotSpecified" %} | The [`sourceAttribute`]({% link _docs_integrate/update-attributes-by-succession.md %}) of the successor must be specified. | -| {% include anchor a="error.consumption.attributes.successorSourceDoesNotSucceedPredecessorSource" %} | The predecessor [`sourceAttribute`]({% link _docs_integrate/update-attributes-by-succession.md %}) is not succeeded by the successor sourceAttribute. | -| {% include anchor a="error.consumption.attributes.successorSourceContentIsNotEqualToCopyContent" %} | The successor [`sourceAttribute`]({% link _docs_integrate/update-attributes-by-succession.md %}) `content` doesn't match the `content` of the successor [shared Attribute copy]({% link _docs_integrate/update-attributes-by-succession.md %}#sharing-a-repositoryattribute). | -| {% include anchor a="error.consumption.attributes.wrongOwnerOfRepositoryAttribute" %} | A wrong `owner` was provided wanting to create a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). You can only create RepositoryAttributes for yourself. | -| {% include anchor a="error.consumption.attributes.wrongRelationshipStatusToSetDeletionInfo" %} | In order to manually set the `deletionInfo` of an own shared or a peer shared [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute), the corresponding [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) must have `"DeletionProposed"` as `status`. | -| {% include anchor a="error.consumption.requests.attributeQueryMismatch" %} | The provided Attribute does not match the AttributeQuery. | -| {% include anchor a="error.consumption.requests.cannotCreateRequestWithExpirationDateInPast" %} | A [Request]({% link _docs_integrate/data-model-overview.md %}#request) with an expiration date that is in the past cannot be created. | -| {% include anchor a="error.consumption.requests.cannotShareRelationshipAttributeOfPendingRelationship" %} | The provided [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) exists in the context of a pending [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) and therefore cannot be shared. | -| {% include anchor a="error.consumption.requests.cannotShareRequestWithYourself" %} | It is not possible to share a [Request]({% link _docs_integrate/data-model-overview.md %}#request) with yourself. | -| {% include anchor a="error.consumption.requests.canOnlyDeleteIncomingRequestThatIsExpired" %} | Only incoming [Requests]({% link _docs_integrate/data-model-overview.md %}#request) that are expired can be deleted. | -| {% include anchor a="error.consumption.requests.decide.validation.invalidNumberOfItems" %} | The [Request- and the ResponseItem count]({% link _docs_integrate/request-and-response-introduction.md %}) is different. | -| {% include anchor a="error.consumption.requests.decide.validation.itemAcceptedButRequestNotAccepted" %} | You accepted a [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems) of a [Request]({% link _docs_integrate/data-model-overview.md %}#request), but you rejected the Request. If you accept a RequestItem, you need to accept the Request as well. | -| {% include anchor a="error.consumption.requests.decide.validation.mustBeAcceptedItemNotAccepted" %} | The [Request]({% link _docs_integrate/data-model-overview.md %}#request) was accepted, but a [RequestItem that was flagged as `mustBeAccepted`]({% link _docs_integrate/request-and-response-introduction.md %}#working-with-required-and-optional-requestitems) was not accepted. | -| {% include anchor a="error.consumption.requests.decide.validation.
requestItemAnsweredAsRequestItemGroup" %} | The [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems) was answered as a [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup), consider ['Request and response introduction']({% link _docs_integrate/request-and-response-introduction.md %}). | -| {% include anchor a="error.consumption.requests.decide.validation.
requestItemGroupAnsweredAsRequestItem" %} | The [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) was answered as a [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems), consider ['Request and response introduction']({% link _docs_integrate/request-and-response-introduction.md %}). | -| {% 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 %}). | -| {% include anchor a="error.consumption.requests.violatedKeyUniquenessOfRelationshipAttributes" %} | For a given combination of `key`, `owner` and `value.@type`, there may only be at most one [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) in the context of a given [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship), whose corresponding [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) has an undefined `succeededBy` property. | -| {% include anchor a="error.consumption.requests.wrongRelationshipStatus" %} | The [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) needs to be in a different `status` (e.g. `"Active"`) to send/decide that [Request]({% link _docs_integrate/data-model-overview.md %}#request). | -| {% include anchor a="error.runtime.alreadyInitialized" %} | The Runtime is already initialized. The init method can only be executed once. | -| {% include anchor a="error.runtime.alreadyStarted" %} | The Runtime is already started. You should stop it first for a restart. | -| {% include anchor a="error.runtime.attributes.cannotCreateDuplicateRepositoryAttribute" %} | The [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) cannot be created because it has the exact same `content.value` as an already existing RepositoryAttribute whose `succeededBy` property is undefined. | -| {% include anchor a="error.runtime.attributes.cannotDeleteSharedAttributeWhileRelationshipIsPending" %} | The shared Attribute cannot be deleted while the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to the `peer` has `"Pending"` as `status`. | -| {% include anchor a="error.runtime.attributes.cannotSeparatelyDeleteChildOfComplexAttribute" %} | The given Attribute is a child of a [complex IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes). If you want to delete it, you must delete its parent. | -| {% include anchor a="error.runtime.attributes.hasSuccessor" %} | The given Attribute already has a successor. | -| {% include anchor a="error.runtime.attributes.isNotOwnSharedAttribute" %} | The given Attribute is not an [own shared Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.runtime.attributes.isNotPeerSharedAttribute" %} | The given Attribute is not a [peer shared Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.runtime.attributes.isNotRepositoryAttribute" %} | The given Attribute is not a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.runtime.attributes.isNotThirdPartyRelationshipAttribute" %} | The given Attribute is not a [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | -| {% include anchor a="error.runtime.attributes.
noPreviousVersionOfRepositoryAttributeHasBeenSharedWithPeerBefore" %} | No previous version of the given [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) has been shared with this peer before. If you wish to execute an initial sharing of this Attribute, [use 'ShareRepositoryAttribute']({% link _docs_integrate/share-attributes-with-peer.md %}). | -| {% include anchor a="error.runtime.attributes.setDefaultRepositoryAttributesIsDisabled" %} | Setting default RepositoryAttributes is disabled for this Account. | -| {% include anchor a="error.runtime.attributes.repositoryAttributeHasAlreadyBeenSharedWithPeer" %} | The given [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) has already been shared with this peer. | -| {% include anchor a="error.runtime.cacheEmpty" %} | The `cache` of a [File]({% link _docs_integrate/data-model-overview.md %}#file), an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess), a [Message]({% link _docs_integrate/data-model-overview.md %}#message), a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship), a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or a [Token]({% link _docs_integrate/data-model-overview.md %}#token) is empty. | -| {% include anchor a="error.runtime.challenges.invalidChallenge" %} | The `challengeString` is invalid. | -| {% include anchor a="error.runtime.challenges.invalidSignature" %} | The `signature` is invalid. | -| {% include anchor a="error.runtime.decide.requestConfigDoesNotMatchResponseConfig" %} | The automation configuration specified when using the [Decider Module]({% link _docs_explore/61-runtime.md %}#decider-module) is invalid because the `requestConfig` does not match the `responseConfig`. | -| {% include anchor a="error.runtime.devices.referenceNotPointingToAnEmptyToken" %} | The given reference is not pointing to an [empty Token]({% link _docs_use-cases/use-case-anonymous-create-empty-token.md %}). | -| {% include anchor a="error.runtime.files.invalidReference" %} | The given reference is not valid. The reference for a [File]({% link _docs_integrate/data-model-overview.md %}#file) must start with 'RklM' or with 'VE9L' in case of a Token. | -| {% include anchor a="error.runtime.files.notOwnedByYou" %} | Only the owner of the [File]({% link _docs_integrate/data-model-overview.md %}#file) can perform this action. | -| {% include anchor a="error.runtime.identityDeletionProcess.noActiveIdentityDeletionProcess" %} | No active [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) was found. | -| {% include anchor a="error.runtime.identityDeletionProcess.activeIdentityDeletionProcessAlreadyExists" %} | There is already an active [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess). You cannot start another, as there may only be one active IdentityDeletionProcess per [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). | -| {% 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.identityMetadata.notFound" %} | There is no stored [IdentityMetadata]({% link _docs_integrate/data-model-overview.md %}#identitymetadata) for the specified combination of `reference` and `key`. | -| {% include anchor a="error.runtime.identityMetadata.unfamiliarReferencedIdentity" %} | The `reference` of the [IdentityMetadata]({% link _docs_integrate/data-model-overview.md %}#identitymetadata) resolves neither to the `address` of a `peer` of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) nor the `address` of the own [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). | -| {% include anchor a="error.runtime.identityRecoveryKits.datawalletDisabled" %} | The identity recovery kit feature for App users will only work if the datawallet is enabled. | -| {% 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.cannotSendMessageWithExpiredRequest" %} | The [Message]({% link _docs_integrate/data-model-overview.md %}#message) cannot be sent as the contained [Request]({% link _docs_integrate/data-model-overview.md %}#request) is already expired. Please create a new Request and try again. | -| {% 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`. | -| {% include anchor a="error.runtime.notifications.messageDoesNotContainNotification" %} | The given [Message]({% link _docs_integrate/data-model-overview.md %}#message) does not contain a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification). | -| {% include anchor a="error.runtime.notInitialized" %} | The Runtime is not initialized. You must run init before you can start or stop the runtime. | -| {% include anchor a="error.runtime.notStarted" %} | The Runtime is not started. You can only stop the Runtime if you executed start before. | -| {% include anchor a="error.runtime.notSupported" %} | The requested feature is not supported. | -| {% include anchor a="error.runtime.recordNotFound" %} | The requested record was not found. Make sure the `id` exists and the record is not expired. | -| {% include anchor a="error.runtime.relationships.isNeitherRejectedNorRevoked" %} | The `status` of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) is neither `"Rejected"` nor `"Revoked"`. | -| {% include anchor a="error.runtime.relationships.noAcceptedIncomingRequest" %} | When attempting to [create a Relationship]({% link _docs_use-cases/use-case-transport-create-relationship-with-relationshiptemplate.md %}) based on a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) with a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent), there must be an associated accepted incoming [Request]({% link _docs_integrate/data-model-overview.md %}#request). | -| {% include anchor a="error.runtime.relationships.wrongRelationshipStatus" %} | The given [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) has the wrong status to run this operation. | -| {% include anchor a="error.runtime.relationships.wrongResponseProvidedAsCreationContent" %} | When attempting to [create a Relationship]({% link _docs_use-cases/use-case-transport-create-relationship-with-relationshiptemplate.md %}) based on a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) with a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent), the [Response]({% link _docs_integrate/data-model-overview.md %}#response) of the associated accepted incoming [Request]({% link _docs_integrate/data-model-overview.md %}#request) must be provided as the `response` of the [RelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#relationshipcreationcontent). | -| {% include anchor a="error.runtime.relationshipTemplates.cannotCreateTokenForPeerTemplate" %} | You cannot [create a Token for a RelationshipTemplate]({% link _docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md %}) of a peer. | -| {% include anchor a="error.runtime.relationshipTemplates.invalidReference" %} | The given reference is not valid. The reference for a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) must start with 'UkxU'. | -| {% include anchor a="error.runtime.relationshipTemplates.personalizationMustBeInherited" %} | If a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is personalized, [Tokens]({% link _docs_integrate/data-model-overview.md %}#token) created from it must have the same personalization. | -| {% include anchor a="error.runtime.relationshipTemplates.passwordProtectionMustBeInherited" %} | If a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) has password protection, [Tokens]({% link _docs_integrate/data-model-overview.md %}#token) created from it must have the same password protection. | -| {% include anchor a="error.runtime.relationshipTemplates.requestCannotExpireAfterRelationshipTemplate" %} | If the `content` of a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent), the expiration date of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) within its `onNewRelationship` property must be set such that the expiration date of the RelationshipTemplate is not exceeded. | -| {% include anchor a="error.runtime.requestDeserialization" %} | There was an error during the request deserialization. | -| {% include anchor a="error.runtime.servalError" %} | A serialization / validation error occurred. | -| {% include anchor a="error.runtime.startup.noActiveAccount" %} | No AccountController could be found. You might have to login first. | -| {% include anchor a="error.runtime.startup.noActiveConsumptionController" %} | No ConsumptionController could be found. You might have to login first. | -| {% include anchor a="error.runtime.startup.noActiveExpander" %} | No DataViewExpander could be found. You might have to login first. | -| {% include anchor a="error.runtime.unknown" %} | An unknown error occurred. Check the error message or the stack trace to learn more. | -| {% include anchor a="error.runtime.unknownType" %} | The given `@type` could not be found during the deserialization. | -| {% include anchor a="error.runtime.validation.invalidPayload" %} | The given combination of properties in the payload is not supported. | -| {% include anchor a="error.runtime.validation.invalidPropertyValue" %} | A property of the given payload is invalid. | -| {% include anchor a="error.transport.accountControllerInitialSyncFailed" %} | The initial sync of the AccountController has failed for a local account. | -| {% include anchor a="error.transport.challenges.challengeTypeRequiresActiveRelationship" %} | The challengeType `"Relationship"` requires an active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship). | -| {% include anchor a="error.transport.datawallet.currentBiggerThanTarget" %} | The current datawallet version is bigger than the target version. | -| {% include anchor a="error.transport.datawallet.insufficientSupportedDatawalletVersion" %} | The current SupportedDatawalletVersion is too low to perform the requested operation. This means that the datawallet of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) was upgraded by another device with a higher version. It is necessary to update the current device. | -| {% include anchor a="error.transport.datawallet.unsupportedModification" %} | The following collections were received in CacheChanged datawallet modifications but are not supported by the current version of this library. | -| {% include anchor a="error.transport.devices.alreadyOnboarded" %} | The device has already been onboarded. | -| {% include anchor a="error.transport.devices.couldNotDeleteDevice" %} | The device cannot be deleted as the device is already onboarded or the Backbone did not authorize the deletion. | -| {% include anchor a="error.transport.files.cipherMismatch" %} | The actual hash of the cipher does not match the given cipherHash. Something went wrong while storing/transmitting the file. | -| {% include anchor a="error.transport.files.invalidMetadata" %} | The metadata of the [File]({% link _docs_integrate/data-model-overview.md %}#file) is invalid. | -| {% include anchor a="error.transport.files.maxFileSizeExceeded" %} | The given [File]({% link _docs_integrate/data-model-overview.md %}#file) content size exceeds the max file size the Backbone accepts. | -| {% include anchor a="error.transport.files.plaintextHashMismatch" %} | The actual hash of the plaintext does not match the given plaintextHash. Something went wrong while encrypting/decrypting the [File]({% link _docs_integrate/data-model-overview.md %}#file). | -| {% include anchor a="error.transport.general.baseUrlNotSet" %} | The [`baseUrl` of the `transportLibrary`]({% link _docs_operate/configuration.md %}#transportlibrary) was not set. | -| {% include anchor a="error.transport.general.invalidBaseUrl" %} | The [`baseUrl` of the `transportLibrary`]({% link _docs_operate/configuration.md %}#transportlibrary) is invalid since it contains a vertical bar |. | -| {% include anchor a="error.transport.general.notIntendedForYou" %} | If a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or a [Token]({% link _docs_integrate/data-model-overview.md %}#token) is personalized, it may only be loaded by the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) for which it is intended. | -| {% include anchor a="error.transport.general.platformClientIdNotSet" %} | The [`platformClientId` of the `transportLibrary`]({% link _docs_operate/configuration.md %}#transportlibrary) was not set. | -| {% include anchor a="error.transport.general.platformClientInvalid" %} | The combination of [`platformClientId` and `platformClientSecret` of the `transportLibrary`]({% link _docs_operate/configuration.md %}#transportlibrary) is invalid. | -| {% include anchor a="error.transport.general.platformClientSecretNotSet" %} | The [`platformClientSecret` of the `transportLibrary`]({% link _docs_operate/configuration.md %}#transportlibrary) was not set. | -| {% 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.noPasswordProvided" %} | If a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or a [Token]({% link _docs_integrate/data-model-overview.md %}#token) has password protection, a password must be provided to load it. | -| {% 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) 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. | -| {% include anchor a="error.transport.relationships.relationshipCurrentlyExists" %} | No new [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to the `peer` can be created as a Relationship with `"Pending"`, `"Active"`, `"Terminated"` or `"DeletionProposed"` as `status` already exists. | -| {% include anchor a="error.transport.relationships.relationshipNotYetDecomposedByPeer" %} | No new [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) can be created as the former Relationship is not yet decomposed by the `peer`. | -| {% include anchor a="error.transport.relationships.relationshipTemplateIsExpired" %} | The [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is already expired and therefore cannot be used to create a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship). | -| {% include anchor a="error.transport.relationships.wrongRelationshipStatus" %} | The [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) has the wrong `status` to run the requested operation. | -| {% include anchor a="error.transport.secrets.secretNotFound" %} | No secret was found for a specific type. | -| {% include anchor a="error.transport.secrets.wrongSecretType" %} | The given secret type is not supported. | -| {% include anchor a="error.transport.signatureNotValid" %} | A `signature` is invalid. | -| {% include anchor a="error.transport.tokens.emptyToken" %} | The `content`, `createdBy` or `createdByDevice` property of the [Token]({% link _docs_integrate/data-model-overview.md %}#token) is empty. | -| {% include anchor a="error.transport.tokens.invalidTokenContent" %} | The given [Token]({% link _docs_integrate/data-model-overview.md %}#token) `content` is not of type TokenContent. | +| ErrorCode | Description | +| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| {% include anchor a="error.connector.errorInErrorHandler" %} | The error handler ran into an error. Check the error message and the stack trace and [report this to a Connector developer](https://github.com/nmshd/feedback/issues), because this should not happen. | +| {% include anchor a="error.connector.http.methodNotAllowed" %} | This method is not supported for the requested resource. | +| {% include anchor a="error.connector.http.notAcceptable" %} | The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request. | +| {% include anchor a="error.connector.http.routeDoesNotExist" %} | The requested route does not exist. | +| {% include anchor a="error.connector.unauthorized" %} | The Connector is unauthorized, because the [API key]({% link _docs_integrate/access-the-connector.md %}) is not set or incorrect. | +| {% include anchor a="error.connector.unexpected" %} | An unexpected error occurred. | +| {% include anchor a="error.connector.validation.invalidJsonInPayload" %} | The given payload is not a valid JSON object. | +| {% include anchor a="error.consumption.attributes.alreadyForwarded" %} | The Attribute is already forwarded to the peer. | +| {% include anchor a="error.consumption.attributes.cannotSetAttributeDeletionInfo" %} | It isn't possible to set the `deletionInfo` of the Attribute since it isn't shared with the peer or already deleted by them. | +| {% include anchor a="error.consumption.attributes.cannotSetForwardingDetailsForPeer" %} | It isn't possible to set the AttributeForwardingDetails for the Attribute since the peer is the peer of the Relationship in whose context the RelationshipAttribute exists. | +| {% include anchor a="error.consumption.attributes.cannotSucceedAttributesWithASuccessor" %} | It isn't possible to [succeed Attributes]({% link _docs_integrate/update-attributes-by-succession.md %}) which have already a successor. Instead, the successor has to be succeeded. | +| {% include anchor a="error.consumption.attributes.cannotSucceedSharedAttributesDeletedByPeer" %} | It isn't possible to [succeed]({% link _docs_integrate/update-attributes-by-succession.md %}) shared Attributes that are already deleted by the peer. Instead, the successor must be shared. | +| {% include anchor a="error.consumption.attributes.forbiddenCharactersInAttribute" %} | The `value` of the Attribute, that is tried to be created, contains forbidden characters. | +| {% include anchor a="error.consumption.attributes.invalidTags" %} | Some of the provided [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) `tags` are invalid. | +| {% include anchor a="error.consumption.attributes.predecessorDoesNotExist" %} | The predecessor does not exist. | +| {% include anchor a="error.consumption.attributes.senderIsNotPeerOfSharedAttribute" %} | The Sender of the [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) is not the peer you shared the Attribute with. | +| {% include anchor a="error.consumption.attributes.setDefaultOwnIdentityAttributesIsDisabled" %} | Setting default OwnIdentityAttributes is disabled for this Account. | +| {% include anchor a="error.consumption.attributes.successionMustChangeContent" %} | An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must change the Attribute's `content`. | +| {% include anchor a="error.consumption.attributes.successionMustNotChangeContentType" %} | The successor Attribute's `content` type does not match that of the predecessor. An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must not change the Attribute's `content` type, i.e. an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) must not be succeeded by a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) and v.v. | +| {% include anchor a="error.consumption.attributes.successionMustNotChangeKey" %} | The predecessor [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute)'s `key` does not match that of the successor. The [succession of a RelationshipAttribute]({% link _docs_integrate/update-attributes-by-succession.md %}#succeeding-a-relationshipattribute-and-notifying-the-peer) must not change the `key`. | +| {% include anchor a="error.consumption.attributes.successionPeerIsNotOwner" %} | The peer of the succeeded Attribute is not its `owner`. This may be an attempt of spoofing. | +| {% include anchor a="error.consumption.attributes.successionMustNotChangeOwner" %} | The successor Attribute's `owner` does not match that of the predecessor. An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must not change the Attribute's `owner`. | +| {% include anchor a="error.consumption.attributes.successionMustNotChangeValueType" %} | The successor Attribute's `value.@type` does not match that of the predecessor. An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must not change the Attribute's `value.@type`. | +| {% include anchor a="error.consumption.attributes.successorDoesNotExist" %} | The successor does not exist. | +| {% include anchor a="error.consumption.attributes.successorIsNotAValidAttribute" %} | During the [creation of the successor]({% link _docs_integrate/update-attributes-by-succession.md %}#succeeding-an-ownidentityattribute) the validation failed. | +| {% include anchor a="error.consumption.attributes.successorMustNotYetExist" %} | The predecessor Attribute's successor must not exist. It will be created by the succession handlers and must not be created manually. | +| {% include anchor a="error.consumption.attributes.wrongOwnerOfAttribute" %} | A wrong `owner` was provided wanting to create an [Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) of a specific type. | +| {% include anchor a="error.consumption.attributes.wrongRelationshipStatusToSetDeletionInfo" %} | In order to manually set the `deletionInfo` of a shared [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) or associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails), the corresponding [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) must have `"DeletionProposed"` as `status`. | +| {% include anchor a="error.consumption.attributes.wrongTypeOfAttribute" %} | A wrong [Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) type was provided for performing this action. | +| {% include anchor a="error.consumption.requests.attributeQueryMismatch" %} | The provided Attribute does not match the AttributeQuery. | +| {% include anchor a="error.consumption.requests.cannotCreateRequestWithExpirationDateInPast" %} | A [Request]({% link _docs_integrate/data-model-overview.md %}#request) with an expiration date that is in the past cannot be created. | +| {% include anchor a="error.consumption.requests.cannotShareRelationshipAttributeOfPendingRelationship" %} | The provided [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) exists in the context of a pending [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) and therefore cannot be shared. | +| {% include anchor a="error.consumption.requests.cannotShareRequestWithYourself" %} | It is not possible to share a [Request]({% link _docs_integrate/data-model-overview.md %}#request) with yourself. | +| {% include anchor a="error.consumption.requests.canOnlyDeleteIncomingRequestThatIsExpired" %} | Only incoming [Requests]({% link _docs_integrate/data-model-overview.md %}#request) that are expired can be deleted. | +| {% include anchor a="error.consumption.requests.decide.validation.invalidNumberOfItems" %} | The [Request- and the ResponseItem count]({% link _docs_integrate/request-and-response-introduction.md %}) is different. | +| {% include anchor a="error.consumption.requests.decide.validation.itemAcceptedButRequestNotAccepted" %} | You accepted a [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems) of a [Request]({% link _docs_integrate/data-model-overview.md %}#request), but you rejected the Request. If you accept a RequestItem, you need to accept the Request as well. | +| {% include anchor a="error.consumption.requests.decide.validation.mustBeAcceptedItemNotAccepted" %} | The [Request]({% link _docs_integrate/data-model-overview.md %}#request) was accepted, but a [RequestItem that was flagged as `mustBeAccepted`]({% link _docs_integrate/request-and-response-introduction.md %}#working-with-required-and-optional-requestitems) was not accepted. | +| {% include anchor a="error.consumption.requests.decide.validation.
requestItemAnsweredAsRequestItemGroup" %} | The [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems) was answered as a [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup), consider ['Request and response introduction']({% link _docs_integrate/request-and-response-introduction.md %}). | +| {% include anchor a="error.consumption.requests.decide.validation.
requestItemGroupAnsweredAsRequestItem" %} | The [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) was answered as a [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitems), consider ['Request and response introduction']({% link _docs_integrate/request-and-response-introduction.md %}). | +| {% 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 %}). | +| {% include anchor a="error.consumption.requests.violatedKeyUniquenessOfRelationshipAttributes" %} | For a given combination of `key`, `owner` and `value.@type`, there may only be at most one [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) in the context of a given [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship), whose corresponding [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) has an undefined `succeededBy` property. | +| {% include anchor a="error.consumption.requests.wrongRelationshipStatus" %} | The [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) needs to be in a different `status` (e.g. `"Active"`) to send/decide that [Request]({% link _docs_integrate/data-model-overview.md %}#request). | +| {% include anchor a="error.runtime.alreadyInitialized" %} | The Runtime is already initialized. The init method can only be executed once. | +| {% include anchor a="error.runtime.alreadyStarted" %} | The Runtime is already started. You should stop it first for a restart. | +| {% include anchor a="error.runtime.attributes.cannotCreateDuplicateOwnIdentityAttribute" %} | The OwnIdentityAttribute cannot be created because it has the exact same `content.value` as an already existing OwnIdentityAttribute whose `succeededBy` property is undefined. | +| {% include anchor a="error.runtime.attributes.cannotDeleteSharedAttributeWhileRelationshipIsPending" %} | The shared Attribute cannot be deleted while the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to the `peer` has `"Pending"` as `status`. If you want to delete it now, you'll have to accept, reject or revoke the pending Relationship. | +| {% include anchor a="error.runtime.attributes.hasSuccessor" %} | The given Attribute already has a successor. | +| {% include anchor a="error.runtime.attributes.isNotOwnIdentityAttribute" %} | The given [Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) is not an OwnIdentityAttribute. | +| {% include anchor a="error.runtime.attributes.isNotOwnRelationshipAttribute" %} | The given [Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) is not an OwnRelationshipAttribute. | +| {% include anchor a="error.runtime.attributes.setDefaultOwnIdentityAttributesIsDisabled" %} | Setting default OwnIdentityAttributes is disabled for this Account. | +| {% include anchor a="error.runtime.attributes.successorOfOwnIdentityAttributeHasAlreadyBeenSharedWithPeer" %} | A successor of the OwnIdentityAttribute has already been shared with the peer. | +| {% include anchor a="error.runtime.attributes.ownIdentityAttributeHasAlreadyBeenSharedWithPeer" %} | The given OwnIdentityAttribute has already been shared with this peer. | +| {% include anchor a="error.runtime.attributes.peerHasNoPreviousVersionOfAttribute" %} | The peer doesn't have any previous version of the given [Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). Either you haven't shared it before or the peer has deleted it. | +| {% include anchor a="error.runtime.challenges.invalidChallenge" %} | The `challengeString` is invalid. | +| {% include anchor a="error.runtime.challenges.invalidSignature" %} | The `signature` is invalid. | +| {% include anchor a="error.runtime.decide.requestConfigDoesNotMatchResponseConfig" %} | The automation configuration specified when using the [Decider Module]({% link _docs_explore/61-runtime.md %}#decider-module) is invalid because the `requestConfig` does not match the `responseConfig`. | +| {% include anchor a="error.runtime.devices.referenceNotPointingToAnEmptyToken" %} | The given reference is not pointing to an [empty Token]({% link _docs_use-cases/use-case-anonymous-create-empty-token.md %}). | +| {% include anchor a="error.runtime.files.invalidReference" %} | The given reference is not valid. The reference for a [File]({% link _docs_integrate/data-model-overview.md %}#file) must start with 'RklM' or with 'VE9L' in case of a Token. | +| {% include anchor a="error.runtime.files.notOwnedByYou" %} | Only the owner of the [File]({% link _docs_integrate/data-model-overview.md %}#file) can perform this action. | +| {% include anchor a="error.runtime.identityDeletionProcess.noActiveIdentityDeletionProcess" %} | No active [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) was found. | +| {% include anchor a="error.runtime.identityDeletionProcess.activeIdentityDeletionProcessAlreadyExists" %} | There is already an active [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess). You cannot start another, as there may only be one active IdentityDeletionProcess per [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). | +| {% include anchor a="error.runtime.identityMetadata.notFound" %} | There is no stored [IdentityMetadata]({% link _docs_integrate/data-model-overview.md %}#identitymetadata) for the specified combination of `reference` and `key`. | +| {% include anchor a="error.runtime.identityMetadata.unfamiliarReferencedIdentity" %} | The `reference` of the [IdentityMetadata]({% link _docs_integrate/data-model-overview.md %}#identitymetadata) resolves neither to the `address` of a `peer` of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) nor the `address` of the own [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). | +| {% include anchor a="error.runtime.identityRecoveryKits.datawalletDisabled" %} | The identity recovery kit feature for App users will only work if the datawallet is enabled. | +| {% 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.cannotSendMessageWithExpiredRequest" %} | The [Message]({% link _docs_integrate/data-model-overview.md %}#message) cannot be sent as the contained [Request]({% link _docs_integrate/data-model-overview.md %}#request) is already expired. Please create a new Request and try again. | +| {% 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`. | +| {% include anchor a="error.runtime.notifications.messageDoesNotContainNotification" %} | The given [Message]({% link _docs_integrate/data-model-overview.md %}#message) does not contain a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification). | +| {% include anchor a="error.runtime.notInitialized" %} | The Runtime is not initialized. You must run init before you can start or stop the runtime. | +| {% include anchor a="error.runtime.notStarted" %} | The Runtime is not started. You can only stop the Runtime if you executed start before. | +| {% include anchor a="error.runtime.notSupported" %} | The requested feature is not supported. | +| {% include anchor a="error.runtime.recordNotFound" %} | The requested record was not found. Make sure the `id` exists and the record is not expired. | +| {% include anchor a="error.runtime.relationships.isNeitherRejectedNorRevoked" %} | The `status` of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) is neither `"Rejected"` nor `"Revoked"`. | +| {% include anchor a="error.runtime.relationships.noAcceptedIncomingRequest" %} | When attempting to [create a Relationship]({% link _docs_use-cases/use-case-transport-create-relationship-with-relationshiptemplate.md %}) based on a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) with a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent), there must be an associated accepted incoming [Request]({% link _docs_integrate/data-model-overview.md %}#request). | +| {% include anchor a="error.runtime.relationships.wrongRelationshipStatus" %} | The given [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) has the wrong status to run this operation. | +| {% include anchor a="error.runtime.relationships.wrongResponseProvidedAsCreationContent" %} | When attempting to [create a Relationship]({% link _docs_use-cases/use-case-transport-create-relationship-with-relationshiptemplate.md %}) based on a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) with a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent), the [Response]({% link _docs_integrate/data-model-overview.md %}#response) of the associated accepted incoming [Request]({% link _docs_integrate/data-model-overview.md %}#request) must be provided as the `response` of the [RelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#relationshipcreationcontent). | +| {% include anchor a="error.runtime.relationshipTemplates.cannotCreateTokenForPeerTemplate" %} | You cannot [create a Token for a RelationshipTemplate]({% link _docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md %}) of a peer. | +| {% include anchor a="error.runtime.relationshipTemplates.invalidReference" %} | The given reference is not valid. The reference for a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) must start with 'UkxU'. | +| {% include anchor a="error.runtime.relationshipTemplates.personalizationMustBeInherited" %} | If a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is personalized, [Tokens]({% link _docs_integrate/data-model-overview.md %}#token) created from it must have the same personalization. | +| {% include anchor a="error.runtime.relationshipTemplates.passwordProtectionMustBeInherited" %} | If a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) has password protection, [Tokens]({% link _docs_integrate/data-model-overview.md %}#token) created from it must have the same password protection. | +| {% include anchor a="error.runtime.relationshipTemplates.requestCannotExpireAfterRelationshipTemplate" %} | If the `content` of a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent), the expiration date of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) within its `onNewRelationship` property must be set such that the expiration date of the RelationshipTemplate is not exceeded. | +| {% include anchor a="error.runtime.requestDeserialization" %} | There was an error during the request deserialization. | +| {% include anchor a="error.runtime.servalError" %} | A serialization / validation error occurred. | +| {% include anchor a="error.runtime.startup.noActiveAccount" %} | No AccountController could be found. You might have to login first. | +| {% include anchor a="error.runtime.startup.noActiveConsumptionController" %} | No ConsumptionController could be found. You might have to login first. | +| {% include anchor a="error.runtime.startup.noActiveExpander" %} | No DataViewExpander could be found. You might have to login first. | +| {% include anchor a="error.runtime.unknown" %} | An unknown error occurred. Check the error message or the stack trace to learn more. | +| {% include anchor a="error.runtime.unknownType" %} | The given `@type` could not be found during the deserialization. | +| {% include anchor a="error.runtime.validation.invalidPayload" %} | The given combination of properties in the payload is not supported. | +| {% include anchor a="error.runtime.validation.invalidPropertyValue" %} | A property of the given payload is invalid. | +| {% include anchor a="error.transport.accountControllerInitialSyncFailed" %} | The initial sync of the AccountController has failed for a local account. | +| {% include anchor a="error.transport.challenges.challengeTypeRequiresActiveRelationship" %} | The challengeType `"Relationship"` requires an active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship). | +| {% include anchor a="error.transport.datawallet.currentBiggerThanTarget" %} | The current datawallet version is bigger than the target version. | +| {% include anchor a="error.transport.datawallet.insufficientSupportedDatawalletVersion" %} | The current SupportedDatawalletVersion is too low to perform the requested operation. This means that the datawallet of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) was upgraded by another device with a higher version. It is necessary to update the current device. | +| {% include anchor a="error.transport.devices.alreadyOnboarded" %} | The device has already been onboarded. | +| {% include anchor a="error.transport.devices.couldNotDeleteDevice" %} | The device cannot be deleted as the device is already onboarded or the Backbone did not authorize the deletion. | +| {% include anchor a="error.transport.files.cipherMismatch" %} | The actual hash of the cipher does not match the given cipherHash. Something went wrong while storing/transmitting the file. | +| {% include anchor a="error.transport.files.invalidMetadata" %} | The metadata of the [File]({% link _docs_integrate/data-model-overview.md %}#file) is invalid. | +| {% include anchor a="error.transport.files.maxFileSizeExceeded" %} | The given [File]({% link _docs_integrate/data-model-overview.md %}#file) content size exceeds the max file size the Backbone accepts. | +| {% include anchor a="error.transport.files.plaintextHashMismatch" %} | The actual hash of the plaintext does not match the given plaintextHash. Something went wrong while encrypting/decrypting the [File]({% link _docs_integrate/data-model-overview.md %}#file). | +| {% include anchor a="error.transport.general.baseUrlNotSet" %} | The [`baseUrl` of the `transportLibrary`]({% link _docs_operate/configuration.md %}#transportlibrary) was not set. | +| {% include anchor a="error.transport.general.invalidBaseUrl" %} | The [`baseUrl` of the `transportLibrary`]({% link _docs_operate/configuration.md %}#transportlibrary) is invalid since it contains a vertical bar |. | +| {% include anchor a="error.transport.general.notIntendedForYou" %} | If a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or a [Token]({% link _docs_integrate/data-model-overview.md %}#token) is personalized, it may only be loaded by the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) for which it is intended. | +| {% include anchor a="error.transport.general.platformClientIdNotSet" %} | The [`platformClientId` of the `transportLibrary`]({% link _docs_operate/configuration.md %}#transportlibrary) was not set. | +| {% include anchor a="error.transport.general.platformClientInvalid" %} | The combination of [`platformClientId` and `platformClientSecret` of the `transportLibrary`]({% link _docs_operate/configuration.md %}#transportlibrary) is invalid. | +| {% include anchor a="error.transport.general.platformClientSecretNotSet" %} | The [`platformClientSecret` of the `transportLibrary`]({% link _docs_operate/configuration.md %}#transportlibrary) was not set. | +| {% 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.noPasswordProvided" %} | If a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or a [Token]({% link _docs_integrate/data-model-overview.md %}#token) has password protection, a password must be provided to load it. | +| {% 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) 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. | +| {% include anchor a="error.transport.relationships.relationshipCurrentlyExists" %} | No new [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to the `peer` can be created as a Relationship with `"Pending"`, `"Active"`, `"Terminated"` or `"DeletionProposed"` as `status` already exists. | +| {% include anchor a="error.transport.relationships.relationshipNotYetDecomposedByPeer" %} | No new [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) can be created as the former Relationship is not yet decomposed by the `peer`. | +| {% include anchor a="error.transport.relationships.relationshipTemplateIsExpired" %} | The [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is already expired and therefore cannot be used to create a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship). | +| {% include anchor a="error.transport.relationships.wrongRelationshipStatus" %} | The [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) has the wrong `status` to run the requested operation. | +| {% include anchor a="error.transport.secrets.secretNotFound" %} | No secret was found for a specific type. | +| {% include anchor a="error.transport.secrets.wrongSecretType" %} | The given secret type is not supported. | +| {% include anchor a="error.transport.signatureNotValid" %} | A `signature` is invalid. | +| {% include anchor a="error.transport.tokens.emptyToken" %} | The `content`, `createdBy` or `createdByDevice` property of the [Token]({% link _docs_integrate/data-model-overview.md %}#token) is empty. | +| {% include anchor a="error.transport.tokens.invalidTokenContent" %} | The given [Token]({% link _docs_integrate/data-model-overview.md %}#token) `content` is not of type TokenContent. | diff --git a/_docs_integrate/establish-relationships.md b/_docs_integrate/establish-relationships.md index 01a3899e8..09ebd9221 100644 --- a/_docs_integrate/establish-relationships.md +++ b/_docs_integrate/establish-relationships.md @@ -23,12 +23,17 @@ required_by: # End automatic generation --- -Communication and sharing of information between two Identities requires the existence of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between them. This guide describes how a Connector can establish an active Relationship to another Identity. Firstly, we explain how to [create a RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#create-a-relationshiptemplate) on a Connector, the so-called templator, and how to [make the RelationshipTemplate available]({% link _docs_integrate/establish-relationships.md %}#make-the-relationshiptemplate-available) to the other Identity. The RelationshipTemplate can then be used by the other Identity, the so-called initiator, to [initiate a Relationship]({% link _docs_integrate/establish-relationships.md %}#initiate-a-relationship) with the templator. This Relationship can finally be accepted by the templator in order to [establish an active Relationship]({% link _docs_integrate/establish-relationships.md %}#establish-an-active-relationship) between them. +Communication and sharing of information between two Identities requires the existence of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between them. +This guide describes how a Connector can establish an active Relationship to another Identity. +Firstly, we explain how to [create a RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#create-a-relationshiptemplate) on a Connector, the so-called templator, and how to [make the RelationshipTemplate available]({% link _docs_integrate/establish-relationships.md %}#make-the-relationshiptemplate-available) to the other Identity. +The RelationshipTemplate can then be used by the other Identity, the so-called initiator, to [initiate a Relationship]({% link _docs_integrate/establish-relationships.md %}#initiate-a-relationship) with the templator. +This Relationship can finally be accepted by the templator in order to [establish an active Relationship]({% link _docs_integrate/establish-relationships.md %}#establish-an-active-relationship) between them. ## Create a RelationshipTemplate The creation of a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) on the templator is the first required step in the process of establishing a Relationship. -A RelationshipTemplate is a formal description of the aspects of a Relationship that can be established between two Identities. In particular, it can specify a [Request]({% link _docs_integrate/data-model-overview.md %}#request) sent from the templator to the initiator, which must be accepted by the initiator as a prerequisite for the establishment of the Relationship. +A RelationshipTemplate is a formal description of the aspects of a Relationship that can be established between two Identities. +In particular, it can specify a [Request]({% link _docs_integrate/data-model-overview.md %}#request) sent from the templator to the initiator, which must be accepted by the initiator as a prerequisite for the establishment of the Relationship. ### Input for Creating a RelationshipTemplate @@ -45,7 +50,11 @@ To create a RelationshipTemplate on the templator, you need to follow the instru } ``` -You need to replace the placeholders marked with `<...>` appropriately as usual. The `maxNumberOfAllocations` property is optional, so you can omit it. If you need help filling the `content` property or the `maxNumberOfAllocations` property with appropriate values, see the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) description in the Data Model Overview. It is important to note that if you intend to use the RelationshipTemplate to establish a Relationship between the templator and an App user, you must use a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) as the value of the `content` property. The input must then be as follows: +You need to replace the placeholders marked with `<...>` appropriately as usual. +The `maxNumberOfAllocations` property is optional, so you can omit it. +If you need help filling the `content` property or the `maxNumberOfAllocations` property with appropriate values, see the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) description in the Data Model Overview. +It is important to note that if you intend to use the RelationshipTemplate to establish a Relationship between the templator and an App user, you must use a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) as the value of the `content` property. +The input must then be as follows: ```jsonc { @@ -68,12 +77,16 @@ You need to replace the placeholders marked with `<...>` appropriately as usual. } ``` -The properties `content.title`, `content.metadata` and `content.onExistingRelationship` are optional, so you can omit them. In case the `content` property of the RelationshipTemplate contains a RelationshipTemplateContent and therefore in particular at least one [Request]({% link _docs_integrate/data-model-overview.md %}#request), you should [check the Requests' validity]({% link _docs_integrate/requests-via-relationshiptemplates.md %}#check-the-requests-validity) before you create the RelationshipTemplate. An Identity to which the RelationshipTemplate will be made available and which does not yet have a Relationship to the templator will receive the Request specified in the `onNewRelationship` property of the [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). However, if a Relationship already exists between them and a Request has been specified in the `onExistingRelationship` property of the RelationshipTemplateContent, the Identity will receive this Request instead. +The properties `content.title`, `content.metadata` and `content.onExistingRelationship` are optional, so you can omit them. +In case the `content` property of the RelationshipTemplate contains a RelationshipTemplateContent and therefore in particular at least one [Request]({% link _docs_integrate/data-model-overview.md %}#request), you should [check the Requests' validity]({% link _docs_integrate/requests-via-relationshiptemplates.md %}#check-the-requests-validity) before you create the RelationshipTemplate. +An Identity to which the RelationshipTemplate will be made available and which does not yet have a Relationship to the templator will receive the Request specified in the `onNewRelationship` property of the [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). +However, if a Relationship already exists between them and a Request has been specified in the `onExistingRelationship` property of the RelationshipTemplateContent, the Identity will receive this Request instead. How to send a Request via a RelationshipTemplate is explained in detail in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide. {: .notice--info} -If the RelationshipTemplate is intended to establish a Relationship between the templator and another Connector, an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) can be used instead of a RelationshipTemplateContent as the value of the [RelationshipTemplate's]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) `content`. An ArbitraryRelationshipTemplateContent has a single `value` property with no type restriction and is appropriate if the standard way is insufficient. +If the RelationshipTemplate is intended to establish a Relationship between the templator and another Connector, an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) can be used instead of a RelationshipTemplateContent as the value of the [RelationshipTemplate's]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) `content`. +An ArbitraryRelationshipTemplateContent has a single `value` property with no type restriction and is appropriate if the standard way is insufficient. #### Personalization of a RelationshipTemplate @@ -91,7 +104,8 @@ If the RelationshipTemplate is only for creating a Relationship with a single kn } ``` -Only that Identity will be able to continue with establishing a Relationship. This also protects sensitive data of that Identity contained in the RelationshipTemplate from outside access. +Only that Identity will be able to continue with establishing a Relationship. +This also protects sensitive data of that Identity contained in the RelationshipTemplate from outside access. #### Password Protection of a RelationshipTemplate @@ -120,13 +134,17 @@ However, if the value is `undefined`, a regular input field for entering the pas ### Successfully Created RelationshipTemplate -If you have successfully created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) on the templator, you will receive a success response from which you can read its `id`. As the templator is the creator of the RelationshipTemplate, the `createdBy` property contains the address of the templator. For this reason, the value of the `isOwn` property is set to `true` in this context. +If you have successfully created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) on the templator, you will receive a success response from which you can read its `id`. +As the templator is the creator of the RelationshipTemplate, the `createdBy` property contains the address of the templator. +For this reason, the value of the `isOwn` property is set to `true` in this context. -{% include copy-notice description="Save the `id` of the RelationshipTemplate so that you can refer to it and make it available to other Identities later. For the same reason, save the value of the property `reference.truncated`." %} +{% include copy-notice description="Save the `id` of the RelationshipTemplate so that you can refer to it and make it available to other Identities later. +For the same reason, save the value of the property `reference.truncated`." %} ## Make the RelationshipTemplate Available -For an Identity to initiate a Relationship with the templator, it must use a valid [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) which is owned by the templator. Depending on whether the Identity is a Connector or an App user, a different approach must be used to make the RelationshipTemplate available to the Identity: +For an Identity to initiate a Relationship with the templator, it must use a valid [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) which is owned by the templator. +Depending on whether the Identity is a Connector or an App user, a different approach must be used to make the RelationshipTemplate available to the Identity: - [Make it available to a Connector]({% link _docs_integrate/establish-relationships.md %}#make-it-available-to-a-connector): Load the RelationshipTemplate onto it. - [Make it available to an App user]({% link _docs_integrate/establish-relationships.md %}#make-it-available-to-an-app-user): Scan the QR code of the RelationshipTemplate. @@ -135,7 +153,8 @@ For an Identity to initiate a Relationship with the templator, it must use a val ### Make It Available to a Connector -If a Connector wants to initate a Relationship with the templator, it must first load a RelationshipTemplate, which is owned by the templator, onto itself. This can be done by following the [Load RelationshipTemplate created by others]({% link _docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md %}) use case description and providing the input: +If a Connector wants to initate a Relationship with the templator, it must first load a RelationshipTemplate, which is owned by the templator, onto itself. +This can be done by following the [Load RelationshipTemplate created by others]({% link _docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md %}) use case description and providing the input: ```jsonc { @@ -145,15 +164,22 @@ If a Connector wants to initate a Relationship with the templator, it must first In doing so, it is necessary to insert the value of the `reference.truncated` property read from the [created RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#successfully-created-relationshiptemplate) into the `reference` property. -When the RelationshipTemplate of the templator is successfully loaded onto the Connector, the `transport.peerRelationshipTemplateLoaded` [Connector event]({% link _docs_integrate/connector-events.md %}) is triggered and a success response is sent. This success response looks like the success response you receive when you have [successfully created a RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#successfully-created-relationshiptemplate) on the templator, except that the value of the property `isOwn` is now `false` instead of `true`. Assuming that there is no Relationship between the Connector and the templator yet and that the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) contains a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) in its `content` property, the Connector will additionally receive a new incoming Request. The Integrator of the Connector can [accept]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) it if they want to [initiate a Relationship]({% link _docs_integrate/establish-relationships.md %}#initiate-it-as-a-connector) with the templator. +When the RelationshipTemplate of the templator is successfully loaded onto the Connector, the `transport.peerRelationshipTemplateLoaded` [Connector event]({% link _docs_integrate/connector-events.md %}) is triggered and a success response is sent. +This success response looks like the success response you receive when you have [successfully created a RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#successfully-created-relationshiptemplate) on the templator, except that the value of the property `isOwn` is now `false` instead of `true`. +Assuming that there is no Relationship between the Connector and the templator yet and that the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) contains a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) in its `content` property, the Connector will additionally receive a new incoming Request. +The Integrator of the Connector can [accept]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) it if they want to [initiate a Relationship]({% link _docs_integrate/establish-relationships.md %}#initiate-it-as-a-connector) with the templator. ### Make It Available to an App User -If an App user wants to initiate a Relationship with the templator, the App user must first scan a QR code that contains the reference to a RelationshipTemplate which is owned by the templator. To create this QR code on the templator, proceed as described in the documentation of the [Get RelationshipTemplate]({% link _docs_use-cases/use-case-transport-get-relationshiptemplate.md %}) use case, use the `id` of the [created RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#successfully-created-relationshiptemplate) and specify the value `image/png` in the `Accept` header field. After scanning the QR code, the App user receives the conditions for establishing a Relationship to the templator as specified in the RelationshipTemplate. If these are accepted, the App user can now [initiate a Relationship]({% link _docs_integrate/establish-relationships.md %}#initiate-it-as-an-app-user) with the templator. +If an App user wants to initiate a Relationship with the templator, the App user must first scan a QR code that contains the reference to a RelationshipTemplate which is owned by the templator. +To create this QR code on the templator, proceed as described in the documentation of the [Get RelationshipTemplate]({% link _docs_use-cases/use-case-transport-get-relationshiptemplate.md %}) use case, use the `id` of the [created RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#successfully-created-relationshiptemplate) and specify the value `image/png` in the `Accept` header field. +After scanning the QR code, the App user receives the conditions for establishing a Relationship to the templator as specified in the RelationshipTemplate. +If these are accepted, the App user can now [initiate a Relationship]({% link _docs_integrate/establish-relationships.md %}#initiate-it-as-an-app-user) with the templator. ## Initiate a Relationship -After the templator has created a RelationshipTemplate and made it available to another Identity, this Identity can use it to initiate a Relationship with the templator. For this reason, this other Identity is also referred to below as the initiator. +After the templator has created a RelationshipTemplate and made it available to another Identity, this Identity can use it to initiate a Relationship with the templator. +For this reason, this other Identity is also referred to below as the initiator. ### Check the Feasibility of a Relationship Initiation @@ -164,32 +190,52 @@ Consult the use case documentation for more details on the various reasons why i ### Initiate It as a Connector -Assuming that the initiator in this section is a Connector, our starting situation is that the initiator has successfully loaded the [created RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#successfully-created-relationshiptemplate) onto itself. The received [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) may or may not contain a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) in its `content` property. We now describe separately in both cases how the initiator can use the RelationshipTemplate to initiate a Relationship with the templator. An overview of this procedure is given in the following diagram. +Assuming that the initiator in this section is a Connector, our starting situation is that the initiator has successfully loaded the [created RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#successfully-created-relationshiptemplate) onto itself. +The received [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) may or may not contain a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) in its `content` property. +We now describe separately in both cases how the initiator can use the RelationshipTemplate to initiate a Relationship with the templator. +An overview of this procedure is given in the following diagram.
#### RelationshipTemplate With RelationshipTemplateContent -We assume that there is no [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between the initiator and the templator yet and that a RelationshipTemplateContent is used within the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate). In this case, the initiator receives a new incoming Request after loading the RelationshipTemplate and the `consumption.incomingRequestReceived` [Connector event]({% link _docs_integrate/connector-events.md %}) is triggered. By proceeding as described in the [Query incoming Requests]({% link _docs_use-cases/use-case-consumption-query-incoming-requests.md %}) use case documentation and specifying `source.reference=` as a query parameter, this Request can be queried on the initiator. The `result` contains the corresponding [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest), from which you can read the `id` of the Request. +We assume that there is no [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between the initiator and the templator yet and that a RelationshipTemplateContent is used within the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate). +In this case, the initiator receives a new incoming Request after loading the RelationshipTemplate and the `consumption.incomingRequestReceived` [Connector event]({% link _docs_integrate/connector-events.md %}) is triggered. +By proceeding as described in the [Query incoming Requests]({% link _docs_use-cases/use-case-consumption-query-incoming-requests.md %}) use case documentation and specifying `source.reference=` as a query parameter, this Request can be queried on the initiator. +The `result` contains the corresponding [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest), from which you can read the `id` of the Request. {% include copy-notice description="Save the `id` of the incoming Request so that you can accept or reject it." %} -The `content` of the LocalRequest is the Request specified in the `onNewRelationship` property of the [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). This Request defines the conditions for establishing an active Relationship between the initiator and the templator. If the initiator agrees to them, it can initiate a Relationship with the templator by accepting the Request. +The `content` of the LocalRequest is the Request specified in the `onNewRelationship` property of the [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). +This Request defines the conditions for establishing an active Relationship between the initiator and the templator. +If the initiator agrees to them, it can initiate a Relationship with the templator by accepting the Request. -The [Request Module]({% link _docs_explore/61-runtime.md %}#request-module) enabled by default ensures that the initiator receives a new incoming Request when the RelationshipTemplate is loaded and that a Relationship is initiated by accepting the incoming Request. If an Integrator of a Connector has disabled the Request Module, they must trigger these and other processes manually, which is not described in this guide. Please note, however, that App users cannot deactivate the Request Module, which is why their processes are more standardized. +The [Request Module]({% link _docs_explore/61-runtime.md %}#request-module) enabled by default ensures that the initiator receives a new incoming Request when the RelationshipTemplate is loaded and that a Relationship is initiated by accepting the incoming Request. +If an Integrator of a Connector has disabled the Request Module, they must trigger these and other processes manually, which is not described in this guide. +Please note, however, that App users cannot deactivate the Request Module, which is why their processes are more standardized. {: .notice--warning} -Accepting the Request is done by following the instructions of the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case and providing the `id` of the Request as well as an appropriate input to build the [Response]({% link _docs_integrate/data-model-overview.md %}#response) of the initiator to the Request. In case of success, the `status` of the LocalRequest will change from `"ManualDecisionRequired"` to `"Decided"` and the `consumption.incomingRequestStatusChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) will be triggered. The Response of the initiator to the Request will be contained within the `response.content` property of the LocalRequest. By accepting the Request, a data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status` is created and the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) is triggered. The Relationship's `creationContent.response` property contains the initiator's Response to the Request. +Accepting the Request is done by following the instructions of the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case and providing the `id` of the Request as well as an appropriate input to build the [Response]({% link _docs_integrate/data-model-overview.md %}#response) of the initiator to the Request. +In case of success, the `status` of the LocalRequest will change from `"ManualDecisionRequired"` to `"Decided"` and the `consumption.incomingRequestStatusChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) will be triggered. +The Response of the initiator to the Request will be contained within the `response.content` property of the LocalRequest. +By accepting the Request, a data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status` is created and the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) is triggered. +The Relationship's `creationContent.response` property contains the initiator's Response to the Request. -It is not necessary, but you can query this Relationship by proceeding as described in the [Query Relationships]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) use case documentation, using the query parameter `template.id=`. If you decide to do this, you will receive a `result` as response from which you can read the `id` of the Relationship. +It is not necessary, but you can query this Relationship by proceeding as described in the [Query Relationships]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) use case documentation, using the query parameter `templateId=`. +If you decide to do this, you will receive a `result` as response from which you can read the `id` of the Relationship. {: .notice--info} -Note that it is of course also possible to reject the incoming Request, if the initiator does not wish to establish an active Relationship to the templator under the given conditions. In order to do this, make use of the documentation of the [Reject incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) use case. More detailed information about how to [reject]({% link _docs_integrate/requests-via-relationshiptemplates.md %}#reject) as well as how to [accept]({% link _docs_integrate/requests-via-relationshiptemplates.md %}#accept) an incoming Request can also be found in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide. +Note that it is of course also possible to reject the incoming Request, if the initiator does not wish to establish an active Relationship to the templator under the given conditions. +In order to do this, make use of the documentation of the [Reject incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) use case. +More detailed information about how to [reject]({% link _docs_integrate/requests-via-relationshiptemplates.md %}#reject) as well as how to [accept]({% link _docs_integrate/requests-via-relationshiptemplates.md %}#accept) an incoming Request can also be found in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide. {: .notice--info} #### RelationshipTemplate With ArbitraryRelationshipTemplateContent -We now consider the situation in which the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) loaded onto the initiator contains an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) in its `content` property instead of a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). In this case, the initiator does not receive an incoming Request. Nevertheless, it can initiate a Relationship with the templator by explicitly creating a data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status` based on the RelationshipTemplate. To do this, follow the instructions of the [Create Relationship with RelationshipTemplate]({% link _docs_use-cases/use-case-transport-create-relationship-with-relationshiptemplate.md %}) use case, use an [ArbitraryRelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshipcreationcontent) as `creationContent` and provide as input: +We now consider the situation in which the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) loaded onto the initiator contains an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) in its `content` property instead of a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). +In this case, the initiator does not receive an incoming Request. +Nevertheless, it can initiate a Relationship with the templator by explicitly creating a data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status` based on the RelationshipTemplate. +To do this, follow the instructions of the [Create Relationship with RelationshipTemplate]({% link _docs_use-cases/use-case-transport-create-relationship-with-relationshiptemplate.md %}) use case, use an [ArbitraryRelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshipcreationcontent) as `creationContent` and provide as input: ```jsonc { @@ -201,16 +247,23 @@ We now consider the situation in which the [RelationshipTemplate]({% link _docs_ } ``` -In case of success, the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) will be triggered and you will receive a `result` as response, which contains the created data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship). The specified ArbitraryRelationshipCreationContent is contained within the `creationContent` property of the Relationship. +In case of success, the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) will be triggered and you will receive a `result` as response, which contains the created data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship). +The specified ArbitraryRelationshipCreationContent is contained within the `creationContent` property of the Relationship. Saving the `id` of the Relationship is useful if you want to return to the created Relationship later in order to retrace changes to the Relationship. {: .notice--info} ### Initiate It as an App user -As already mentioned in the description of the [input for creating a RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#input-for-creating-a-relationshiptemplate), a RelationshipTemplateContent must be used as the value of the `content` property of the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) if you intend to use the RelationshipTemplate to establish a Relationship between the templator and an App user. Assuming that there is no Relationship between them yet, the App user receives the Request specified in the `onNewRelationship` property of the [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) after scanning the QR code associated with the RelationshipTemplate. The App user has the option of accepting or rejecting the Request. If they accept the Request appropriately, a Relationship with the templator is initiated. This means the creation of a data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status`. The Response of the App user to the Request is contained within the `creationContent.response` property of the Relationship. +As already mentioned in the description of the [input for creating a RelationshipTemplate]({% link _docs_integrate/establish-relationships.md %}#input-for-creating-a-relationshiptemplate), a RelationshipTemplateContent must be used as the value of the `content` property of the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) if you intend to use the RelationshipTemplate to establish a Relationship between the templator and an App user. +Assuming that there is no Relationship between them yet, the App user receives the Request specified in the `onNewRelationship` property of the [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) after scanning the QR code associated with the RelationshipTemplate. +The App user has the option of accepting or rejecting the Request. +If they accept the Request appropriately, a Relationship with the templator is initiated. +This means the creation of a data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status`. +The Response of the App user to the Request is contained within the `creationContent.response` property of the Relationship. -Please note that the general procedure is the same if an App user instead of a Connector wants to initiate a Relationship with the templator. The difference is that the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) does not need to contain a RelationshipTemplateContent in its `content` property if it is intended to be used by a Connector. +Please note that the general procedure is the same if an App user instead of a Connector wants to initiate a Relationship with the templator. +The difference is that the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) does not need to contain a RelationshipTemplateContent in its `content` property if it is intended to be used by a Connector. {: .notice--info} ### Undo the Initiation of a Relationship @@ -229,31 +282,47 @@ This means that previous attempts to establish an active Relationship, which wer ## Establish an Active Relationship -After the initiator has initiated the Relationship, the Integrator of the templator can accept it if they want to establish an active Relationship to the initiator. We now explain all required steps for establishing an active Relationship, including the necessary synchronization of the templator and any other Connector that may be involved at certain points in time. Please note that the synchronization can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync). +After the initiator has initiated the Relationship, the Integrator of the templator can accept it if they want to establish an active Relationship to the initiator. +We now explain all required steps for establishing an active Relationship, including the necessary synchronization of the templator and any other Connector that may be involved at certain points in time. +Please note that the synchronization can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync).
### Receive the Pending Relationship -The templator must first [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}) in order to receive the data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status` previously created by the initiator. The synchronization causes the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) to be triggered. To view the created Relationship, proceed as described in the [Query Relationships]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) use case documentation and specify `` as the value for the `template.id` query parameter. In particular, the `id` of the Relationship can be read from the `result`. +The templator must first [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}) in order to receive the data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status` previously created by the initiator. +The synchronization causes the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) to be triggered. +To view the created Relationship, proceed as described in the [Query Relationships]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) use case documentation and specify `` as the value for the `templateId` query parameter. +In particular, the `id` of the Relationship can be read from the `result`. {% include copy-notice description="Read the `id` of the Relationship from the `result` for the next step." %} ### Accept the Pending Relationship -If the templator accepts the pending Relationship, the `status` of the data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) will change from `"Pending"` to `"Active"` and therefore an active Relationship between the templator and the initiator will be established. In addition, the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) will be triggered. To accept the pending Relationship, consult the [Accept Relationship]({% link _docs_use-cases/use-case-transport-accept-relationship.md %}) use case description and specify the `id` of the Relationship. +If the templator accepts the pending Relationship, the `status` of the data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) will change from `"Pending"` to `"Active"` and therefore an active Relationship between the templator and the initiator will be established. +In addition, the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) will be triggered. +To accept the pending Relationship, consult the [Accept Relationship]({% link _docs_use-cases/use-case-transport-accept-relationship.md %}) use case description and specify the `id` of the Relationship. -For rejecting the pending Relationship and therefore not establishing an active Relationship between the templator and the initiator, take a look at the documentation of the [Reject Relationship]({% link _docs_use-cases/use-case-transport-reject-relationship.md %}) use case. By rejecting a pending [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship), its `status` changes from `"Pending"` to `"Rejected"`. This rejected Relationship can then no longer be accepted by the templator in order to establish an active Relationship. If the templator has rejected a pending Relationship and the initiator [initiates another Relationship]({% link _docs_integrate/establish-relationships.md %}#initiate-a-relationship) at a later point in time, a new Relationship is created with `"Pending"` as `status`. +For rejecting the pending Relationship and therefore not establishing an active Relationship between the templator and the initiator, take a look at the documentation of the [Reject Relationship]({% link _docs_use-cases/use-case-transport-reject-relationship.md %}) use case. +By rejecting a pending [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship), its `status` changes from `"Pending"` to `"Rejected"`. +This rejected Relationship can then no longer be accepted by the templator in order to establish an active Relationship. +If the templator has rejected a pending Relationship and the initiator [initiates another Relationship]({% link _docs_integrate/establish-relationships.md %}#initiate-a-relationship) at a later point in time, a new Relationship is created with `"Pending"` as `status`. The `status` of the previous Relationship is not changed from `"Rejected"` to `"Pending"`. This means that previous attempts to establish an active Relationship, which were then rejected by the templator, can still be viewed by executing the [Query Relationships]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) use case using the `status=Rejected` query parameter. {: .notice--info} ### Get Informed About the Acceptance of the Relationship -Assuming the initiator is a Connector, it must [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}) after the templator has accepted the Relationship. The synchronization causes the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) to be triggered as the `status` of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) has been changed from `"Pending"` to `"Active"`. Now the initiator is informed that the templator has accepted the Relationship and therefore an active Relationship has been established between them. If the initiator is an App user instead, they are informed about the acceptance of the Relationship analogously. +Assuming the initiator is a Connector, it must [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}) after the templator has accepted the Relationship. +The synchronization causes the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) to be triggered as the `status` of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) has been changed from `"Pending"` to `"Active"`. +Now the initiator is informed that the templator has accepted the Relationship and therefore an active Relationship has been established between them. +If the initiator is an App user instead, they are informed about the acceptance of the Relationship analogously.
## What's Next? -After an active Relationship between the two Identities is established, they are able to share information with each other. For example, they can exchange Messages. A possible scenario that demonstrates how a Connector can send a Message to another Identity with which it has an active Relationship is described in the [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) scenario documentation. It is also possible for both Identities involved in the Relationship to [terminate the Relationship]({% link _docs_integrate/terminate-relationships.md %}) as soon as it is no longer wanted. +After an active Relationship between the two Identities is established, they are able to share information with each other. +For example, they can exchange Messages. +A possible scenario that demonstrates how a Connector can send a Message to another Identity with which it has an active Relationship is described in the [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) scenario documentation. +It is also possible for both Identities involved in the Relationship to [terminate the Relationship]({% link _docs_integrate/terminate-relationships.md %}) as soon as it is no longer wanted. diff --git a/_docs_integrate/examples/example.config.json b/_docs_integrate/examples/example.config.json index 228f9f153..bc97b625e 100644 --- a/_docs_integrate/examples/example.config.json +++ b/_docs_integrate/examples/example.config.json @@ -10,7 +10,15 @@ }, "infrastructure": { "httpServer": { - "apiKey": " https://enmeshed.eu/operate/configuration#httpserver>" + "authentication": { + "apiKey": { + "keys": { + "": { + "key": " https://enmeshed.eu/operate/configuration#apikey>" + } + } + } + } } }, "modules": { diff --git a/_docs_integrate/exchange-files-using-attributes.md b/_docs_integrate/exchange-files-using-attributes.md index 4b013ee2e..abb455dac 100644 --- a/_docs_integrate/exchange-files-using-attributes.md +++ b/_docs_integrate/exchange-files-using-attributes.md @@ -61,21 +61,19 @@ After [uploading a File](#upload-a-file), a certain kind of [Attribute]({% link To be more precise, this is an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) that has [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) as its `value.@type`. An IdentityFileReference stores the value of the `reference.truncated` property of the File within its `value` property. By [sending a suitable Request]({% link _docs_integrate/share-attributes-with-peer.md %}#send-and-receive-the-request), this IdentityAttribute can be shared with a `peer` of an already existing [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) or in the process of [establishing a Relationship]({% link _docs_integrate/establish-relationships.md %}). -If the peer accepts the Request, a peer shared IdentityAttribute will be created for them and they will gain read access to the underlying File, that was [uploaded to the Backbone](#upload-a-file). -For the sender an own shared IdentityAttribute will be created. +If the peer accepts the Request, a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) will be created for them and they will gain read access to the underlying File, that was [uploaded to the Backbone](#upload-a-file). +For the sender, [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with their [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) will be created. -
+
## Create an IdentityFileReference After [uploading the File](#upload-a-file), an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) with an [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) as its `value.@type` and the `reference.truncated` of the uploaded [File]({% link _docs_integrate/data-model-overview.md %}#file) as its `value.value` can be created by proceeding as described in the documentation on how to [create an IdentityAttribute for yourself]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-an-identityattribute-for-yourself). -The following `content` can be used during the creation process, with its properties `validFrom`, `validTo` and `tags` being optional: +The following `content` can be used during the creation process, with its property `tags` being optional: ```jsonc { "content": { - "validFrom": "", - "validTo": "", "value": { "@type": "IdentityFileReference", "value": "" @@ -129,8 +127,8 @@ Instead, the ownership of the File needs to be transferred to the recipient. To this end, firstly the sender needs to [upload the File](#upload-a-file) to the Backbone. Then, an appropriate [TransferFileOwnershipRequestItem]({% link _docs_integrate/data-model-overview.md %}#transferfileownershiprequestitem) must be sent to the peer, who shall become the new owner of the File. If they accept it, the ownership of the File on the Backbone will be transferred to them. -Additionally, a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) will be created for the recipient, whose `content` is an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) with [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) as `value.@type`. -Moreover, this RepositoryAttribute will be shared with the sender, i.e. an own shared IdentityAttribute will be created for the recipient and a peer shared IdentityAttribute will be created for the sender. +Additionally, an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) will be created for the recipient, whose `content` is an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) with [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) as `value.@type`. +Moreover, this OwnIdentityAttribute will be shared with the sender, i.e. associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) will be created for the recipient and a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) will be created for the sender. ## Request for Transferring the Ownership of a File @@ -219,22 +217,15 @@ If the recipient agrees to receive the ownership of one of the sender's Files, t The [AcceptRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptrequestitemparameters) must be used for this. The acceptance of a TransferFileOwnershipRequestItem leads to the transfer of the ownership of the File on the Backbone. Thereby, the `ownershipToken` of the File is regenerated. -Additionally, a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) will be created for the recipient, whose `content` is an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) with [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) as `value.@type`. +Additionally, an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) will be created for the recipient, whose `content` is an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) with [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) as `value.@type`. +If the File has `tags`, the IdentityAttribute will have the same `tags`. The `value` of the IdentityFileReference is the value of `reference.truncated` of the File that is now owned by the recipient. Also, if the File has any `tags`, they will become `tags` of the IdentityAttribute. -Moreover, the newly created RepositoryAttribute of the recipient will be shared with the sender, i.e. an own shared IdentityAttribute will be created for the recipient. +Moreover, the newly created OwnIdentityAttribute of the recipient will be shared with the sender, i.e. associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) will be created for the recipient. Based on this, an appropriate AcceptResponseItem of type [TransferFileOwnershipAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#transferfileownershipacceptresponseitem) is generated. -It contains the `id` and the `content` of the created own shared IdentityAttribute in its `attributeId` and `attribute` property, respectively. +It contains the `id` and the `content` of the OwnIdentityAttribute in its `attributeId` and `attribute` property, respectively. This ResponseItem will appear within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for transferring the ownership of Files, which will be sent back to the sender. -In case no `ownershipToken` was specified in the TransferFileOwnershipRequestItem, the actual ownership of the File that was uploaded to the Backbone does not change. -Instead, accepting a TransferFileOwnershipRequestItem downloads the corresponding File and uploads it again to the Backbone, such that the recipient is its owner. -The created IdentityAttributes with `value.@type` IdentityFileReference references this newly uploaded File. -Consequently, after [receiving the Response](#receive-the-response-to-the-request), the File that was originally uploaded by the sender lost its meaning and can be [deleted]({% link _docs_use-cases/use-case-transport-delete-file.md %}). -Due to this workaround, it is not recommended to send a TransferFileOwnershipRequestItem without specifying an `ownershipToken`. -Thus, in the next major version the `ownershipToken` will be a mandatory property of the TransferFileOwnershipRequestItem. -{: .notice--warning} - ### Reject a TransferFileOwnershipRequestItem Even if the recipient accepts the Request for transferring the ownership of Files as a whole, it may decide not to accept the ownership of all of the sender's Files. @@ -256,8 +247,8 @@ To view the Response to the Request, proceed as described in the [Query outgoing The Integrator of the sender can now get the Response of the recipient from the `response.content` property of the result. In the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) is a [TransferFileOwnershipAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#transferfileownershipacceptresponseitem) for each accepted TransferFileOwnershipRequestItem and a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) for each rejected TransferFileOwnershipRequestItem included. -Note that each accepted TransferFileOwnershipRequestItem leads to the creation of an appropriate [peer shared IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) of the sender. -The `content` and `id` of the LocalAttribute are the underlying `attribute` and `attributeId` of the TransferFileOwnershipAcceptResponseItem, respectively. +Note that each accepted TransferFileOwnershipRequestItem leads to the creation of an appropriate [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) of the sender. +Its `content` and `id` are the underlying `attribute` and `attributeId` of the TransferFileOwnershipAcceptResponseItem, respectively. In case of an error, [ErrorResponseItems]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) can also be included in the Response. If the Request for transferring the ownership of Files contains a RequestItemGroup in its `items` property, the Response to this Request contains a corresponding [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) in its `items` property. diff --git a/_docs_integrate/exchange-messages.md b/_docs_integrate/exchange-messages.md index 0d1b2caa3..a6a09a6ab 100644 --- a/_docs_integrate/exchange-messages.md +++ b/_docs_integrate/exchange-messages.md @@ -27,19 +27,23 @@ required_by: -The Connector can send and receive Messages with attachments using REST requests and file IDs, which are first uploaded and encrypted on the Platform. Messages can be queried and downloaded, and the Connector pulls for new Messages periodically. +The Connector can send and receive Messages with attachments using REST requests and file IDs, which are first uploaded and encrypted on the Platform. +Messages can be queried and downloaded, and the Connector pulls for new Messages periodically. {% include properties_list.html %} -In order to send Messages to recipients, a REST request can be sent with the given `recipients` and Message `content`. Different Message content structures are possible and defined in the chapter Data Structures. Additionally, an array of file ids can be added for property `attachments` in order to send attachments. +In order to send Messages to recipients, a REST request can be sent with the given `recipients` and Message `content`. +Different Message content structures are possible and defined in the chapter Data Structures. +Additionally, an array of file ids can be added for property `attachments` in order to send attachments. ![Send Message Sequence Diagram]({{ '/assets/diagrams/integrate/Connector_SendMessage.png' | relative_url }} "Send Message") ## Upload Files -In order to submit attachments/files via Message, they have to be first uploaded to the Connector. The files are then encrypted and uploaded to the Platform, which results in a FileId for every file. +In order to submit attachments/files via Message, they have to be first uploaded to the Connector. +The files are then encrypted and uploaded to the Platform, which results in a FileId for every file. These FileIds can then be used as attachments to send Messages with attachments. ## Get Messages @@ -54,4 +58,5 @@ The metadata of attachments can be found within the Message, the actual files/bi ## Receive Messages -The Connector pulls occasionally for new Messages from the Platform and temporarily stores them in the database. They can then be fetched by the corresponding business systems by the REST API (pull) or by the defined HTTP endpoint (push). +The Connector pulls occasionally for new Messages from the Platform and temporarily stores them in the database. +They can then be fetched by the corresponding business systems by the REST API (pull) or by the defined HTTP endpoint (push). diff --git a/_docs_integrate/faq.md b/_docs_integrate/faq.md index 836efb8bd..d642f7e1d 100644 --- a/_docs_integrate/faq.md +++ b/_docs_integrate/faq.md @@ -21,7 +21,8 @@ required_by: # End automatic generation --- -Welcome to our FAQ page! Here, you'll find answers to the most common questions about enmeshed. If you're looking for quick and straightforward information, you've come to the right place. +Welcome to our FAQ page! Here, you'll find answers to the most common questions about enmeshed. +If you're looking for quick and straightforward information, you've come to the right place. # Common questions @@ -33,4 +34,5 @@ A description of enmeshed can be found on the [main page]({% link index.md %}#wh ## When I scan the QR code, why do I get the error "error.relationshipTemplateProcessedModule.relationshipTemplateNotSupported"? -It seems the wrapper [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) around the RequestItems in the RelationshipTemplate is missing. If the RelationshipTemplate is intended for a User of the enmeshed App (which is the primary use-case), the wrapper RelationshipTemplateContent has to be used. +It seems the wrapper [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) around the RequestItems in the RelationshipTemplate is missing. +If the RelationshipTemplate is intended for a User of the enmeshed App (which is the primary use-case), the wrapper RelationshipTemplateContent has to be used. diff --git a/_docs_integrate/integration-example.md b/_docs_integrate/integration-example.md index f8e6352f0..affa1f42f 100644 --- a/_docs_integrate/integration-example.md +++ b/_docs_integrate/integration-example.md @@ -42,7 +42,8 @@ You need to replace them with values before you send the Requests. - If you want to use your own Connector for executing the examples: - [Install the Connector]({% link _docs_operate/setup-with-docker-compose.md %}) - - Make sure the [Sync Module]({% link _docs_operate/modules.md %}#sync) and the [Server-Sent Events Module]({% link _docs_operate/modules.md %}#sse) are disabled (because in this tutorial we will synchronize manually via the HTTP endpoint). We are also neither utilizing the [Webhooks Module]({% link _docs_operate/modules.md %}#webhooks) nor the [Message Broker Publisher Module]({% link _docs_operate/modules.md %}#messagebrokerpublisher), even though using one of them is recommended in productive use. + - Make sure the [Sync Module]({% link _docs_operate/modules.md %}#sync) and the [Server-Sent Events Module]({% link _docs_operate/modules.md %}#sse) are disabled (because in this tutorial we will synchronize manually via the HTTP endpoint). + We are also neither utilizing the [Webhooks Module]({% link _docs_operate/modules.md %}#webhooks) nor the [Message Broker Publisher Module]({% link _docs_operate/modules.md %}#messagebrokerpublisher), even though using one of them is recommended in productive use. - Make sure the [docs are enabled]({% link _docs_operate/configuration.md %}#corehttpapi) for the documentation route to work - Get the API key that was configured during installation of the Connector (it needs to be sent in the `X-API-KEY` header of every HTTP Request) - You need the [enmeshed App]({% link _docs_use/install-the-app.md %}) with a minimum version of `4.0.0` installed on your mobile device. @@ -64,7 +65,7 @@ It in turn accepts the Relationship, which results in an active Relationship. Firstly, let's create a display name for our Connector. While communicating with the other Identity in the subsequent steps, we will choose to share this display name. Technically, for this we need to create an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) with a value of type [DisplayName]({% link _docs_integrate/attribute-values.md %}#displayname) for our Connector. -To do so, execute `POST /api/v2/Attributes` with the following payload: +To do so, execute `POST /api/core/v1/Attributes` with the following payload: ```json { @@ -77,9 +78,10 @@ To do so, execute `POST /api/v2/Attributes` with the following payload: } ``` -{% include rapidoc api_route_regex="^post /api/v2/Attributes$" %} +{% include rapidoc api_route_regex="^post /api/core/v1/Attributes$" %} -{% include copy-notice description="Save the `id` and the `owner` of the Attribute that you can find in the response. You will need it in the next step." %} +{% include copy-notice description="Save the `id` and the `owner` of the Attribute that you can find in the response. +You will need it in the next step." %} ### Connector: Test your Request's Validity @@ -109,7 +111,7 @@ Let's assume the Connector needs to know the given name and surname of its conta "value": "Demo Connector of integration example" } }, - "sourceAttributeId": "" + "attributeId": "" } ] }, @@ -148,9 +150,10 @@ Let's assume the Connector needs to know the given name and surname of its conta } ``` -Before we actually create the RelationshipTemplate, we want to ensure the validity of the Request and its items. To do so, execute `POST /api/v2/Requests/Outgoing/Validate` with the Request. +Before we actually create the RelationshipTemplate, we want to ensure the validity of the Request and its items. +To do so, execute `POST /api/core/v1/Requests/Outgoing/Validate` with the Request. -{% include rapidoc api_route_regex="^post /api/v2/Requests/Outgoing/Validate$" %} +{% include rapidoc api_route_regex="^post /api/core/v1/Requests/Outgoing/Validate$" %} Even though the Requests are validated during the RelationshipTemplate creation, you should not skip this step, as it gives you additional information in case of validation errors. {: .notice--info} @@ -158,7 +161,7 @@ Even though the Requests are validated during the RelationshipTemplate creation, ### Connector: Create a RelationshipTemplate If the Connector states your Request as valid, we can create the RelationshipTemplate. -To do so, we use the `content` we just validated in `POST /api/v2/RelationshipTemplates/Own`. +To do so, we use the `content` we just validated in `POST /api/core/v1/RelationshipTemplates/Own`. Furthermore, we specify an expiration date, which is located in the future, and restrict the access to a single allocation. ```jsonc @@ -175,38 +178,44 @@ Furthermore, we specify an expiration date, which is located in the future, and } ``` -{% include rapidoc api_route_regex="^post /api/v2/RelationshipTemplates/Own$" %} +{% include rapidoc api_route_regex="^post /api/core/v1/RelationshipTemplates/Own$" %} -{% include copy-notice description="Save the `id` of the RelationshipTemplate that you can find in the Response. You will need it in the next step." %} +{% include copy-notice description="Save the `id` of the RelationshipTemplate that you can find in the Response. +You will need it in the next step." %} ### Connector: Create a QR code for the RelationshipTemplate Now, to allow the App to retrieve the RelationshipTemplate, we create a QR code, that can be scanned by the App. -For this, execute the `GET /api/v2/RelationshipTemplates/{id}` route (Accept Header: `image/png`) and use the `id` of the RelationshipTemplate from the previous step as the value for `id`. +For this, execute the `GET /api/core/v1/RelationshipTemplates/{id}` route (Accept Header: `image/png`) and use the `id` of the RelationshipTemplate from the previous step as the value for `id`. -{% include rapidoc api_route_regex="^get /api/v2/RelationshipTemplates/{id}$" %} +{% include rapidoc api_route_regex="^get /api/core/v1/RelationshipTemplates/{id}$" %} ### App: Initiate a Relationship -When the App is opened and no profile has been created yet, the user must create one. From the profile overview, the user can add a new contact using the "Add Contact" option. A QR code must be scanned to complete the process. +When the App is opened and no profile has been created yet, the user must create one. +From the profile overview, the user can add a new contact using the "Add Contact" option. +A QR code must be scanned to complete the process. Scanning the QR code should result in a screen similar to the one below, where you can see the information that you added as `content` to the RelationshipTemplate. ![Add contact screen]({{ '/assets/images/add-contact-screen.jpg' | relative_url }}){: width="40%"} -Finally, fill out the required fields and click on "Add contact" to send the Relationship. This will initiate a Relationship between the App and the Connector. This Relationship has the status `Pending` for now. +Finally, fill out the required fields and click on "Add contact" to send the Relationship. +This will initiate a Relationship between the App and the Connector. +This Relationship has the status `Pending` for now. ### Connector: Accept the Relationship In order to move the Relationship into the `Active` state, we now need to [accept the Relationship]({% link _docs_use-cases/use-case-transport-accept-relationship.md %}) with the Connector. To do so, we [synchronize updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}), which will fetch all changes that occurred since the last time this endpoint was executed. -{% include rapidoc api_route_regex="^post /api/v2/Account/Sync$" %} +{% include rapidoc api_route_regex="^post /api/core/v1/Account/Sync$" %} The synchronization causes the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) to be triggered, which should be listened to in order to get the Relationship in status `Pending`. -We can also [get the Relationship]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) via `GET /api/v2/Relationships`. Should you be repeating this tutorial, you could e.g. filter by the `id` of the RelationshipTemplate from earlier via `GET /api/v2/Relationships?template.id=` if you use a different RelationshipTemplate. +We can also [get the Relationship]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) via `GET /api/core/v1/Relationships`. +Should you be repeating this tutorial, you could e.g. filter by the `id` of the RelationshipTemplate from earlier via `GET /api/core/v1/Relationships?templateId=` if you use a different RelationshipTemplate. -{% include rapidoc api_route_regex="^get /api/v2/Relationships$" %} +{% include rapidoc api_route_regex="^get /api/core/v1/Relationships$" %} Example: @@ -223,15 +232,17 @@ Example: } ``` -{% include copy-notice description="Save the `id` of the Relationship (`REL_________________`) and use it as input to the `PUT /api/v2/Relationships/{id}/Accept` route. You can leave that Request body as it is." %} +{% include copy-notice description="Save the `id` of the Relationship (`REL_________________`) and use it as input to the `PUT /api/core/v1/Relationships/{id}/Accept` route. +You can leave that Request body as it is." %} -{% include rapidoc api_route_regex="^put /api/v2/Relationships/{id}/Accept$" %} +{% include rapidoc api_route_regex="^put /api/core/v1/Relationships/{id}/Accept$" %} Now the Relationship is in the `Active` state, so we can start to communicate with the opposite Identity, which we will do in the next part of this tutorial. For this, we will need the `address` of that [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). It can be found in the Response, when accepting the Relationship. -{% include copy-notice description="Save the `peer` property of the Response (`did:e:_________________`). You will need it in the next step." %} +{% include copy-notice description="Save the `peer` property of the Response (`did:e:_________________`). +You will need it in the next step." %} ## Sending and Receiving Messages @@ -257,7 +268,7 @@ Further, the `subject` and `body` properties can be modified with some custom `c } ``` -{% include rapidoc api_route_regex="^post /api/v2/Messages$" %} +{% include rapidoc api_route_regex="^post /api/core/v1/Messages$" %} After having sent the Message, you should receive a push notification on your phone. Open the enmeshed App, navigate to "Contacts" and select the Relationship. @@ -272,17 +283,20 @@ Then, tap on "New Message", enter a subject and body and tap on "Send". In order to fetch the Message, we need to synchronize the Connector with the Backbone again. -{% include rapidoc api_route_regex="^post /api/v2/Account/Sync$" %} +{% include rapidoc api_route_regex="^post /api/core/v1/Account/Sync$" %} -After syncing, all Messages can be displayed with the `GET /api/v2/Messages` route. Additionally, the [Event]({% link _docs_integrate/connector-events.md %}) `transport.messageReceived` is triggered after a Message is received. If you use the [Message Broker Publisher Module]({% link _docs_operate/modules.md %}#messagebrokerpublisher) or the [Webhooks Module]({% link _docs_operate/modules.md %}#webhooks) to subscribe to this event, you will receive the information whenever a new Message arrives. +After syncing, all Messages can be displayed with the `GET /api/core/v1/Messages` route. +Additionally, the [Event]({% link _docs_integrate/connector-events.md %}) `transport.messageReceived` is triggered after a Message is received. +If you use the [Message Broker Publisher Module]({% link _docs_operate/modules.md %}#messagebrokerpublisher) or the [Webhooks Module]({% link _docs_operate/modules.md %}#webhooks) to subscribe to this event, you will receive the information whenever a new Message arrives. -{% include rapidoc api_route_regex="^get /api/v2/Messages$" %} +{% include rapidoc api_route_regex="^get /api/core/v1/Messages$" %} The response should contain a Message with the `content` you entered in the App. ## What's next? -Now that you have successfully established a Relationship and exchanged Messages, you can further explore the enmeshed API. You can for example: +Now that you have successfully established a Relationship and exchanged Messages, you can further explore the enmeshed API. +You can for example: - explore the [enmeshed data model]({% link _docs_integrate/data-model-overview.md %}) and learn more about the objects you used during this tutorial and the objects you will encounter in the future - learn how to send [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) with your established Relationship diff --git a/_docs_integrate/manage-identitymetadata.md b/_docs_integrate/manage-identitymetadata.md index 9dab381da..1b90f8b41 100644 --- a/_docs_integrate/manage-identitymetadata.md +++ b/_docs_integrate/manage-identitymetadata.md @@ -63,8 +63,8 @@ The following table provides an overview of the differences between IdentityAttr | Managing Identity | It can be managed by both an Integrator of a Connector or an App user. | It can only be managed by an Integrator of a Connector. | | Possible types of `value` | There is a predefined list of permitted [IdentityAttribute value types]({% link _docs_integrate/attribute-values.md %}#identity-attributes). | It must only be compatible with the JSON data types `string`, `number`, `boolean`, `object`, `array` and `null`. | | Kind of storage | Local storage within the `content` property of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). The LocalAttribute can be identified by its `id`, which has `ATT` as prefix. | Local storage within an [IdentityMetadata]({% link _docs_integrate/data-model-overview.md %}#identitymetadata) data object. It can be identified by its `id`, which has `IDM` as prefix, or alternatively by its combination of `reference` and `key`. | -| Storability for own Identity | Stored as a [RepositoryAttribute]({% link _docs_integrate/attribute-introduction.md %}#repositoryattributes). When [sharing a RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-share-a-repositoryattribute.md %}), an [own shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes) is created as a copy. | Stored as an [IdentityMetadata]({% link _docs_integrate/data-model-overview.md %}#identitymetadata) that has the `address` of the own [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) as its `reference`. | -| Storability for `peer` of [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) | Stored as a [peer shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes). Cannot be created manually, but is created automatically if the `peer` of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) has [shared their RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-share-a-repositoryattribute.md %}). | Stored as an [IdentityMetadata]({% link _docs_integrate/data-model-overview.md %}#identitymetadata) that has the `peer` of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) as its `reference`. | +| Storability for own Identity | Stored as an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute). When [sharing an OwnIdentityAttribute]({% link _docs_use-cases/use-case-consumption-share-an-ownidentityattribute.md %}), associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) are created. | Stored as an [IdentityMetadata]({% link _docs_integrate/data-model-overview.md %}#identitymetadata) that has the `address` of the own [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) as its `reference`. | +| Storability for `peer` of [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) | Stored as a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute). Cannot be created manually, but is created automatically if the `peer` of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) has [shared their OwnIdentityAttribute]({% link _docs_use-cases/use-case-consumption-share-an-ownidentityattribute.md %}). | Stored as an [IdentityMetadata]({% link _docs_integrate/data-model-overview.md %}#identitymetadata) that has the `peer` of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) as its `reference`. | | Set of features | Comprehensive feature set which, in addition to [creating]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-an-identityattribute-for-yourself), [updating]({% link _docs_integrate/update-attributes-by-succession.md %}#succeeding-own-identityattributes), [getting]({% link _docs_use-cases/use-case-consumption-get-attribute.md %}) and [deleting]({% link _docs_integrate/delete-attributes.md %}) an IdentityAttribute, also includes [sharing with peer]({% link _docs_integrate/share-attributes-with-peer.md %}), [reading from peer]({% link _docs_integrate/read-attributes-from-peer.md %}), [creating for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) and [proposing to peer]({% link _docs_integrate/propose-attributes-to-peer.md %}). | Minimal feature set that includes [creating and updating]({% link _docs_use-cases/use-case-consumption-upsert-identitymetadata.md %}), [getting]({% link _docs_use-cases/use-case-consumption-get-identitymetadata.md %}) and [deleting]({% link _docs_use-cases/use-case-consumption-delete-identitymetadata.md %}) IdentityMetadata. | | Kind of update of `value` | The `value` is [updated by succession]({% link _docs_integrate/update-attributes-by-succession.md %}#succeeding-own-identityattributes) and the history of changes is preserved. | The `value` is [updated inplace]({% link _docs_use-cases/use-case-consumption-upsert-identitymetadata.md %}) and the history of changes is lost. | diff --git a/_docs_integrate/migration-from-v4-to-v5.md b/_docs_integrate/migration-from-v4-to-v5.md index 5df8be42b..010b4851a 100644 --- a/_docs_integrate/migration-from-v4-to-v5.md +++ b/_docs_integrate/migration-from-v4-to-v5.md @@ -35,36 +35,62 @@ More [detailed explanations]({% link _docs_integrate/migration-from-v4-to-v5.md ### Connector Setup -- The data from the database that was used by the Connector of the former version is outdated. This is because the [format of addresses has changed to DIDs]({% link _docs_integrate/migration-from-v4-to-v5.md %}#dids-as-addresses), for example. For this reason, the old data must be deleted. Alternatively, the database can be deleted as a whole and [set up again]({% link _docs_operate/setup-with-docker-compose.md %}). +- The data from the database that was used by the Connector of the former version is outdated. + This is because the [format of addresses has changed to DIDs]({% link _docs_integrate/migration-from-v4-to-v5.md %}#dids-as-addresses), for example. + For this reason, the old data must be deleted. + Alternatively, the database can be deleted as a whole and [set up again]({% link _docs_operate/setup-with-docker-compose.md %}). - The [image](https://github.com/nmshd/connector?tab=readme-ov-file#connector) used to run the Connector must be updated to version 5. - Some changes must be made to the [configuration]({% link _docs_operate/configuration.md %}) of the Connector. - - It must be ensured that a [Backbone](https://github.com/nmshd/backbone/tags) is used which is compatible with version 5 of the Connector. This means that a Backbone of version 6 must be used. Therefore, specify appropriate Backbone credentials in the fields `transportLibrary.baseUrl`, `transportLibrary.platformClientId` and `transportLibrary.platformClientSecret` of the [configuration]({% link _docs_operate/configuration.md %}#transportlibrary). The URL `/api/v1/version` can be accessed to validate the version of the Backbone. - - The AutoAcceptRelationshipCreationChangesModule has been renamed to the [AutoAcceptPendingRelationshipsModule]({% link _docs_operate/modules.md %}#autoacceptpendingrelationships), because the [RelationshipChanges have been removed]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-relationshipchanges). For this reason, the `modules.autoAcceptRelationshipCreationChanges` field must be renamed to `modules.autoAcceptPendingRelationships` in the [configuration]({% link _docs_operate/configuration.md %}#autoacceptpendingrelationships) if it was previously specified. In addition, it must be made sure that the `modules.autoAcceptRelationshipCreationChanges.responseContent` field is removed. - - In version 4, the WebhooksV2Module module has already been renamed to the [WebhooksModule]({% link _docs_operate/modules.md %}#webhooks). However, backwards compatibility was ensured. With the migration to version 5, the `modules.webhooksV2` field must be renamed to `modules.webhooks` in the [configuration]({% link _docs_operate/configuration.md %}#webhooks) if it was previously specified and the migration to the WebhooksModule has not yet taken place. + - It must be ensured that a [Backbone](https://github.com/nmshd/backbone/tags) is used which is compatible with version 5 of the Connector. + This means that a Backbone of version 6 must be used. + Therefore, specify appropriate Backbone credentials in the fields `transportLibrary.baseUrl`, `transportLibrary.platformClientId` and `transportLibrary.platformClientSecret` of the [configuration]({% link _docs_operate/configuration.md %}#transportlibrary). + The URL `/api/v1/version` can be accessed to validate the version of the Backbone. + - The AutoAcceptRelationshipCreationChangesModule has been renamed to the [AutoAcceptPendingRelationshipsModule]({% link _docs_operate/modules.md %}#autoacceptpendingrelationships), because the [RelationshipChanges have been removed]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-relationshipchanges). + For this reason, the `modules.autoAcceptRelationshipCreationChanges` field must be renamed to `modules.autoAcceptPendingRelationships` in the [configuration]({% link _docs_operate/configuration.md %}#autoacceptpendingrelationships) if it was previously specified. + In addition, it must be made sure that the `modules.autoAcceptRelationshipCreationChanges.responseContent` field is removed. + - In version 4, the WebhooksV2Module module has already been renamed to the [WebhooksModule]({% link _docs_operate/modules.md %}#webhooks). + However, backwards compatibility was ensured. + With the migration to version 5, the `modules.webhooksV2` field must be renamed to `modules.webhooks` in the [configuration]({% link _docs_operate/configuration.md %}#webhooks) if it was previously specified and the migration to the WebhooksModule has not yet taken place. ### Removed and Changed Data Structures - The [RelationshipChanges have been removed]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-relationshipchanges). - This has led to the removal of the `changes` property of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) and the addition of the `creationContent` and `auditLog` properties to the Relationship. - - In particular, the use cases for accepting and rejecting RelationshipChanges had to be removed. With the use cases [Accept Relationship]({% link _docs_use-cases/use-case-transport-accept-relationship.md %}) and [Reject Relationship]({% link _docs_use-cases/use-case-transport-reject-relationship.md %}), two [new use cases]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-relationshipchanges-1) have been added that now provide these functionalities. - - For this reason, the route `PUT /api/v2/Relationships/{id}/Accept` must be executed instead of the route `PUT /api/v2/Relationships/{id}/Changes/{changeId}/Accept` and the route `PUT /api/v2/Relationships/{id}/Reject` must be executed instead of the route `PUT /api/v2/Relationships/{id}/Changes/{changeId}/Reject` when using the Connector. In contrast to the old Connector routes, a request body no longer needs to be provided when using the new Connector routes. -- Non-standard `content` of a [Message]({% link _docs_integrate/data-model-overview.md %}#message), non-standard `content` of a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) and non-standard `creationContent` of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) is now typed. The [new mandatory wrappers]({% link _docs_integrate/migration-from-v4-to-v5.md %}#new-mandatory-wrappers-for-non-standard-content-of-messages-relationshiptemplates-and-relationships) are [ArbitraryMessageContent]({% link _docs_integrate/data-model-overview.md %}#arbitrarymessagecontent), [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) and [ArbitraryRelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshipcreationcontent), respectively, which must now be used. + - In particular, the use cases for accepting and rejecting RelationshipChanges had to be removed. + With the use cases [Accept Relationship]({% link _docs_use-cases/use-case-transport-accept-relationship.md %}) and [Reject Relationship]({% link _docs_use-cases/use-case-transport-reject-relationship.md %}), two [new use cases]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-relationshipchanges-1) have been added that now provide these functionalities. + - For this reason, the route `PUT /api/v2/Relationships/{id}/Accept` must be executed instead of the route `PUT /api/v2/Relationships/{id}/Changes/{changeId}/Accept` and the route `PUT /api/v2/Relationships/{id}/Reject` must be executed instead of the route `PUT /api/v2/Relationships/{id}/Changes/{changeId}/Reject` when using the Connector. + In contrast to the old Connector routes, a request body no longer needs to be provided when using the new Connector routes. +- Non-standard `content` of a [Message]({% link _docs_integrate/data-model-overview.md %}#message), non-standard `content` of a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) and non-standard `creationContent` of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) is now typed. + The [new mandatory wrappers]({% link _docs_integrate/migration-from-v4-to-v5.md %}#new-mandatory-wrappers-for-non-standard-content-of-messages-relationshiptemplates-and-relationships) are [ArbitraryMessageContent]({% link _docs_integrate/data-model-overview.md %}#arbitrarymessagecontent), [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) and [ArbitraryRelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshipcreationcontent), respectively, which must now be used. - The `mustBeAccepted` property of the [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) has been removed, which is why this [property must be removed if RequestItemGroups were used]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-the-mustbeaccepted-property-of-the-requestitemgroup). -- The type of the `owner` property of the [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) has changed. The [values specified for this property must therefore be adjusted if ThirdPartyRelationshipAttributeQueries were used]({% link _docs_integrate/migration-from-v4-to-v5.md %}#changed-type-of-the-owner-property-of-the-thirdpartyrelationshipattributequery). +- The type of the `owner` property of the [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) has changed. + The [values specified for this property must therefore be adjusted if ThirdPartyRelationshipAttributeQueries were used]({% link _docs_integrate/migration-from-v4-to-v5.md %}#changed-type-of-the-owner-property-of-the-thirdpartyrelationshipattributequery). ### Changed Behavior of Known Features -- The [Synchronize updates of Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}) use case, which corresponds to the Connector route `POST /api/v2/Account/Sync`, no longer returns any content. Previously, new Messages or changes to Relationships were shown in the response after the use case was executed. As the [synchronization with the Backbone no longer returns anything]({% link _docs_integrate/migration-from-v4-to-v5.md %}#synchronization-with-backbone-returns-no-content-anymore), the corresponding [events]({% link _docs_integrate/connector-events.md %}) must be listened to instead in order to be informed about new Messages or changes to Relationships. -- Stricter [validation of Requests]({% link _docs_integrate/migration-from-v4-to-v5.md %}#validation-of-requests) has been added. Therefore, changes will probably have to be made to existing Request flows. Both [sending Requests]({% link _docs_integrate/migration-from-v4-to-v5.md %}#sending-of-requests) and [responding to Requests]({% link _docs_integrate/migration-from-v4-to-v5.md %}#responding-to-requests) are affected. +- The [Synchronize updates of Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}) use case, which corresponds to the Connector route `POST /api/v2/Account/Sync`, no longer returns any content. + Previously, new Messages or changes to Relationships were shown in the response after the use case was executed. + As the [synchronization with the Backbone no longer returns anything]({% link _docs_integrate/migration-from-v4-to-v5.md %}#synchronization-with-backbone-returns-no-content-anymore), the corresponding [events]({% link _docs_integrate/connector-events.md %}) must be listened to instead in order to be informed about new Messages or changes to Relationships. +- Stricter [validation of Requests]({% link _docs_integrate/migration-from-v4-to-v5.md %}#validation-of-requests) has been added. + Therefore, changes will probably have to be made to existing Request flows. + Both [sending Requests]({% link _docs_integrate/migration-from-v4-to-v5.md %}#sending-of-requests) and [responding to Requests]({% link _docs_integrate/migration-from-v4-to-v5.md %}#responding-to-requests) are affected. ### Changes to Error Codes, Connector Routes and Events -Changes have been made to the [error codes]({% link _docs_integrate/error-codes.md %}), [use cases]({% link _docs_integrate/use-cases.md %}) and [events]({% link _docs_integrate/connector-events.md %}). Naturally, the Connector routes associated with the changed use cases of the Runtime are often affected as well. All these changes may lead to unexpected behavior when updating from version 4 to version 5. In this case, it is worth taking a look at the following lists: +Changes have been made to the [error codes]({% link _docs_integrate/error-codes.md %}), [use cases]({% link _docs_integrate/use-cases.md %}) and [events]({% link _docs_integrate/connector-events.md %}). +Naturally, the Connector routes associated with the changed use cases of the Runtime are often affected as well. +All these changes may lead to unexpected behavior when updating from version 4 to version 5. +In this case, it is worth taking a look at the following lists: - An overview of the [removed and changed error codes]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removed-and-changed-error-codes) can be found below. - An overview of the [removed, changed and added use cases]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removed-changed-and-added-use-cases) with regard to their impact on the Connector routes can be found below. - - In particular, it must be noted that the [use case of getting shared versions of a RepositoryAttribute has been renamed]({% link _docs_integrate/migration-from-v4-to-v5.md %}#renaming-of-the-use-case-getsharedversionsofrepositoryattribute-to-getsharedversionsofattribute). The [Get shared versions of an Attribute]({% link _docs_use-cases/use-case-consumption-get-shared-versions-of-an-attribute.md %}) use case must now be executed instead. Please note, however, that the associated Connector route `GET /api/v2/Attributes/{id}/Versions/Shared` has not changed. - - With the execution of the Connector route `POST /api/v2/Attributes`, which corresponds to the execution of the associated [Create a RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-create-a-repositoryattribute.md %}) use case, an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) can be created for yourself. When executing this Connector route, the fields `content.@type` and `content.owner` may no longer be specified as input. This is due to the fact that previously only the IdentityAttribute as `@type` and the own address as the value of the `owner` property of the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) to be created for yourself came into question anyway. Therefore, [less input needs to be provided when executing the use case to create a RepositoryAttribute]({% link _docs_integrate/migration-from-v4-to-v5.md %}#less-input-needed-for-the-use-case-createrepositoryattribute). + - In particular, it must be noted that the [use case of getting shared versions of a RepositoryAttribute has been renamed]({% link _docs_integrate/migration-from-v4-to-v5.md %}#renaming-of-the-use-case-getsharedversionsofrepositoryattribute-to-getsharedversionsofattribute). + The [Get shared versions of an Attribute]({% link _docs_use-cases/use-case-consumption-get-versions-of-attribute-shared-with-peer.md %}) use case must now be executed instead. + Please note, however, that the associated Connector route `GET /api/v2/Attributes/{id}/Versions/Shared` has not changed. + - With the execution of the Connector route `POST /api/v2/Attributes`, which corresponds to the execution of the associated [Create a RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-create-an-ownidentityattribute.md %}) use case, an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) can be created for yourself. + When executing this Connector route, the fields `content.@type` and `content.owner` may no longer be specified as input. + This is due to the fact that previously only the IdentityAttribute as `@type` and the own address as the value of the `owner` property of the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) to be created for yourself came into question anyway. + Therefore, [less input needs to be provided when executing the use case to create a RepositoryAttribute]({% link _docs_integrate/migration-from-v4-to-v5.md %}#less-input-needed-for-the-use-case-createrepositoryattribute). - An overview of the [renamed and added events]({% link _docs_integrate/migration-from-v4-to-v5.md %}#renamed-and-added-events) can be found below. ## Detailed Explanations @@ -73,7 +99,10 @@ The aspects to be taken into account when migrating to version 5, which were bri ### DIDs as Addresses -Each [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) within enmeshed has a unique `address` for identification. The format of this [address]({% link _docs_explore/60-addresses.md %}) has changed from `<3-character realm><32- or 33-character base58-encoded string>` to `did:e::dids:<22-character lowercase hexadecimal string>`. Accordingly, the `realm` property of the Identity was removed as well. Furthermore, the two error codes `error.runtime.MultiAccount.WrongRealm` and `error.transport.identity.realmLength` have been removed. +Each [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) within enmeshed has a unique `address` for identification. +The format of this [address]({% link _docs_explore/60-addresses.md %}) has changed from `<3-character realm><32- or 33-character base58-encoded string>` to `did:e::dids:<22-character lowercase hexadecimal string>`. +Accordingly, the `realm` property of the Identity was removed as well. +Furthermore, the two error codes `error.runtime.MultiAccount.WrongRealm` and `error.transport.identity.realmLength` have been removed. ### Removal of RelationshipChanges @@ -89,12 +118,15 @@ In contrast to the new [RelationshipAuditLogEntries]({% link _docs_integrate/dat For example, there was the RelationshipChange with `"Creation"` as `type`, which stored the `content` required for the initial creation of a pending Relationship within its `request` property. To activate this pending Relationship, the other Identity involved in the Relationship had to accept the RelationshipChange. Alternatively, it could decide not to establish the Relationship by rejecting the RelationshipChange. -The two use cases of accepting and rejecting RelationshipChanges have been removed. Instead, the content required to initially create a pending Relationship is now stored in the newly introduced `creationContent` property of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) itself. +The two use cases of accepting and rejecting RelationshipChanges have been removed. +Instead, the content required to initially create a pending Relationship is now stored in the newly introduced `creationContent` property of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) itself. It fulfills the same role as the previous `request.content` property of the RelationshipChange with the difference that it now has the type [RelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#relationshipcreationcontent) instead of RelationshipCreationChangeRequestContent if a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) whose `content` is of the type [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) was used for the initial creation of the pending Relationship. Otherwise, the type of the `creationContent` property of the Relationship is [ArbitraryRelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshipcreationcontent). Before the introduction of the [new mandatory wrappers for non-standard content]({% link _docs_integrate/migration-from-v4-to-v5.md %}#new-mandatory-wrappers-for-non-standard-content-of-messages-relationshiptemplates-and-relationships), such arbitrary `creationContent` of the Relationship was stored in the `request.content` property of the RelationshipChange by also permitting the storage of data of unknown type. -The functionalities of the old two use cases of accepting and rejecting RelationshipChanges are now provided by the two new use cases [Accept Relationship]({% link _docs_use-cases/use-case-transport-accept-relationship.md %}) and [Reject Relationship]({% link _docs_use-cases/use-case-transport-reject-relationship.md %}). Accordingly, the Connector routes using RelationshipChanges were replaced. When using the two new Connector routes, which work directly on the Relationships, a request body no longer needs to be provided. +The functionalities of the old two use cases of accepting and rejecting RelationshipChanges are now provided by the two new use cases [Accept Relationship]({% link _docs_use-cases/use-case-transport-accept-relationship.md %}) and [Reject Relationship]({% link _docs_use-cases/use-case-transport-reject-relationship.md %}). +Accordingly, the Connector routes using RelationshipChanges were replaced. +When using the two new Connector routes, which work directly on the Relationships, a request body no longer needs to be provided. This means that no `content` must be sent with any of these operations anymore. The former, more generic Connector routes using RelationshipChanges could also have been used to accept or reject changes to a Relationship other than the establishment of an active Relationship, which might have required the transmission of additional data. @@ -105,7 +137,8 @@ The former, more generic Connector routes using RelationshipChanges could also h #### Modifications to Relationship -A Relationship is returned by various Connector routes and events. The data object type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) has been modified as follows due to the removal of the RelationshipChanges: +A Relationship is returned by various Connector routes and events. +The data object type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) has been modified as follows due to the removal of the RelationshipChanges: | Name | Type | Changes | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -121,7 +154,8 @@ For example, the first [RelationshipAuditLogEntry]({% link _docs_integrate/data- ### New Mandatory Wrappers for Non-Standard Content of Messages, RelationshipTemplates and Relationships -New wrapping types have been introduced for sending arbitrary content that does not fit the standard content types of enmeshed, the [ArbitraryMessageContent]({% link _docs_integrate/data-model-overview.md %}#arbitrarymessagecontent) for [Messages]({% link _docs_integrate/data-model-overview.md %}#message) with non-standard `content`, the [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) for [RelationshipTemplates]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) with non-standard `content` and the [ArbitraryRelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshipcreationcontent) for [Relationships]({% link _docs_integrate/data-model-overview.md %}#relationship) with non-standard `creationContent`. Please note that the `creationContent` of the Relationship itself is newly introduced in the section about the [Removal of RelationshipChanges](#removal-of-relationshipchanges). +New wrapping types have been introduced for sending arbitrary content that does not fit the standard content types of enmeshed, the [ArbitraryMessageContent]({% link _docs_integrate/data-model-overview.md %}#arbitrarymessagecontent) for [Messages]({% link _docs_integrate/data-model-overview.md %}#message) with non-standard `content`, the [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) for [RelationshipTemplates]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) with non-standard `content` and the [ArbitraryRelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshipcreationcontent) for [Relationships]({% link _docs_integrate/data-model-overview.md %}#relationship) with non-standard `creationContent`. +Please note that the `creationContent` of the Relationship itself is newly introduced in the section about the [Removal of RelationshipChanges](#removal-of-relationshipchanges). These new wrappers are all of the following form, whereby the `<...>` notation indicates a placeholder for one of the [transport types]({% link _docs_integrate/data-model-overview.md %}#transport-types) Message, RelationshipTemplate or Relationship: ```jsonc @@ -163,17 +197,23 @@ Similarly, when reading the value of a [Relationship]({% link _docs_integrate/da ### Removal of the `mustBeAccepted` Property of the RequestItemGroup -A [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) still provides a way of grouping the [RequestItems]({% link _docs_integrate/data-model-overview.md %}#requestitems) contained in its `items` property in the UI. However, the `mustBeAccepted` property of the RequestItemGroup has now been removed, as it had easily misunderstood interactions with the `mustBeAccepted` property of the RequestItems. More precisely, a certain, complicated dependency of the acceptance of the RequestItems contained in its `items` property could be described via the `mustBeAccepted` property of the RequestItemGroup: +A [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) still provides a way of grouping the [RequestItems]({% link _docs_integrate/data-model-overview.md %}#requestitems) contained in its `items` property in the UI. +However, the `mustBeAccepted` property of the RequestItemGroup has now been removed, as it had easily misunderstood interactions with the `mustBeAccepted` property of the RequestItems. +More precisely, a certain, complicated dependency of the acceptance of the RequestItems contained in its `items` property could be described via the `mustBeAccepted` property of the RequestItemGroup: -- If the value of the `mustBeAccepted` property of the RequestItemGroup was set to `true`, all RequestItems contained within its `items` property whose value of their respective `mustBeAccepted` property is `true` must be accepted if the entire Request is accepted. Included RequestItems whose value of their respective `mustBeAccepted` property is `false` could still be rejected. -- If the value of the `mustBeAccepted` property of the RequestItemGroup was set to `false`, all RequestItems contained in its `items` property could be rejected if the entire Request is accepted. However, if any RequestItem contained was to be accepted, all RequestItems whose `mustBeAccepted` property is `true` must also be accepted when the Request is accepted. In this respect, there was a dependency between the individual RequestItems. +- If the value of the `mustBeAccepted` property of the RequestItemGroup was set to `true`, all RequestItems contained within its `items` property whose value of their respective `mustBeAccepted` property is `true` must be accepted if the entire Request is accepted. + Included RequestItems whose value of their respective `mustBeAccepted` property is `false` could still be rejected. +- If the value of the `mustBeAccepted` property of the RequestItemGroup was set to `false`, all RequestItems contained in its `items` property could be rejected if the entire Request is accepted. + However, if any RequestItem contained was to be accepted, all RequestItems whose `mustBeAccepted` property is `true` must also be accepted when the Request is accepted. + In this respect, there was a dependency between the individual RequestItems. It was not clear enough from the `mustBeAccepted` property of the RequestItemGroup which of the RequestItems contained within its `items` property are optional or mandatory, depending on how their respective values of the `mustBeAccepted` property are set. Making it necessary to accept certain RequestItems once certain other RequestItems have been accepted is nevertheless a useful feature that will be provided in the future, but will be implemented without the `mustBeAccepted` property of the RequestItemGroup. {: .notice--info} -In addition, in contrast to the RequestItems, a RequestItemGroup did not have to be explicitly accepted or rejected when a Request was accepted, which is why it was confusing that both the RequestItemGroups and the RequestItems had a `mustBeAccepted` property. Overall, it was therefore decided to remove the `mustBeAccepted` property of the RequestItemGroup. +In addition, in contrast to the RequestItems, a RequestItemGroup did not have to be explicitly accepted or rejected when a Request was accepted, which is why it was confusing that both the RequestItemGroups and the RequestItems had a `mustBeAccepted` property. +Overall, it was therefore decided to remove the `mustBeAccepted` property of the RequestItemGroup. The `mustBeAccepted` property of the RequestItems will be kept. {: .notice--info} @@ -182,54 +222,91 @@ Furthermore, please note that the removal of this property has resulted in the r ### Changed Type of the `owner` Property of the ThirdPartyRelationshipAttributeQuery -The [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) is usually used within the `query` property of a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem), which in turn appears in the `items` property of a [Request]({% link _docs_integrate/data-model-overview.md %}#request). It is used to query an existing [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), which exists within a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between the Recipient of the Request and a third party, as the Sender of the Request. The `owner` property of the ThirdPartyRelationshipAttributeQuery determines the `owner` of the queried RelationshipAttribute. Previously, it was possible within the `owner` property of the ThirdPartyRelationshipAttributeQuery to specify a concrete address for the `owner` of the queried RelationshipAttribute or an empty string as a placeholder for the address of the Recipient of the Request instead. Thus, a RelationshipAttribute could be queried which is owned by a specific third party or which is owned by the Recipient of the Request itself. +The [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) is usually used within the `query` property of a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem), which in turn appears in the `items` property of a [Request]({% link _docs_integrate/data-model-overview.md %}#request). +It is used to query an existing [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), which exists within a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between the Recipient of the Request and a third party, as the Sender of the Request. +The `owner` property of the ThirdPartyRelationshipAttributeQuery determines the `owner` of the queried RelationshipAttribute. +Previously, it was possible within the `owner` property of the ThirdPartyRelationshipAttributeQuery to specify a concrete address for the `owner` of the queried RelationshipAttribute or an empty string as a placeholder for the address of the Recipient of the Request instead. +Thus, a RelationshipAttribute could be queried which is owned by a specific third party or which is owned by the Recipient of the Request itself. -However, it was not possible to query a RelationshipAttribute that is owned by any of the third parties specified within the `thirdParty` property of the ThirdPartyRelationshipAttributeQuery. It was also not possible to query a RelationshipAttribute that could be owned by either one of the specified third parties or the Recipient of the Request. The type of the `owner` property of the ThirdPartyRelationshipAttributeQuery has therefore been changed to extend the functionalities. The values `""`, `"recipient"` or `"thirdParty"` can now be specified for this `owner` property. Specify the string `"recipient"` if the Recipient should be the `owner` of the queried RelationshipAttribute. Use the string `"thirdParty"` if any of the third parties specified in the array string `thirdParty` should be the `owner`. If both the Recipient and each of the given third parties may be the `owner`, an empty string `""` must be specified. Using this option is useful if the `owner` of the queried RelationshipAttribute is not known in advance. +However, it was not possible to query a RelationshipAttribute that is owned by any of the third parties specified within the `thirdParty` property of the ThirdPartyRelationshipAttributeQuery. +It was also not possible to query a RelationshipAttribute that could be owned by either one of the specified third parties or the Recipient of the Request. +The type of the `owner` property of the ThirdPartyRelationshipAttributeQuery has therefore been changed to extend the functionalities. +The values `""`, `"recipient"` or `"thirdParty"` can now be specified for this `owner` property. +Specify the string `"recipient"` if the Recipient should be the `owner` of the queried RelationshipAttribute. +Use the string `"thirdParty"` if any of the third parties specified in the array string `thirdParty` should be the `owner`. +If both the Recipient and each of the given third parties may be the `owner`, an empty string `""` must be specified. +Using this option is useful if the `owner` of the queried RelationshipAttribute is not known in advance. -This change enables the Sender of the Request to specify more precisely which Identity should be the `owner` of a RelationshipAttribute when querying it. As a result, real application scenarios can be better represented. +This change enables the Sender of the Request to specify more precisely which Identity should be the `owner` of a RelationshipAttribute when querying it. +As a result, real application scenarios can be better represented. ### Synchronization With Backbone Returns No Content Anymore -Previously, the [synchronization with the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}) via the route `POST /api/v2/Account/Sync` returned a list of Relationships and Messages with the HTTP code 201. This has been changed to the sync returning nothing with the HTTP code 204. This removes the support for the workflow of regularly calling the sync and checking the response since unexpected response values happen if syncs are executed from different spots. We recommend working event-based with the [Message Broker Publisher Module]({% link _docs_operate/modules.md %}#messagebrokerpublisher), which sends events to a message broker you have set up. We send a variety of events like `consumption.incomingRequestReceived` or `consumption.incomingRequestStatusChanged`, each of them containing the relevant changed object. See [Connector Events]({% link _docs_integrate/connector-events.md %}) for the full list. Slightly related, we also recommend using the recently published [Server-Sent Events Module]({% link _docs_operate/modules.md %}#sse), which listens to events emitted from the Backbone and syncs with the Backbone when an event is received. +Previously, the [synchronization with the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}) via the route `POST /api/v2/Account/Sync` returned a list of Relationships and Messages with the HTTP code 201. +This has been changed to the sync returning nothing with the HTTP code 204. +This removes the support for the workflow of regularly calling the sync and checking the response since unexpected response values happen if syncs are executed from different spots. +We recommend working event-based with the [Message Broker Publisher Module]({% link _docs_operate/modules.md %}#messagebrokerpublisher), which sends events to a message broker you have set up. +We send a variety of events like `consumption.incomingRequestReceived` or `consumption.incomingRequestStatusChanged`, each of them containing the relevant changed object. +See [Connector Events]({% link _docs_integrate/connector-events.md %}) for the full list. +Slightly related, we also recommend using the recently published [Server-Sent Events Module]({% link _docs_operate/modules.md %}#sse), which listens to events emitted from the Backbone and syncs with the Backbone when an event is received. ### Validation of Requests -Validations have been added when sending [Requests]({% link _docs_integrate/request-and-response-introduction.md %}#requests) and [responding to Requests]({% link _docs_integrate/data-model-overview.md %}#deciderequestitemparameters) to ensure the proper functioning of business processes. However, the added validations can also reduce flexibility in the use of Requests, which is why they could cause previously functioning Request flows to fail. Most affected by the changes are Requests where an [Attribute is shared with a peer]({% link _docs_integrate/share-attributes-with-peer.md %}), an [Attribute is proposed to a peer]({% link _docs_integrate/propose-attributes-to-peer.md %}), an [Attribute is read from a peer]({% link _docs_integrate/read-attributes-from-peer.md %}) or an [Attribute is created for a peer]({% link _docs_integrate/create-attributes-for-peer.md %}). In the case of problems with previously functioning Request flows that now fail, it is recommended that the corresponding documented scenarios be consulted. Descriptive error messages are also thrown to help restore the integrity of Request flows. +Validations have been added when sending [Requests]({% link _docs_integrate/request-and-response-introduction.md %}#requests) and [responding to Requests]({% link _docs_integrate/data-model-overview.md %}#deciderequestitemparameters) to ensure the proper functioning of business processes. +However, the added validations can also reduce flexibility in the use of Requests, which is why they could cause previously functioning Request flows to fail. +Most affected by the changes are Requests where an [Attribute is shared with a peer]({% link _docs_integrate/share-attributes-with-peer.md %}), an [Attribute is proposed to a peer]({% link _docs_integrate/propose-attributes-to-peer.md %}), an [Attribute is read from a peer]({% link _docs_integrate/read-attributes-from-peer.md %}) or an [Attribute is created for a peer]({% link _docs_integrate/create-attributes-for-peer.md %}). +In the case of problems with previously functioning Request flows that now fail, it is recommended that the corresponding documented scenarios be consulted. +Descriptive error messages are also thrown to help restore the integrity of Request flows. #### Sending of Requests Even though reference has already been made to the corresponding scenarios in the documentation, a few examples of the added validation for sending Requests are given in the following. -- The new error code `error.consumption.requests.attributeQueryMismatch` has been implemented to mark provided [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes) that do not fulfill a certain [AttributeQuery]({% link _docs_integrate/data-model-overview.md %}#attributequeries) accordingly. It is thrown, for example, if the Sender of the [Request]({% link _docs_integrate/data-model-overview.md %}#request), which contains a [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) within its `items` property, specifies an `attribute` and a `query` that are incompatible. -- If the Sender of a Request wants to share an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) that is owned by itself with the Recipient of the Request by using a [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem), the Sender must specify its associated [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) in the `attribute` property of the ShareAttributeRequestItem. It is no longer permitted to specify shared copies, meaning [own shared IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute), instead. +- The new error code `error.consumption.requests.attributeQueryMismatch` has been implemented to mark provided [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes) that do not fulfill a certain [AttributeQuery]({% link _docs_integrate/data-model-overview.md %}#attributequeries) accordingly. + It is thrown, for example, if the Sender of the [Request]({% link _docs_integrate/data-model-overview.md %}#request), which contains a [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) within its `items` property, specifies an `attribute` and a `query` that are incompatible. +- If the Sender of a Request wants to share an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) that is owned by itself with the Recipient of the Request by using a [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem), the Sender must specify its associated [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) in the `attribute` property of the ShareAttributeRequestItem. + It is no longer permitted to specify shared copies, meaning [own shared IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute), instead. #### Responding to Requests Even though reference has already been made to the corresponding scenarios in the documentation, a few examples of the added validation for responding to Requests are given in the following. -- The new error code `error.consumption.requests.attributeQueryMismatch` has been implemented to mark provided [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes) that do not fulfill a certain [AttributeQuery]({% link _docs_integrate/data-model-overview.md %}#attributequeries) accordingly. It is thrown, for example, if the Attribute provided by the Recipient of the Request does not match the AttributeQuery specified in the `query` property of a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem). -- If a Request that contains a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem) whose `query` is a [RelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#relationshipattributequery) or a [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) is sent, the Recipient of the Request can only validly answer a RelationshipAttributeQuery with a new Attribute, and a ThirdPartyRelationshipAttributeQuery with an existing Attribute. Otherwise, the error code [`error.consumption.requests.invalidAcceptParameters`]({% link _docs_integrate/error-codes.md %}#error.consumption.requests.invalidAcceptParameters) arises. +- The new error code `error.consumption.requests.attributeQueryMismatch` has been implemented to mark provided [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes) that do not fulfill a certain [AttributeQuery]({% link _docs_integrate/data-model-overview.md %}#attributequeries) accordingly. + It is thrown, for example, if the Attribute provided by the Recipient of the Request does not match the AttributeQuery specified in the `query` property of a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem). +- If a Request that contains a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem) whose `query` is a [RelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#relationshipattributequery) or a [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) is sent, the Recipient of the Request can only validly answer a RelationshipAttributeQuery with a new Attribute, and a ThirdPartyRelationshipAttributeQuery with an existing Attribute. + Otherwise, the error code [`error.consumption.requests.invalidAcceptParameters`]({% link _docs_integrate/error-codes.md %}#error.consumption.requests.invalidAcceptParameters) arises. ### Removed and Changed Error Codes -An overview of the [Error codes]({% link _docs_integrate/error-codes.md %}) that may occur is given on the corresponding documentation page. The most important changes regarding the error codes due to the update from version 4 to version 5 are: - -- As already mentioned, the `mustBeAccepted` property of the [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) has been removed. The [removal of this property]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-the-mustbeaccepted-property-of-the-requestitemgroup) has also led to the replacement of the error code `error.consumption.requests.decide.validation.itemAcceptedButParentNotAccepted` with [`error.consumption.requests.decide.validation.itemAcceptedButRequestNotAccepted`]({% link _docs_integrate/error-codes.md %}#error.consumption.requests.decide.validation.itemAcceptedButRequestNotAccepted). This is because the word `"Parent"` contained in the former error code could refer to both the [Request]({% link _docs_integrate/data-model-overview.md %}#request) as a whole and to a RequestItemGroup contained within its `items` property. As RequestItemGroups are now only used for visual structuring in the UI of [RequestItems]({% link _docs_integrate/data-model-overview.md %}#requestitems) and no longer have any effect when accepting RequestItems, the word `"Parent"` can also be replaced by `"Request"`. -- The [address format was changed to DIDs]({% link _docs_integrate/migration-from-v4-to-v5.md %}#dids-as-addresses), which is why the `realm` property of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) was removed. Therefore, the error codes `error.runtime.MultiAccount.WrongRealm` and `error.transport.identity.realmLength` have been deleted. -- Since the [RelationshipChanges have been removed]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-relationshipchanges), the corresponding error code `error.transport.relationships.wrongChangeStatus` was deleted as well. In this context, the error code `error.transport.messages.noMatchingRelationship` was substituted by the more appropriate error code [`error.transport.messages.missingOrInactiveRelationship`]({% link _docs_integrate/error-codes.md %}#error.transport.messages.missingOrInactiveRelationship). -- The error code `error.consumption.attributes.invalidPropertyValue` was removed and substituted by [`error.consumption.attributes.wrongOwnerOfRepositoryAttribute`]({% link _docs_integrate/error-codes.md %}#error.consumption.attributes.wrongOwnerOfRepositoryAttribute), which is a more specific error code. -- For reasons of consistency, the error code `inheritedFromItem` was replaced by [`error.consumption.validation.inheritedFromItem`]({% link _docs_integrate/error-codes.md %}#error.consumption.validation.inheritedFromItem). The replacement of error code `error.transport.secrets.wrongBaseKeyType` with [`error.transport.secrets.wrongSecretType`]({% link _docs_integrate/error-codes.md %}#error.transport.secrets.wrongSecretType) was done for the same reason. +An overview of the [Error codes]({% link _docs_integrate/error-codes.md %}) that may occur is given on the corresponding documentation page. +The most important changes regarding the error codes due to the update from version 4 to version 5 are: + +- As already mentioned, the `mustBeAccepted` property of the [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) has been removed. + The [removal of this property]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-the-mustbeaccepted-property-of-the-requestitemgroup) has also led to the replacement of the error code `error.consumption.requests.decide.validation.itemAcceptedButParentNotAccepted` with [`error.consumption.requests.decide.validation.itemAcceptedButRequestNotAccepted`]({% link _docs_integrate/error-codes.md %}#error.consumption.requests.decide.validation.itemAcceptedButRequestNotAccepted). + This is because the word `"Parent"` contained in the former error code could refer to both the [Request]({% link _docs_integrate/data-model-overview.md %}#request) as a whole and to a RequestItemGroup contained within its `items` property. + As RequestItemGroups are now only used for visual structuring in the UI of [RequestItems]({% link _docs_integrate/data-model-overview.md %}#requestitems) and no longer have any effect when accepting RequestItems, the word `"Parent"` can also be replaced by `"Request"`. +- The [address format was changed to DIDs]({% link _docs_integrate/migration-from-v4-to-v5.md %}#dids-as-addresses), which is why the `realm` property of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) was removed. + Therefore, the error codes `error.runtime.MultiAccount.WrongRealm` and `error.transport.identity.realmLength` have been deleted. +- Since the [RelationshipChanges have been removed]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-relationshipchanges), the corresponding error code `error.transport.relationships.wrongChangeStatus` was deleted as well. + In this context, the error code `error.transport.messages.noMatchingRelationship` was substituted by the more appropriate error code [`error.transport.messages.missingOrInactiveRelationship`]({% link _docs_integrate/error-codes.md %}#error.transport.messages.missingOrInactiveRelationship). +- The error code `error.consumption.attributes.invalidPropertyValue` was removed and substituted by [`error.consumption.attributes.wrongOwnerOfRepositoryAttribute`]({% link _docs_integrate/error-codes.md %}), which is a more specific error code. +- For reasons of consistency, the error code `inheritedFromItem` was replaced by [`error.consumption.validation.inheritedFromItem`]({% link _docs_integrate/error-codes.md %}#error.consumption.validation.inheritedFromItem). + The replacement of error code `error.transport.secrets.wrongBaseKeyType` with [`error.transport.secrets.wrongSecretType`]({% link _docs_integrate/error-codes.md %}#error.transport.secrets.wrongSecretType) was done for the same reason. - The error code `error.runtime.notifications.cannotSaveSendNotificationFromPeerMessage` was renamed to [`error.runtime.notifications.cannotSaveSentNotificationFromPeerMessage`]({% link _docs_integrate/error-codes.md %}#error.runtime.notifications.cannotSaveSentNotificationFromPeerMessage), because throwing this error is about marking a Notification as sent and not about sending a Notification. -- The two error codes `error.transport.datawallet.encryptedPayloadIsNoCipher` and `error.transport.files.fileContentUndefined` were eliminated, since they aren't used anymore. However, they were also not used before the migration. +- The two error codes `error.transport.datawallet.encryptedPayloadIsNoCipher` and `error.transport.files.fileContentUndefined` were eliminated, since they aren't used anymore. + However, they were also not used before the migration. ### Removed, Changed and Added Use Cases -An overview of the [Use Cases]({% link _docs_integrate/use-cases.md %}) that may occur is given on the corresponding documentation page. The most important changes regarding the use cases due to the update from version 4 to version 5 are summarized in the following subsections. The effects of these changes on the Connector routes are also described. +An overview of the [Use Cases]({% link _docs_integrate/use-cases.md %}) that may occur is given on the corresponding documentation page. +The most important changes regarding the use cases due to the update from version 4 to version 5 are summarized in the following subsections. +The effects of these changes on the Connector routes are also described. #### Revocation of Relationships The [Revoke Relationship]({% link _docs_use-cases/use-case-transport-revoke-relationship.md %}) use case has been added. -It is now possible to revoke a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status` if it was created by yourself. To execute this use case, the Connector route `PUT /api/v2/Relationships/{id}/Revoke` can be used. +It is now possible to revoke a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status` if it was created by yourself. +To execute this use case, the Connector route `PUT /api/v2/Relationships/{id}/Revoke` can be used. #### Removal of RelationshipChanges @@ -245,7 +322,8 @@ Therefore, the following new use cases had to be added, which now provide these #### Termination of Relationships -Based on the restructuring of the Relationship by [removing the RelationshipChanges](#removal-of-relationshipchanges), the new functionality of [terminating Relationships]({% link _docs_integrate/terminate-relationships.md %}) was implemented. In connection with this feature, the following use cases have been added, whereby the corresponding added Connector routes can be found on the documentation pages of the respective use cases: +Based on the restructuring of the Relationship by [removing the RelationshipChanges](#removal-of-relationshipchanges), the new functionality of [terminating Relationships]({% link _docs_integrate/terminate-relationships.md %}) was implemented. +In connection with this feature, the following use cases have been added, whereby the corresponding added Connector routes can be found on the documentation pages of the respective use cases: - [Terminate Relationship]({% link _docs_use-cases/use-case-transport-terminate-relationship.md %}) - [Request Relationship reactivation]({% link _docs_use-cases/use-case-transport-request-relationship-reactivation.md %}) @@ -258,10 +336,11 @@ Based on the restructuring of the Relationship by [removing the RelationshipChan Taking [ThirdPartyRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) into account, we wanted to extend the functionality of the use case of getting shared versions of a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) to [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute). -For this reason, the [Get shared versions of an Attribute]({% link _docs_use-cases/use-case-consumption-get-shared-versions-of-an-attribute.md %}) use case was already added in version 4 and the use case of getting shared versions of a RepositoryAttribute was marked as deprecated. +For this reason, the [Get shared versions of an Attribute]({% link _docs_use-cases/use-case-consumption-get-versions-of-attribute-shared-with-peer.md %}) use case was already added in version 4 and the use case of getting shared versions of a RepositoryAttribute was marked as deprecated. It has now been deleted with the update to version 5. -Please note, however, that the Connector route `GET /api/v2/Attributes/{id}/Versions/Shared` that belonged to the use case of getting shared versions of a RepositoryAttribute can still be used. If the Connector route `GET /api/v2/Attributes/{id}/Versions/Shared` is executed, the [Get shared versions of an Attribute]({% link _docs_use-cases/use-case-consumption-get-shared-versions-of-an-attribute.md %}) use case is now executed instead. +Please note, however, that the Connector route `GET /api/v2/Attributes/{id}/Versions/Shared` that belonged to the use case of getting shared versions of a RepositoryAttribute can still be used. +If the Connector route `GET /api/v2/Attributes/{id}/Versions/Shared` is executed, the [Get shared versions of an Attribute]({% link _docs_use-cases/use-case-consumption-get-versions-of-attribute-shared-with-peer.md %}) use case is now executed instead. As the functionality has only been extended, there is no breaking change with regard to the Connector route. #### Less Input Needed for the Use Case CreateRepositoryAttribute @@ -269,14 +348,15 @@ As the functionality has only been extended, there is no breaking change with re In version 4, there was already a use case for creating Attributes for yourself that could be executed by Connector route `POST /api/v2/Attributes`. An Attribute created for yourself is automatically an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) which is owned by yourself. Technically, this corresponds exactly to the creation of a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). -Therefore, the use case for creating Attributes for yourself is named the [Create a RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-create-a-repositoryattribute.md %}) use case. +Therefore, the use case for creating Attributes for yourself is named the [Create a RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-create-an-ownidentityattribute.md %}) use case. When [creating Attributes for yourself]({% link _docs_integrate/create-attributes-for-yourself.md %}), it is therefore apparently not valuable to have to explicitly specify that an IdentityAttribute should be created instead of a RelationshipAttribute and that the IdentityAttribute should be owned by yourself instead of another Identity. -For this reason, when executing the Connector route `POST /api/v2/Attributes`, which corresponds to the execution of the associated [Create a RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-create-a-repositoryattribute.md %}) use case, less input must now be provided, since the `@type` and the `owner` of the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) to be created may no longer be specified. +For this reason, when executing the Connector route `POST /api/v2/Attributes`, which corresponds to the execution of the associated [Create a RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-create-an-ownidentityattribute.md %}) use case, less input must now be provided, since the `@type` and the `owner` of the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) to be created may no longer be specified. ### Renamed and Added Events -There are several [Connector events]({% link _docs_integrate/connector-events.md %}) which have been added. Regarding the [termination of Relationships]({% link _docs_integrate/terminate-relationships.md %}), for example, the following have been added: +There are several [Connector events]({% link _docs_integrate/connector-events.md %}) which have been added. +Regarding the [termination of Relationships]({% link _docs_integrate/terminate-relationships.md %}), for example, the following have been added: - `transport.relationshipReactivationRequested` - `transport.relationshipReactivationCompleted` @@ -291,8 +371,12 @@ An overview of the [Connector Events]({% link _docs_integrate/connector-events.m Some [Modules]({% link _docs_operate/modules.md %}) of the Connector have been renamed: -- The AutoAcceptRelationshipCreationChangesModule has been renamed to the [AutoAcceptPendingRelationshipsModule]({% link _docs_operate/modules.md %}#autoacceptpendingrelationships), because the [RelationshipChanges have been removed]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-relationshipchanges). For this reason, the `modules.autoAcceptRelationshipCreationChanges` field must be renamed to `modules.autoAcceptPendingRelationships` in the [configuration]({% link _docs_operate/configuration.md %}#autoacceptpendingrelationships) if it was previously specified. The `modules.autoAcceptRelationshipCreationChanges.responseContent` field must be removed additionally. -- The WebhooksV2Module module has already been renamed to the [WebhooksModule]({% link _docs_operate/modules.md %}#webhooks) in version 4. However, backwards compatibility was ensured. With the migration to version 5, the `modules.webhooksV2` field must be renamed to `modules.webhooks` in the [configuration]({% link _docs_operate/configuration.md %}#webhooks) if it was previously specified and the migration to the WebhooksModule has not yet taken place. +- The AutoAcceptRelationshipCreationChangesModule has been renamed to the [AutoAcceptPendingRelationshipsModule]({% link _docs_operate/modules.md %}#autoacceptpendingrelationships), because the [RelationshipChanges have been removed]({% link _docs_integrate/migration-from-v4-to-v5.md %}#removal-of-relationshipchanges). + For this reason, the `modules.autoAcceptRelationshipCreationChanges` field must be renamed to `modules.autoAcceptPendingRelationships` in the [configuration]({% link _docs_operate/configuration.md %}#autoacceptpendingrelationships) if it was previously specified. + The `modules.autoAcceptRelationshipCreationChanges.responseContent` field must be removed additionally. +- The WebhooksV2Module module has already been renamed to the [WebhooksModule]({% link _docs_operate/modules.md %}#webhooks) in version 4. + However, backwards compatibility was ensured. + With the migration to version 5, the `modules.webhooksV2` field must be renamed to `modules.webhooks` in the [configuration]({% link _docs_operate/configuration.md %}#webhooks) if it was previously specified and the migration to the WebhooksModule has not yet taken place. An overview of the [Connector Modules]({% link _docs_operate/modules.md %}) that may occur is given on the corresponding documentation page. {: .notice--info} diff --git a/_docs_integrate/migration-from-v5-to-v6.md b/_docs_integrate/migration-from-v5-to-v6.md index 4a064e780..5a04d1238 100644 --- a/_docs_integrate/migration-from-v5-to-v6.md +++ b/_docs_integrate/migration-from-v5-to-v6.md @@ -51,4 +51,5 @@ In preperation for upcoming features loading peer objects by id and key has been ## Removal of `secretKey` from objects -The `secretKey` field has been removed from all objects. As it is not possible to load peer objects by id and key anymore, the `secretKey` field became redundant. +The `secretKey` field has been removed from all objects. +As it is not possible to load peer objects by id and key anymore, the `secretKey` field became redundant. diff --git a/_docs_integrate/migration-from-v6-to-v7.md b/_docs_integrate/migration-from-v6-to-v7.md new file mode 100644 index 000000000..b619113d8 --- /dev/null +++ b/_docs_integrate/migration-from-v6-to-v7.md @@ -0,0 +1,175 @@ +--- +# Start automatic generation +permalink: integrate/migration-from-v6-to-v7 +published: true +title: "Migration From v6 to v7" +type: scenario +toc: true +properties: + - id: SC123 + - category: Migration Guides + - description: Changes due to release/v7 + - customer: + - component: integrate + - level: + - implementation status: DOCS ONLY + - documentation status: DONE + - published: true + - link: migration-from-v6-to-v7 +require: +required_by: +# End automatic generation +--- + +The [Runtime](https://github.com/nmshd/runtime) of enmeshed has recently been updated from version 6 to version 7. +Accordingly, a new version of the [Connector](https://github.com/nmshd/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](#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]({% link _docs_operate/setup-with-docker-compose.md %}). +- The [image](https://github.com/nmshd/connector?tab=readme-ov-file#connector) used to run the Connector must be updated to version 7. +- Some changes must be made to the [configuration]({% link _docs_operate/configuration.md %}) of the Connector. + - The `database.dbNamePrefix` field of the [database configuration]({% link _docs_operate/configuration.md %}#database) 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` parameter of the [authentication configuration]({% link _docs_operate/configuration.md %}#authentication). + The `authentication.apiKey.keys..scopes` field provides a convenient way to configure the permissions that apply when the API key identified by `` is used. + - Additionally, the support for the `API_KEY` [environment variable]({% link _docs_operate/configuration.md %}#environment-variables) 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` configuration property can be set using an environment variable. +- It must be ensured that a [Backbone](https://github.com/nmshd/backbone/tags) 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]({% link _docs_operate/configuration.md %}#transportlibrary). + The URL `/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]({% link _docs_integrate/data-model-overview.md %}#formfieldrequestitem) with [StringFormFieldSettings]({% link _docs_integrate/data-model-overview.md %}#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]({% link _docs_integrate/data-model-overview.md %}#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]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem) and the [FormFieldRequestItem]({% link _docs_integrate/data-model-overview.md %}#formfieldrequestitem) to provide context. +- The `title` property of the [AuthenticationRequestItem]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem) is now mandatory to always convey the subject of authentication. +- The `requireManualDecision` property of all [RequestItems]({% link _docs_integrate/data-model-overview.md %}#requestitems) has been removed. + [Requests]({% link _docs_integrate/data-model-overview.md %}#request) containing at least one [AuthenticationRequestItem]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem) or [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem) within their `items` property are no longer eligible for automatic acceptance or rejection by the [Decider Module]({% link _docs_explore/61-runtime.md %}#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]({% link _docs_integrate/data-model-overview.md %}#identityattribute), the [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), the [IdentityAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#identityattributequery), the [RelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#relationshipattributequery) and the [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery). + Specifying validity periods for [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes) is no longer supported as they were not enforced during Attribute processing so far. +- The `template` property of the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) was replaced by the `templateId` property in order to reduce data duplication by storing only the `id` of the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) rather than the RelationshipTemplate itself within the Relationship. +- The `truncatedReference` property of the [Token]({% link _docs_integrate/data-model-overview.md %}#token), the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) and the [File]({% link _docs_integrate/data-model-overview.md %}#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]({% link _docs_integrate/data-model-overview.md %}#file) became optional and should no longer be relied upon to be set. +- The `ownershipToken` property of the [TransferFileOwnershipRequestItem]({% link _docs_integrate/data-model-overview.md %}#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]({% link _docs_integrate/data-model-overview.md %}#file) ought to be transferred, that doesn't have an `ownershipToken` yet, it will need to be [regenerated]({% link _docs_use-cases/use-case-transport-regenerate-file-ownership-token.md %}). +- The properties `approvedAt` and `approvedByDevice` of the [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#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. +- AffiliationOrganization, AffiliationRole, AffiliationUnit, BirthCity, BirthCountry, BirthDay, BirthMonth, BirthState, BirthYear, City, Country, HouseNumber, State, Street, and ZipCode can no longer be used as `value.@type` of [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) as there is no child Attribute feature anymore. + Sharing individual components of a [complex IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes) will be possible again in future releases. +- With the new [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) concept, an Attribute copy is no longer created when an Attribute is [shared]({% link _docs_integrate/share-attributes-with-peer.md %}). + Furthermore, LocalAttribute subtypes have been introduced to help distinguish between different kinds of LocalAttributes. + - RepositoryAttributes were renamed to [OwnIdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute). + There are no own shared IdentityAttributes anymore. + Instead, sharing an OwnIdentityAttribute leads to the creation of [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails). + - The peer shared IdentityAttribute, the own shared RelationshipAttribute and the peer shared RelationshipAttribute have been replaced by the LocalAttribute subtypes [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute), [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) and [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute), respectively. + - There are no emitted ThirdPartyRelationshipAttributes anymore. + Instead, forwarding a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) to a peer, which is not involved in the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) in which the RelationshipAttribute exists, leads to the creation of [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails). + For this reason, the received ThirdPartyRelationshipAttribute is called [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute) from now on. + - The `shareInfo` property of the [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) and the corresponding LocalAttributeShareInfo data object were removed. + To track with which peer an Attribute was [shared]({% link _docs_integrate/share-attributes-with-peer.md %}), [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) are now used and, in the case of [PeerIdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute), [OwnRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute), [PeerRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute), and [ThirdPartyRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute), the properties `peer`, `sourceReference`, and `deletionInfo` are utilized. + For the ThirdPartyRelationshipAttributes, the `initialAttributePeer` property is additionally needed. + - Some [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) subtypes may have a `deletionInfo` set, which has either [EmittedAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#emittedattributedeletioninfo) or [ReceivedAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#receivedattributedeletioninfo) as its type. + The LocalAttributeDeletionInfo data object has been removed. + - The introduction of the [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) subtypes has led to a renaming of the [NotificationItems]({% link _docs_integrate/data-model-overview.md %}#notificationitems). + The [PeerAttributeSucceededNotificationItem]({% link _docs_integrate/data-model-overview.md %}#peerattributesucceedednotificationitem) replaces the PeerSharedAttributeSucceededNotificationItem. + The OwnSharedAttributeDeletedByOwnerNotificationItem, the PeerSharedAttributeDeletedByPeerNotificationItem and the ThirdPartyRelationshipAttributeDeletedByPeerNotificationItem have been replaced by the [OwnAttributeDeletedByOwnerNotificationItem]({% link _docs_integrate/data-model-overview.md %}#ownattributedeletedbyownernotificationitem), the [PeerRelationshipAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#peerrelationshipattributedeletedbypeernotificationitem) and the [ForwardedAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#forwardedattributedeletedbypeernotificationitem). + - To better align with the `initialAttributePeer` property of the [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute), the `thirdPartyAddress` property of the [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) and the [ReadAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#readattributeacceptresponseitem) has been renamed to `initialAttributePeer`. + Furthermore, the `sourceAttributeId` property of the ShareAttributeRequestItem has been renamed to `attributeId`. + - The `parentId` property of the [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) was removed as there is no child Attribute feature anymore. + +### Changed Behavior of Known Features + +- Stricter validation of `tags` of [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) and [Files]({% link _docs_integrate/data-model-overview.md %}#file) have been added as documented in their description in the data model overview. + An error with [error code]({% link _docs_integrate/error-codes.md %}) `error.consumption.attributes.invalidTags` will be thrown if an attempt is made to use invalid `tags`. +- For Attribute values, a [character set is introduced]({% link _docs_integrate/attribute-values.md %}#valid-characters-in-attributes). + An error with [error code]({% link _docs_integrate/error-codes.md %}) `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]({% link _docs_operate/modules.md %}#corehttpapi), 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 introduction of the [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) subtypes has led to a change of some Connector routes and their underlying [use cases]({% link _docs_integrate/use-cases.md %}). + - The Connector routes `GET /api/core/v1/Attributes/Own/Identity`, `GET /api/core/v1/Attributes/Own/Shared/{peer}`, and `GET /api/core/v1/Attributes/Peer/{peer}` replace the `GET /api/v2/Attributes/Own/Repository`, `GET /api/v2/Attributes/Own/Shared/Identity`, and `GET /api/v2/Attributes/Peer/Shared/Identity` Connector routes. + The corresponding use cases for getting RepositoryAttributes, for getting own shared IdentityAttributes, and for getting peer shared IdentityAttributes were replaced by [Get OwnIdentityAttributes]({% link _docs_use-cases/use-case-consumption-get-ownidentityattributes.md %}), [Get own Attributes shared with peer]({% link _docs_use-cases/use-case-consumption-get-own-attributes-shared-with-peer.md %}) and [Get peer Attributes]({% link _docs_use-cases/use-case-consumption-get-peer-attributes.md %}). + - The [Delete an Attribute and notify]({% link _docs_use-cases/use-case-consumption-delete-an-attribute-and-notify.md %}) use case replaces the use cases for deleting a RepositoryAttribute, deleting an own shared Attribute and notifying peer, deleting a peer shared Attribute and notifying owner, and deleting a ThirdPartyRelationshipAttribute and notifying peer use cases. + The corresponding Connector route now returns an array of `notificationIds` instead of a single `notificationId`. + - The [Get versions of Attribute shared with peer]({% link _docs_use-cases/use-case-consumption-get-versions-of-attribute-shared-with-peer.md %}) use case replaces the use case for getting shared versions of an Attribute. + The parameters of the corresponding Connector route have changed. + Additionally, the [Get ForwardingDetails for Attribute]({% link _docs_use-cases/use-case-consumption-get-forwardingdetails-for-attribute.md %}) use case was added. + Furthermore, the parameters of the Connector route associated with the [Get Attributes]({% link _docs_use-cases/use-case-consumption-get-attributes.md %}) use case have changed. +- The `GET /api/v2/Attributes/Valid` Connector route and its underlying [use case]({% link _docs_integrate/use-cases.md %}) for getting valid [Attributes]({% link _docs_integrate/data-model-overview.md %}#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]({% link _docs_use-cases/use-case-consumption-get-attributes.md %}), [Get own Attributes shared with peer]({% link _docs_use-cases/use-case-consumption-get-own-attributes-shared-with-peer.md %}) and [Get peer Attributes]({% link _docs_use-cases/use-case-consumption-get-peer-attributes.md %}). + 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]({% link _docs_integrate/access-the-connector.md %}#accessing-the-connector-by-software-development-kits-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: + +```typescript +import { ApiKeyAuthenticator, ConnectorClient } from "@nmshd/connector-sdk"; + +const connectorClient = ConnectorClient.create({ + baseUrl: "", + authenticator: new ApiKeyAuthenticator("") +}); +``` + +### Removed and Changed Error Codes + +An overview of the [Error codes]({% link _docs_integrate/error-codes.md %}) 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]({% link _docs_integrate/data-model-overview.md %}#localattribute) concept, an Attribute copy is no longer created when an Attribute is [shared]({% link _docs_integrate/share-attributes-with-peer.md %}). + 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]({% link _docs_integrate/data-model-overview.md %}#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]({% link _docs_integrate/data-model-overview.md %}#localattribute) 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]({% link _docs_integrate/data-model-overview.md %}#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 and Changed Use Cases + +Some [use cases]({% link _docs_integrate/use-cases.md %}) 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]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute) 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]({% link _docs_use-cases/use-case-consumption-delete-an-attribute-and-notify.md %}) 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]({% link _docs_use-cases/use-case-transport-load-item-from-reference.md %}) 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. + +The introduction of the [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) subtypes has led to a renaming of some [use cases]({% link _docs_integrate/use-cases.md %}). + +- The use cases for checking if a RepositoryAttribute can be created, for creating a RepositoryAttribute, for sharing a RepositoryAttribute, and for changing a default RepositoryAttribute were renamed to [Check if OwnIdentityAttribute can be created]({% link _docs_use-cases/use-case-consumption-check-if-ownidentityattribute-can-be-created.md %}), [Create an OwnIdentityAttribute]({% link _docs_use-cases/use-case-consumption-create-an-ownidentityattribute.md %}), [Share an OwnIdentityAttribute]({% link _docs_use-cases/use-case-consumption-share-an-ownidentityattribute.md %}), and [Change default OwnIdentityAttribute]({% link _docs_use-cases/use-case-consumption-change-default-ownidentityattribute.md %}). +- The use cases for succeeding a RepositoryAttribute and notifying a peer about a RepositoryAttribute succession were renamed to [Succeed an OwnIdentityAttribute]({% link _docs_use-cases/use-case-consumption-succeed-an-ownidentityattribute.md %}) and [Notify peer about OwnIdentityAttribute succession]({% link _docs_use-cases/use-case-consumption-notify-peer-about-ownidentityattribute-succession.md %}). diff --git a/_docs_integrate/propose-attributes-to-peer.md b/_docs_integrate/propose-attributes-to-peer.md index c74ac79c3..a6b9e7712 100644 --- a/_docs_integrate/propose-attributes-to-peer.md +++ b/_docs_integrate/propose-attributes-to-peer.md @@ -23,27 +23,42 @@ required_by: # End automatic generation --- -An Identity may have received information about a peer in the past that it needs to process a transaction at a later time. To ensure the accuracy of the available information, the Identity can propose [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes) to the peer for creation. Depending on whether the peer confirms the fittingness of a proposed Attribute, it can agree to its creation or correct the [Attribute value]({% link _docs_integrate/attribute-values.md %}) beforehand. Proposing Attributes to a peer can be useful in these and many other situations, such as: +An Identity may have received information about a peer in the past that it needs to process a transaction at a later time. +To ensure the accuracy of the available information, the Identity can propose [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes) to the peer for creation. +Depending on whether the peer confirms the fittingness of a proposed Attribute, it can agree to its creation or correct the [Attribute value]({% link _docs_integrate/attribute-values.md %}) beforehand. +Proposing Attributes to a peer can be useful in these and many other situations, such as: - An organization supports an Identity in setting up an enmeshed account by proposing Attributes to it that was derived from the organization's knowledge about the Identity. - A company wants to make sure that the currently stored street address of a customer is valid before using it to ship an item to the customer. -We will now explain how a Connector, hereinafter referred to as the Sender, can propose an Attribute to another Connector, the so-called Recipient. Since understanding this proposing process requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) and how to use them in general, you should take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) before continuing reading this guide. +We will now explain how a Connector, hereinafter referred to as the Sender, can propose an Attribute to another Connector, the so-called Recipient. +Since understanding this proposing process requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) and how to use them in general, you should take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) before continuing reading this guide. -Please note that the general procedure is the same if the Connector wants to propose an Attribute to an App user instead of another Connector. For reasons of clarity, this guide focuses on the proposing process with two Connectors. +Please note that the general procedure is the same if the Connector wants to propose an Attribute to an App user instead of another Connector. +For reasons of clarity, this guide focuses on the proposing process with two Connectors. {: .notice--info} ## Request for proposing Attributes -The Sender wants to propose an Attribute to the Recipient. To do this, the Sender must first create a suitable Request, which it can then send to the Recipient. In the following subsections, we describe the general appearance of a Request for proposing Attributes. +The Sender wants to propose an Attribute to the Recipient. +To do this, the Sender must first create a suitable Request, which it can then send to the Recipient. +In the following subsections, we describe the general appearance of a Request for proposing Attributes. ### Role of ProposeAttributeRequestItem -To propose a single Attribute to the Recipient, a single RequestItem of type [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) must be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request). It is possible to propose an IdentityAttribute or a RelationshipAttribute, which must be inserted into the `attribute` property of the ProposeAttributeRequestItem. As it only makes sense for the Sender to propose an Attribute to the Recipient which is owned by the Recipient, the Sender must specify an empty string as the value for the `owner` property of the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes). The Recipient automatically becomes the owner of the Attribute later on. As the Recipient may want to change the Attribute value of the proposed Attribute, the Sender must formulate a `query` matching the `attribute`. If the Sender specifies an `attribute` and a `query` that are incompatible, an [error]({% link _docs_integrate/error-codes.md %}) with the code `error.runtime.requestDeserialization` or with the code `error.consumption.requests.attributeQueryMismatch` is to be expected. +To propose a single Attribute to the Recipient, a single RequestItem of type [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) must be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request). +It is possible to propose an IdentityAttribute or a RelationshipAttribute, which must be inserted into the `attribute` property of the ProposeAttributeRequestItem. +As it only makes sense for the Sender to propose an Attribute to the Recipient which is owned by the Recipient, the Sender must specify an empty string as the value for the `owner` property of the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes). +The Recipient automatically becomes the owner of the Attribute later on. +As the Recipient may want to change the Attribute value of the proposed Attribute, the Sender must formulate a `query` matching the `attribute`. +If the Sender specifies an `attribute` and a `query` that are incompatible, an [error]({% link _docs_integrate/error-codes.md %}) with the code `error.runtime.requestDeserialization` or with the code `error.consumption.requests.attributeQueryMismatch` is to be expected. ### Combinations and usage scenarios of ProposeAttributeRequestItem -The following table provides an overview of the possible kinds of Attributes that the Sender can propose to the Recipient using the ProposeAttributeRequestItem. It must be taken into account whether the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) is an IdentityAttribute or a RelationshipAttribute and that its `owner` must be the Recipient, which is why the Sender must always specify an empty string as the value for the `owner` property of the Attribute contained within the `attribute` property of the ProposeAttributeRequestItem. If a [RelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#relationshipattributequery) is used as the `query` of the ProposeAttributeRequestItem, an empty string must also be specified as the value for its `owner` property. A ProposeAttributeRequestItem can only be used to propose the creation of RelationshipAttributes that exist in the context of the Relationship between the Sender and the Recipient. +The following table provides an overview of the possible kinds of Attributes that the Sender can propose to the Recipient using the ProposeAttributeRequestItem. +It must be taken into account whether the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) is an IdentityAttribute or a RelationshipAttribute and that its `owner` must be the Recipient, which is why the Sender must always specify an empty string as the value for the `owner` property of the Attribute contained within the `attribute` property of the ProposeAttributeRequestItem. +If a [RelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#relationshipattributequery) is used as the `query` of the ProposeAttributeRequestItem, an empty string must also be specified as the value for its `owner` property. +A ProposeAttributeRequestItem can only be used to propose the creation of RelationshipAttributes that exist in the context of the Relationship between the Sender and the Recipient. | Type and context | Owner | Possible? | Automation | Remarks, reasons and examples | | --------------------------------------------------------------------------------------------------------- | --------- | :-------: | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -54,7 +69,11 @@ The following table provides an overview of the possible kinds of Attributes tha ### Example of proposing an IdentityAttribute -In the case in which the Sender wants to propose an IdentityAttribute to the Recipient, it must use a [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) which contains the IdentityAttribute in its `attribute` property and a matching [IdentityAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#identityattributequery) in its `query` property. This means that the specified value for the `valueType` property of the IdentityAttributeQuery must correspond to the Attribute value type of the IdentityAttribute. The ProposeAttributeRequestItem must then be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for proposing Attributes. For example, the Sender wants to propose an IdentityAttribute of type [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) to the Recipient. The value of the `mustBeAccepted` property of the ProposeAttributeRequestItem is set to `true` in our example and the `<...>` notation is used as a placeholder for the actual data as usual. +In the case in which the Sender wants to propose an IdentityAttribute to the Recipient, it must use a [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) which contains the IdentityAttribute in its `attribute` property and a matching [IdentityAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#identityattributequery) in its `query` property. +This means that the specified value for the `valueType` property of the IdentityAttributeQuery must correspond to the Attribute value type of the IdentityAttribute. +The ProposeAttributeRequestItem must then be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for proposing Attributes. +For example, the Sender wants to propose an IdentityAttribute of type [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) to the Recipient. +The value of the `mustBeAccepted` property of the ProposeAttributeRequestItem is set to `true` in our example and the `<...>` notation is used as a placeholder for the actual data as usual. ```jsonc { @@ -84,7 +103,10 @@ It is also possible to use an appropriate [IQLQuery]({% link _docs_integrate/dat ### Example of proposing a RelationshipAttribute -Let's consider the case in which the Sender has established an active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with the Recipient and the Sender wants to propose a RelationshipAttribute for this Relationship to the Recipient. Then the Sender needs to insert a corresponding [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem), which contains the RelationshipAttribute in its `attribute` property and a matching [RelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#relationshipattributequery) in its `query` property, into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for proposing Attributes. In particular, it is necessary that the specified value for the `attributeCreationHints.valueType` property of the RelationshipAttributeQuery corresponds to the Attribute value type of the RelationshipAttribute. For example, the Sender wants to propose a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) of type [ProprietaryString]({% link _docs_integrate/attribute-values.md %}#proprietarystring) to the Recipient whose `confidentiality` is `"public"`, whereby the value of the `mustBeAccepted` property of the associated ProposeAttributeRequestItem is set to `true`. +Let's consider the case in which the Sender has established an active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with the Recipient and the Sender wants to propose a RelationshipAttribute for this Relationship to the Recipient. +Then the Sender needs to insert a corresponding [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem), which contains the RelationshipAttribute in its `attribute` property and a matching [RelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#relationshipattributequery) in its `query` property, into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for proposing Attributes. +In particular, it is necessary that the specified value for the `attributeCreationHints.valueType` property of the RelationshipAttributeQuery corresponds to the Attribute value type of the RelationshipAttribute. +For example, the Sender wants to propose a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) of type [ProprietaryString]({% link _docs_integrate/attribute-values.md %}#proprietarystring) to the Recipient whose `confidentiality` is `"public"`, whereby the value of the `mustBeAccepted` property of the associated ProposeAttributeRequestItem is set to `true`. ```jsonc { @@ -121,28 +143,39 @@ Let's consider the case in which the Sender has established an active [Relations ### Propose multiple Attributes -Proposing Attributes to a peer is not limited to just a single Attribute, but it is possible to propose multiple Attributes to a peer at the same time. For this purpose, several ProposeAttributeRequestItems or suitable [RequestItemGroups]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) can be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for proposing Attributes. If you want to use a RequestItemGroup in order to propose multiple Attributes to the Recipient at the same time, you must insert corresponding ProposeAttributeRequestItems into the `items` property of it. +Proposing Attributes to a peer is not limited to just a single Attribute, but it is possible to propose multiple Attributes to a peer at the same time. +For this purpose, several ProposeAttributeRequestItems or suitable [RequestItemGroups]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) can be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for proposing Attributes. +If you want to use a RequestItemGroup in order to propose multiple Attributes to the Recipient at the same time, you must insert corresponding ProposeAttributeRequestItems into the `items` property of it. ## Send and receive the Request -The Sender that wants to propose an Attribute to the Recipient may or may not already have a Relationship with the Recipient. Depending on which is the case, a different method can be used to send the [Request for proposing Attributes]({% link _docs_integrate/propose-attributes-to-peer.md %}#request-for-proposing-attributes). There are two ways to send the Request for proposing Attributes created by the Sender to the Recipient. +The Sender that wants to propose an Attribute to the Recipient may or may not already have a Relationship with the Recipient. +Depending on which is the case, a different method can be used to send the [Request for proposing Attributes]({% link _docs_integrate/propose-attributes-to-peer.md %}#request-for-proposing-attributes). +There are two ways to send the Request for proposing Attributes created by the Sender to the Recipient. ### Request via RelationshipTemplate -If there is currently no Relationship between the Sender and the Recipient, this approach must be used. However, it is also possible for the Sender to use a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) to send a Request to the Recipient if there is already an active Relationship between them. All details on how to send and receive a Request via a RelationshipTemplate in general can be found in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide. +If there is currently no Relationship between the Sender and the Recipient, this approach must be used. +However, it is also possible for the Sender to use a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) to send a Request to the Recipient if there is already an active Relationship between them. +All details on how to send and receive a Request via a RelationshipTemplate in general can be found in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide. ### Request via Message -The Sender only has the option of sending a Request to the Recipient via a [Message]({% link _docs_integrate/data-model-overview.md %}#message) if there is already an active Relationship between them. All information on how to send and receive a Request via a Message can be found in the [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) guide. +The Sender only has the option of sending a Request to the Recipient via a [Message]({% link _docs_integrate/data-model-overview.md %}#message) if there is already an active Relationship between them. +All information on how to send and receive a Request via a Message can be found in the [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) guide. ## Accept the Request and deal with the proposed Attributes -After the Recipient has received the [Request for proposing Attributes]({% link _docs_integrate/propose-attributes-to-peer.md %}#request-for-proposing-attributes), it can accept it to create all or some of the Attributes that were proposed for creation by the Sender. The Recipient also has the option of overwriting the Attribute values beforehand or sending existing Attributes back to the Sender instead of creating new ones. To accept the Request, proceed as described in the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case documentation and specify the `id` of the received [Request]({% link _docs_integrate/data-model-overview.md %}#request). Also, you need to decide and specify for each ProposeAttributeRequestItem contained in the Request for proposing Attributes whether you want to accept or reject it. +After the Recipient has received the [Request for proposing Attributes]({% link _docs_integrate/propose-attributes-to-peer.md %}#request-for-proposing-attributes), it can accept it to create all or some of the Attributes that were proposed for creation by the Sender. +The Recipient also has the option of overwriting the Attribute values beforehand or sending existing Attributes back to the Sender instead of creating new ones. +To accept the Request, proceed as described in the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case documentation and specify the `id` of the received [Request]({% link _docs_integrate/data-model-overview.md %}#request). +Also, you need to decide and specify for each ProposeAttributeRequestItem contained in the Request for proposing Attributes whether you want to accept or reject it. -If the Recipient does not want to deal with any of the Attributes proposed by the Sender and, therefore, does not want to accept the Request for proposing Attributes of the Sender, it can reject it as a whole as well. For that, follow the instructions of the [Reject incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) use case. +If the Recipient does not want to deal with any of the Attributes proposed by the Sender and, therefore, does not want to accept the Request for proposing Attributes of the Sender, it can reject it as a whole as well. +For that, follow the instructions of the [Reject incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) use case. {: .notice--info} -
+
### Accept a ProposeAttributeRequestItem @@ -154,35 +187,48 @@ The `attributeId` parameter of the AcceptProposeAttributeRequestItemParameters m The existing Attribute may only differ from the proposed Attribute by its Attribute value. As it makes no sense for the Sender to request a RelationshipAttribute from the Recipient that already exists in the context of their Relationship to each other, a RelationshipAttributeQuery that is potentially specified in the `query` property of the ProposeAttributeRequestItem can only be validly answered by the Recipient with a new Attribute. -Otherwise, the [error code]({% link _docs_integrate/error-codes.md %}) `error.consumption.requests.invalidAcceptParameters` arises. Furthermore, an error with the code `error.consumption.requests.attributeQueryMismatch` will be thrown if the Attribute provided by the Recipient does not match the [AttributeQuery]({% link _docs_integrate/data-model-overview.md %}#attributequeries) specified in the `query` property of the ProposeAttributeRequestItem. +Otherwise, the [error code]({% link _docs_integrate/error-codes.md %}) `error.consumption.requests.invalidAcceptParameters` arises. +Furthermore, an error with the code `error.consumption.requests.attributeQueryMismatch` will be thrown if the Attribute provided by the Recipient does not match the [AttributeQuery]({% link _docs_integrate/data-model-overview.md %}#attributequeries) specified in the `query` property of the ProposeAttributeRequestItem. {: .notice--info} -Accepting a ProposeAttributeRequestItem with a new Attribute or an existing, that isn’t shared with the Sender already neither itself nor any of its predecessing versions, leads to the creation of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) with a [LocalAttributeShareInfo]({% link _docs_integrate/data-model-overview.md %}#localattributeshareinfo) contained within its `shareInfo` property. +Accepting a ProposeAttributeRequestItem with a new Attribute, that isn’t shared with the Sender already neither itself nor any of its predecessing versions, leads to the creation of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). The `content` of the LocalAttribute is the Attribute that the Recipient wants to send back to the Sender, that is, the proposed Attribute itself or a corrected version of it. -Depending on whether the Recipient sends back an IdentityAttribute or a RelationshipAttribute, it is referred to as either an [own shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes) or an [own shared RelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-relationshipattributes). -An appropriate AcceptResponseItem of type [ProposeAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributeacceptresponseitem) is generated, which incorporates the `id` of the LocalAttribute in its `attributeId` property and the Attribute that the Recipient wants to send back to the Sender in its `attribute` property. -If a new IdentityAttribute is to be created and sent back to the Sender, a [RepositoryAttribute]({% link _docs_integrate/attribute-introduction.md %}#repositoryattributes) will additionally be created for the Recipient beforehand. +Depending on whether the Recipient sends back an IdentityAttribute or a RelationshipAttribute, it is referred to as either an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) or a [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute). +If a new IdentityAttribute is to be shared, [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with the created OwnIdentityAttribute will additionally be created for the Recipient beforehand. +Accepting a ProposeAttributeRequestItem with an existing Attribute, that isn’t shared with the Sender already neither itself nor any of its predecessing versions, leads to the creation of associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) for the existing [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute). +An appropriate AcceptResponseItem of type [ProposeAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributeacceptresponseitem) which incorporates the `id` of the LocalAttribute in its `attributeId` property and the Attribute that the Recipient wants to send back to the Sender in its `attribute` property, is generated both when accepting with a new Attribute and with an existing one. -If the ProposeAttributeRequestItem is accepted with an existing Attribute that the Recipient already shared with the Sender and the corresponding [own shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes) does not have `"DeletedByPeer"` or `"ToBeDeletedByPeer"` as `deletionInfo.deletionStatus`, an [AttributeAlreadySharedAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributealreadysharedacceptresponseitem) will be generated. -Instead of creating a further pair consisting of an [own shared and a peer shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes), the `id` of the already existing [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) is returned. -Note that the `id` of the LocalAttribute of the Sender matches the `id` of the corresponding LocalAttribute of the Recipient. +If the ProposeAttributeRequestItem is accepted with an existing Attribute that the Recipient already shared with the Sender and the corresponding [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) do not have `"DeletedByRecipient"` as `deletionInfo.deletionStatus`, an [AttributeAlreadySharedAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributealreadysharedacceptresponseitem) will be generated. +The `id` of the already existing [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute), which is an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), is returned. +Note that the `id` of the OwnIdentityAttribute of the Sender matches the `id` of the corresponding [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) of the Recipient. +If the `deletionInfo.deletionStatus` of the AttributeForwardingDetails was `"ToBeDeletedByRecipient"`, their `deletionInfo` will be set to undefined. -Lastly, if the ProposeAttributeRequestItem is accepted with an existing Attribute of which the Recipient already shared a predecessor with the Sender, an [AttributeSuccessionAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributesuccessionacceptresponseitem) will be generated, given that it is an [own shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes) that does not have `"DeletedByPeer"` or `"ToBeDeletedByPeer"` as `deletionInfo.deletionStatus`. -Instead of creating an independent pair consisting of an [own shared and a peer shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes), internally an [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) is performed. -The `id` of the already existing [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) predecessor is returned, as well as the `id` and `content` of the newly created LocalAttribute successor. +Lastly, if the ProposeAttributeRequestItem is accepted with an existing Attribute of which the Recipient already shared a predecessor with the Sender, an [AttributeSuccessionAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributesuccessionacceptresponseitem) will be generated, given that there are [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with the predecessor that do not have `"DeletedByRecipient"` as `deletionInfo.deletionStatus`. +[AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) for the [successor]({% link _docs_integrate/update-attributes-by-succession.md %}), which is an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), are created. +The `id` of the already existing OwnIdentityAttribute predecessor is returned, as well as the `id` and `content` of the newly created OwnIdentityAttribute successor. In any case, the respective AcceptResponseItem will be included in the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for proposing Attributes that will be transferred to the Sender. -It is noticeable that accepting a ProposeAttributeRequestItem essentially works in the same way as accepting a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem). Both types of RequestItems are used when an Identity needs information from a peer. The difference between the two RequestItems is that when using the ProposeAttributeRequestItem, the Identity not only asks for an Attribute of a certain Attribute value type, but also proposes a specific Attribute to the peer for creation that might be suitable. The ProposeAttributeRequestItem can therefore also be understood as a combination of the ReadAttributeRequestItem and the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem). To gain a deeper understanding of these connections, take a look at the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide and the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. +It is noticeable that accepting a ProposeAttributeRequestItem essentially works in the same way as accepting a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem). +Both types of RequestItems are used when an Identity needs information from a peer. +The difference between the two RequestItems is that when using the ProposeAttributeRequestItem, the Identity not only asks for an Attribute of a certain Attribute value type, but also proposes a specific Attribute to the peer for creation that might be suitable. +The ProposeAttributeRequestItem can therefore also be understood as a combination of the ReadAttributeRequestItem and the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem). +To gain a deeper understanding of these connections, take a look at the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide and the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. {: .notice--info} ### Reject a ProposeAttributeRequestItem -Even if the Recipient accepts the Request for proposing Attributes as a whole, it may decide not to accept all of the [ProposeAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) it contains. To be more precise, the Recipient has the option of rejecting ProposeAttributeRequestItems that have the value `false` specified in their `mustBeAccepted` property. To reject a ProposeAttributeRequestItem, use the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters). The rejection of a ProposeAttributeRequestItem leads to the creation of a corresponding ResponseItem of type [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem). This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for proposing Attributes. +Even if the Recipient accepts the Request for proposing Attributes as a whole, it may decide not to accept all of the [ProposeAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) it contains. +To be more precise, the Recipient has the option of rejecting ProposeAttributeRequestItems that have the value `false` specified in their `mustBeAccepted` property. +To reject a ProposeAttributeRequestItem, use the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters). +The rejection of a ProposeAttributeRequestItem leads to the creation of a corresponding ResponseItem of type [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem). +This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for proposing Attributes. ### Example of accepting a RequestItemGroup -Let's look at an example where the Sender proposes the Recipient's [PersonName]({% link _docs_integrate/attribute-values.md %}#personname) and contact information in the form of an [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) and a [PhoneNumber]({% link _docs_integrate/attribute-values.md %}#phonenumber) to the Recipient during its onboarding process. For this purpose, the Sender creates a [Request]({% link _docs_integrate/data-model-overview.md %}#request) for proposing Attributes, which contains a ProposeAttributeRequestItem belonging to the PersonName and a RequestItemGroup belonging to the contact information in its `items` property. The [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) itself includes two ProposeAttributeRequestItems in its `items` property, namely one for the EMailAddress and one for the PhoneNumber. +Let's look at an example where the Sender proposes the Recipient's [PersonName]({% link _docs_integrate/attribute-values.md %}#personname) and contact information in the form of an [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) and a [PhoneNumber]({% link _docs_integrate/attribute-values.md %}#phonenumber) to the Recipient during its onboarding process. +For this purpose, the Sender creates a [Request]({% link _docs_integrate/data-model-overview.md %}#request) for proposing Attributes, which contains a ProposeAttributeRequestItem belonging to the PersonName and a RequestItemGroup belonging to the contact information in its `items` property. +The [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) itself includes two ProposeAttributeRequestItems in its `items` property, namely one for the EMailAddress and one for the PhoneNumber. ```jsonc { @@ -246,12 +292,17 @@ Let's look at an example where the Sender proposes the Recipient's [PersonName]( } ``` -In our example, the Sender only requires the Recipient to accept the ProposeAttributeRequestItems belonging to the PersonName and the EMailAddress, which is why the individual [ProposeAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) within the Request have specified corresponding values in their `mustBeAccepted` property. We assume that the Recipient wants to accept the Request and all its ProposeAttributeRequestItems with the exception of the PhoneNumber. +In our example, the Sender only requires the Recipient to accept the ProposeAttributeRequestItems belonging to the PersonName and the EMailAddress, which is why the individual [ProposeAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) within the Request have specified corresponding values in their `mustBeAccepted` property. +We assume that the Recipient wants to accept the Request and all its ProposeAttributeRequestItems with the exception of the PhoneNumber. -If the Recipient wants to accept the Request for proposing Attributes, it must accept all ProposeAttributeRequestItems for which the `mustBeAccepted` property is set to `true`. It is therefore not permitted for the Recipient to refuse to accept the ProposeAttributeRequestItem belonging to the PersonName or the EMailAddress. +If the Recipient wants to accept the Request for proposing Attributes, it must accept all ProposeAttributeRequestItems for which the `mustBeAccepted` property is set to `true`. +It is therefore not permitted for the Recipient to refuse to accept the ProposeAttributeRequestItem belonging to the PersonName or the EMailAddress. {: .notice--info} -We assume that the Recipient confirms the fittingness of the PersonName proposed by the Sender and that the Sender has proposed an outdated EMailAddress to the Recipient for creation. The Recipient therefore wants to create a corrected version of the EMailAddress and send it back to the Sender. The Recipient rejects the PhoneNumber and accepts the ProposeAttributeRequestItems belonging to the PersonName and the EMailAddress. Consequently, it responds to the Request for proposing Attributes as follows: +We assume that the Recipient confirms the fittingness of the PersonName proposed by the Sender and that the Sender has proposed an outdated EMailAddress to the Recipient for creation. +The Recipient therefore wants to create a corrected version of the EMailAddress and send it back to the Sender. +The Recipient rejects the PhoneNumber and accepts the ProposeAttributeRequestItems belonging to the PersonName and the EMailAddress. +Consequently, it responds to the Request for proposing Attributes as follows: ```jsonc { @@ -297,10 +348,12 @@ Note that it is important to respond to RequestItems, some of which may be conta ## Receive the Response to the Request -We now assume that the Recipient has accepted the [Request for proposing Attributes]({% link _docs_integrate/propose-attributes-to-peer.md %}#request-for-proposing-attributes) of the Sender. In order for the Sender to receive the Response of the Recipient, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). Please note that this synchronization can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync). +We now assume that the Recipient has accepted the [Request for proposing Attributes]({% link _docs_integrate/propose-attributes-to-peer.md %}#request-for-proposing-attributes) of the Sender. +In order for the Sender to receive the Response of the Recipient, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). +Please note that this synchronization can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync). + +
-
-s To view the Response to the Request, proceed as described in the [Query outgoing Requests]({% link _docs_use-cases/use-case-consumption-query-outgoing-requests.md %}) use case documentation and use the following query parameter: - If the [Request was sent via a RelationshipTemplate]({% link _docs_integrate/propose-attributes-to-peer.md %}#request-via-relationshiptemplate): Specify `` as the value for the `source.reference` query parameter. @@ -308,15 +361,20 @@ To view the Response to the Request, proceed as described in the [Query outgoing The Integrator of the Sender can now get the Response of the Recipient from the `response.content` property of the result. In the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) is a [ProposeAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributeacceptresponseitem), an [AttributeAlreadySharedAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributealreadysharedacceptresponseitem) or an [AttributeSuccessionAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributesuccessionacceptresponseitem) for each accepted and a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) for each rejected ProposeAttributeRequestItem included. -Internally, a returned `attribute` that can be read from a ProposeAttributeAcceptResponseItem is used to create an appropriate LocalAttribute with a LocalAttributeShareInfo of the Sender. -Depending on whether the Recipient has sent back an IdentityAttribute or a RelationshipAttribute to the Sender, it is referred to as either a [peer shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes) or a [peer shared RelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-relationshipattributes). +Internally, a returned `attribute` that can be read from a ProposeAttributeAcceptResponseItem is used to create an appropriate [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) of the Sender. +Depending on whether the Recipient has sent back an IdentityAttribute or a RelationshipAttribute to the Sender, it is referred to as either a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) or a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute). The `content` of the LocalAttribute is the Attribute that the Recipient has sent back to the Sender. Depending on whether the Recipient has confirmed the fittingness of the Attribute proposed by the Sender, it is therefore the proposed Attribute itself or a corrected version of it. When receiving an AttributeSuccessionAcceptResponseItem, the according [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) is automatically performed. +Processing an AttributeAlreadySharedAcceptResponseItem in the case where the `deletionInfo.deletionStatus` of the [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) was `"ToBeDeleted"`, its `deletionInfo` will be set to undefined. -In case of an error, [ErrorResponseItems]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) can also be included in the Response. If the Request for proposing Attributes contains a RequestItemGroup in its `items` property, the Response to this Request contains a corresponding [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) in its `items` property. +In case of an error, [ErrorResponseItems]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) can also be included in the Response. +If the Request for proposing Attributes contains a RequestItemGroup in its `items` property, the Response to this Request contains a corresponding [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) in its `items` property. {: .notice--info} ## What's next? -An Identity has several options for requesting an Attribute creation. This guide covers how an Identity can request the creation of an Attribute for a peer so that the [Attribute value]({% link _docs_integrate/attribute-values.md %}) is proposed by the Identity, but can be modified by the peer when accepting the Request. In some cases, it makes more sense if the peer cannot change the proposed Attribute value. For that, take a look at the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. +An Identity has several options for requesting an Attribute creation. +This guide covers how an Identity can request the creation of an Attribute for a peer so that the [Attribute value]({% link _docs_integrate/attribute-values.md %}) is proposed by the Identity, but can be modified by the peer when accepting the Request. +In some cases, it makes more sense if the peer cannot change the proposed Attribute value. +For that, take a look at the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. diff --git a/_docs_integrate/read-attributes-from-peer.md b/_docs_integrate/read-attributes-from-peer.md index c47a64437..255f17ab1 100644 --- a/_docs_integrate/read-attributes-from-peer.md +++ b/_docs_integrate/read-attributes-from-peer.md @@ -30,27 +30,44 @@ There are many situations in which an Identity is interested in an [IdentityAttr - An organization is interested in the birth date of a member so that it can wish them a happy birthday every year. - A university needs to know the email address of a student in order to be able to send them emails. -In this guide, we explain how a Connector, hereinafter referred to as the Sender, can read an [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) of another Connector, the so-called Recipient. Since understanding this reading process requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) and how to use them in general, you should take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) before continuing reading this guide. +In this guide, we explain how a Connector, hereinafter referred to as the Sender, can read an [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) of another Connector, the so-called Recipient. +Since understanding this reading process requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) and how to use them in general, you should take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) before continuing reading this guide. -Please note that the general procedure is the same if the Connector wants to read an Attribute of an App user instead of another Connector. For reasons of clarity, this guide focuses on the reading process with two Connectors. +Please note that the general procedure is the same if the Connector wants to read an Attribute of an App user instead of another Connector. +For reasons of clarity, this guide focuses on the reading process with two Connectors. {: .notice--info} ## Request for reading Attributes -The Sender wants to read an Attribute of the Recipient. To do this, the Sender must first create a suitable Request, which it can then send to the Recipient. In the following subsections, we describe the general appearance of a Request for reading Attributes. +The Sender wants to read an Attribute of the Recipient. +To do this, the Sender must first create a suitable Request, which it can then send to the Recipient. +In the following subsections, we describe the general appearance of a Request for reading Attributes. ### Role of ReadAttributeRequestItem -For reading a single Attribute, the Sender needs to insert a single RequestItem of type [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem) into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request). The input it has to provide for the `query` property of the ReadAttributeRequestItem depends on what type of Attribute it wants to get. If the Sender wants to read an IdentityAttribute, it can use an appropriate [IdentityAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#identityattributequery). Only IdentityAttributes that are owned by the Recipient can be requested by the Sender. It makes no sense for the Sender to request a RelationshipAttribute from the Recipient that already exists in the context of their [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to each other. However, the Sender may want to create a RelationshipAttribute for this Relationship whose `value` is set by the Recipient. This can be done by using a [RelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#relationshipattributequery). +For reading a single Attribute, the Sender needs to insert a single RequestItem of type [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem) into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request). +The input it has to provide for the `query` property of the ReadAttributeRequestItem depends on what type of Attribute it wants to get. +If the Sender wants to read an IdentityAttribute, it can use an appropriate [IdentityAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#identityattributequery). +Only IdentityAttributes that are owned by the Recipient can be requested by the Sender. +It makes no sense for the Sender to request a RelationshipAttribute from the Recipient that already exists in the context of their [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to each other. +However, the Sender may want to create a RelationshipAttribute for this Relationship whose `value` is set by the Recipient. +This can be done by using a [RelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#relationshipattributequery). -The Sender can use a ReadAttributeRequestItem to create a RelationshipAttribute in the context of a Relationship between itself and the Recipient if it wants the [RelationshipAttributeValue]({% link _docs_integrate/attribute-values.md %}#relationship-attributes) to be set by the Recipient. Even if it seems misleading to use a ReadAttributeRequestItem to create a RelationshipAttribute, this terminology makes sense insofar as the RelationshipAttributeValue should be read from the Recipient in order to be able to create it. +The Sender can use a ReadAttributeRequestItem to create a RelationshipAttribute in the context of a Relationship between itself and the Recipient if it wants the [RelationshipAttributeValue]({% link _docs_integrate/attribute-values.md %}#relationship-attributes) to be set by the Recipient. +Even if it seems misleading to use a ReadAttributeRequestItem to create a RelationshipAttribute, this terminology makes sense insofar as the RelationshipAttributeValue should be read from the Recipient in order to be able to create it. {: .notice--info} -Note that the Sender cannot explicitly specify the Recipient's address as the value for the `owner` property of the RelationshipAttributeQuery because the address does not have to be known beforehand. This is the case if the [Request is sent via a RelationshipTemplate]({% link _docs_integrate/read-attributes-from-peer.md %}#request-via-relationshiptemplate) and not via a Message. Therefore, an empty string must be specified as the `owner` instead if the Sender wants the RelationshipAttribute to be owned by the Recipient. If the Sender is interested in a RelationshipAttribute that the Recipient has in the context of a Relationship with a third party, a [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) can be used. In addition, it is also permitted to specify an [IQLQuery]({% link _docs_integrate/data-model-overview.md %}#iqlquery) for the `query` property of the ReadAttributeRequestItem. +Note that the Sender cannot explicitly specify the Recipient's address as the value for the `owner` property of the RelationshipAttributeQuery because the address does not have to be known beforehand. +This is the case if the [Request is sent via a RelationshipTemplate]({% link _docs_integrate/read-attributes-from-peer.md %}#request-via-relationshiptemplate) and not via a Message. +Therefore, an empty string must be specified as the `owner` instead if the Sender wants the RelationshipAttribute to be owned by the Recipient. +If the Sender is interested in a RelationshipAttribute that the Recipient has in the context of a Relationship with a third party, a [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) can be used. +In addition, it is also permitted to specify an [IQLQuery]({% link _docs_integrate/data-model-overview.md %}#iqlquery) for the `query` property of the ReadAttributeRequestItem. ### Combinations and usage scenarios of ReadAttributeRequestItem -The following table provides an overview of the possible kinds of Attributes that the Sender can read from the Recipient using the ReadAttributeRequestItem. It must be taken into account whether the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) is an IdentityAttribute or a RelationshipAttribute and which Identity is its `owner`. If the Sender wants to read a RelationshipAttribute from the Recipient, a distinction must be made between which Identities the Relationship in question exists. +The following table provides an overview of the possible kinds of Attributes that the Sender can read from the Recipient using the ReadAttributeRequestItem. +It must be taken into account whether the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) is an IdentityAttribute or a RelationshipAttribute and which Identity is its `owner`. +If the Sender wants to read a RelationshipAttribute from the Recipient, a distinction must be made between which Identities the Relationship in question exists. | Type and context | Owner | Possible? | Automation | Remarks, reasons and examples | | ---------------------------------------------------------------------------------------------------------- | ----------- | :----------------------------------------: | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -64,7 +81,9 @@ The following table provides an overview of the possible kinds of Attributes tha ### Example of reading an IdentityAttribute -We assume that the Sender wants to read an IdentityAttribute of type [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) of the Recipient. To do this, it inserts the corresponding [IdentityAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#identityattributequery) into the `query` property of the [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem), which is contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for reading Attributes. In our example, we have chosen to set the value of the `mustBeAccepted` property of the ReadAttributeRequestItem to `true`. +We assume that the Sender wants to read an IdentityAttribute of type [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) of the Recipient. +To do this, it inserts the corresponding [IdentityAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#identityattributequery) into the `query` property of the [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem), which is contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for reading Attributes. +In our example, we have chosen to set the value of the `mustBeAccepted` property of the ReadAttributeRequestItem to `true`. ```jsonc { @@ -84,7 +103,9 @@ We assume that the Sender wants to read an IdentityAttribute of type [EMailAddre ### Example of reading a RelationshipAttribute without a third party involved -We now consider the case that the Sender has an active Relationship established with the Recipient and that it wants to create a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) for this Relationship whose `value` is read from the Recipient. Then the associated [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem), which is contained in the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for reading Attributes created by the Sender, must contain an appropriate RelationshipAttributeQuery in its `query` property. For example, if the Sender wants to request a RelationshipAttribute of type [ProprietaryString]({% link _docs_integrate/attribute-values.md %}#proprietarystring) that is owned by the Recipient and whose `confidentiality` is `"public"`, the Request could look like this: +We now consider the case that the Sender has an active Relationship established with the Recipient and that it wants to create a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) for this Relationship whose `value` is read from the Recipient. +Then the associated [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem), which is contained in the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for reading Attributes created by the Sender, must contain an appropriate RelationshipAttributeQuery in its `query` property. +For example, if the Sender wants to request a RelationshipAttribute of type [ProprietaryString]({% link _docs_integrate/attribute-values.md %}#proprietarystring) that is owned by the Recipient and whose `confidentiality` is `"public"`, the Request could look like this: ```jsonc { @@ -112,7 +133,10 @@ Note that an empty string must be specified as the value for the `owner` propert ### Example of reading a RelationshipAttribute with a third party involved -If the Sender has established an active Relationship with the Recipient and the Recipient has also established an active Relationship with a third party, the Sender can request to read [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) that exist in the context of the Relationship between the Recipient and the third party. To do this, a corresponding [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) must be used. The Sender inserts it into the `query` property of the [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem), which is contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for reading Attributes. For example, if the Sender wants to request a RelationshipAttribute that is owned by the Recipient and that exists in the context of the Relationship between the Recipient and a specific third party, the Request could look like this: +If the Sender has established an active Relationship with the Recipient and the Recipient has also established an active Relationship with a third party, the Sender can request to read [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) that exist in the context of the Relationship between the Recipient and the third party. +To do this, a corresponding [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) must be used. +The Sender inserts it into the `query` property of the [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem), which is contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for reading Attributes. +For example, if the Sender wants to request a RelationshipAttribute that is owned by the Recipient and that exists in the context of the Relationship between the Recipient and a specific third party, the Request could look like this: ```jsonc { @@ -132,62 +156,86 @@ If the Sender has established an active Relationship with the Recipient and the } ``` -Note that the string `"recipient"` must be specified as the value for the `owner` property of the ThirdPartyRelationshipAttributeQuery if the Sender wants the requested RelationshipAttribute to be owned by the Recipient. RelationshipAttributes that exist in the context of the Relationship between the Recipient and the third party and whose `confidentitality` is `"private"` cannot be sent by the Recipient to the Sender. +Note that the string `"recipient"` must be specified as the value for the `owner` property of the ThirdPartyRelationshipAttributeQuery if the Sender wants the requested RelationshipAttribute to be owned by the Recipient. +RelationshipAttributes that exist in the context of the Relationship between the Recipient and the third party and whose `confidentitality` is `"private"` cannot be sent by the Recipient to the Sender. ### Read multiple Attributes -Requesting read access is not limited to just a single Attribute, but it is possible to request read access to multiple Attributes at the same time. Several ReadAttributeRequestItems or suitable [RequestItemGroups]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) can be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for reading Attributes for this purpose. If you want to use a RequestItemGroup in order to request read access to multiple Attributes of the Recipient at the same time, you must insert corresponding ReadAttributeRequestItems into the `items` property of it. +Requesting read access is not limited to just a single Attribute, but it is possible to request read access to multiple Attributes at the same time. +Several ReadAttributeRequestItems or suitable [RequestItemGroups]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) can be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for reading Attributes for this purpose. +If you want to use a RequestItemGroup in order to request read access to multiple Attributes of the Recipient at the same time, you must insert corresponding ReadAttributeRequestItems into the `items` property of it. ## Send and receive the Request -The Sender that wants to read an Attribute of the Recipient may or may not already have a Relationship with the Recipient. Depending on which is the case, a different method can be used to send the [Request for reading Attributes]({% link _docs_integrate/read-attributes-from-peer.md %}#request-for-reading-attributes). There are two ways to send the Request for reading Attributes created by the Sender to the Recipient. +The Sender that wants to read an Attribute of the Recipient may or may not already have a Relationship with the Recipient. +Depending on which is the case, a different method can be used to send the [Request for reading Attributes]({% link _docs_integrate/read-attributes-from-peer.md %}#request-for-reading-attributes). +There are two ways to send the Request for reading Attributes created by the Sender to the Recipient. ### Request via RelationshipTemplate -If there is currently no Relationship between the Sender and the Recipient, this approach must be used. But it is also possible for the Sender to use a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) to send a Request to the Recipient if there is already an active Relationship between them. All details on how to send and receive a Request via a RelationshipTemplate in general can be found in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide. +If there is currently no Relationship between the Sender and the Recipient, this approach must be used. +But it is also possible for the Sender to use a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) to send a Request to the Recipient if there is already an active Relationship between them. +All details on how to send and receive a Request via a RelationshipTemplate in general can be found in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide. ### Request via Message -The Sender only has the option of sending a Request to the Recipient via a [Message]({% link _docs_integrate/data-model-overview.md %}#message) if there is already an active Relationship between them. All information on how to send and receive a Request via a Message can be found in the [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) guide. +The Sender only has the option of sending a Request to the Recipient via a [Message]({% link _docs_integrate/data-model-overview.md %}#message) if there is already an active Relationship between them. +All information on how to send and receive a Request via a Message can be found in the [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) guide. ## Accept the Request -After the Recipient has received the [Request for reading Attributes]({% link _docs_integrate/read-attributes-from-peer.md %}#request-for-reading-attributes), it can accept it to give the Sender read access to all or some of the requested Attributes. To do this, proceed as described in the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case documentation and specify the `id` of the received [Request]({% link _docs_integrate/data-model-overview.md %}#request). You must also decide and specify for each ReadAttributeRequestItem contained in the Request for reading Attributes whether you want to accept or reject it. +After the Recipient has received the [Request for reading Attributes]({% link _docs_integrate/read-attributes-from-peer.md %}#request-for-reading-attributes), it can accept it to give the Sender read access to all or some of the requested Attributes. +To do this, proceed as described in the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case documentation and specify the `id` of the received [Request]({% link _docs_integrate/data-model-overview.md %}#request). +You must also decide and specify for each ReadAttributeRequestItem contained in the Request for reading Attributes whether you want to accept or reject it. -If the Recipient does not want the Sender to read any of its Attributes and, therefore, does not want to accept the Request for reading Attributes of the Sender, it can reject it as a whole as well. For this, follow the instructions of the [Reject incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) use case. +If the Recipient does not want the Sender to read any of its Attributes and, therefore, does not want to accept the Request for reading Attributes of the Sender, it can reject it as a whole as well. +For this, follow the instructions of the [Reject incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) use case. {: .notice--info} -
+
### Accept a ReadAttributeRequestItem -If the Recipient agrees to share a requested Attribute with the Sender, it can accept the associated ReadAttributeRequestItem contained in the Request for reading Attributes. In particular, it must then provide the Attribute requested via the `query` property of the ReadAttributeRequestItem for its Response to the Request. Depending on whether the Recipient wants to share an Attribute that already exists as a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) or that has to be created first, different [AcceptReadAttributeRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptreadattributerequestitemparameters) must be used for this. If the Recipient decides to share an existing Attribute that doesn't contain at least one tag matching the `tags` specified within the `query` of the ReadAttributeRequestItem, they have the possibility to specify additional `tags` within the AcceptReadAttributeRequestItemParameters. As already indicated, a RelationshipAttributeQuery can only be validly answered with a new Attribute, and a ThirdPartyRelationshipAttributeQuery can only be validly answered with an existing Attribute. +If the Recipient agrees to share a requested Attribute with the Sender, it can accept the associated ReadAttributeRequestItem contained in the Request for reading Attributes. +In particular, it must then provide the Attribute requested via the `query` property of the ReadAttributeRequestItem for its Response to the Request. +Depending on whether the Recipient wants to share an Attribute that already exists as a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) or that has to be created first, different [AcceptReadAttributeRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptreadattributerequestitemparameters) must be used for this. +If the Recipient decides to share an existing Attribute that doesn't contain at least one tag matching the `tags` specified within the `query` of the ReadAttributeRequestItem, they have the possibility to specify additional `tags` within the AcceptReadAttributeRequestItemParameters. +As already indicated, a RelationshipAttributeQuery can only be validly answered with a new Attribute, and a ThirdPartyRelationshipAttributeQuery can only be validly answered with an existing Attribute. -Otherwise, the [error code]({% link _docs_integrate/error-codes.md %}) `error.consumption.requests.invalidAcceptParameters` arises. Furthermore, an error with the code `error.consumption.requests.attributeQueryMismatch` will be thrown if the Attribute provided by the Recipient does not match the [AttributeQuery]({% link _docs_integrate/data-model-overview.md %}#attributequeries) specified in the `query` property of the ReadAttributeRequestItem. +Otherwise, the [error code]({% link _docs_integrate/error-codes.md %}) `error.consumption.requests.invalidAcceptParameters` arises. +Furthermore, an error with the code `error.consumption.requests.attributeQueryMismatch` will be thrown if the Attribute provided by the Recipient does not match the [AttributeQuery]({% link _docs_integrate/data-model-overview.md %}#attributequeries) specified in the `query` property of the ReadAttributeRequestItem. {: .notice--info} -Accepting a ReadAttributeRequestItem with a new Attribute or an existing, that isn't shared with the Sender already neither itself nor any of its predecessing versions, leads to the creation of a LocalAttribute with a [LocalAttributeShareInfo]({% link _docs_integrate/data-model-overview.md %}#localattributeshareinfo) contained within its `shareInfo` property, whose underlying `content` is given by the shared Attribute. -Depending on whether the Recipient sends back an IdentityAttribute or a RelationshipAttribute, the ownership, and, in the case of RelationshipAttributes, from which Relationship context the RelationshipAttribute originates, it is referred to as either an [own shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes), an [own shared RelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-relationshipattributes), a [peer shared RelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-relationshipattributes) or an [emitted ThirdPartyRelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#emitted-and-received-thirdpartyrelationshipattributes). -An appropriate AcceptResponseItem of type [ReadAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#readattributeacceptresponseitem) is generated, which incorporates the `id` of the LocalAttribute in its `attributeId` property and the shared Attribute in its `attribute` property. -If a new IdentityAttribute is to be shared, a [RepositoryAttribute]({% link _docs_integrate/attribute-introduction.md %}#repositoryattributes) will additionally be created for the Recipient beforehand. +Accepting a ReadAttributeRequestItem with a new Attribute, that isn't shared with the Sender already neither itself nor any of its predecessing versions, leads to the creation of a LocalAttribute, whose underlying `content` is given by the shared Attribute. +Depending on whether the Recipient sends back an IdentityAttribute or a RelationshipAttribute and the ownership, such a LocalAttribute is referred to as either an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) or a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute). +If a new IdentityAttribute is to be shared, [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with the created OwnIdentityAttribute will additionally be created for the Recipient beforehand. +Accepting a ReadAttributeRequestItem with an existing Attribute, that isn't shared with the Sender already neither itself nor any of its predecessing versions, leads to the creation of associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) for the existing [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) or [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute). +An appropriate AcceptResponseItem of type [ReadAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#readattributeacceptresponseitem), which incorporates the `id` of the LocalAttribute in its `attributeId` property and the shared Attribute in its `attribute` property, is generated both when accepting with a new Attribute and with an existing one. -If the ReadAttributeRequestItem is accepted with an existing Attribute that the Recipient already shared with the Sender and the corresponding [own shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes) or [emitted ThirdPartyRelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#emitted-and-received-thirdpartyrelationshipattributes) does not have `"DeletedByPeer"` or `"ToBeDeletedByPeer"` as `deletionInfo.deletionStatus`, an [AttributeAlreadySharedAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributealreadysharedacceptresponseitem) will be generated. -Instead of creating a further pair consisting of an [own shared and a peer shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes) or of an [emitted and a received ThirdPartyRelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#emitted-and-received-thirdpartyrelationshipattributes), the `id` of the already existing [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute), which represent the sharing of the Attribute, is returned. +If the ReadAttributeRequestItem is accepted with an existing Attribute that the Recipient already shared with the Sender and the corresponding [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) do not have `"DeletedByRecipient"` as `deletionInfo.deletionStatus`, an [AttributeAlreadySharedAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributealreadysharedacceptresponseitem) will be generated. +The `id` of the already existing [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute), which is an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) or a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute), is returned. Note that the `id` of the LocalAttribute of the Sender matches the `id` of the corresponding LocalAttribute of the Recipient. +If the `deletionInfo.deletionStatus` of the AttributeForwardingDetails was `"ToBeDeletedByRecipient"`, their `deletionInfo` will be set to undefined. -Lastly, if the ReadAttributeRequestItem is accepted with an existing Attribute of which the Recipient already shared a predecessor with the Sender, an [AttributeSuccessionAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributesuccessionacceptresponseitem) will be generated, given that it is an [own shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes) or an [emitted ThirdPartyRelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#emitted-and-received-thirdpartyrelationshipattributes) that does not have `"DeletedByPeer"` or `"ToBeDeletedByPeer"` as `deletionInfo.deletionStatus`. -Instead of creating an independent pair consisting of an [own shared and a peer shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes) or of an [emitted and a received ThirdPartyRelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#emitted-and-received-thirdpartyrelationshipattributes), internally an [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) is performed. -The `id` of the already existing [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) predecessor is returned, as well as the `id` and `content` of the newly created LocalAttribute successor. +Lastly, if the ReadAttributeRequestItem is accepted with an existing Attribute of which the Recipient already shared a predecessor with the Sender, an [AttributeSuccessionAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributesuccessionacceptresponseitem) will be generated, given that there are [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with the predecessor that do not have `"DeletedByRecipient"` as `deletionInfo.deletionStatus`. +[AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) for the [successor]({% link _docs_integrate/update-attributes-by-succession.md %}), which is an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) or a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute), are created. +The `id` of the already existing LocalAttribute predecessor is returned, as well as the `id` and `content` of the newly created LocalAttribute successor. In any case, the respective AcceptResponseItem will be included in the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for reading Attributes that will be transferred to the Sender. ### Reject a ReadAttributeRequestItem -Even if the Recipient accepts the Request for reading Attributes as a whole, it may decide not to share every requested Attribute with the Sender. To be more precise, the Recipient has the option of rejecting [ReadAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem) that have the value `false` specified in their `mustBeAccepted` property. To reject a ReadAttributeRequestItem, use the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters). The rejection of a ReadAttributeRequestItem leads to the creation of a ResponseItem of type [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem). This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for reading Attributes. +Even if the Recipient accepts the Request for reading Attributes as a whole, it may decide not to share every requested Attribute with the Sender. +To be more precise, the Recipient has the option of rejecting [ReadAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem) that have the value `false` specified in their `mustBeAccepted` property. +To reject a ReadAttributeRequestItem, use the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters). +The rejection of a ReadAttributeRequestItem leads to the creation of a ResponseItem of type [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem). +This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for reading Attributes. ### Example of accepting a RequestItemGroup -Let's look at an example where the Sender is interested in the Recipient's [BirthDate]({% link _docs_integrate/attribute-values.md %}#birthdate) and contact information in the form of an [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) or a [PhoneNumber]({% link _docs_integrate/attribute-values.md %}#phonenumber). To ask the Recipient for this data, the Sender creates a [Request]({% link _docs_integrate/data-model-overview.md %}#request) for reading Attributes, which contains a ReadAttributeRequestItem belonging to the BirthDate and a RequestItemGroup belonging to the contact information in its `items` property. The [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) itself contains two ReadAttributeRequestItems in its `items` property, namely one for the EMailAddress and one for the PhoneNumber. +Let's look at an example where the Sender is interested in the Recipient's [BirthDate]({% link _docs_integrate/attribute-values.md %}#birthdate) and contact information in the form of an [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) or a [PhoneNumber]({% link _docs_integrate/attribute-values.md %}#phonenumber). +To ask the Recipient for this data, the Sender creates a [Request]({% link _docs_integrate/data-model-overview.md %}#request) for reading Attributes, which contains a ReadAttributeRequestItem belonging to the BirthDate and a RequestItemGroup belonging to the contact information in its `items` property. +The [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) itself contains two ReadAttributeRequestItems in its `items` property, namely one for the EMailAddress and one for the PhoneNumber. ```jsonc { @@ -227,12 +275,15 @@ Let's look at an example where the Sender is interested in the Recipient's [Birt ``` In our example, the Sender only requires the Recipient to share its EMailAddress, which is why the individual [ReadAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem) within the Request have specified corresponding values in their `mustBeAccepted` property. -We assume that the Recipient wants to accept the Request and only wants to share its EMailAddress, which is already saved as an appropriate [RepositoryAttribute]({% link _docs_integrate/attribute-introduction.md %}#repositoryattributes), with the Sender. +We assume that the Recipient wants to accept the Request and only wants to share its EMailAddress, which is already saved as an appropriate [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), with the Sender. -If the Recipient wants to accept the Request for reading Attributes, it must accept all ReadAttributeRequestItems for which the `mustBeAccepted` property is set to `true`. It is therefore not permitted, for example, for the Recipient to refuse to share its EMailAddress and instead share its PhoneNumber. +If the Recipient wants to accept the Request for reading Attributes, it must accept all ReadAttributeRequestItems for which the `mustBeAccepted` property is set to `true`. +It is therefore not permitted, for example, for the Recipient to refuse to share its EMailAddress and instead share its PhoneNumber. {: .notice--info} -The Recipient refuses to share its BirthDate with the Sender. Also, the Recipient accepts the sharing of its EMailAddress and rejects the sharing of its PhoneNumber. Thus, it responds to the Request for reading Attributes as follows: +The Recipient refuses to share its BirthDate with the Sender. +Also, the Recipient accepts the sharing of its EMailAddress and rejects the sharing of its PhoneNumber. +Thus, it responds to the Request for reading Attributes as follows: ```jsonc { @@ -246,7 +297,7 @@ The Recipient refuses to share its BirthDate with the Sender. Also, the Recipien { // Accept sharing of existing EMailAddress "accept": true, - "existingAttributeId": "" + "existingAttributeId": "" }, { // Reject sharing of PhoneNumber @@ -262,9 +313,11 @@ Note that it is important to respond to RequestItems, some of which may be conta ## Get the Attributes -We now assume that the Recipient has accepted the [Request for reading Attributes]({% link _docs_integrate/read-attributes-from-peer.md %}#request-for-reading-attributes) of the Sender. In order for the Sender to receive the Response of the Recipient, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). Please note that this synchronization can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync). +We now assume that the Recipient has accepted the [Request for reading Attributes]({% link _docs_integrate/read-attributes-from-peer.md %}#request-for-reading-attributes) of the Sender. +In order for the Sender to receive the Response of the Recipient, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). +Please note that this synchronization can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync). -
+
To view the Response to the Request, proceed as described in the [Query outgoing Requests]({% link _docs_use-cases/use-case-consumption-query-outgoing-requests.md %}) use case documentation and use the following query parameter: @@ -273,13 +326,17 @@ To view the Response to the Request, proceed as described in the [Query outgoing The Integrator of the Sender can now get the Response of the Recipient from the `response.content` property of the result. In the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) is a [ReadAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#readattributeacceptresponseitem), an [AttributeAlreadySharedAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributealreadysharedacceptresponseitem) or an [AttributeSuccessionAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributesuccessionacceptresponseitem) for each accepted and a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) for each rejected ReadAttributeRequestItem included. -A shared `attribute` that can be read from a ReadAttributeAcceptResponseItem is used to create an appropriate LocalAttribute with a LocalAttributeShareInfo of the Sender. -Depending on whether the Recipient has sent back an IdentityAttribute or a RelationshipAttribute to the Sender, the ownership, and, in the case of RelationshipAttributes, from which Relationship context the RelationshipAttribute originates, it is referred to as either a [peer shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes), an [own shared RelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-relationshipattributes), a [peer shared RelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-relationshipattributes) or a [received ThirdPartyRelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#emitted-and-received-thirdpartyrelationshipattributes). +A shared `attribute` that can be read from a ReadAttributeAcceptResponseItem is used to create an appropriate [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) of the Sender. +Depending on whether the Recipient has sent back an IdentityAttribute or a RelationshipAttribute to the Sender, the ownership, and, in the case of RelationshipAttributes, from which Relationship context the RelationshipAttribute originates, it is referred to as either a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute), an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute), a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) or a [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute). When the Sender of the Request receives an AttributeSuccessionAcceptResponseItem, the according [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) is automatically performed for them. +Processing an AttributeAlreadySharedAcceptResponseItem in the case where the `deletionInfo.deletionStatus` of the [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) or the [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute) was `"ToBeDeleted"`, its `deletionInfo` will be set to undefined. -In case of an error, [ErrorResponseItems]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) can also be included in the Response. If the Request for reading Attributes contains a RequestItemGroup in its `items` property, the Response to this Request contains a corresponding [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) in its `items` property. +In case of an error, [ErrorResponseItems]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) can also be included in the Response. +If the Request for reading Attributes contains a RequestItemGroup in its `items` property, the Response to this Request contains a corresponding [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) in its `items` property. {: .notice--info} ## What's next? -Take a look at our [Integration example]({% link _docs_integrate/integration-example.md %}) if you want to see how an Attribute of a peer is read by an Identity in the context of a larger process. Also note that it is not only possible to request the reading of an Attribute from a peer, but that you can share an Attribute with a peer as well. Consult the [Share Attributes with peer]({% link _docs_integrate/share-attributes-with-peer.md %}) guide for this. +Take a look at our [Integration example]({% link _docs_integrate/integration-example.md %}) if you want to see how an Attribute of a peer is read by an Identity in the context of a larger process. +Also note that it is not only possible to request the reading of an Attribute from a peer, but that you can share an Attribute with a peer as well. +Consult the [Share Attributes with peer]({% link _docs_integrate/share-attributes-with-peer.md %}) guide for this. diff --git a/_docs_integrate/request-and-response-introduction.md b/_docs_integrate/request-and-response-introduction.md index f153bf982..f7b4a42da 100644 --- a/_docs_integrate/request-and-response-introduction.md +++ b/_docs_integrate/request-and-response-introduction.md @@ -31,7 +31,7 @@ The Request-Response flow allows to establish transactional behavior between Ide ## Requests -
+
### Structure of Requests @@ -46,7 +46,10 @@ To extinguish different scenarios how to use Requests, there are various types o #### AuthenticationRequestItem -With the [AuthenticationRequestItem]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem) the Sender can request the peer for an authentication in a business context for a certain purpose. The peer can then decide to authenticate or not. This authentication is mostly short-lived and limited in time. Possible examples are: +With the [AuthenticationRequestItem]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem) the Sender can request the peer for an authentication in a business context for a certain purpose. +The peer can then decide to authenticate or not. +This authentication is mostly short-lived and limited in time. +Possible examples are: - Authentication for a login to a website. - Authentication for opening a door. @@ -64,7 +67,8 @@ After the Recipient has responded to the AuthenticationRequestItem, a suitable [ #### ConsentRequestItem -With the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem) it is possible to request the one-time consent of a peer to an arbitrary text and thus reach agreement on a certain non-machine-processable context. All details on how to use the ConsentRequestItem and examples of use cases for it can be found in the [Request one-time consent of peer]({% link _docs_integrate/request-one-time-consent-of-peer.md %}) guide. +With the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem) it is possible to request the one-time consent of a peer to an arbitrary text and thus reach agreement on a certain non-machine-processable context. +All details on how to use the ConsentRequestItem and examples of use cases for it can be found in the [Request one-time consent of peer]({% link _docs_integrate/request-one-time-consent-of-peer.md %}) guide. Note that the ConsentRequestItem cannot be used if intending to [request persistent consent from a peer]({% link _docs_integrate/request-persistent-consent-of-peer.md %}). {: .notice--info} @@ -82,7 +86,11 @@ After the Recipient has responded to the ConsentRequestItem, a suitable [Respons #### CreateAttributeRequestItem -If you want to create IdentityAttributes or RelationshipAttributes for the peer, the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) can be used. Please have a look at the [ProposeAttributeRequestItem](#proposeattributerequestitem) if the peer should be able to overwrite the Attribute. To create an Attribute with a fixed value defined by the Sender, an Identity uses the CreateAttributeRequestItem. A fixed value in this case means, that the Recipient is not allowed to change the value when accepting the Request. All details on how to use the CreateAttributeRequestItem and examples of use cases for it can be found in the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. +If you want to create IdentityAttributes or RelationshipAttributes for the peer, the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) can be used. +Please have a look at the [ProposeAttributeRequestItem](#proposeattributerequestitem) if the peer should be able to overwrite the Attribute. +To create an Attribute with a fixed value defined by the Sender, an Identity uses the CreateAttributeRequestItem. +A fixed value in this case means, that the Recipient is not allowed to change the value when accepting the Request. +All details on how to use the CreateAttributeRequestItem and examples of use cases for it can be found in the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. Depending on whether the CreateAttributeRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it: @@ -97,7 +105,7 @@ After the Recipient has responded to the CreateAttributeRequestItem, a suitable #### DeleteAttributeRequestItem -If you want to [request the deletion of an own Attribute from a peer]({% link _docs_integrate/delete-attributes.md %}#request-the-deletion-of-own-attributes-from-peer), the [DeleteAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#deleteattributerequestitem) must be used. +If you want to [request the deletion of an emitted Attribute from its recipient]({% link _docs_integrate/delete-attributes.md %}#request-the-deletion-of-emitted-attributes-from-recipient), the [DeleteAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#deleteattributerequestitem) must be used. Depending on whether the DeleteAttributeRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it: @@ -127,24 +135,13 @@ After the Recipient has responded to the FormFieldRequestItem, a suitable [Respo - After rejecting this RequestItem, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) will be transferred. - In case of an error, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) will be transferred. -#### FreeTextRequestItem - -With the [FreeTextRequestItem]({% link _docs_integrate/data-model-overview.md %}#freetextrequestitem) it is possible to send a free text to the peer. The peer itself can accept this with a free text as well. - -Depending on whether the FreeTextRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it: - -- To accept this RequestItem, the [AcceptFreeTextRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptfreetextrequestitemparameters) can be utilized. -- To reject this RequestItem, the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters) can be utilized. - -After the Recipient has responded to the FreeTextRequestItem, a suitable [ResponseItem]({% link _docs_integrate/data-model-overview.md %}#responseitems) is generated and transferred to the Sender of the Request: - -- After accepting this RequestItem, a [FreeTextAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#freetextacceptresponseitem) will be transferred. -- After rejecting this RequestItem, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) will be transferred. -- In case of an error, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) will be transferred. - #### ProposeAttributeRequestItem -The [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) is a combination of a [ReadAttributeRequestItem](#readattributerequestitem) and a [CreateAttributeRequestItem](#createattributerequestitem). The Sender would like to receive a correct Attribute from the peer, thinks it has a possible value but the peer might overrule this value with an existing or new one. To create an Attribute with a value proposed by the Sender, an Identity uses the ProposeAttributeRequestItem. A proposed value in this case means, that the Recipient is allowed to change the value if accepting the Request. All details on how to use the ProposeAttributeRequestItem and examples of use cases for it can be found in the [Propose Attributes to peer]({% link _docs_integrate/propose-attributes-to-peer.md %}) guide. +The [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) is a combination of a [ReadAttributeRequestItem](#readattributerequestitem) and a [CreateAttributeRequestItem](#createattributerequestitem). +The Sender would like to receive a correct Attribute from the peer, thinks it has a possible value but the peer might overrule this value with an existing or new one. +To create an Attribute with a value proposed by the Sender, an Identity uses the ProposeAttributeRequestItem. +A proposed value in this case means, that the Recipient is allowed to change the value if accepting the Request. +All details on how to use the ProposeAttributeRequestItem and examples of use cases for it can be found in the [Propose Attributes to peer]({% link _docs_integrate/propose-attributes-to-peer.md %}) guide. Depending on whether the ProposeAttributeRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it: @@ -154,14 +151,16 @@ Depending on whether the ProposeAttributeRequestItem is to be accepted or reject After the Recipient has responded to the ProposeAttributeRequestItem, a suitable [ResponseItem]({% link _docs_integrate/data-model-overview.md %}#responseitems) is generated and transferred to the Sender of the Request: - After accepting this RequestItem with a new Attribute or an existing one that isn't shared with the peer already neither itself nor any of its predecessing versions, a [ProposeAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributeacceptresponseitem) will be transferred. -- After accepting this RequestItem with an existing Attribute that was shared with the peer already, an [AttributeAlreadySharedAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributealreadysharedacceptresponseitem) will be transferred, given that the own shared LocalAttribute doesn't have `"DeletedByPeer"` or `"ToBeDeletedByPeer"` as `deletionInfo.deletionStatus`. -- After accepting this RequestItem with an existing Attribute of which a predecessor was shared with the peer already, an [AttributeSuccessionAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributesuccessionacceptresponseitem) will be transferred, given that the own shared predecessor doesn't have `"DeletedByPeer"` or `"ToBeDeletedByPeer"` as `deletionInfo.deletionStatus`. +- After accepting this RequestItem with an existing Attribute that was shared with the peer already, an [AttributeAlreadySharedAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributealreadysharedacceptresponseitem) will be transferred, given that the associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) don't have `"DeletedByRecipient"` as `deletionInfo.deletionStatus`. +- After accepting this RequestItem with an existing Attribute of which a predecessor was shared with the peer already, an [AttributeSuccessionAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributesuccessionacceptresponseitem) will be transferred, given that the associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) don't have `"DeletedByRecipient"` as `deletionInfo.deletionStatus`. - After rejecting this RequestItem, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) will be transferred. - In case of an error, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) will be transferred. #### ReadAttributeRequestItem -If you want to query an Identity's Attributes, this is done with the [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem). To query Attributes which are not known to the Sender, an Identity uses the ReadAttributeRequestItem. All details on how to use the ReadAttributeRequestItem and examples of use cases for it can be found in the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide. +If you want to query an Identity's Attributes, this is done with the [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem). +To query Attributes which are not known to the Sender, an Identity uses the ReadAttributeRequestItem. +All details on how to use the ReadAttributeRequestItem and examples of use cases for it can be found in the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide. Depending on whether the ReadAttributeRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it: @@ -171,31 +170,17 @@ Depending on whether the ReadAttributeRequestItem is to be accepted or rejected, After the Recipient has responded to the ReadAttributeRequestItem, a suitable [ResponseItem]({% link _docs_integrate/data-model-overview.md %}#responseitems) is generated and transferred to the Sender of the Request: - After accepting this RequestItem with a new Attribute or an existing one that isn't shared with the peer already neither itself nor any of its predecessing versions, a [ReadAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#readattributeacceptresponseitem) will be transferred. -- After accepting this RequestItem with an existing Attribute that was shared with the peer already, an [AttributeAlreadySharedAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributealreadysharedacceptresponseitem) will be transferred, given that the own shared LocalAttribute doesn't have `DeletedByPeer` as `deletionInfo.deletionStatus`. -- After accepting this RequestItem with an existing Attribute of which a predecessor was shared with the peer already, an [AttributeSuccessionAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributesuccessionacceptresponseitem) will be transferred, given that the own shared predecessor doesn't have `"DeletedByPeer"` or `"ToBeDeletedByPeer"` as `deletionInfo.deletionStatus`. -- After rejecting this RequestItem, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) will be transferred. -- In case of an error, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) will be transferred. - -#### RegisterAttributeListenerRequestItem - -This item is used to register a [Listener]({% link _docs_integrate/data-model-overview.md %}#localattributelistener) for a specific Attribute. The Listener will create a Request in status `Draft` if an Attribute was created that matches the given query and the user is able to send the Request to the creator of the [RegisterAttributeListenerRequestItem]({% link _docs_integrate/data-model-overview.md %}#registerattributelistenerrequestitem). Possible examples are: - -- Asking for a specific RelationshipAttribute of a partner organization. - -Depending on whether the RegisterAttributeListenerRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it: - -- To accept this RequestItem, the [AcceptRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptrequestitemparameters) can be utilized. -- To reject this RequestItem, the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters) can be utilized. - -After the Recipient has responded to the RegisterAttributeListenerRequestItem, a suitable [ResponseItem]({% link _docs_integrate/data-model-overview.md %}#responseitems) is generated and transferred to the Sender of the Request: - -- After accepting this RequestItem, a [RegisterAttributeListenerAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#registerattributelisteneracceptresponseitem) will be transferred. +- After accepting this RequestItem with an existing Attribute that was shared with the peer already, an [AttributeAlreadySharedAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributealreadysharedacceptresponseitem) will be transferred, given that the associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) don't have `"DeletedByRecipient"` as `deletionInfo.deletionStatus`. +- After accepting this RequestItem with an existing Attribute of which a predecessor was shared with the peer already, an [AttributeSuccessionAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#attributesuccessionacceptresponseitem) will be transferred, given that the associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) don't have `"DeletedByRecipient"` as `deletionInfo.deletionStatus`. - After rejecting this RequestItem, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) will be transferred. - In case of an error, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) will be transferred. #### ShareAttributeRequestItem -If you want to share the own DisplayName and possibly other Attributes, this is done with the [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem). To share own IdentityAttributes (owner = self) an Identity uses the ShareAttributeRequestItem. The Identity needs to create the IdentityAttribute separately before the Attribute can be shared. All details on how to use the ShareAttributeRequestItem and examples of use cases for it can be found in the [Share Attributes with peer]({% link _docs_integrate/share-attributes-with-peer.md %}) guide. +If you want to share the own DisplayName and possibly other Attributes, this is done with the [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem). +To share own IdentityAttributes (owner = self) an Identity uses the ShareAttributeRequestItem. +The Identity needs to create the IdentityAttribute separately before the Attribute can be shared. +All details on how to use the ShareAttributeRequestItem and examples of use cases for it can be found in the [Share Attributes with peer]({% link _docs_integrate/share-attributes-with-peer.md %}) guide. Depending on whether the ShareAttributeRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it: @@ -210,7 +195,9 @@ After the Recipient has responded to the ShareAttributeRequestItem, a suitable [ #### TransferFileOwnershipRequestItem -If you want to transfer the ownership of a [File]({% link _docs_integrate/data-model-overview.md %}#file), this is done with the [TransferFileOwnershipRequestItem]({% link _docs_integrate/data-model-overview.md %}#transferfileownershiprequestitem). The File needs to be uploaded to the Backbone beforehand. All details on how to use the TransferFileOwnershipRequestItem and examples of use cases for it can be found in the [Exchange Files using Attributes]({% link _docs_integrate/exchange-files-using-attributes.md %}#transfer-the-ownership-of-a-file-to-a-peer) guide. +If you want to transfer the ownership of a [File]({% link _docs_integrate/data-model-overview.md %}#file), this is done with the [TransferFileOwnershipRequestItem]({% link _docs_integrate/data-model-overview.md %}#transferfileownershiprequestitem). +The File needs to be uploaded to the Backbone beforehand. +All details on how to use the TransferFileOwnershipRequestItem and examples of use cases for it can be found in the [Exchange Files using Attributes]({% link _docs_integrate/exchange-files-using-attributes.md %}#transfer-the-ownership-of-a-file-to-a-peer) guide. Depending on whether the TransferFileOwnershipRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it: @@ -225,10 +212,13 @@ After the Recipient has responded to the TransferFileOwnershipRequestItem, a sui ### Rendering of RequestItems -Please note that the rendering of the [RequestItems]({% link _docs_integrate/data-model-overview.md %}#requestitems) in the App is currently being revised. As soon as the changes to the App have been made, the example here will also be adapted. +Please note that the rendering of the [RequestItems]({% link _docs_integrate/data-model-overview.md %}#requestitems) in the App is currently being revised. +As soon as the changes to the App have been made, the example here will also be adapted. {: .notice--warning} -This section gives an example of a [Request]({% link _docs_integrate/data-model-overview.md %}#request) that contains various [RequestItems]({% link _docs_integrate/data-model-overview.md %}#requestitems), namely an [AuthenticationRequestItem]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem), a [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem), a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem), a [FreeTextRequestItem]({% link _docs_integrate/data-model-overview.md %}#freetextrequestitem), a [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem), a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem), a [RegisterAttributeListenerRequestItem]({% link _docs_integrate/data-model-overview.md %}#registerattributelistenerrequestitem) and a [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem), within its `items` property. This Request can be sent from a Sender to an App user. A screenshot from the App showing how the Request is displayed to the App user is provided afterwards. +This section gives an example of a [Request]({% link _docs_integrate/data-model-overview.md %}#request) that contains various [RequestItems]({% link _docs_integrate/data-model-overview.md %}#requestitems), namely an [AuthenticationRequestItem]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem), a [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem), a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem), a [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem), a [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem) and a [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem), within its `items` property. +This Request can be sent from a Sender to an App user. +A screenshot from the App showing how the Request is displayed to the App user is provided afterwards. ```json { @@ -244,7 +234,6 @@ This section gives an example of a [Request]({% link _docs_integrate/data-model- { "@type": "ConsentRequestItem", "mustBeAccepted": true, - "title": "", "description": "<description of ConsentRequestItem>", "consent": "<consent issue originating from the Sender>", "link": "<link to external website with more information on the issue>" @@ -252,7 +241,6 @@ This section gives an example of a [Request]({% link _docs_integrate/data-model- { "@type": "CreateAttributeRequestItem", "mustBeAccepted": true, - "title": "<title of CreateAttributeRequestItem>", "description": "<description of CreateAttributeRequestItem>", "attribute": { "@type": "IdentityAttribute", @@ -261,22 +249,12 @@ This section gives an example of a [Request]({% link _docs_integrate/data-model- "@type": "Surname", "value": "<surname created for the App user by the Sender>" }, - "tags": ["<tag of surname to be created>"], - "validFrom": "<start of IdentityAttribute's validity>", - "validTo": "<end of IdentityAttribute's validity>" + "tags": ["<tag of surname to be created>"] } }, - { - "@type": "FreeTextRequestItem", - "mustBeAccepted": false, - "title": "<title of FreeTextRequestItem>", - "description": "<description of FreeTextRequestItem>", - "freeText": "<free text written by the Sender>" - }, { "@type": "ProposeAttributeRequestItem", "mustBeAccepted": false, - "title": "<title of ProposeAttributeRequestItem>", "description": "<description of ProposeAttributeRequestItem>", "attribute": { "@type": "IdentityAttribute", @@ -285,9 +263,7 @@ This section gives an example of a [Request]({% link _docs_integrate/data-model- "@type": "GivenName", "value": "<given name proposed by the Sender>" }, - "tags": ["<tag of proposed given name>"], - "validFrom": "<start of IdentityAttribute's validity>", - "validTo": "<end of IdentityAttribute's validity>" + "tags": ["<tag of proposed given name>"] }, "query": { "@type": "IdentityAttributeQuery", @@ -297,33 +273,16 @@ This section gives an example of a [Request]({% link _docs_integrate/data-model- { "@type": "ReadAttributeRequestItem", "mustBeAccepted": false, - "title": "<title of ReadAttributeRequestItem>", "description": "<description of ReadAttributeRequestItem>", "query": { "@type": "IdentityAttributeQuery", "valueType": "BirthDate", - "tags": ["<tag of date of birth to be read>"], - "validFrom": "<start of IdentityAttribute's validity>", - "validTo": "<end of IdentityAttribute's validity>" - } - }, - { - "@type": "RegisterAttributeListenerRequestItem", - "mustBeAccepted": false, - "title": "<title of RegisterAttributeListenerRequestItem>", - "description": "<description of RegisterAttributeListenerRequestItem>", - "query": { - "@type": "IdentityAttributeQuery", - "valueType": "StreetAddress", - "tags": ["<tag of street address for which the registration was made>"], - "validFrom": "<start of IdentityAttribute's validity>", - "validTo": "<end of IdentityAttribute's validity>" + "tags": ["<tag of date of birth to be read>"] } }, { "@type": "ShareAttributeRequestItem", "mustBeAccepted": true, - "title": "<title of ShareAttributeRequestItem>", "description": "<description of ShareAttributeRequestItem>", "attribute": { "@type": "IdentityAttribute", @@ -332,32 +291,34 @@ This section gives an example of a [Request]({% link _docs_integrate/data-model- "@type": "DisplayName", "value": "<display name shared by the Sender>" }, - "tags": ["<tag of shared display name>"], - "validFrom": "<start of IdentityAttribute's validity>", - "validTo": "<end of IdentityAttribute's validity>" + "tags": ["<tag of shared display name>"] }, - "sourceAttributeId": "<ID of source RepositoryAttribute>" + "attributeId": "<ID of source OwnIdentityAttribute>" } ] } ``` -The `<...>` notation is used as a placeholder for the actual data as usual. Also note that in the example Request, the [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) have been used for test purposes instead of the [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) for those RequestItems that relate to [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes). For an overview of the different types of Attributes, consult the [Attribute introduction]({% link _docs_integrate/attribute-introduction.md %}). +The `<...>` notation is used as a placeholder for the actual data as usual. +Also note that in the example Request, the [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) have been used for test purposes instead of the [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) for those RequestItems that relate to [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes). +For an overview of the different types of Attributes, consult the [Attribute introduction]({% link _docs_integrate/attribute-introduction.md %}). {: .notice--info} After the Sender has created the Request and sent it to the App user [via a Message]({% link _docs_integrate/requests-via-messages.md %}) or [via a RelationshipTemplate]({% link _docs_integrate/requests-via-relationshiptemplates.md %}), the Request is displayed to the App user. The following screenshot shows the rendering of the example Request in the App. The order in which the RequestItems are rendered corresponds to the order in which they appear in the example Request. -<div style="width: 640px; height: 600px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:600px" src="https://lucid.app/documents/embedded/847ca447-3c5b-461b-a9f8-206a2384475b" id="bN9IW2Drzrx."></iframe></div> +<div style="width: 640px; height: 600px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:600px" src="https://lucid.app/documents/embedded/cefb2b00-928c-431b-8bf6-3086534f891c" id="bN9IW2Drzrx."></iframe></div> -At the bottom of the App screen, there is a "Reject" button to [reject the Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) and an "Accept" button to [accept the Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}). If no Relationship has been established between the Sender and the App user, and the Request was sent [via a RelationshipTemplate]({% link _docs_integrate/requests-via-relationshiptemplates.md %}), the "Accept" button is labeled "Add Contact" instead. +At the bottom of the App screen, there is a "Reject" button to [reject the Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) and an "Accept" button to [accept the Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}). +If no Relationship has been established between the Sender and the App user, and the Request was sent [via a RelationshipTemplate]({% link _docs_integrate/requests-via-relationshiptemplates.md %}), the "Accept" button is labeled "Add Contact" instead. {: .notice--info} The screenshot demonstrates that the rendering of the individual kinds of [RequestItems]({% link _docs_integrate/data-model-overview.md %}#requestitems) differs from one another. However, the display of a RequestItem in the App depends not only on its properties, but also on which [DecideRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#deciderequestitemparameters) must be used to accept it. -For instance, when accepting a ProposeAttributeRequestItem, the [AcceptProposeAttributeRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptproposeattributerequestitemparameters) must be utilized. These parameters enable acceptance of the ProposeAttributeRequestItem with either an existing Attribute or a new one, which could be the Attribute proposed by the Sender. +For instance, when accepting a ProposeAttributeRequestItem, the [AcceptProposeAttributeRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptproposeattributerequestitemparameters) must be utilized. +These parameters enable acceptance of the ProposeAttributeRequestItem with either an existing Attribute or a new one, which could be the Attribute proposed by the Sender. In the App, a small arrow icon is displayed to the right of the ProposeAttributeRequestItem, which leads the App user to a list of existing Attributes that would be suitable for accepting the ProposeAttributeRequestItem, too. In addition, further new Attributes suitable for accepting the ProposeAttributeRequestItem can be created there. {: .notice--info} @@ -370,8 +331,9 @@ In our example Request, this is the case for the [AuthenticationRequestItem]({% If you do not agree to accept a RequestItem whose value of its `mustBeAccepted` property is set to `true`, you are forced to reject the Request as a whole. Some RequestItems exhibit particular characteristics. -For the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem), for example, a `link` to an external website with more information on the `consent` issue originating from the Sender can optionally be specified. -Specifying a `link` causes an icon to appear to the right of the ConsentRequestItem. +For the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem), for example, setting the optional property `requiresInteraction` to `true` means that the checkbox in the App associated with it is not preselected and must be explicitly ticked, even if `mustBeAccepted` is set to `true`. +Furthermore, a `link` to an external website with more information on the `consent` issue originating from the Sender can optionally be specified for the ConsentRequestItem. +This causes an icon to appear to the right of it. Clicking on this icon redirects to the corresponding website. The ConsentRequestItem from our example Request provides a `link`. For this reason, the mentioned icon can be found in the screenshot of the App. @@ -394,7 +356,7 @@ If a RequestItem is accepted, an [AcceptResponseItem]({% link _docs_integrate/da Depending on the kind of RequestItem, it might be a specific AcceptResponseItem, extending the base AcceptResponseItem to answer to RequestItems demanding additional information. For example, a ReadAttributeRequestItem is accepted using a [ReadAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#readattributeacceptresponseitem), additionally transmitting information about the respective Attribute. -<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/fd7932ee-c69a-4c31-9968-b9331ba780ba" id="A1WuBwZ9NzC8"></iframe></div> +<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/ee05d3a9-d8a8-4096-8f92-ee1fa4300577" id="W1Y-VwMz6n.a"></iframe></div> If a RequestItem is rejected, however, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) is created. Lastly, in case the enmeshed Runtime detects a problem, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) is generated. diff --git a/_docs_integrate/request-one-time-consent-of-peer.md b/_docs_integrate/request-one-time-consent-of-peer.md index f0771c7b3..53c969e4f 100644 --- a/_docs_integrate/request-one-time-consent-of-peer.md +++ b/_docs_integrate/request-one-time-consent-of-peer.md @@ -25,9 +25,14 @@ required_by: # End automatic generation --- -This guide explains how an Identity can obtain the one-time consent of one of its peers on a particular issue using the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem). With the ConsentRequestItem it is possible to request the consent of a peer to an arbitrary text and thus reach agreement on a certain non-machine-processable context. The text for which the peer is asked for a one-time consent is specified in its `consent` property. To obtain a one-time consent, the Identity must send a [Request]({% link _docs_integrate/data-model-overview.md %}#request) to its peer that contains the corresponding ConsentRequestItem within its `items` property. The peer can accept or reject the ConsentRequestItem depending on whether or not the peer gives one-time consent to the text. - -Since understanding the process of asking a peer for a one-time consent requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) in general, you should take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) before continuing to read this guide. Further information on the [ConsentRequestItem]({% link _docs_integrate/request-and-response-introduction.md %}#consentrequestitem) can be found there as well. +This guide explains how an Identity can obtain the one-time consent of one of its peers on a particular issue using the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem). +With the ConsentRequestItem it is possible to request the consent of a peer to an arbitrary text and thus reach agreement on a certain non-machine-processable context. +The text for which the peer is asked for a one-time consent is specified in its `consent` property. +To obtain a one-time consent, the Identity must send a [Request]({% link _docs_integrate/data-model-overview.md %}#request) to its peer that contains the corresponding ConsentRequestItem within its `items` property. +The peer can accept or reject the ConsentRequestItem depending on whether or not the peer gives one-time consent to the text. + +Since understanding the process of asking a peer for a one-time consent requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) in general, you should take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) before continuing to read this guide. +Further information on the [ConsentRequestItem]({% link _docs_integrate/request-and-response-introduction.md %}#consentrequestitem) can be found there as well. {: .notice--info} <!-- This include inserts the table with the metadata --> @@ -50,14 +55,19 @@ Also note that the ConsentRequestItem should not be used for contractual agreeme ## Request for one-time consent -In the following, we describe how a Connector, hereinafter referred to as the Sender, can get the one-time consent of another Connector, with which it has already established a Relationship and which is also referred to as the Recipient. To do this, the Sender sends an appropriate [Request]({% link _docs_integrate/data-model-overview.md %}#request), which contains a [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem) within its `items` property, to the Recipient. +In the following, we describe how a Connector, hereinafter referred to as the Sender, can get the one-time consent of another Connector, with which it has already established a Relationship and which is also referred to as the Recipient. +To do this, the Sender sends an appropriate [Request]({% link _docs_integrate/data-model-overview.md %}#request), which contains a [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem) within its `items` property, to the Recipient. -The general procedure is the same if the Connector wants to obtain the one-time consent of an App user instead of another Connector. For reasons of clarity, this guide focuses on the process with two Connectors. For information on how to establish Relationships, refer to the [Establish Relationships]({% link _docs_integrate/establish-relationships.md %}) scenario documentation. +The general procedure is the same if the Connector wants to obtain the one-time consent of an App user instead of another Connector. +For reasons of clarity, this guide focuses on the process with two Connectors. +For information on how to establish Relationships, refer to the [Establish Relationships]({% link _docs_integrate/establish-relationships.md %}) scenario documentation. {: .notice--info} -As there is already a Relationship between the Sender and the Recipient, the Sender can send the [Request via a Message]({% link _docs_integrate/requests-via-messages.md %}) to the Recipient. Even if the Relationship has already been established, the Sender could also send the [Request via a RelationshipTemplate]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) to the Recipient, but this is not discussed further here. +As there is already a Relationship between the Sender and the Recipient, the Sender can send the [Request via a Message]({% link _docs_integrate/requests-via-messages.md %}) to the Recipient. +Even if the Relationship has already been established, the Sender could also send the [Request via a RelationshipTemplate]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) to the Recipient, but this is not discussed further here. -Please note that if there is no active Relationship between the Sender and the Recipient, the Request for one-time consent must be sent via a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) instead of a [Message]({% link _docs_integrate/data-model-overview.md %}#message). The process of [establishing a Relationship]({% link _docs_integrate/establish-relationships.md %}) is then initiated at the same time. +Please note that if there is no active Relationship between the Sender and the Recipient, the Request for one-time consent must be sent via a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) instead of a [Message]({% link _docs_integrate/data-model-overview.md %}#message). +The process of [establishing a Relationship]({% link _docs_integrate/establish-relationships.md %}) is then initiated at the same time. {: .notice--info} ### Create the Request @@ -67,6 +77,7 @@ To create the Request, the Sender must proceed as described in the [Create outgo In this example, the value of the `mustBeAccepted` property of the ConsentRequestItem is set to `true`. Please note that the `<...>` notation is used as a placeholder for the actual data as usual and that the `link` property of the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem) is optional and can therefore also be omitted. In addition to the `link`, a `linkDisplayText` could optionally be specified, which would be displayed in the App instead of the URL of the `link`. +Furthermore, the `requiresInteraction` property could be used to ensure that the checkbox in the App associated with the ConsentRequestItem is definitely not preselected. ```jsonc { @@ -84,12 +95,18 @@ In addition to the `link`, a `linkDisplayText` could optionally be specified, wh } ``` -Before creating the Request, the Sender should check whether it is valid. This can be done by proceeding as described in the documentation of the [Check if outgoing Request can be created]({% link _docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md %}) use case. The advantage of checking the validity of the Request first before attempting to create it is that the Sender will receive a more precise [error]({% link _docs_integrate/error-codes.md %}) description in the case of a faulty Request. +Before creating the Request, the Sender should check whether it is valid. +This can be done by proceeding as described in the documentation of the [Check if outgoing Request can be created]({% link _docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md %}) use case. +The advantage of checking the validity of the Request first before attempting to create it is that the Sender will receive a more precise [error]({% link _docs_integrate/error-codes.md %}) description in the case of a faulty Request. {: .notice--info} ### Send the Request -After the Request has been created, the Sender can send it to the Recipient. To send the [Request via a Message]({% link _docs_integrate/requests-via-messages.md %}), the Sender has to follow the instructions of the [Send a Message to the Recipient]({% link _docs_use-cases/use-case-transport-send-message-to-recipients.md %}) use case documentation. To continue the example, the following payload must be used by the Sender to send the [created Request]({% link _docs_integrate/request-one-time-consent-of-peer.md %}#create-the-request) to the Recipient via a Message. It is essential that the `id` of the Request is specified, which was generated after the Request was created by the Sender with the [Create outgoing Request]({% link _docs_use-cases/use-case-consumption-create-outgoing-request.md %}) use case. This enables the Request to be processed correctly by the Recipient. +After the Request has been created, the Sender can send it to the Recipient. +To send the [Request via a Message]({% link _docs_integrate/requests-via-messages.md %}), the Sender has to follow the instructions of the [Send a Message to the Recipient]({% link _docs_use-cases/use-case-transport-send-message-to-recipients.md %}) use case documentation. +To continue the example, the following payload must be used by the Sender to send the [created Request]({% link _docs_integrate/request-one-time-consent-of-peer.md %}#create-the-request) to the Recipient via a Message. +It is essential that the `id` of the Request is specified, which was generated after the Request was created by the Sender with the [Create outgoing Request]({% link _docs_use-cases/use-case-consumption-create-outgoing-request.md %}) use case. +This enables the Request to be processed correctly by the Recipient. ```jsonc { @@ -113,20 +130,26 @@ After the Request has been created, the Sender can send it to the Recipient. To In order to receive the [Message]({% link _docs_integrate/data-model-overview.md %}#message) that contains the [Request for one-time consent]({% link _docs_integrate/request-one-time-consent-of-peer.md %}#request-for-one-time-consent) as `content`, the Recipient must [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). If the Recipient wants to accept the Request and in particular all its [ConsentRequestItems]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem) for which the value of the `mustBeAccepted` property is set to `true`, it must proceed as described in the documentation of the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case. -In doing so, the [AcceptRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptrequestitemparameters) must be used to accept a ConsentRequestItem. If the Recipient gives the Sender one-time consent to an issue, it should accept the corresponding ConsentRequestItem. +In doing so, the [AcceptRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptrequestitemparameters) must be used to accept a ConsentRequestItem. +If the Recipient gives the Sender one-time consent to an issue, it should accept the corresponding ConsentRequestItem. If the Recipient does not want to agree to the issue that the Sender wants the Recipient to agree to, it can of course also reject the corresponding [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem) by using the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters), as long as its value of the `mustBeAccepted` property is set to `false`, or [reject the incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) as a whole. {: .notice--info} -Accepting the ConsentRequestItem leads to the creation of an [AcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#acceptresponseitem). This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for one-time consent that will be transferred to the Sender. +Accepting the ConsentRequestItem leads to the creation of an [AcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#acceptresponseitem). +This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for one-time consent that will be transferred to the Sender. ### Receive the Response to the Request -We now assume that the Recipient has accepted the [Request for one-time consent]({% link _docs_integrate/request-one-time-consent-of-peer.md %}#request-for-one-time-consent) of the Sender and in particular the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem), whose value of the `mustBeAccepted` property is set to `true` and which is used in the example studied to request a one-time consent. In order for the Sender to receive the Recipient's Response to the Request, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). The Sender is then informed whether or not the Recipient has given one-time consent to the issue originating from the Sender. +We now assume that the Recipient has accepted the [Request for one-time consent]({% link _docs_integrate/request-one-time-consent-of-peer.md %}#request-for-one-time-consent) of the Sender and in particular the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem), whose value of the `mustBeAccepted` property is set to `true` and which is used in the example studied to request a one-time consent. +In order for the Sender to receive the Recipient's Response to the Request, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). +The Sender is then informed whether or not the Recipient has given one-time consent to the issue originating from the Sender. Please note that the required synchronization of both Identities can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync). {: .notice--info} ## What's next? -If an Identity asks for a persistent consent instead of a one-time consent of one of its peers, the ConsentRequestItem cannot be used. For persistent consent, it is necessary that the Identity sends a [Request]({% link _docs_integrate/data-model-overview.md %}#request) to its peer, which leads to the creation of a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with [Consent]({% link _docs_integrate/attribute-values.md %}#consent) as `value.@type`. For more details, the documentation of the [Request persistent consent of peer]({% link _docs_integrate/request-persistent-consent-of-peer.md %}) scenario can be consulted. +If an Identity asks for a persistent consent instead of a one-time consent of one of its peers, the ConsentRequestItem cannot be used. +For persistent consent, it is necessary that the Identity sends a [Request]({% link _docs_integrate/data-model-overview.md %}#request) to its peer, which leads to the creation of a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with [Consent]({% link _docs_integrate/attribute-values.md %}#consent) as `value.@type`. +For more details, the documentation of the [Request persistent consent of peer]({% link _docs_integrate/request-persistent-consent-of-peer.md %}) scenario can be consulted. diff --git a/_docs_integrate/request-persistent-consent-of-peer.md b/_docs_integrate/request-persistent-consent-of-peer.md index f4f76f42e..94d2ab862 100644 --- a/_docs_integrate/request-persistent-consent-of-peer.md +++ b/_docs_integrate/request-persistent-consent-of-peer.md @@ -23,34 +23,50 @@ required_by: # End automatic generation --- -This guide explains how an Identity can obtain the persistent consent of one of its peers on a particular issue. Technically, this form of consent is stored by a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with [Consent]({% link _docs_integrate/attribute-values.md %}#consent) as `value.@type`, that exists in the context of their [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) and that is usually owned by the peer. +This guide explains how an Identity can obtain the persistent consent of one of its peers on a particular issue. +Technically, this form of consent is stored by a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with [Consent]({% link _docs_integrate/attribute-values.md %}#consent) as `value.@type`, that exists in the context of their [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) and that is usually owned by the peer. For information on how to establish Relationships, refer to the [Establish Relationships]({% link _docs_integrate/establish-relationships.md %}) scenario documentation. {: .notice--info} -If an Identity wants to obtain the persistent consent of one of its peers and thus [create a RelationshipAttribute]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-a-relationshipattribute) with Consent as `value.@type` for their Relationship, it has several options on how to do this. These have in common that the Identity must send a [Request]({% link _docs_integrate/data-model-overview.md %}#request) to create such a RelationshipAttribute to its peer, which must be accepted by the peer. The Identity usually wants to define the values for the properties of the [Consent]({% link _docs_integrate/attribute-values.md %}#consent) itself. This applies in particular to its `consent` property, in which the text is specified to which the peer should persistently agree. The peer should not be able to change this text or the other values for the properties of the Consent. For this purpose, it makes the most sense for the Identity to send a [Request]({% link _docs_integrate/data-model-overview.md %}#request) to the peer that contains a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) within its `items` property. The RelationshipAttribute to be created must then be inserted into the `attribute` property of the CreateAttributeRequestItem. Further information on using the CreateAttributeRequestItem can be found in the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. +If an Identity wants to obtain the persistent consent of one of its peers and thus [create a RelationshipAttribute]({% link _docs_integrate/create-attributes-for-yourself.md %}#create-a-relationshipattribute) with Consent as `value.@type` for their Relationship, it has several options on how to do this. +These have in common that the Identity must send a [Request]({% link _docs_integrate/data-model-overview.md %}#request) to create such a RelationshipAttribute to its peer, which must be accepted by the peer. +The Identity usually wants to define the values for the properties of the [Consent]({% link _docs_integrate/attribute-values.md %}#consent) itself. +This applies in particular to its `consent` property, in which the text is specified to which the peer should persistently agree. +The peer should not be able to change this text or the other values for the properties of the Consent. +For this purpose, it makes the most sense for the Identity to send a [Request]({% link _docs_integrate/data-model-overview.md %}#request) to the peer that contains a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) within its `items` property. +The RelationshipAttribute to be created must then be inserted into the `attribute` property of the CreateAttributeRequestItem. +Further information on using the CreateAttributeRequestItem can be found in the [Create Attributes for peer]({% link _docs_integrate/create-attributes-for-peer.md %}) guide. ## Examples of consents -There are many situations in which an Identity needs or wants the persistent consent of one of its peers. The corresponding text that the peer should agree to is contained within the `consent` property of a [Consent]({% link _docs_integrate/attribute-values.md %}#consent), for example: +There are many situations in which an Identity needs or wants the persistent consent of one of its peers. +The corresponding text that the peer should agree to is contained within the `consent` property of a [Consent]({% link _docs_integrate/attribute-values.md %}#consent), for example: - "I hereby confirm that I have read and agree to the privacy terms of this cloud service." - "The provided EULA has been read and agreed to." - "Yes, I have backed up all of my data on this computer and you can wipe it." - "Yes, I want to opt-in to the newsletter." -The `consent` property of a Consent is not intended to be used by an Identity to send a lot of text to the peer. Instead, it should contain a brief summary of the issue, which the peer should agree to. Longer texts should be placed on external websites. A link to such a website can be specified in the optional `link` property of the Consent. Also note that the Consent should not be used for contractual agreements. +The `consent` property of a Consent is not intended to be used by an Identity to send a lot of text to the peer. +Instead, it should contain a brief summary of the issue, which the peer should agree to. +Longer texts should be placed on external websites. +A link to such a website can be specified in the optional `link` property of the Consent. +Also note that the Consent should not be used for contractual agreements. ## Request for persistent consent In the following, we describe how a Connector, hereinafter referred to as the Sender, can create a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with [Consent]({% link _docs_integrate/attribute-values.md %}#consent) as `value.@type` for a Relationship to another Connector, the so-called Recipient, by sending an appropriate [Request]({% link _docs_integrate/data-model-overview.md %}#request). -The general procedure is the same if the Connector wants to obtain the persistent consent of an App user instead of another Connector. For reasons of clarity, this guide focuses on the process with two Connectors. +The general procedure is the same if the Connector wants to obtain the persistent consent of an App user instead of another Connector. +For reasons of clarity, this guide focuses on the process with two Connectors. {: .notice--info} -As there is already a Relationship between the Sender and the Recipient, the Sender can send the [Request via a Message]({% link _docs_integrate/requests-via-messages.md %}) to the Recipient. Even if the Relationship has already been established, the Sender could also send the [Request via a RelationshipTemplate]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) to the Recipient, but this is not discussed further here. +As there is already a Relationship between the Sender and the Recipient, the Sender can send the [Request via a Message]({% link _docs_integrate/requests-via-messages.md %}) to the Recipient. +Even if the Relationship has already been established, the Sender could also send the [Request via a RelationshipTemplate]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) to the Recipient, but this is not discussed further here. -Please note that if there is no active Relationship between the Sender and the Recipient, the Request for persistent consent must be sent via a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) instead of a [Message]({% link _docs_integrate/data-model-overview.md %}#message). The process of [establishing a Relationship]({% link _docs_integrate/establish-relationships.md %}) is then initiated at the same time. +Please note that if there is no active Relationship between the Sender and the Recipient, the Request for persistent consent must be sent via a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) instead of a [Message]({% link _docs_integrate/data-model-overview.md %}#message). +The process of [establishing a Relationship]({% link _docs_integrate/establish-relationships.md %}) is then initiated at the same time. {: .notice--info} ### Create the Request @@ -90,12 +106,18 @@ In addition to the `link`, a `linkDisplayText` could optionally be specified, wh } ``` -Before creating the Request, the Sender should check whether it is valid. This can be done by proceeding as described in the documentation of the [Check if outgoing Request can be created]({% link _docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md %}) use case. The advantage of checking the validity of the Request first before attempting to create it is that the Sender will receive a more precise [error]({% link _docs_integrate/error-codes.md %}) description in the case of a faulty Request. +Before creating the Request, the Sender should check whether it is valid. +This can be done by proceeding as described in the documentation of the [Check if outgoing Request can be created]({% link _docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md %}) use case. +The advantage of checking the validity of the Request first before attempting to create it is that the Sender will receive a more precise [error]({% link _docs_integrate/error-codes.md %}) description in the case of a faulty Request. {: .notice--info} ### Send the Request -After the Request has been created, the Sender can send it to the Recipient. To send the [Request via a Message]({% link _docs_integrate/requests-via-messages.md %}), the Sender has to follow the instructions of the [Send a Message to the Recipient]({% link _docs_use-cases/use-case-transport-send-message-to-recipients.md %}) use case documentation. To continue the example, the following payload must be used by the Sender to send the [created Request]({% link _docs_integrate/request-persistent-consent-of-peer.md %}#create-the-request) to the Recipient via a Message. It is essential that the `id` of the Request is specified, which was generated after the Request was created by the Sender with the [Create outgoing Request]({% link _docs_use-cases/use-case-consumption-create-outgoing-request.md %}) use case. This enables the Request to be processed correctly by the Recipient. +After the Request has been created, the Sender can send it to the Recipient. +To send the [Request via a Message]({% link _docs_integrate/requests-via-messages.md %}), the Sender has to follow the instructions of the [Send a Message to the Recipient]({% link _docs_use-cases/use-case-transport-send-message-to-recipients.md %}) use case documentation. +To continue the example, the following payload must be used by the Sender to send the [created Request]({% link _docs_integrate/request-persistent-consent-of-peer.md %}#create-the-request) to the Recipient via a Message. +It is essential that the `id` of the Request is specified, which was generated after the Request was created by the Sender with the [Create outgoing Request]({% link _docs_use-cases/use-case-consumption-create-outgoing-request.md %}) use case. +This enables the Request to be processed correctly by the Recipient. ```jsonc { @@ -126,22 +148,33 @@ After the Request has been created, the Sender can send it to the Recipient. To ### Receive and accept the Request -In order to receive the [Message]({% link _docs_integrate/data-model-overview.md %}#message) that contains the [Request for persistent consent]({% link _docs_integrate/request-persistent-consent-of-peer.md %}#request-for-persistent-consent) as `content`, the Recipient must [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). If the Recipient wants to accept the Request and in particular all its [CreateAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) for which the value of the `mustBeAccepted` property is set to `true`, it must proceed as described in the documentation of the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case. In doing so, the [AcceptRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptrequestitemparameters) must be used to accept a CreateAttributeRequestItem, which is used in this context to request the creation of a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with [Consent]({% link _docs_integrate/attribute-values.md %}#consent) as `value.@type`, if the Recipient persistently consents to the corresponding issue originating from the Sender. +In order to receive the [Message]({% link _docs_integrate/data-model-overview.md %}#message) that contains the [Request for persistent consent]({% link _docs_integrate/request-persistent-consent-of-peer.md %}#request-for-persistent-consent) as `content`, the Recipient must [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). +If the Recipient wants to accept the Request and in particular all its [CreateAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) for which the value of the `mustBeAccepted` property is set to `true`, it must proceed as described in the documentation of the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case. +In doing so, the [AcceptRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptrequestitemparameters) must be used to accept a CreateAttributeRequestItem, which is used in this context to request the creation of a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with [Consent]({% link _docs_integrate/attribute-values.md %}#consent) as `value.@type`, if the Recipient persistently consents to the corresponding issue originating from the Sender. If the Recipient does not want to agree to the issue that the Sender wants the Recipient to agree to, it can of course also reject the corresponding [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) by using the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters), as long as its value of the `mustBeAccepted` property is set to `false`, or [reject the incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) as a whole. {: .notice--info} -Accepting the CreateAttributeRequestItem leads to the creation of the [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with Consent as `value.@type`. Technically, this is stored as the `content` of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). As the Recipient is the `owner` of the underlying RelationshipAttribute in the example studied, the LocalAttribute is also referred to as own shared RelationshipAttribute. Based on this, an appropriate AcceptResponseItem of type [CreateAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#createattributeacceptresponseitem) is generated, which incorporates the `id` of the created own shared RelationshipAttribute in its `attributeId` property. This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for persistent consent that will be transferred to the Sender. +Accepting the CreateAttributeRequestItem leads to the creation of the [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with Consent as `value.@type`. +Technically, this is stored as the `content` of an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute), as the Recipient is the `owner` of the underlying RelationshipAttribute in the example studied. +Based on this, an appropriate AcceptResponseItem of type [CreateAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#createattributeacceptresponseitem) is generated, which incorporates the `id` of the created OwnRelationshipAttribute in its `attributeId` property. +This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for persistent consent that will be transferred to the Sender. ### Receive the Response to the Request -We now assume that the Recipient has accepted the [Request for persistent consent]({% link _docs_integrate/request-persistent-consent-of-peer.md %}#request-for-persistent-consent) of the Sender and in particular the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem), whose value of the `mustBeAccepted` property is set to `true` and which is used in the example studied to request the creation of a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with Consent as `value.@type`. In order for the Sender to receive the Recipient's Response to the Request, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). +We now assume that the Recipient has accepted the [Request for persistent consent]({% link _docs_integrate/request-persistent-consent-of-peer.md %}#request-for-persistent-consent) of the Sender and in particular the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem), whose value of the `mustBeAccepted` property is set to `true` and which is used in the example studied to request the creation of a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with Consent as `value.@type`. +In order for the Sender to receive the Recipient's Response to the Request, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). Please note that the required synchronization of both Identities can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync). {: .notice--info} -The accepted CreateAttributeRequestItem leads to the creation of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) for the Sender, a so-called peer shared RelationshipAttribute. Its `content` is given by the `attribute` specified within the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem), in other words by the [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with Consent as `value.@type`, which is owned by the Recipient. It represents the necessary counterpart to the Recipient's own shared RelationshipAttribute. +The accepted CreateAttributeRequestItem leads to the creation of a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) for the Sender. +Its `content` is given by the `attribute` specified within the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem), in other words by the [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with Consent as `value.@type`, which is owned by the Recipient. +It represents the necessary counterpart to the Recipient's OwnRelationshipAttribute. ## What's next? -If an Identity asks for a one-time consent instead of a persistent consent of one of its peers, the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem) can be used. It must be inserted into the `items` property of an appropriate [Request]({% link _docs_integrate/data-model-overview.md %}#request). Processing the ConsentRequestItem does not lead to the creation of a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with Consent as `value.@type`. For more details, the documentation of the [Request one-time consent of peer]({% link _docs_integrate/request-one-time-consent-of-peer.md %}) scenario can be consulted. +If an Identity asks for a one-time consent instead of a persistent consent of one of its peers, the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem) can be used. +It must be inserted into the `items` property of an appropriate [Request]({% link _docs_integrate/data-model-overview.md %}#request). +Processing the ConsentRequestItem does not lead to the creation of a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with Consent as `value.@type`. +For more details, the documentation of the [Request one-time consent of peer]({% link _docs_integrate/request-one-time-consent-of-peer.md %}) scenario can be consulted. diff --git a/_docs_integrate/requests-via-messages.md b/_docs_integrate/requests-via-messages.md index 8d4e3d892..7e3bc3a7d 100644 --- a/_docs_integrate/requests-via-messages.md +++ b/_docs_integrate/requests-via-messages.md @@ -50,7 +50,8 @@ To retrieve it, the Sender can [query their Relationships]({% link _docs_use-cas ] ``` -{% include copy-notice description="Look for the correct Relationship and save its `peer` property. You are going to need it later." %} +{% include copy-notice description="Look for the correct Relationship and save its `peer` property. +You are going to need it later." %} ## Check the Request's validity @@ -108,7 +109,8 @@ Also, note that the `content` was extented by the `@type` property and a generat } ``` -{% include copy-notice description="Save the complete `content` of the response. You will need it in the next step." %} +{% include copy-notice description="Save the complete `content` of the response. +You will need it in the next step." %} ## Send the Request diff --git a/_docs_integrate/requests-via-relationshiptemplates.md b/_docs_integrate/requests-via-relationshiptemplates.md index 96fdde8e0..b33f522d5 100644 --- a/_docs_integrate/requests-via-relationshiptemplates.md +++ b/_docs_integrate/requests-via-relationshiptemplates.md @@ -31,14 +31,17 @@ This guide explains the end-to-end flow of sending a [Request]({% link _docs_int Usually, this flow happens between a [Connector]({% link _docs_explore/52-connector.md %}) and the [App]({% link _docs_explore/50-app.md %}), but for simplicity and more transparency, two Connectors are used here. To try out the examples in this guide on your own, you therefore need two Connectors. -You can use the [Connector Setup]({% link _docs_operate/setup-with-docker-compose.md %}) guide if you need help installing the Connectors. Since understanding the process of sending a Request via a RelationshipTemplate requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) in general, you should also take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}). +You can use the [Connector Setup]({% link _docs_operate/setup-with-docker-compose.md %}) guide if you need help installing the Connectors. +Since understanding the process of sending a Request via a RelationshipTemplate requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) in general, you should also take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}). {: .notice--info} On the first Connector, which is referred to as the Sender, you construct the Request and [create the RelationshipTemplate](#create-the-relationshiptemplate) that contains the Request. -The second Connector, which is referred to as the Recipient, [receives the Request by loading the RelationshipTemplate](#receive-the-request-by-loading-the-relationshiptemplate). The Recipient then [responds to the Request](#respond-to-the-request). +The second Connector, which is referred to as the Recipient, [receives the Request by loading the RelationshipTemplate](#receive-the-request-by-loading-the-relationshiptemplate). +The Recipient then [responds to the Request](#respond-to-the-request). Note that the Sender and the Recipient may or may not have already established a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) at the beginning. -A RelationshipTemplate is generally used to establish a Relationship between two Identities. A Request can be sent in this process of establishing a Relationship. +A RelationshipTemplate is generally used to establish a Relationship between two Identities. +A Request can be sent in this process of establishing a Relationship. Nevertheless, a RelationshipTemplate can also be used to exchange Requests between Identities that have already established a Relationship. For more information on how to establish Relationships, refer to the [Establish Relationships]({% link _docs_integrate/establish-relationships.md %}) scenario documentation. {: .notice--info} @@ -48,7 +51,8 @@ For more information on how to establish Relationships, refer to the [Establish The Sender wants to construct a Request that it can send to the Recipient by inserting it into a RelationshipTemplate. Before the [RelationshipTemplate is created](#create-the-relationshiptemplate), the Sender should first check the Request's validity by proceeding as described in the documentation of the [Check if outgoing Request can be created]({% link _docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md %}) use case. To do this, the Request must be specified in the `content` property of the payload. -In this guide, an example [Request]({% link _docs_integrate/data-model-overview.md %}#request) is given that contains only a single [AuthenticationRequestItem]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem) within its `items` property. However, you can use any Request that suits you. +In this guide, an example [Request]({% link _docs_integrate/data-model-overview.md %}#request) is given that contains only a single [AuthenticationRequestItem]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem) within its `items` property. +However, you can use any Request that suits you. ```jsonc { @@ -66,16 +70,19 @@ In this guide, an example [Request]({% link _docs_integrate/data-model-overview. } ``` -If a Request is contained within a RelationshipTemplate, its validity is automatically checked when the [RelationshipTemplate is created](#create-the-relationshiptemplate). The RelationshipTemplate cannot be created if the Request is faulty. +If a Request is contained within a RelationshipTemplate, its validity is automatically checked when the [RelationshipTemplate is created](#create-the-relationshiptemplate). +The RelationshipTemplate cannot be created if the Request is faulty. Nevertheless, the Request's validity should be checked before attempting to create the RelationshipTemplate in order to obtain additional information about the reasons for the error in the case of a faulty Request. {: .notice--info} ## Create the RelationshipTemplate -Next, the Sender wants to create the RelationshipTemplate, which contains the Request it wants to send to the Recipient. To specify a Request within a RelationshipTemplate, a data object of type [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) must be used within the `content` property of the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate). +Next, the Sender wants to create the RelationshipTemplate, which contains the Request it wants to send to the Recipient. +To specify a Request within a RelationshipTemplate, a data object of type [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) must be used within the `content` property of the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate). A Request can be specified in the `onNewRelationship` property or the `onExistingRelationship` property of the RelationshipTemplateContent. If no Relationship has yet been established between the Sender and the Recipient, the Recipient will receive the Request specified in the `onNewRelationship` property when loading the RelationshipTemplate. -However, if an active Relationship already exists, the Recipient will receive the Request specified in the `onExistingRelationship` property, if such is specified. The specification of a Request in the `onNewRelationship` property is mandatory in contrast to the specification of a Request in the `onExistingRelationship` property. +However, if an active Relationship already exists, the Recipient will receive the Request specified in the `onExistingRelationship` property, if such is specified. +The specification of a Request in the `onNewRelationship` property is mandatory in contrast to the specification of a Request in the `onExistingRelationship` property. Note that the same Request can be specified in the `onExistingRelationship` property as in the `onNewRelationship` property, but a different Request can also be used. These customization options are useful as the Recipient that loads the RelationshipTemplate may not be known in advance. @@ -86,7 +93,8 @@ The creator of the RelationshipTemplate may have a Relationship to some of these To create a RelationshipTemplate, the instructions of the [Create own RelationshipTemplate]({% link _docs_use-cases/use-case-transport-create-own-relationshiptemplate.md %}) use case documentation must be followed. A RelationshipTemplateContent needs to be specified in the `content` of the payload because the Sender wants to send the Recipient a Request via the RelationshipTemplate. -In the payload example below, the [Request whose validity was already checked](#check-the-requests-validity) is contained both within the `onNewRelationship` property and within the `onExistingRelationship` property of the [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). The same Request should therefore be sent regardless of whether a Relationship to the Recipient already exists or not. +In the payload example below, the [Request whose validity was already checked](#check-the-requests-validity) is contained both within the `onNewRelationship` property and within the `onExistingRelationship` property of the [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). +The same Request should therefore be sent regardless of whether a Relationship to the Recipient already exists or not. ```jsonc { @@ -123,7 +131,9 @@ In the payload example below, the [Request whose validity was already checked](# } ``` -If the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) has been successfully created, the Sender receives a success response from which its `id` and `reference.truncated` can be read. Note that the creation of a RelationshipTemplate which contains a Request does not yet lead to the creation of a corresponding [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest). This is only created after the Recipient of the Request has responded to it. +If the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) has been successfully created, the Sender receives a success response from which its `id` and `reference.truncated` can be read. +Note that the creation of a RelationshipTemplate which contains a Request does not yet lead to the creation of a corresponding [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest). +This is only created after the Recipient of the Request has responded to it. {% include copy-notice description="Save the `id` and the `reference.truncated` of the RelationshipTemplate because these values are needed in the next steps." %} @@ -137,12 +147,14 @@ To receive a Request that is contained within a RelationshipTemplate, the Recipi } ``` -Loading the RelationshipTemplate triggers a process in the [enmeshed Runtime]({% link _docs_explore/61-runtime.md %}) that creates a new incoming Request for the Recipient. Depending on whether a Relationship has already been established between the Sender and the Recipient, the Recipient receives the Request specified in the `onNewRelationship` property or in the `onExistingRelationship` property of the [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). +Loading the RelationshipTemplate triggers a process in the [enmeshed Runtime]({% link _docs_explore/61-runtime.md %}) that creates a new incoming Request for the Recipient. +Depending on whether a Relationship has already been established between the Sender and the Recipient, the Recipient receives the Request specified in the `onNewRelationship` property or in the `onExistingRelationship` property of the [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). If a Relationship has already been established between the Sender and the Recipient and no Request has been specified in the `onExistingRelationship` property, the Recipient will not receive an incoming Request when the RelationshipTemplate is loaded. {: .notice--info} -By proceeding as described in the [Query incoming Requests]({% link _docs_use-cases/use-case-consumption-query-incoming-requests.md %}) use case documentation and specifying `source.reference=<ID of RelationshipTemplate>` and `status=ManualDecisionRequired` as query parameters, the new incoming Request can be queried. The `result` contains the corresponding [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest), from which you can read the `id` of the Request. +By proceeding as described in the [Query incoming Requests]({% link _docs_use-cases/use-case-consumption-query-incoming-requests.md %}) use case documentation and specifying `source.reference=<ID of RelationshipTemplate>` and `status=ManualDecisionRequired` as query parameters, the new incoming Request can be queried. +The `result` contains the corresponding [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest), from which you can read the `id` of the Request. {% include copy-notice description="Save the `id` of the incoming Request so that you can accept or reject it." %} @@ -209,7 +221,7 @@ The Sender, then, can fetch it by [synchronizing the updates of the Backbone]({% However, if there is no active Relationship between the Connectors yet, a Relationship will be created, which has the `status` `"Pending"` for now. Its creation content is of type [RelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#relationshipcreationcontent) and contains the Response to the Request. This Relationship is sent back to the Sender via a Message. -Then, the Request is set to `status` `"Completed"` and you can [query the Relationship]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) using the query parameter `template.id=<ID of RelationshipTemplate>`. +Then, the Request is set to `status` `"Completed"` and you can [query the Relationship]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) using the query parameter `templateId=<ID of RelationshipTemplate>`. As long as the Relationship is `"Pending"`, no new Request is created by [loading the RelationshipTemplate](#receive-the-request-by-loading-the-relationshiptemplate). The Sender can fetch the Relationship by [synchronizing the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). @@ -218,9 +230,7 @@ The new Relationship looks as follows: ```jsonc { "id": "REL...", - "template": { - // ... - }, + "templateId": "RLT...", "status": "Pending", "peer": "did:e:...", "creationContent": { diff --git a/_docs_integrate/share-attributes-with-peer.md b/_docs_integrate/share-attributes-with-peer.md index d1a3b8498..217d480bb 100644 --- a/_docs_integrate/share-attributes-with-peer.md +++ b/_docs_integrate/share-attributes-with-peer.md @@ -30,29 +30,37 @@ There are many situations in which an Identity wants to share an [IdentityAttrib - An organization wants to share its email address with its members in order to be able to receive emails from them. - A company wants to share the customer number of one of its customers with another company. -In this guide, we explain how a Connector, hereinafter referred to as the Sender, can share an [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) with another Connector, the so-called Recipient. Since understanding this sharing process requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) and how to use them in general, you should take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) before continuing reading this guide. +In this guide, we explain how a Connector, hereinafter referred to as the Sender, can share an [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) with another Connector, the so-called Recipient. +Since understanding this sharing process requires knowledge about [Requests]({% link _docs_integrate/data-model-overview.md %}#request) and how to use them in general, you should take a look at our [Request and Response introduction]({% link _docs_integrate/request-and-response-introduction.md %}) before continuing reading this guide. -Please note that the general procedure is the same if the Connector wants to share an Attribute with an App user instead of another Connector. For reasons of clarity, this guide focuses on the sharing process with two Connectors. +Please note that the general procedure is the same if the Connector wants to share an Attribute with an App user instead of another Connector. +For reasons of clarity, this guide focuses on the sharing process with two Connectors. {: .notice--info} ## Request for sharing Attributes -The Sender wants to share an Attribute with the Recipient. To do this, the Sender must first create a suitable Request, which it can then send to the Recipient. In the following subsections, we describe the general appearance of a Request for sharing Attributes. +The Sender wants to share an Attribute with the Recipient. +To do this, the Sender must first create a suitable Request, which it can then send to the Recipient. +In the following subsections, we describe the general appearance of a Request for sharing Attributes. ### Role of ShareAttributeRequestItem For sharing a single Attribute, the Sender needs to insert a single RequestItem of type [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request). The Sender can only share an Attribute that already exists as a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) and, in the case of IdentityAttributes, is owned by it. The latter means that the address of the Sender is contained in the `content.owner` property of the corresponding LocalAttribute. -The `id` of the LocalAttribute must be inserted into the `sourceAttributeId` property and the `content` of the LocalAttribute into the `attribute` property of the ShareAttributeRequestItem. -If a RelationshipAttribute is to be shared, the `thirdPartyAddress` property of the ShareAttributeRequestItem must contain the address of the `peer` with whom the Sender has the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) from which the RelationshipAttribute originates. +The `id` of the LocalAttribute must be inserted into the `attributeId` property and the `content` of the LocalAttribute into the `attribute` property of the ShareAttributeRequestItem. +If a RelationshipAttribute is to be shared, the `initialAttributePeer` property of the ShareAttributeRequestItem must contain the address of the `peer` with whom the Sender has the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) from which the RelationshipAttribute originates. -To get a list of all LocalAttributes that are owned by the Sender, proceed as described in the [Get Attributes]({% link _docs_use-cases/use-case-consumption-get-attributes.md %}) use case documentation and use `content.owner=<address of Sender>` as query parameter. Please note that the `<...>` notation is used as a placeholder for the actual data as usual. If the `id` of a LocalAttribute is known, the underlying IdentityAttribute or RelationshipAttribute within its `content` property can be displayed by consulting the [Get Attribute]({% link _docs_use-cases/use-case-consumption-get-attribute.md %}) use case description and specifying the `id` of the LocalAttribute. +To get a list of all LocalAttributes that are owned by the Sender, proceed as described in the [Get Attributes]({% link _docs_use-cases/use-case-consumption-get-attributes.md %}) use case documentation and use `content.owner=<address of Sender>` as query parameter. +Please note that the `<...>` notation is used as a placeholder for the actual data as usual. +If the `id` of a LocalAttribute is known, the underlying IdentityAttribute or RelationshipAttribute within its `content` property can be displayed by consulting the [Get Attribute]({% link _docs_use-cases/use-case-consumption-get-attribute.md %}) use case description and specifying the `id` of the LocalAttribute. {: .notice--info} ### Combinations and usage scenarios of ShareAttributeRequestItem -The following table provides an overview of the possible kinds of Attributes that the Sender can share with the Recipient using the ShareAttributeRequestItem. It must be taken into account whether the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) to be shared is an IdentityAttribute or a RelationshipAttribute and which Identity is its `owner`. If the Sender wants to share a RelationshipAttribute with the Recipient, it must exist in the context of a Relationship between the Sender and a third party, because it makes no sense for the Sender to share a RelationshipAttribute that exists in the context of the Relationship between the Sender and the Recipient with the Recipient. +The following table provides an overview of the possible kinds of Attributes that the Sender can share with the Recipient using the ShareAttributeRequestItem. +It must be taken into account whether the [Attribute]({% link _docs_integrate/data-model-overview.md %}#attributes) to be shared is an IdentityAttribute or a RelationshipAttribute and which Identity is its `owner`. +If the Sender wants to share a RelationshipAttribute with the Recipient, it must exist in the context of a Relationship between the Sender and a third party, because it makes no sense for the Sender to share a RelationshipAttribute that exists in the context of the Relationship between the Sender and the Recipient with the Recipient. | Type and context | Owner | Possible? | Automation | Remarks, reasons and examples | | ------------------------------------------------------------------------------------------------------- | ----------- | :----------------------------------------: | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -65,13 +73,13 @@ The following table provides an overview of the possible kinds of Attributes tha ### Example of sharing an IdentityAttribute We assume that the Integrator of the Sender has created an IdentityAttribute of type [BirthDate]({% link _docs_integrate/attribute-values.md %}#birthdate) for the Sender by following the instructions of our [Create Attributes for yourself]({% link _docs_integrate/create-attributes-for-yourself.md %}) scenario documentation. -This IdentityAttribute is stored locally within the `content` property of a corresponding [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) of the Sender, which is also referred to as a [RepositoryAttribute]({% link _docs_integrate/attribute-introduction.md %}#repositoryattributes). +This IdentityAttribute is stored locally within the `content` property of a corresponding [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) of the Sender. ```jsonc { - "@type": "LocalAttribute", - "id": "<ID of RepositoryAttribute>", - "createdAt": "<creation date of RepositoryAttribute>", + "@type": "OwnIdentityAttribute", + "id": "<ID of OwnIdentityAttribute>", + "createdAt": "<creation date of OwnIdentityAttribute>", "content": { "@type": "IdentityAttribute", "owner": "<address of Sender>", @@ -86,7 +94,7 @@ This IdentityAttribute is stored locally within the `content` property of a corr ``` In our example, the Sender wants to share the IdentityAttribute with the Recipient. -To do so, it needs to insert the `id` of the corresponding RepositoryAttribute into the `sourceAttributeId` property and the IdentityAttribute itself into the `attribute` property of the [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for sharing Attributes. +To do so, it needs to insert the `id` of the corresponding OwnIdentityAttribute into the `attributeId` property and the IdentityAttribute itself into the `attribute` property of the [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for sharing Attributes. The value of the `mustBeAccepted` property of the ShareAttributeRequestItem is set to `true` in this example. ```jsonc @@ -106,7 +114,7 @@ The value of the `mustBeAccepted` property of the ShareAttributeRequestItem is s "year": <year of birth date> } }, - "sourceAttributeId": "<ID of RepositoryAttribute>" + "attributeId": "<ID of OwnIdentityAttribute>" } ] } @@ -114,13 +122,15 @@ The value of the `mustBeAccepted` property of the ShareAttributeRequestItem is s ### Example of sharing a RelationshipAttribute -We now consider the case in which the Sender has an active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with a third party and owns a RelationshipAttribute, which has already been created by using an appropriate Request, of type [ProprietaryString]({% link _docs_integrate/attribute-values.md %}#proprietarystring) of this Relationship. The Sender can request to share this RelationshipAttribute with the Recipient if its `confidentiality` is `"protected"` or `"public"`. In our example, we assume that the `confidentiality` of the RelationshipAttribute is `"public"` and that it is stored locally within the `content` property of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) with a [LocalAttributeShareInfo]({% link _docs_integrate/data-model-overview.md %}#localattributeshareinfo) of the Sender, which is also referred to as an [own shared RelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-relationshipattributes). +We now consider the case in which the Sender has an active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with a third party and owns a RelationshipAttribute, which has already been created by using an appropriate Request, of type [ProprietaryString]({% link _docs_integrate/attribute-values.md %}#proprietarystring) of this Relationship. +The Sender can request to share this RelationshipAttribute with the Recipient if its `confidentiality` is `"protected"` or `"public"`. +In our example, we assume that the `confidentiality` of the RelationshipAttribute is `"public"` and that it is stored locally within the `content` property of an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) of the Sender. ```jsonc { - "@type": "LocalAttribute", - "id": "<ID of own shared RelationshipAttribute>", - "createdAt": "<creation date of own shared RelationshipAttribute>", + "@type": "OwnRelationshipAttribute", + "id": "<ID of OwnRelationshipAttribute>", + "createdAt": "<creation date of OwnRelationshipAttribute>", "content": { "@type": "RelationshipAttribute", "owner": "<address of Sender>", @@ -132,15 +142,13 @@ We now consider the case in which the Sender has an active [Relationship]({% lin "value": "<actual value of RelationshipAttribute>" } }, - "shareInfo": { - "peer": "<address of third party>", - "requestReference": "<ID of Request used for creation of own shared RelationshipAttribute>" - } + "peer": "<address of third party>", + "sourceReference": "<ID of Request or Notification used for creation of OwnRelationshipAttribute>" } ``` -To share the RelationshipAttribute with the Recipient, the Sender needs to insert the `id` of the corresponding own shared RelationshipAttribute into the `sourceAttributeId` property and the RelationshipAttribute itself into the `attribute` property of the [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for sharing Attributes. -Furthermore, the address of the third party, which corresponds to the `shareInfo.peer` of the own shared RelationshipAttribute, must be specified as the `thirdPartyAddress` of the ShareAttributeRequestItem. +To share the RelationshipAttribute with the Recipient, the Sender needs to insert the `id` of the corresponding OwnRelationshipAttribute into the `attributeId` property and the RelationshipAttribute itself into the `attribute` property of the [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for sharing Attributes. +Furthermore, the address of the third party, which corresponds to the `peer` of the OwnRelationshipAttribute, must be specified as the `initialAttributePeer` of the ShareAttributeRequestItem. The value of the `mustBeAccepted` property is set to `true` in this example. ```jsonc @@ -161,8 +169,8 @@ The value of the `mustBeAccepted` property is set to `true` in this example. "value": "<actual value of RelationshipAttribute>" } }, - "sourceAttributeId": "<ID of own shared RelationshipAttribute>", - "thirdPartyAddress": "<address of third party>" + "attributeId": "<ID of OwnRelationshipAttribute>", + "initialAttributePeer": "<address of third party>" } ] } @@ -172,46 +180,62 @@ Further information on sharing RelationshipAttributes in different application s ### Share multiple Attributes -Sharing is not limited to just a single Attribute, but it is possible to request the sharing of multiple Attributes at the same time. For this purpose, several ShareAttributeRequestItems or suitable [RequestItemGroups]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) can be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for sharing Attributes. If you want to use a RequestItemGroup in order to share multiple Attributes with the Recipient at the same time, you must insert corresponding ShareAttributeRequestItems into the `items` property of it. +Sharing is not limited to just a single Attribute, but it is possible to request the sharing of multiple Attributes at the same time. +For this purpose, several ShareAttributeRequestItems or suitable [RequestItemGroups]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) can be inserted into the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for sharing Attributes. +If you want to use a RequestItemGroup in order to share multiple Attributes with the Recipient at the same time, you must insert corresponding ShareAttributeRequestItems into the `items` property of it. ## Send and receive the Request -The Sender that wants to share an Attribute with the Recipient may or may not already have a Relationship with the Recipient. Depending on which is the case, a different method can be used to send the [Request for sharing Attributes]({% link _docs_integrate/share-attributes-with-peer.md %}#request-for-sharing-attributes). There are two ways to send the Request for sharing Attributes created by the Sender to the Recipient. +The Sender that wants to share an Attribute with the Recipient may or may not already have a Relationship with the Recipient. +Depending on which is the case, a different method can be used to send the [Request for sharing Attributes]({% link _docs_integrate/share-attributes-with-peer.md %}#request-for-sharing-attributes). +There are two ways to send the Request for sharing Attributes created by the Sender to the Recipient. ### Request via RelationshipTemplate -If there is currently no Relationship between the Sender and the Recipient, this approach must be used. However, it is also possible for the Sender to use a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) to send a Request to the Recipient if there is already an active Relationship between them. All details on how to send and receive a Request via a RelationshipTemplate in general can be found in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide. +If there is currently no Relationship between the Sender and the Recipient, this approach must be used. +However, it is also possible for the Sender to use a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) to send a Request to the Recipient if there is already an active Relationship between them. +All details on how to send and receive a Request via a RelationshipTemplate in general can be found in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide. ### Request via Message -The Sender only has the option of sending a Request to the Recipient via a [Message]({% link _docs_integrate/data-model-overview.md %}#message) if there is already an active Relationship between them. All information on how to send and receive a Request via a Message can be found in the [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) guide. +The Sender only has the option of sending a Request to the Recipient via a [Message]({% link _docs_integrate/data-model-overview.md %}#message) if there is already an active Relationship between them. +All information on how to send and receive a Request via a Message can be found in the [Requests via Messages]({% link _docs_integrate/requests-via-messages.md %}) guide. ## Accept the Request and get the Attributes -After the Recipient has received the [Request for sharing Attributes]({% link _docs_integrate/share-attributes-with-peer.md %}#request-for-sharing-attributes), it can accept it to get all or some of the Sender's shared Attributes. To do this, proceed as described in the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case documentation and specify the `id` of the received [Request]({% link _docs_integrate/data-model-overview.md %}#request). Also, you need to decide and specify for each ShareAttributeRequestItem contained in the Request for sharing Attributes whether you want to accept or reject it. +After the Recipient has received the [Request for sharing Attributes]({% link _docs_integrate/share-attributes-with-peer.md %}#request-for-sharing-attributes), it can accept it to get all or some of the Sender's shared Attributes. +To do this, proceed as described in the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case documentation and specify the `id` of the received [Request]({% link _docs_integrate/data-model-overview.md %}#request). +Also, you need to decide and specify for each ShareAttributeRequestItem contained in the Request for sharing Attributes whether you want to accept or reject it. -If the Recipient does not want to get any of the Sender's shared Attributes and, therefore, does not want to accept the Request for sharing Attributes of the Sender, it can reject it as a whole too. For that, follow the instructions of the [Reject incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) use case. +If the Recipient does not want to get any of the Sender's shared Attributes and, therefore, does not want to accept the Request for sharing Attributes of the Sender, it can reject it as a whole too. +For that, follow the instructions of the [Reject incoming Request]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) use case. {: .notice--info} -<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/ac0ca016-1e9b-40f7-b897-290f54c43782" id="crwP~ShTXcFl"></iframe></div> +<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/9f9ad94d-1b83-46a5-90b0-5cbd064511e4" id="GrR_LR94fm6N"></iframe></div> ### Accept a ShareAttributeRequestItem If the Recipient agrees to get one of the Sender's shared Attributes, it can accept the associated ShareAttributeRequestItem contained in the Request for sharing Attributes. The [AcceptRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptrequestitemparameters) must be used for this. -The acceptance of a ShareAttributeRequestItem leads to the creation of a corresponding LocalAttribute with a [LocalAttributeShareInfo]({% link _docs_integrate/data-model-overview.md %}#localattributeshareinfo) contained within its `shareInfo` property. -Depending on whether an IdentityAttribute or a RelationshipAttribute has been shared by the Sender, it is referred to as either a [peer shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes) or a [received ThirdPartyRelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#emitted-and-received-thirdpartyrelationshipattributes). +The acceptance of a ShareAttributeRequestItem leads to the creation of a corresponding [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). +Depending on whether an IdentityAttribute or a RelationshipAttribute has been shared by the Sender, it is referred to as either a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) or a [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute). The `content` of the LocalAttribute corresponds to the underlying `attribute` of the ShareAttributeRequestItem. Based on this, an appropriate AcceptResponseItem of type [ShareAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#shareattributeacceptresponseitem) is generated, which incorporates the `id` of the created LocalAttribute in its `attributeId` property. This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for sharing Attributes that will be transferred to the Sender. ### Reject a ShareAttributeRequestItem -Even if the Recipient accepts the Request for sharing Attributes as a whole, it may decide not to accept all of the Sender's shared Attributes. To be more precise, the Recipient has the option of rejecting [ShareAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) that have the value `false` specified in their `mustBeAccepted` property. To reject a ShareAttributeRequestItem, use the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters). The rejection of a ShareAttributeRequestItem leads to the creation of a corresponding ResponseItem of type [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem). This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for sharing Attributes. +Even if the Recipient accepts the Request for sharing Attributes as a whole, it may decide not to accept all of the Sender's shared Attributes. +To be more precise, the Recipient has the option of rejecting [ShareAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) that have the value `false` specified in their `mustBeAccepted` property. +To reject a ShareAttributeRequestItem, use the [RejectRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#rejectrequestitemparameters). +The rejection of a ShareAttributeRequestItem leads to the creation of a corresponding ResponseItem of type [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem). +This will be contained within the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the Request for sharing Attributes. ### Example of accepting a RequestItemGroup -Let's look at an example where the Sender wants to share its [DisplayName]({% link _docs_integrate/attribute-values.md %}#displayname) and contact information in the form of an [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) or a [PhoneNumber]({% link _docs_integrate/attribute-values.md %}#phonenumber) with the Recipient. For this purpose, the Sender creates a [Request]({% link _docs_integrate/data-model-overview.md %}#request) for sharing Attributes, which contains a ShareAttributeRequestItem belonging to the DisplayName and a RequestItemGroup belonging to the contact information in its `items` property. The [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) itself includes two ShareAttributeRequestItems in its `items` property, namely one for the EMailAddress and one for the PhoneNumber. +Let's look at an example where the Sender wants to share its [DisplayName]({% link _docs_integrate/attribute-values.md %}#displayname) and contact information in the form of an [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) or a [PhoneNumber]({% link _docs_integrate/attribute-values.md %}#phonenumber) with the Recipient. +For this purpose, the Sender creates a [Request]({% link _docs_integrate/data-model-overview.md %}#request) for sharing Attributes, which contains a ShareAttributeRequestItem belonging to the DisplayName and a RequestItemGroup belonging to the contact information in its `items` property. +The [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup) itself includes two ShareAttributeRequestItems in its `items` property, namely one for the EMailAddress and one for the PhoneNumber. ```jsonc { @@ -228,7 +252,7 @@ Let's look at an example where the Sender wants to share its [DisplayName]({% li "value": "<display name that the Sender wants to share>" } }, - "sourceAttributeId": "<ID of source RepositoryAttribute of DisplayName>" + "attributeId": "<ID of source OwnIdentityAttribute of DisplayName>" }, { "@type": "RequestItemGroup", @@ -244,7 +268,7 @@ Let's look at an example where the Sender wants to share its [DisplayName]({% li "value": "<email address that the Sender wants to share>" } }, - "sourceAttributeId": "<ID of source RepositoryAttribute of EMailAddress>" + "attributeId": "<ID of source OwnIdentityAttribute of EMailAddress>" }, { "@type": "ShareAttributeRequestItem", @@ -257,7 +281,7 @@ Let's look at an example where the Sender wants to share its [DisplayName]({% li "value": "<phone number that the Sender wants to share>" } }, - "sourceAttributeId": "<ID of source RepositoryAttribute of PhoneNumber>" + "attributeId": "<ID of source OwnIdentityAttribute of PhoneNumber>" } ] } @@ -265,12 +289,16 @@ Let's look at an example where the Sender wants to share its [DisplayName]({% li } ``` -In our example, the Sender only requires the Recipient to accept the DisplayName and the EMailAddress, which is why the individual [ShareAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) within the Request have specified corresponding values in their `mustBeAccepted` property. We assume that the Recipient wants to accept the Request and all its ShareAttributeRequestItems with the exception of the PhoneNumber. +In our example, the Sender only requires the Recipient to accept the DisplayName and the EMailAddress, which is why the individual [ShareAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) within the Request have specified corresponding values in their `mustBeAccepted` property. +We assume that the Recipient wants to accept the Request and all its ShareAttributeRequestItems with the exception of the PhoneNumber. -If the Recipient wants to accept the Request for sharing Attributes, it must accept all ShareAttributeRequestItems for which the `mustBeAccepted` property is set to `true`. It is therefore not permitted for the Recipient to refuse to accept the DisplayName or the EMailAddress shared by the Sender. +If the Recipient wants to accept the Request for sharing Attributes, it must accept all ShareAttributeRequestItems for which the `mustBeAccepted` property is set to `true`. +It is therefore not permitted for the Recipient to refuse to accept the DisplayName or the EMailAddress shared by the Sender. {: .notice--info} -The Recipient accepts the DisplayName of the Sender. Also, the Recipient accepts the EMailAddress and rejects the PhoneNumber of the Sender. It therefore responds to the Request for sharing Attributes as follows: +The Recipient accepts the DisplayName of the Sender. +Also, the Recipient accepts the EMailAddress and rejects the PhoneNumber of the Sender. +It therefore responds to the Request for sharing Attributes as follows: ```jsonc { @@ -299,9 +327,11 @@ Note that it is important to respond to RequestItems, some of which may be conta ## Receive the Response to the Request -We now assume that the Recipient has accepted the [Request for sharing Attributes]({% link _docs_integrate/share-attributes-with-peer.md %}#request-for-sharing-attributes) of the Sender. In order for the Sender to receive the Response of the Recipient, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). Please note that this synchronization can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync). +We now assume that the Recipient has accepted the [Request for sharing Attributes]({% link _docs_integrate/share-attributes-with-peer.md %}#request-for-sharing-attributes) of the Sender. +In order for the Sender to receive the Response of the Recipient, it needs to [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}). +Please note that this synchronization can also be automated by using the [Sync Module]({% link _docs_operate/modules.md %}#sync). -<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/8c6f398e-07ad-43a9-8dda-d4e638c34e57" id="giwP0P_T6Pk8"></iframe></div> +<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/6d75dbf7-4ab2-4924-b579-ede8a889a0cb" id="1tR_SCPGgYJ-"></iframe></div> To view the Response to the Request, proceed as described in the [Query outgoing Requests]({% link _docs_use-cases/use-case-consumption-query-outgoing-requests.md %}) use case documentation and use the following query parameter: @@ -310,13 +340,15 @@ To view the Response to the Request, proceed as described in the [Query outgoing The Integrator of the Sender can now get the Response of the Recipient from the `response.content` property of the result. In the `items` property of the [Response]({% link _docs_integrate/data-model-overview.md %}#response) is a [ShareAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#shareattributeacceptresponseitem) for each accepted ShareAttributeRequestItem and a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) for each rejected ShareAttributeRequestItem included. -Note that each accepted ShareAttributeRequestItem leads to the creation of an appropriate LocalAttribute with a LocalAttributeShareInfo of the Sender. -Depending on whether an IdentityAttribute or a RelationshipAttribute has been shared by the Sender, it is referred to as either an [own shared IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#own-shared-and-peer-shared-identityattributes) or an [emitted ThirdPartyRelationshipAttribute]({% link _docs_integrate/attribute-introduction.md %}#emitted-and-received-thirdpartyrelationshipattributes). -The `content` of the LocalAttribute is the underlying `attribute` of the ShareAttributeRequestItem. +Note that each accepted ShareAttributeRequestItem leads to the creation of appropriate [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails). +Depending on whether an IdentityAttribute or a RelationshipAttribute has been shared by the Sender, they refer either to an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) or a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute). -In case of an error, [ErrorResponseItems]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) can also be included in the Response. If the Request for sharing Attributes contains a RequestItemGroup in its `items` property, the Response to this Request contains a corresponding [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) in its `items` property. +In case of an error, [ErrorResponseItems]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) can also be included in the Response. +If the Request for sharing Attributes contains a RequestItemGroup in its `items` property, the Response to this Request contains a corresponding [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) in its `items` property. {: .notice--info} ## What's next? -Take a look at our [Integration example]({% link _docs_integrate/integration-example.md %}) if you want to see how an Identity shares an Attribute with a peer in the context of a larger process. Also note that it is not only possible to share an Attribute with a peer, but you can also request to read an Attribute from a peer. Consult the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide for this. +Take a look at our [Integration example]({% link _docs_integrate/integration-example.md %}) if you want to see how an Identity shares an Attribute with a peer in the context of a larger process. +Also note that it is not only possible to share an Attribute with a peer, but you can also request to read an Attribute from a peer. +Consult the [Read Attributes from peer]({% link _docs_integrate/read-attributes-from-peer.md %}) guide for this. diff --git a/_docs_integrate/support.md b/_docs_integrate/support.md index ea9869f13..a396cc68e 100644 --- a/_docs_integrate/support.md +++ b/_docs_integrate/support.md @@ -23,4 +23,5 @@ required_by: For assisted support with the Connector or the Backbone provided by the j&s-soft AG contact us via `support[at]enmeshed.eu`. -Community support is a great way to get help and even contribute to the projects. Open bug reports and feature requests in the [enmeshed issue tracker](https://github.com/nmshd/feedback/issues) or share your feedback with the enmeshed team via the [enmeshed discussions](https://github.com/nmshd/feedback/discussions). +Community support is a great way to get help and even contribute to the projects. +Open bug reports and feature requests in the [enmeshed issue tracker](https://github.com/nmshd/feedback/issues) or share your feedback with the enmeshed team via the [enmeshed discussions](https://github.com/nmshd/feedback/discussions). diff --git a/_docs_integrate/terminate-relationships.md b/_docs_integrate/terminate-relationships.md index e91141aca..140df18a8 100644 --- a/_docs_integrate/terminate-relationships.md +++ b/_docs_integrate/terminate-relationships.md @@ -21,7 +21,8 @@ required_by: # End automatic generation --- -In order for two Identities to communicate with each other and exchange data, they must [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}) between them. If an active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to another Identity is no longer wanted, it can be terminated. +In order for two Identities to communicate with each other and exchange data, they must [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}) between them. +If an active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) to another Identity is no longer wanted, it can be terminated. [Terminating an active Relationship]({% link _docs_integrate/terminate-relationships.md %}#terminate-an-active-relationship) initially blocks regular communication for both Identities, but does not yet delete any Relationship data. The only possible communication between them is to request the [reactivation of the terminated Relationship]({% link _docs_integrate/terminate-relationships.md %}#reactivate-a-terminated-relationship), which can be done by both Identities. @@ -37,7 +38,8 @@ An active Relationship can be terminated by executing the use case [Terminate Re 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). +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. @@ -54,19 +56,32 @@ If you want to keep the Relationship terminated, you reject the reactivation wit 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 %}). -Each use case has the `relationshipId` as input. Only accepting the reactivation changes the `status` of the Relationship, namely from `"Terminated"` to `"Active"`. Requesting, rejecting or revoking the reactivation don't change its `status`. However, they still are recorded as an [AuditLogEntry]({% link _docs_integrate/data-model-overview.md %}#auditlogentry) in the `auditLog` of the Relationship. Regardless of whether the reactivation is accepted, rejected or revoked, you receive a `transport.relationshipReactivationCompleted` [event]({% link _docs_integrate/connector-events.md %}) in addition to a `transport.relationshipChanged` event and the peer as well if they use a Connector. +Each use case has the `relationshipId` as input. +Only accepting the reactivation changes the `status` of the Relationship, namely from `"Terminated"` to `"Active"`. +Requesting, rejecting or revoking the reactivation don't change its `status`. +However, they still are recorded as an [AuditLogEntry]({% link _docs_integrate/data-model-overview.md %}#auditlogentry) in the `auditLog` of the Relationship. +Regardless of whether the reactivation is accepted, rejected or revoked, you receive a `transport.relationshipReactivationCompleted` [event]({% link _docs_integrate/connector-events.md %}) in addition to a `transport.relationshipChanged` event and the peer as well if they use a Connector. ## Decompose a Relationship Decomposing a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) deletes all data associated with the peer that was transmitted during the Relationship which includes: - The Relationship itself. -- The [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) used to establish the Relationship if it was for single use, which means that the value of its `maxNumberOfAllocations` property is one, or is owned by the peer. A RelationshipTemplate must be exchanged again to establish a new Relationship. -- In any case, all RelationshipTemplates of the peer. During a Relationship, several RelationshipTemplates may have been exchanged, as [Requests can be sent via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}#create-the-relationshiptemplate) both when establishing new Relationships and for existing Relationships. +- The [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) used to establish the Relationship if it was for single use, which means that the value of its `maxNumberOfAllocations` property is one, or is owned by the peer. + A RelationshipTemplate must be exchanged again to establish a new Relationship. +- In any case, all RelationshipTemplates of the peer. + During a Relationship, several RelationshipTemplates may have been exchanged, as [Requests can be sent via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}#create-the-relationshiptemplate) both when establishing new Relationships and for existing Relationships. - Both the sent and the received shared [Attributes]({% link _docs_integrate/data-model-overview.md %}#attributes), [Notifications]({% link _docs_integrate/data-model-overview.md %}#notification) and [Requests]({% link _docs_integrate/data-model-overview.md %}#request). -- Sent and received [Messages]({% link _docs_integrate/data-model-overview.md %}#message) with one exception: If a Message has been sent to multiple `recipients`, the Message is not deleted but the peer's address is replaced with a pseudonym. The pseudonym is the same for every peer whose Relationship was decomposed. +- Sent and received [Messages]({% link _docs_integrate/data-model-overview.md %}#message) with one exception: If a Message has been sent to multiple `recipients`, the Message is not deleted but the peer's address is replaced with a pseudonym. + The pseudonym is the same for every peer whose Relationship was decomposed. - The [IdentityMetadata]({% link _docs_integrate/data-model-overview.md %}#identitymetadata) that have the peer as their `reference`. -- Furthermore, the corresponding [Tokens]({% link _docs_integrate/data-model-overview.md %}#token) and [AttributeListeners]({% link _docs_integrate/data-model-overview.md %}#localattributelistener). +- Furthermore, the corresponding [Tokens]({% link _docs_integrate/data-model-overview.md %}#token). -The use case is [Decompose Relationship]({% link _docs_use-cases/use-case-transport-decompose-relationship.md %}), which takes the `relationshipId` as input. For the peer, the Relationship is not deleted, but its `status` now is `"DeletionProposed"`. -If the peer uses a Connector, they receive a `transport.relationshipChanged` [event]({% link _docs_integrate/connector-events.md %}). You receive a `transport.relationshipDecomposedBySelf` event. The peer is expected to follow suit once the shared data is no longer needed. Only after both Identities involved in the Relationship have decomposed it, the Relationship itself and data transmitted during it are deleted from the Backbone. To get to an active Relationship again after one involved Identity has decomposed, the other Identity must decompose as well. After that, the two have to start from scratch to [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}), as reactivation of the former Relationship is no longer possible. +The use case is [Decompose Relationship]({% link _docs_use-cases/use-case-transport-decompose-relationship.md %}), which takes the `relationshipId` as input. +For the peer, the Relationship is not deleted, but its `status` now is `"DeletionProposed"`. +If the peer uses a Connector, they receive a `transport.relationshipChanged` [event]({% link _docs_integrate/connector-events.md %}). +You receive a `transport.relationshipDecomposedBySelf` event. +The peer is expected to follow suit once the shared data is no longer needed. +Only after both Identities involved in the Relationship have decomposed it, the Relationship itself and data transmitted during it are deleted from the Backbone. +To get to an active Relationship again after one involved Identity has decomposed, the other Identity must decompose as well. +After that, the two have to start from scratch to [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}), as reactivation of the former Relationship is no longer possible. diff --git a/_docs_integrate/update-attributes-by-succession.md b/_docs_integrate/update-attributes-by-succession.md index aab748133..65e723344 100644 --- a/_docs_integrate/update-attributes-by-succession.md +++ b/_docs_integrate/update-attributes-by-succession.md @@ -33,93 +33,90 @@ How the Attribute succession works in detail depends on the type of Attribute. When talking about [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute), we need to distinguish three cases: -- The Identity maintains an unshared Attribute about itself. This IdentityAttribute is stored in the `content` field of a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute), whose `shareInfo` is undefined. Since this LocalAttribute is created for the Identity's private repository of Attributes, it is referred to as **RepositoryAttribute**. -- When sharing a RepositoryAttribute with a peer, a copy of the IdentityAttribute is created for the Sender and stored in the `content` field of a LocalAttribute with a defined `shareInfo`. We call this LocalAttribute an **own shared IdentityAttribute**. -- Receiving a shared IdentityAttribute from a peer leads to the creation of a LocalAttribute with according `content` and a defined `shareInfo` for the Recipient. We call this LocalAttribute a **peer shared IdentityAttribute**. +- The Identity maintains an unshared Attribute about itself. + This IdentityAttribute is stored in the `content` field of an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute). + It is created for the Identity's private repository of Attributes. +- When sharing an OwnIdentityAttribute with a peer, associated [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) are created. +- Receiving a shared IdentityAttribute from a peer leads to the creation of a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) with according `content` for the Recipient. Discussing the succession of IdentityAttributes requires some background knowledge about this differentiation and the behavior of shared Attributes. Hence, we will look at the process of creating, sharing and succeeding an IdentityAttribute step by step. -### Creating a RepositoryAttribute +### Creating an OwnIdentityAttribute -enmeshed allows you to store data about yourself in the form of IdentityAttributes. +enmeshed allows you to store data about yourself in the form of [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute). When [creating an IdentityAttribute]({% link _docs_integrate/create-attributes-for-yourself.md %}), it is not necessary to share it immediately with a peer. -Instead, it will be stored in the `content` property of a LocalAttribute with an undefined `shareInfo`. -We refer to these unshared LocalAttributes as RepositoryAttributes, since they make up your private repository of Attributes. +Instead, it will be stored in the `content` property of an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute). -In the following examples, the `createdAt` and `deletionInfo` properties of all occuring LocalAttributes is omitted, since they aren't required for the explanation. +In the following examples, some properties of the occuring [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) will be omitted if they aren't required for the explanation. {: .notice--info} -<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/33654502-420f-41bd-801a-e0d4c1564df0" id="zs0-w2Ag-nJ4"></iframe></div> +<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/7bcf7e2c-00cd-471b-9a58-3f3521d129f3" id="5dq.VFpnN6MB"></iframe></div> -### Sharing a RepositoryAttribute +### Sharing an OwnIdentityAttribute -Now, in order to [share a RepositoryAttribute]({% link _docs_integrate/share-attributes-with-peer.md %}), you need to send an according [Request]({% link _docs_integrate/data-model-overview.md %}#request) to the peer you want to share it with. -If they [accept your Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}), a new LocalAttribute will be created at the peer's side. -This peer shared IdentityAttribute has the same `content` like your RepositoryAttribute and, in addition, a defined `shareInfo` property. -It stores the address of the `peer` who shared the Attribute with them, i.e. the `address` of your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity), and a reference to the Request that was used to share the Attribute. -Receiving the [Response]({% link _docs_integrate/data-model-overview.md %}#response), an own shared IdentityAttribute with equal `content` will be created at your side. -Its `shareInfo` stores the same `requestReference` and the peer's address, as well as the `id` of the RepositoryAttribute, whose `content` was copied, in the field `sourceAttribute`. +Now, in order to [share an OwnIdentityAttribute]({% link _docs_integrate/share-attributes-with-peer.md %}), you need to send an according [Request]({% link _docs_integrate/data-model-overview.md %}#request) to the peer you want to share it with. +If they [accept your Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}), a new [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) will be created at the peer's side. +This PeerIdentityAttribute has the same `content` like your [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) and, in addition, defined `peer` and `sourceReference` properties. +They store the address of the `peer` who shared the Attribute with them, i.e. the `address` of your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity), and a reference to the Request that was used to share the Attribute. +Receiving the [Response]({% link _docs_integrate/data-model-overview.md %}#response), [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with your OwnIdentityAttribute will be created at your side. +They store the same `sourceReference` and the peer's address. -Concluding, sharing an IdentityAttribute will create an own shared IdentityAttribute copy for every peer you shared the Attribute with at your side and a peer shared IdentityAttribute copy for each peer at their side. +Concluding, sharing an IdentityAttribute will create AttributeForwardingDetails for every peer you shared the Attribute with at your side and a PeerIdentityAttribute for each peer at their side. -<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/c1195765-c1ca-46b4-9468-1735f4a018cc" id="_s0-VcxrpcCM"></iframe></div> +<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/b23acc1c-2111-4dfa-8f6d-4fe203a6a2b2" id="Yeq.jI1BRTvp"></iframe></div> -### Succeeding a RepositoryAttribute +### Succeeding an OwnIdentityAttribute Next, let's consider the case that the `value` of your [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) changes and you want to update it. -To [succeed the RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-succeed-a-repositoryattribute.md %}), a new [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) with the updated `content` will be created. +To [succeed the OwnIdentityAttribute]({% link _docs_use-cases/use-case-consumption-succeed-an-ownidentityattribute.md %}), a new [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) with the updated `content` will be created. This successor stores the `id` of the old version, the predecessor, in its `succeeds` property. The predecessor is updated, too, such that its `succeededBy` property links to the successor. -Consequently, the different versions of a LocalAttribute created by Attribute successions make up a doubly linked list. +Consequently, the different versions of an OwnIdentityAttribute created by Attribute successions make up a doubly linked list. -**Note:** -During the succession of a [complex IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes) implicitly all its children will be succeeded, so it isn't possible to succeed a child of a complex IdentityAttribute on its own. -{: .notice--info} - -<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/8e81cd6b-240f-4e41-ae08-9eea13b32974" id="zt0-EawwJWIx"></iframe></div> +<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/ce6f5b05-001d-44d4-be3a-f0201b384d36" id="igq.Zo9SfPxR"></iframe></div> -### Notifying a peer about a RepositoryAttribute succession +### Notifying a peer about an OwnIdentityAttribute succession -After succeeding a RepositoryAttribute, you can check [with which of your peers you have previously shared the succeeded Attribute]({% link _docs_use-cases/use-case-consumption-get-shared-versions-of-an-attribute.md %}) to choose those, you'd like to [notify about the succession]({% link _docs_use-cases/use-case-consumption-notify-peer-about-repositoryattribute-succession.md %}). -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. +After succeeding an OwnIdentityAttribute, you can check [with which of your peers you have previously shared the succeeded Attribute]({% link _docs_use-cases/use-case-consumption-get-versions-of-attribute-shared-with-peer.md %}) to choose those, you'd like to [notify about the succession]({% link _docs_use-cases/use-case-consumption-notify-peer-about-ownidentityattribute-succession.md %}). +[AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with the successor will be created for each chosen peer. +Then, a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) is sent to the peers, containing a [PeerAttributeSucceededNotificationItem]({% link _docs_integrate/data-model-overview.md %}#peerattributesucceedednotificationitem). +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 [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) 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 %}). -<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/079d7602-95af-4ddf-8fd5-cca5294038d9" id="Fv0-x9lenepV"></iframe></div> +<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/b4eb8903-58fa-453e-8f10-8e3646250497" id="Khq.m5nY-72w"></iframe></div> ## Succeeding own RelationshipAttributes [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) are, as the name suggests, always associated with a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship). Thus, it is not possible to have unshared instances of them. -Instead, you and your peer will always each have a LocalAttribute with the same RelationshipAttribute as `content`. -We refer to the LocalAttribute of the `owner` as **own shared RelationshipAttribute** and to the peer's LocalAttribute as **peer shared RelationshipAttribute**. +Instead, you and your peer will always each have a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) with the same RelationshipAttribute as `content`. +The LocalAttribute of the `owner` is an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) and the peer's LocalAttribute is a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute). ### Creating and sharing a RelationshipAttribute Wanting to [create a RelationshipAttribute]({% link _docs_use-cases/use-case-consumption-create-and-share-a-relationshipattribute.md %}) always involves sharing it directly with a peer. To this end, a Request containing a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) with the RelationshipAttribute will be created and will be sent to the peer. -Only if the peer accepts this Request will a LocalAttribute with the RelationshipAttribute as `content` be created at their side and after you receive their Response, at your side, too. -Hence, you and your peer will always have an identical shared RelationshipAttribute, only differing in the LocalAttribute's `shareInfo.peer` property. +Only if the peer accepts this Request, a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) with the RelationshipAttribute as `content` will be created at their side and, after you receive their Response, an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) will be created at your side. +Hence, you and your peer will always have an identical shared RelationshipAttribute, only differing in the `peer` property. -<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/11244175-05b4-4225-b08f-7da48aa21e2f" id="gw0-8Yqzp0IL"></iframe></div> +<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/3c07ae76-d010-45cf-8408-c5b20aad2869" id="ekq..g1qyvSY"></iframe></div> ### Succeeding a RelationshipAttribute and notifying the peer Equally to IdentityAttributes, again only the `owner` can [succeed a RelationshipAttribute]({% link _docs_use-cases/use-case-consumption-succeed-a-relationshipattribute-and-notify-peer.md %}) to update its `value`. -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. +Doing so, a new version of the [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) will be created at your side. +The `succeeds` property of this OwnRelationshipAttribute 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 [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) at their side, such that their PeerRelationshipAttribute 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 %}). -<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/67c46978-696b-4adf-b04a-cf27d0438f53" id="ww0-.JinZtEX"></iframe></div> +<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://lucid.app/documents/embedded/875fec45-1dc4-4df3-b173-4d917366aaf9" id="zlq.Yjqk0Mu4"></iframe></div> ## What's next? diff --git a/_docs_operate/backbone-security-considerations.md b/_docs_operate/backbone-security-considerations.md index 5862877b0..650a179b5 100644 --- a/_docs_operate/backbone-security-considerations.md +++ b/_docs_operate/backbone-security-considerations.md @@ -91,8 +91,8 @@ There is no authorization set up. So if you have the API-Key, you can access all The Consumer API supports configuring quotas on different write-actions to limit how often a user can execute those. These quotas can be defined per identity. However, there are some endpoints that allow anonymous access and that therefore cannot be rate limited by quotas. These endpoints currently are: -- `POST /api/v1/Challenges` -- `POST /api/v1/Identities` +- `POST /api/v2/Challenges` +- `POST /api/v2/Identities` When operating the Backbone's Consumer API, you should make sure that the endpoints mentioned above are not abused by malicious users by implementing rate limiting on the network level. diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index d48bfc4d3..4c2b889aa 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -33,7 +33,7 @@ required_by: "infrastructure": { "httpServer": { "enabled": true, - "apiKey": "an-api-key" + "authentication": {} } } } @@ -70,7 +70,15 @@ You want to configure the following values: "httpServer": { "enabled": true, "port": 8080, - "apiKey": "an-api-key" + "authentication": { + "apiKey": { + "keys": { + "default": { + "key": "a-valid-API-key" + } + } + } + } } } } @@ -78,7 +86,7 @@ You want to configure the following values: - The first value can be configured using the variable `infrastructure:httpServer:enabled="true"`. Note that the value is represented as a string in the environment variable and the Connector will rewrite it to its boolean representation. - The second value can be configured using the variable `infrastructure:httpServer:port="8080"`. Note that the value is represented as a string in the environment variable and the Connector will rewrite it to its number representation. -- The third value can be configured using the variable `infrastructure:httpServer:apiKey="an-api-key"`. +- The third value can be configured using the variable `infrastructure:httpServer:authentication:apiKey:keys:default:key="a-valid-API-key"`. ## Configuration options @@ -196,19 +204,13 @@ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa - **dbName** `default: "default"` - The `dbName` string is used as the name of the MongoDB database, prefixed with `acc-`. You can use any name you like, but keep in mind that changing it later will NOT rename the database. Instead a new database will be created, together with a new enmeshed Identity. Even though the old database will still exist, the Connector will not be able to access the data until you change the `dbName` back to its original value. + The `dbName` string is used as the name of the MongoDB database. You can use any name you like, but keep in mind that changing it later will NOT rename the database. Instead a new database will be created, together with a new enmeshed Identity. Even though the old database will still exist, the Connector will not be able to access the data until you change the `dbName` back to its original value. If you would like to use multiple Connectors with distinct Identities (one Identity per Connector) running on the same database, you have to specify a unique `dbName` for each of them. **Note:** If you are using the Connector in combintation with a FerretDB, you have to pay attention to the database name restrictions specified in the [FerretDB documentation](https://docs.ferretdb.io/diff/). {: .notice--warning} -- **dbNamePrefix** `default: "acc-"` - - The `dbNamePrefix` string is used as a prefix for the MongoDB database name. It will be **prepended** to the string configured by the `dbName` property. - - If you don't want your database name to be prefixed, you can set this value to an empty string. - ### infrastructure Each infrastructure can be enabled or disabled by passing true / false to `enabled`. @@ -229,7 +231,15 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT "cors": { "origin": false }, - "apiKey": "an-api-key" + "authentication": { + "apiKey": { + "keys": { + "default": { + "key": "a-valid-API-key" + } + } + } + } } } } @@ -243,15 +253,9 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT configure the CORS middleware. Valid options can be found [here](https://github.com/expressjs/cors#configuration-options). -- **apiKey** `required` - - Define the API-Key the Connector should use to authenticate requests. - - The API-Key can be chosen arbitrarily and has to be sent with every request in the `X-API-KEY` HTTP-Header. - - There are no limitations regarding the allowed characters. We recommend using an API-Key that is at least 20 characters long. +- **authentication** `required if running in production mode` - The API-Key protects your Connector from unauthorized access and should therefore be kept secret. + Configure the authentication methods for the HTTP server. At least one authentication method must be configured if the Connector is running in [production mode](#debug). See the [authentication section](#authentication) for more information. - **helmetOptions** `default: depending on the Connector mode` @@ -274,6 +278,157 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT } ``` +##### authentication {#authentication} + +**Default Configuration:** + +```jsonc +{ + // ... + + "authentication": { + "apiKey": { + "headerName": "X-API-KEY", + "keys": {} + }, + "jwtBearer": {}, + "oidc": {} + } +} +``` + +There are currently three authentication methods available for the HTTP server: `apiKey`, `jwtBearer` and `oidc`. At least one authentication method must be configured if the Connector is running in [production mode](#debug). + +If multiple authentication methods are configured, the authentication methods will be executed in the following order: `apiKey` > `jwtBearer` > `oidc`. <br><br> For example, this means if you enabled `apiKey` and `jwtBearer` and send a wrong API key in combination with a valid JWT bearer token, the request will be rejected. Only sending a valid JWT bearer token will succeed. +{: .notice--info} + +###### apiKey + +**Example Configuration:** + +```jsonc +{ + // ... + "apiKey": { + "keys": { + "default": { + "key": "a-valid-API-key" + } + } + } +} +``` + +The `apiKey` authentication method is used to authenticate requests using an API key in a header. + +- **enabled** `default: true (if API keys are configured)` + + Whether the API key authentication is enabled or not. If set to `false`, no API keys will be accepted by the Connector. This can be used to temporarily disable the API key authentication without removing it from the configuration. + +- **headerName** `default: "X-API-KEY"` + + The name of the header in which the API key is sent. Defaults to `X-API-KEY`. + +- **keys** `required` + + A map of API keys that are allowed to access the Connector. The key of each map entry acts as an id of the API key and the value is an object containing the actual API key and some additional configuration options. + - **enabled** `default: true` + + Whether the API key is enabled or not. If set to `false`, the API key will not be accepted by the Connector. This can be used to temporarily disable the API key without removing it from the configuration. + + - **key** `required` + + The actual API key that is used to authenticate the request. This key must be kept secret and should not be shared with anyone. A valid API key must be at least 30 characters long and contain at least 2 digits, 2 uppercase letters, 2 lowercase letters and 1 special character out of ``!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~``. + + - **description** `optional` + + A description of the API key. This is optional and can be used to provide additional information about the API key. This is not used by the Connector itself, but can be useful for documentation purposes. + + - **expiresAt** `optional` + + The date and time when the API key expires. This is optional and can be used to automatically disable the API key after a certain period of time. The date must be in ISO 8601 format (e.g. `2063-10-01T00:00:00Z`). + + - **scopes** `optional` + + An optional array of strings that defines roles, specifying the permissions granted to anyone using the API key. + These roles are matched against the [Connector’s permission model]({% link _docs_operate/security-considerations.md %}#permission-model-of-the-connector) to control which resources are available. + By default, administrator rights are assigned, represented explicitly by `"**"`, providing unrestricted access. + +###### jwtBearer + +**Example Configuration:** + +```jsonc +{ + // ... + "jwtBearer": { + "issuerBaseURL": "https://auth.example.com", + "audience": "an-audience" + } +} +``` + +The `jwtBearer` authentication method is used to authenticate requests using JSON Web Tokens (JWT). +The permissions available to anyone authenticated with a JWT bearer token are determined by the scope of the JWT payload. +Depending on the identity provider, roles may be provided in a different way and need to be mapped into the scope. +These roles are then matched against the [Connector’s permission model]({% link _docs_operate/security-considerations.md %}#permission-model-of-the-connector) to control which resources are accessible. +By default, no rights are assigned, providing limited access. +To configure the `jwtBearer` authentication method, you need to provide at least the following parameters: + +- **enabled** `default: true (if other options are configured)` + + Whether the JWT bearer authentication is enabled or not. If set to `false`, no JWT bearer tokens will be accepted by the Connector. This can be used to temporarily disable the JWT bearer authentication without removing it from the configuration. + +- **issuerBaseURL** `required` + + The base URL of the JWT issuer. This is the URL where the JWT issuer is hosted. This URL must be reachable from the Connector and must not contain a trailing slash `/`. + +- **audience** `required` + + The audience of the JWT. This is the identifier of the Connector in your identity server. + +For more sophisticated use cases, please refer to the [JWT documentation page](https://auth0.github.io/node-oauth2-jwt-bearer/interfaces/AuthOptions.html) where all possibilities are explained in detail. + +###### oidc + +**Example Configuration:** + +```jsonc +{ + // ... + "oidc": { + "issuerBaseURL": "https://auth.example.com", + "baseUrl": "https://connector.example.com", + "clientID": "a-client-id", + "secret": "an-encryption-secret" + } +} +``` + +The `oidc` authentication method is used to authenticate requests using the OpenID Connect protocol. To configure this authentication method, you need to provide at least the following parameters: + +- **enabled** `default: true (if other options are configured)` + + Whether the OpenID Connect authentication is enabled or not. If set to `false`, no OpenID Connect tokens will be accepted by the Connector. This can be used to temporarily disable the OpenID Connect authentication without removing it from the configuration. + +- **issuerBaseURL** `required` + + The base URL of the OpenID Connect provider. This is the URL where the OpenID Connect provider is hosted. This URL must be reachable from the Connector and must not contain a trailing slash `/`. + +- **baseURL** `required` + + The base URL of the Connector. This is the URL where the Connector is hosted. + +- **clientID** `required` + + The client ID of the Connector. This is the ID that the OpenID Connect provider uses to identify the Connector. + +- **secret** `required` + + The secret(s) of the Connector used to derive an encryption key for the user identity in a stateless session cookie. + +For more sophisticated use cases, please refer to the [OIDC documentation page](https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html) where all possibilities are explained in detail. + ### modules Every Module can be enabled or disabled by passing true / false to `enabled`. Read more about the Module by clicking on the <i class="fas fa-fw fa-info-circle"/> icon in each title. diff --git a/_docs_operate/modules.md b/_docs_operate/modules.md index 740be42a2..35ff906c2 100644 --- a/_docs_operate/modules.md +++ b/_docs_operate/modules.md @@ -36,7 +36,7 @@ It is not recommended to use this Module for production scenarios. The `autoAcceptPendingRelationships` Module listens to the [events]({% link _docs_integrate/connector-events.md %}) about changed Relationships. It immediately accepts pending Relationships. -Keep in mind that you need to synchronize the state of the Connector with the Backbone in order to receive changed Relationships. The `sync` Module automates this, but you can also do this manually by calling the `/api/v2/Account/Sync` route. +Keep in mind that you need to synchronize the state of the Connector with the Backbone in order to receive changed Relationships. The `sync` Module automates this, but you can also do this manually by calling the `/api/core/v1/Account/Sync` route. ### Core HTTP API <a href="{% link _docs_operate/configuration.md %}#corehttpapi"><i class="fas fa-fw fa-cog"/></a> {#corehttpapi} @@ -64,7 +64,7 @@ With the REST API, pull mechanisms are supported. However, as there are many bid For this, the Connector supports the configuration of webhooks which are called every time a specific [Connector Event]({% link _docs_integrate/connector-events.md %}) is triggered (e.g. a new Message has been received => `transport.messageReceived`). -Keep in mind that you need to synchronize the state of the Connector with the Backbone in order to receive events. The `sync` Module automates this, but you can also do this manually by calling the `/api/v2/Account/Sync` route. +Keep in mind that you need to synchronize the state of the Connector with the Backbone in order to receive events. The `sync` Module automates this, but you can also do this manually by calling the `/api/core/v1/Account/Sync` route. ### sse (Server-Sent Events) <a href="{% link _docs_operate/configuration.md %}#sse"><i class="fas fa-fw fa-cog"/></a> {#sse} diff --git a/_docs_operate/security-considerations.md b/_docs_operate/security-considerations.md index aa33cc160..51225c2ad 100644 --- a/_docs_operate/security-considerations.md +++ b/_docs_operate/security-considerations.md @@ -94,14 +94,28 @@ Certificate pinning adds additional effort to the Connector administrators, as f So far, the Connector supports API-key authentication to securely authenticate technical users. These API-Keys are random character strings with a high entropy and should be kept confidential at all times. Each internal system communicating with the Connector should receive its own API-Key. -There is no authorization set up, thus every API-key can call any API of the Connector API. - End user authentication, e.g. business users accessing the system, should be done on the respective business system. Usually, there is no need for end users to access the Connector and thus they should not have access to the Connector (from a network and authentication perspective). ### API-key rotation It is important to ensure that API-keys are secure and cannot be easily compromised. One of the key aspects of API-key security is regular rotation and expiration which we recommend. If an API-key is not rotated or expired, it can potentially be used by an attacker who has obtained the key through unauthorized means. +### Permission Model of the Connector + +Roles across different [authentication]({% link _docs_operate/configuration.md %}#authentication) methods for the Connector are defined in a consistent format, specifying how they map to the Connector’s permission model. +Roles can be limited to specific resources, for example, `"core:messages"` allows access only to the Connector routes related to messages. +A wildcard `"*"` can be used within a namespace to allow access to all top-level resources in that namespace. +For instance, `core:*` allows access to `core:messages`, `core:requests`, and any other top-level resources within the `core` namespace. +However, it does not grant access to deeper sub-resources such as `core:requests:incoming`. +To allow access to a resource and all of its sub-resources recursively, `"**"` can be utilized. +For example, `core:**` grants access to `core:requests`, `core:requests:incoming`, and any other deeper sub-resources under the `core` namespace. +Overall, there are the `core` and `monitoring` top-level namespaces with the following sub-resources: + +- `core:account`, `core:announcements`, `core:attributes`, `core:backboneNotifications`, `core:challenges`, `core:files`, `core:identityMetadata`, `core:messages`, `core:requests`, `core:requests:incoming`, `core:requests:outgoing`, `core:relationshipTemplates`, `core:relationships` and `core:tokens`. +- `monitoring:requests`, `monitoring:support` and `monitoring:version`. + +However, it is possible to assign roles following a custom structure for custom functionality. + ## Kernel Dumps Kernel dumps can be a useful tool for diagnosing and troubleshooting system issues. However, they can also be a security risk if they contain sensitive information such as encryption keys. If an attacker gains access to a kernel dump file, they may be able to extract this information and use it to compromise the security of your system. diff --git a/_docs_operate/setup-with-docker-compose.md b/_docs_operate/setup-with-docker-compose.md index 9449ef811..3d3f59854 100644 --- a/_docs_operate/setup-with-docker-compose.md +++ b/_docs_operate/setup-with-docker-compose.md @@ -137,7 +137,15 @@ To use the api platform hosted on the Connector you need to make the following c "infrastructure": { "httpServer": { "enabled": true, - "apiKey": "an-api-key" + "authentication": { + "apiKey": { + "keys": { + "<an-api-key-id>": { + "key": "<a-valid-API-key>" + } + } + } + } } } } diff --git a/_docs_operate/setup-with-helm-charts.md b/_docs_operate/setup-with-helm-charts.md index a34071af5..e8b14a244 100644 --- a/_docs_operate/setup-with-helm-charts.md +++ b/_docs_operate/setup-with-helm-charts.md @@ -93,7 +93,7 @@ pod: name: platform-client-secret key: VALUE - - name: infrastructure__httpServer__apiKey + - name: infrastructure__httpServer__authentication__apiKey__keys__default__key valueFrom: secretKeyRef: name: api-key @@ -148,7 +148,7 @@ pod: name: platform-client-secret key: VALUE - - name: infrastructure__httpServer__apiKey + - name: infrastructure__httpServer__authentication__apiKey__keys__default__key valueFrom: secretKeyRef: name: api-key diff --git a/_docs_use-cases/use-case-anonymous-load-token-by-truncated-reference-without-having-an-account.md b/_docs_use-cases/use-case-anonymous-load-token-by-reference-without-having-an-account.md similarity index 82% rename from _docs_use-cases/use-case-anonymous-load-token-by-truncated-reference-without-having-an-account.md rename to _docs_use-cases/use-case-anonymous-load-token-by-reference-without-having-an-account.md index cd17a2244..5b3c25604 100644 --- a/_docs_use-cases/use-case-anonymous-load-token-by-truncated-reference-without-having-an-account.md +++ b/_docs_use-cases/use-case-anonymous-load-token-by-reference-without-having-an-account.md @@ -1,8 +1,10 @@ --- # Start automatic generation -permalink: use-case-anonymous-load-token-by-truncated-reference-without-having-an-account +permalink: use-case-anonymous-load-token-by-reference-without-having-an-account +redirect_from: + - use-case-anonymous-load-token-by-truncated-reference-without-having-an-account published: true -title: "Load Token by truncated reference (without having an account)" +title: "Load Token by reference (without having an account)" type: use-case toc: true sidebar: @@ -13,7 +15,7 @@ properties: - component: Runtime - layer: Anonymous - facade: AnonymousTokensFacade - - function: loadPeerTokenByTruncatedReference + - function: loadPeerToken - description: - feature category: Share information over side-channel - tech category: AnonymousTokens @@ -31,7 +33,7 @@ properties: - changed_at: - api_route_regex: - published: default - - link: use-case-anonymous-load-token-by-truncated-reference-without-having-an-account + - link: use-case-anonymous-load-token-by-reference-without-having-an-account require: required_by: # End automatic generation diff --git a/_docs_use-cases/use-case-consumption-accept-incoming-request.md b/_docs_use-cases/use-case-consumption-accept-incoming-request.md index 509e11cf8..2cea9aaa2 100644 --- a/_docs_use-cases/use-case-consumption-accept-incoming-request.md +++ b/_docs_use-cases/use-case-consumption-accept-incoming-request.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Requests/Incoming/{id}/Accept + - api_route_regex: PUT /api/core/v1/Requests/Incoming/{id}/Accept - published: default - link: use-case-consumption-accept-incoming-request require: required_by: -api_route_regex: ^PUT /api/v2/Requests/Incoming/{id}/Accept$ +api_route_regex: ^PUT /api/core/v1/Requests/Incoming/{id}/Accept$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-change-default-ownidentityattribute.md b/_docs_use-cases/use-case-consumption-change-default-ownidentityattribute.md new file mode 100644 index 000000000..b8daa3286 --- /dev/null +++ b/_docs_use-cases/use-case-consumption-change-default-ownidentityattribute.md @@ -0,0 +1,67 @@ +--- +# Start automatic generation +permalink: use-case-consumption-change-default-ownidentityattribute +redirect_from: + - /use-case-consumption-change-default-repositoryattribute +published: true +title: "Change default OwnIdentityAttribute" +type: use-case +toc: true +sidebar: + - title: "Integrate enmeshed" + nav: "docs_integrate" +properties: + - id: RA4 + - component: Runtime + - layer: Consumption + - facade: AttributesFacade + - function: changeDefaultOwnIdentityAttribute + - description: + - feature category: Normalized Attributes + - tech category: Attributes + - status: DONE + - documentation status: DONE + - comments: + - actor: Identity + - trigger: REST API + - precondition: + - result: + - priority: n/a + - complexity: n/a + - size: n/a + - created_at: + - changed_at: + - api_route_regex: + - published: default + - link: use-case-consumption-change-default-ownidentityattribute +require: +required_by: +# End automatic generation +--- + +{{properties.description}} + +{% include properties_list.html %} + +This use case is only accessible if setting default OwnIdentityAttributes is enabled in the Runtime configuration. +By default, this is only the case for the App and not for the Connector. +{: .notice--info} + +If setting default OwnIdentityAttributes is enabled, for every [IdentityAttribute value type]({% link _docs_integrate/attribute-values.md %}#identity-attributes) exactly one [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) will have the property `isDefault` set, given that at least one OwnIdentityAttribute of that value type exists. +By default, this is the first OwnIdentityAttribute of that value type that was created. +However, if the default OwnIdentityAttribute is [succeeded]({% link _docs_integrate/update-attributes-by-succession.md %}), its successor will become the new default OwnIdentityAttribute. +This use case allows you to change the default OwnIdentityAttribute. + +## Parameters + +- The `attributeId` of the OwnIdentityAttribute that is to be the new default OwnIdentityAttribute. + +## On Success + +- The OwnIdentityAttribute belonging to the input `attributeId` has `isDefault` set and is returned. Further, the former default OwnIdentityAttribute has `isDefault` unset. + +## On Failure + +- The default OwnIdentityAttribute can't be changed if the provided `attributeId` doesn't correlate to an OwnIdentityAttribute. +- The default OwnIdentityAttribute can't be changed if the provided `attributeId` correlates to an OwnIdentityAttribute with a successor. +- The default OwnIdentityAttribute can't be changed if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-change-default-repositoryattribute.md b/_docs_use-cases/use-case-consumption-change-default-repositoryattribute.md deleted file mode 100644 index ed95eb34a..000000000 --- a/_docs_use-cases/use-case-consumption-change-default-repositoryattribute.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-change-default-repositoryattribute -published: true -title: "Change default RepositoryAttribute" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA28 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: changeDefaultRepositoryAttribute - - description: - - feature category: Normalized Attributes - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: - - published: default - - link: use-case-consumption-change-default-repositoryattribute -require: -required_by: -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case is only accessible if setting default RepositoryAttributes is enabled in the Runtime configuration. -By default, this is only the case for the App and not for the Connector. -{: .notice--info} - -If setting default RepositoryAttributes is enabled, for every [IdentityAttribute value type]({% link _docs_integrate/attribute-values.md %}#identity-attributes) exactly one [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) will have the property `isDefault` set, given that at least one RepositoryAttribute of that value type exists. -By default, this is the first RepositoryAttribute of that value type that was created. -However, if the default RepositoryAttribute is [succeeded]({% link _docs_integrate/update-attributes-by-succession.md %}), its successor will become the new default RepositoryAttribute. -This use case allows you to change the default RepositoryAttribute. - -## Parameters - -- The `attributeId` of the RepositoryAttribute that is to be the new default RepositoryAttribute. - -## On Success - -- The RepositoryAttribute belonging to the input `attributeId` has `isDefault` set and is returned. Further, the former default RepositoryAttribute has `isDefault` unset. - -## On Failure - -- The default RepositoryAttribute can't be changed if the provided `attributeId` doesn't correlate to a RepositoryAttribute. -- The default RepositoryAttribute can't be changed if the provided `attributeId` correlates to a RepositoryAttribute with a successor. -- The default RepositoryAttribute can't be changed if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-accepted.md b/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-accepted.md index 54d01f6c4..94bded44e 100644 --- a/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-accepted.md +++ b/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-accepted.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Requests/Incoming/{id}/CanAccept + - api_route_regex: PUT /api/core/v1/Requests/Incoming/{id}/CanAccept - published: default - link: use-case-consumption-check-if-incoming-request-can-be-accepted require: required_by: -api_route_regex: ^PUT /api/v2/Requests/Incoming/{id}/CanAccept$ +api_route_regex: ^PUT /api/core/v1/Requests/Incoming/{id}/CanAccept$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-rejected.md b/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-rejected.md index 2c683ba1e..f93985e4a 100644 --- a/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-rejected.md +++ b/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-rejected.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Requests/Incoming/{id}/CanReject + - api_route_regex: PUT /api/core/v1/Requests/Incoming/{id}/CanReject - published: default - link: use-case-consumption-check-if-incoming-request-can-be-rejected require: required_by: -api_route_regex: ^PUT /api/v2/Requests/Incoming/{id}/CanReject$ +api_route_regex: ^PUT /api/core/v1/Requests/Incoming/{id}/CanReject$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md b/_docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md index 180a5ff0c..286928e5d 100644 --- a/_docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md +++ b/_docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Requests/Outgoing/Validate + - api_route_regex: POST /api/core/v1/Requests/Outgoing/Validate - published: default - link: use-case-consumption-check-if-outgoing-request-can-be-created require: required_by: -api_route_regex: ^POST /api/v2/Requests/Outgoing/Validate$ +api_route_regex: ^POST /api/core/v1/Requests/Outgoing/Validate$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-check-if-ownidentityattribute-can-be-created.md b/_docs_use-cases/use-case-consumption-check-if-ownidentityattribute-can-be-created.md new file mode 100644 index 000000000..38ecc7587 --- /dev/null +++ b/_docs_use-cases/use-case-consumption-check-if-ownidentityattribute-can-be-created.md @@ -0,0 +1,65 @@ +--- +# Start automatic generation +permalink: use-case-consumption-check-if-ownidentityattribute-can-be-created +redirect_from: + - /use-case-consumption-check-if-repositoryattribute-can-be-created +published: true +title: "Check if OwnIdentityAttribute can be created" +type: use-case +toc: true +sidebar: + - title: "Integrate enmeshed" + nav: "docs_integrate" +properties: + - id: RA2 + - component: Runtime + - layer: Consumption + - facade: AttributesFacade + - function: canCreateOwnIdentityAttribute + - description: + - feature category: Normalized Attributes + - tech category: Attributes + - status: DONE + - documentation status: DONE + - comments: + - actor: Identity + - trigger: REST API + - precondition: + - result: + - priority: n/a + - complexity: n/a + - size: n/a + - created_at: + - changed_at: + - api_route_regex: PUT /api/core/v1/Attributes/CanCreate + - published: default + - link: use-case-consumption-check-if-ownidentityattribute-can-be-created +require: +required_by: +api_route_regex: ^PUT /api/core/v1/Attributes/CanCreate$ +# End automatic generation +--- + +{{properties.description}} + +{% include properties_list.html %} + +This use case checks whether an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) can be created without actually creating it. +If an OwnIdentityAttribute can be created, this can be achieved by executing the [Create an OwnIdentityAttribute]({% link _docs_use-cases/use-case-consumption-create-an-ownidentityattribute.md %}) use case. + +## Parameters + +- The `content` is an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) without the `owner` property, since its value would automatically be set to the `address` of your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) during the potential [creation of the OwnIdentityAttribute]({% link _docs_use-cases/use-case-consumption-create-an-ownidentityattribute.md %}). + +## On Success + +- Returns a `result` that indicates if an OwnIdentityAttribute can be created based on the specified `content`. +- If the `isSuccess` property of the `result` has the value `true`, the OwnIdentityAttribute can currently be created. +- If the `isSuccess` property of the `result` has the value `false`, the OwnIdentityAttribute cannot currently be created. This may have the following reasons: + - The provided `content.value.@type` does not match one of the allowed [IdentityAttribute value types]({% link _docs_integrate/attribute-values.md %}#identity-attributes). + - Invalid `content.tags` were provided. A tag is invalid if it is neither contained in the [AttributeTagCollection]({% link _docs_integrate/data-model-overview.md %}#attributetagcollection) for the `content.value.@type` and starts with the prefix `bkb:` nor starts with the custom tag prefix `x:` or `X:`, the prefix `urn:`, the prefix `language:` followed by a valid ISO 639 language code nor the prefix `mimetype:` followed by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$`. + - There is already an existing [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) whose `succeededBy` property is undefined that has the exact same `content.value`. + +## On Failure + +- The parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-check-if-repositoryattribute-can-be-created.md b/_docs_use-cases/use-case-consumption-check-if-repositoryattribute-can-be-created.md deleted file mode 100644 index 64b8e054b..000000000 --- a/_docs_use-cases/use-case-consumption-check-if-repositoryattribute-can-be-created.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-check-if-repositoryattribute-can-be-created -published: true -title: "Check if RepositoryAttribute can be created" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA31 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: canCreateRepositoryAttribute - - description: - - feature category: Normalized Attributes - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: PUT /api/v2/Attributes/CanCreate - - published: default - - link: use-case-consumption-check-if-repositoryattribute-can-be-created -require: -required_by: -api_route_regex: ^PUT /api/v2/Attributes/CanCreate$ -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case checks whether a [RepositoryAttribute]({% link _docs_integrate/attribute-introduction.md %}#repositoryattributes), which is an unshared [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) whose `content` is an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute), can be created without actually creating it. -If a RepositoryAttribute can be created, this can be achieved by executing the [Create a RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-create-a-repositoryattribute.md %}) use case. - -## Parameters - -- The `content` is an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) without the `owner` property, since its value would automatically be set to the `address` of your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) during the potential [creation of the RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-create-a-repositoryattribute.md %}). - -## On Success - -- Returns a `result` that indicates if a RepositoryAttribute can be created based on the specified `content`. -- If the `isSuccess` property of the `result` has the value `true`, the RepositoryAttribute can currently be created. -- If the `isSuccess` property of the `result` has the value `false`, the RepositoryAttribute cannot currently be created. This may have the following reasons: - - The provided `content.value.@type` does not match one of the allowed [IdentityAttribute value types]({% link _docs_integrate/attribute-values.md %}#identity-attributes). - - There is already an existing [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) whose `succeededBy` property is undefined that has the exact same `content.value`. - -## On Failure - -- The parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-create-a-repositoryattribute.md b/_docs_use-cases/use-case-consumption-create-a-repositoryattribute.md deleted file mode 100644 index a6a5f1ab3..000000000 --- a/_docs_use-cases/use-case-consumption-create-a-repositoryattribute.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-create-a-repositoryattribute -redirect_from: - - /use-case-consumption-create-an-attribute -published: true -title: "Create a RepositoryAttribute" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA1 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: createRepositoryAttribute - - description: - - feature category: Normalized Attributes - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: We cannot create RelationshipAttributes with this UseCase - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: POST /api/v2/Attributes - - published: default - - link: use-case-consumption-create-a-repositoryattribute -require: -required_by: -api_route_regex: ^POST /api/v2/Attributes$ -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case is intended to create a RepositoryAttribute, i.e. an unshared [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) based on a given [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute). - -## Parameters - -- The `content` for the LocalAttribute that ought to be created as IdentityAttribute without the `owner` property, since it is automatically set to the `address` of your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). - -## On Success - -- A LocalAttribute is created according to the parameters and returned with an undefined `shareInfo`. - -## On Failure - -- The LocalAttribute cannot be created if there is already an existing RepositoryAttribute whose `succeededBy` property is undefined that has the exact same `content.value`. diff --git a/_docs_use-cases/use-case-consumption-create-a-shared-attribute-copy.md b/_docs_use-cases/use-case-consumption-create-a-shared-attribute-copy.md deleted file mode 100644 index b9a256fab..000000000 --- a/_docs_use-cases/use-case-consumption-create-a-shared-attribute-copy.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-create-a-shared-attribute-copy -published: true -title: "Create a shared Attribute copy" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA6 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: createSharedAttributeCopy - - description: - - feature category: Cross-Identity Attribute sharing - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: Internal - - actor: Identity - - trigger: Runtime - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: - - published: default - - link: use-case-consumption-create-a-shared-attribute-copy -require: -required_by: -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -Be advised that this is a Runtime-internal use case which is automatically used by the module system. You should not call this use case without having good reason. -{: .notice--warning} - -This use case is intended to create a copy of a LocalAttribute with the intent to share it. The copy references the original [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattributeshareinfo). - -## Parameters - -- `attributeId` is the ID of the Attribute that the copy is made of. -- `peer` is the address of the peer the copy will be sent to. -- `requestReference` is a reference to the Request the copy will be sent with. - -## On Success - -- The copy is created and returned as a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). - -## On Failure - -- The parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-create-an-ownidentityattribute.md b/_docs_use-cases/use-case-consumption-create-an-ownidentityattribute.md new file mode 100644 index 000000000..9f1769e4a --- /dev/null +++ b/_docs_use-cases/use-case-consumption-create-an-ownidentityattribute.md @@ -0,0 +1,61 @@ +--- +# Start automatic generation +permalink: use-case-consumption-create-an-ownidentityattribute +redirect_from: + - /use-case-consumption-create-a-repositoryattribute +published: true +title: "Create an OwnIdentityAttribute" +type: use-case +toc: true +sidebar: + - title: "Integrate enmeshed" + nav: "docs_integrate" +properties: + - id: RA1 + - component: Runtime + - layer: Consumption + - facade: AttributesFacade + - function: createOwnIdentityAttribute + - description: + - feature category: Normalized Attributes + - tech category: Attributes + - status: DONE + - documentation status: DONE + - comments: We cannot create RelationshipAttributes with this UseCase + - actor: Identity + - trigger: REST API + - precondition: + - result: + - priority: n/a + - complexity: n/a + - size: n/a + - created_at: + - changed_at: + - api_route_regex: POST /api/core/v1/Attributes + - published: default + - link: use-case-consumption-create-an-ownidentityattribute +require: +required_by: +api_route_regex: ^POST /api/core/v1/Attributes$ +# End automatic generation +--- + +{{properties.description}} + +{% include properties_list.html %} + +This use case is intended to create an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute). + +## Parameters + +- The `content` for the OwnIdentityAttribute that ought to be created as [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) without the `owner` property, since it is automatically set to the `address` of your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). + +## On Success + +- An OwnIdentityAttribute is created according to the parameters. + +## On Failure + +- The OwnIdentityAttribute cannot be created if the provided `content.value.@type` does not match one of the allowed [IdentityAttribute value types]({% link _docs_integrate/attribute-values.md %}#identity-attributes). +- The OwnIdentityAttribute cannot be created if invalid `content.tags` were specified. A tag is invalid if it is neither contained in the [AttributeTagCollection]({% link _docs_integrate/data-model-overview.md %}#attributetagcollection) for the `content.value.@type` and starts with the prefix `bkb:` nor starts with the custom tag prefix `x:` or `X:`, the prefix `urn:`, the prefix `language:` followed by a valid ISO 639 language code nor the prefix `mimetype:` followed by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$`. +- The OwnIdentityAttribute cannot be created if there is already an existing OwnIdentityAttribute whose `succeededBy` property is undefined that has the exact same `content.value`. diff --git a/_docs_use-cases/use-case-consumption-create-and-share-a-relationshipattribute.md b/_docs_use-cases/use-case-consumption-create-and-share-a-relationshipattribute.md index 45b3ddd94..acb86e8a0 100644 --- a/_docs_use-cases/use-case-consumption-create-and-share-a-relationshipattribute.md +++ b/_docs_use-cases/use-case-consumption-create-and-share-a-relationshipattribute.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA21 + - id: RA5 - component: Runtime - layer: Consumption - facade: AttributesFacade @@ -43,7 +43,7 @@ required_by: [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) are always associated with a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between two Identities. Consequently, in contrast to [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute), there cannot be unshared RelationshipAttributes. -Instead, you and your peer will always each have a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) with the same RelationshipAttribute as `content` and which only differs in the `shareInfo.peer` property. +Instead, you and your peer will always each have a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) with the same RelationshipAttribute as `content`. Thus, wanting to create a new RelationshipAttribute, a [Request]({% link _docs_integrate/data-model-overview.md %}#request) is sent to the peer via [Message]({% link _docs_integrate/data-model-overview.md %}#message). Only if the peer accepts this Request, the RelationshipAttribute will be created at their side. Once you receive the [Response]({% link _docs_integrate/data-model-overview.md %}#response), a LocalAttribute with the same `content` will be created at your side. @@ -56,9 +56,10 @@ Once you receive the [Response]({% link _docs_integrate/data-model-overview.md % ## On Success -- A Request is sent via Message to the peer, containing a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) with the RelationshipAttribute you want to create and share with the peer. Furthermore, the Request is returned. +- A Request is sent via Message to the peer, containing a [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) with the RelationshipAttribute you want to create and share with the peer. + Furthermore, the Request is returned. ## On Failure -- The Request cannot be created, if the `peer` is unknown. -- The Request cannot be created, if the parameters are malformed. +- The Request cannot be created if the `peer` is unknown. +- The Request cannot be created if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-create-outgoing-request.md b/_docs_use-cases/use-case-consumption-create-outgoing-request.md index 42df79f5e..38a5140bd 100644 --- a/_docs_use-cases/use-case-consumption-create-outgoing-request.md +++ b/_docs_use-cases/use-case-consumption-create-outgoing-request.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Requests/Outgoing + - api_route_regex: POST /api/core/v1/Requests/Outgoing - published: default - link: use-case-consumption-create-outgoing-request require: required_by: -api_route_regex: ^POST /api/v2/Requests/Outgoing$ +api_route_regex: ^POST /api/core/v1/Requests/Outgoing$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-delete-a-peer-shared-attribute-and-notify-peer.md b/_docs_use-cases/use-case-consumption-delete-a-peer-shared-attribute-and-notify-peer.md deleted file mode 100644 index 70b759af8..000000000 --- a/_docs_use-cases/use-case-consumption-delete-a-peer-shared-attribute-and-notify-peer.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-delete-a-peer-shared-attribute-and-notify-peer -published: true -title: "Delete a peer shared Attribute and notify peer" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA24 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: deletePeerSharedAttributeAndNotifyPeer - - description: - - feature category: Cross-Identity Attribute sharing - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: DELETE /api/v2/Attributes/Peer/Shared/{id} - - published: default - - link: use-case-consumption-delete-a-peer-shared-attribute-and-notify-peer -require: -required_by: -api_route_regex: ^DELETE /api/v2/Attributes/Peer/Shared/{id}$ -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case allows you to delete a peer shared Attribute, i.e. a [LocalAttribute]({%link _docs_integrate/data-model-overview.md %}#localattribute) that a peer owns and has shared with you. - -## Parameters - -- The `attributeId` of the peer shared Attribute you want to delete. - -## On Success - -- The peer shared Attribute will be deleted. -- All predecessors of the peer shared Attribute will be deleted. -- If the peer shared Attribute was succeeded, the `succeeds` property of the successor will be set to undefined. -- If the `attributeId` relates to a [RelationshipAttribute]({%link _docs_integrate/data-model-overview.md %}#relationshipattribute) and there are shared copies of the peer shared RelationshipAttribute or potential predecessors of it, the `shareInfo.sourceAttribute` of those emitted ThirdPartyRelationshipAttributes will be set to undefined. -- A [Notification]({%link _docs_integrate/data-model-overview.md %}#notification) with a [PeerSharedAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#peersharedattributedeletedbypeernotificationitem) is sent to the owner of the Attribute, informing them that you deleted their Attribute. Technically, the own shared Attribute of the owner and all predecessors will get a `deletionInfo` with `deletionStatus` `"DeletedByPeer"` and the time of receiving the Notification as `deletionDate`. -- The `notificationId` is returned. - -## On Failure - -- No Attribute can be deleted if you don't have a LocalAttribute with given `attributeId`. -- No Attribute can be deleted if the Attribute with given `attributeId` is not a peer shared Attribute. diff --git a/_docs_use-cases/use-case-consumption-delete-a-repositoryattribute.md b/_docs_use-cases/use-case-consumption-delete-a-repositoryattribute.md deleted file mode 100644 index 2136ba296..000000000 --- a/_docs_use-cases/use-case-consumption-delete-a-repositoryattribute.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-delete-a-repositoryattribute -published: true -title: "Delete a RepositoryAttribute" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA7 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: deleteRepositoryAttribute - - description: - - feature category: Normalized Attributes - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: DELETE /api/v2/Attributes/{id} - - published: default - - link: use-case-consumption-delete-a-repositoryattribute -require: -required_by: -api_route_regex: ^DELETE /api/v2/Attributes/{id}$ -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case allows you to delete a RepositoryAttribute, i.e. a [LocalAttribute]({%link _docs_integrate/data-model-overview.md %}#localattribute) that is owned by yourself and whose `shareInfo` property is undefined. - -## Parameters - -- The `attributeId` of the RepositoryAttribute you want to delete. - -## On Success - -- The RepositoryAttribute will be deleted. -- All predecessors of the RepositoryAttribute will be deleted. -- If the RepositoryAttribute was succeeded, the `succeeds` property of the successor will be set to undefined. -- If there are shared copies of the RepositoryAttribute or potential predecessors of it, the `shareInfo.sourceAttribute` of those own shared Attributes will be set to undefined. - -## On Failure - -- No Attribute can be deleted if you don't have a LocalAttribute with given `attributeId`. -- No Attribute can be deleted if the Attribute with given `attributeId` is not a RepositoryAttribute. diff --git a/_docs_use-cases/use-case-consumption-delete-a-third-party-owned-relationshipattribute-and-notify-peer.md b/_docs_use-cases/use-case-consumption-delete-a-third-party-owned-relationshipattribute-and-notify-peer.md deleted file mode 100644 index 81b4255c9..000000000 --- a/_docs_use-cases/use-case-consumption-delete-a-third-party-owned-relationshipattribute-and-notify-peer.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-delete-a-third-party-owned-relationshipattribute-and-notify-peer -published: true -title: "Delete a third party owned RelationshipAttribute and notify peer" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA25 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: deleteThirdPartyOwnedRelationshipAttributeAndNotifyPeer - - description: - - feature category: Cross-Identity Attribute sharing - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: deprecated use /use-case-consumption-delete-a-thirdpartyrelationshipattribute-and-notify-peer instead - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: DELETE /api/v2/Attributes/ThirdParty/{id} - - published: default - - link: use-case-consumption-delete-a-third-party-owned-relationshipattribute-and-notify-peer -require: -required_by: -api_route_regex: ^DELETE /api/v2/Attributes/ThirdParty/{id}$ -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case is deprecated and will be removed in the next major version. Please use the use case [Delete a ThirdPartyRelationshipAttribute and notify peer](use-case-consumption-delete-a-thirdpartyrelationshipattribute-and-notify-peer) instead. -{: .notice--warning} - -This use case allows you to delete a ThirdPartyRelationshipAttribute, i.e. a [LocalAttribute]({%link _docs_integrate/data-model-overview.md %}#localattribute) that has the property `shareInfo.thirdPartyAddress` set. - -## Parameters - -- The `attributeId` of the ThirdPartyRelationshipAttribute you want to delete. - -## On Success - -- The ThirdPartyRelationshipAttribute will be deleted. -- All predecessors of the ThirdPartyRelationshipAttribute will be deleted. -- If the ThirdPartyRelationshipAttribute was succeeded, the `succeeds` property of the successor will be set to undefined. -- A [Notification]({%link _docs_integrate/data-model-overview.md %}#notification) with a [ThirdPartyRelationshipAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributedeletedbypeernotificationitem) is sent to the peer of the Attribute, informing them that you deleted the Attribute. Technically, the Attribute of the peer and all predecessors will get a `deletionInfo` with `deletionStatus` `"DeletedByPeer"` and the time of receiving the Notification as `deletionDate`. -- The `notificationId` is returned. - -## On Failure - -- No Attribute can be deleted if you don't have a LocalAttribute with given `attributeId`. -- No Attribute can be deleted if the Attribute with given `attributeId` is not a ThirdPartyRelationshipAttribute. diff --git a/_docs_use-cases/use-case-consumption-delete-a-thirdpartyrelationshipattribute-and-notify-peer.md b/_docs_use-cases/use-case-consumption-delete-a-thirdpartyrelationshipattribute-and-notify-peer.md deleted file mode 100644 index ec82823b4..000000000 --- a/_docs_use-cases/use-case-consumption-delete-a-thirdpartyrelationshipattribute-and-notify-peer.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-delete-a-thirdpartyrelationshipattribute-and-notify-peer -published: true -title: "Delete a ThirdPartyRelationshipAttribute and notify peer" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA29 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: deleteThirdPartyRelationshipAttributeAndNotifyPeer - - description: - - feature category: Cross-Identity Attribute sharing - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: add redirect from /use-case-consumption-delete-a-third-party-owned-relationshipattribute-and-notify-peer as soon as that use case is deleted - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: DELETE /api/v2/Attributes/ThirdParty/{id} - - published: default - - link: use-case-consumption-delete-a-thirdpartyrelationshipattribute-and-notify-peer -require: -required_by: -api_route_regex: ^DELETE /api/v2/Attributes/ThirdParty/{id}$ -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case allows you to delete a ThirdPartyRelationshipAttribute, i.e. a [LocalAttribute]({%link _docs_integrate/data-model-overview.md %}#localattribute) that has the property `shareInfo.thirdPartyAddress` set. - -## Parameters - -- The `attributeId` of the ThirdPartyRelationshipAttribute you want to delete. - -## On Success - -- The ThirdPartyRelationshipAttribute will be deleted. -- All predecessors of the ThirdPartyRelationshipAttribute will be deleted. -- If the ThirdPartyRelationshipAttribute was succeeded, the `succeeds` property of the successor will be set to undefined. -- A [Notification]({%link _docs_integrate/data-model-overview.md %}#notification) with a [ThirdPartyRelationshipAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributedeletedbypeernotificationitem) is sent to the peer of the Attribute, informing them that you deleted the Attribute. Technically, the Attribute of the peer and all predecessors will get a `deletionInfo` with `deletionStatus` `"DeletedByPeer"` and the time of receiving the Notification as `deletionDate`. -- The `notificationId` is returned. - -## On Failure - -- No Attribute can be deleted if you don't have a LocalAttribute with given `attributeId`. -- No Attribute can be deleted if the Attribute with given `attributeId` is not a ThirdPartyRelationshipAttribute. diff --git a/_docs_use-cases/use-case-consumption-delete-an-attribute-and-notify.md b/_docs_use-cases/use-case-consumption-delete-an-attribute-and-notify.md new file mode 100644 index 000000000..19bd43dd7 --- /dev/null +++ b/_docs_use-cases/use-case-consumption-delete-an-attribute-and-notify.md @@ -0,0 +1,69 @@ +--- +# Start automatic generation +permalink: use-case-consumption-delete-an-attribute-and-notify +redirect_from: + - /use-case-consumption-delete-a-repositoryattribute + - /use-case-consumption-delete-an-own-shared-attribute-and-notify-peer + - /use-case-consumption-delete-a-peer-shared-attribute-and-notify-peer + - /use-case-consumption-delete-a-thirdpartyrelationshipattribute-and-notify-peer +published: true +title: "Delete an Attribute and notify" +type: use-case +toc: true +sidebar: + - title: "Integrate enmeshed" + nav: "docs_integrate" +properties: + - id: RA6 + - component: Runtime + - layer: Consumption + - facade: AttributesFacade + - function: deleteAttributeAndNotify + - description: + - feature category: Normalized Attributes + - tech category: Attributes + - status: DONE + - documentation status: DONE + - comments: + - actor: Identity + - trigger: REST API + - precondition: + - result: + - priority: n/a + - complexity: n/a + - size: n/a + - created_at: + - changed_at: + - api_route_regex: DELETE /api/core/v1/Attributes/{id} + - published: default + - link: use-case-consumption-delete-an-attribute-and-notify +require: +required_by: +api_route_regex: ^DELETE /api/core/v1/Attributes/{id}$ +# End automatic generation +--- + +{{properties.description}} + +{% include properties_list.html %} + +This use case allows you to delete a [LocalAttribute]({%link _docs_integrate/data-model-overview.md %}#localattribute) and notify the peers it is shared with. + +## Parameters + +- The `attributeId` of the LocalAttribute you want to delete. + +## On Success + +- The LocalAttribute will be deleted. +- All predecessors of the LocalAttribute will be deleted. +- If the LocalAttribute was succeeded, the `succeeds` property of the successor will be set to undefined. +- If there are [AttributeForwardingDetails]({%link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with the LocalAttribute belonging to the `attributeId` or a potential predecessor of it, they will be removed as well. +- Any peer you shared the LocalAttribute or a potential predecessor of it with is informed that you deleted it. + A [Notification]({%link _docs_integrate/data-model-overview.md %}#notification) with an [OwnAttributeDeletedByOwnerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#ownattributedeletedbyownernotificationitem), a [ForwardedAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#forwardedattributedeletedbypeernotificationitem), or a [PeerRelationshipAttributeDeletedByPeerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#peerrelationshipattributedeletedbypeernotificationitem) is sent, depending on the [LocalAttribute]({%link _docs_integrate/data-model-overview.md %}#localattribute) subtype. + Technically, the LocalAttribute at the peer's side and all predecessors will get a `deletionInfo` with `"DeletedByEmitter"` or `"DeletedByRecipient"` as `deletionStatus` and the time of receiving the Notification as `deletionDate`. +- The `notificationIds` are returned. + +## On Failure + +- If there is no LocalAttribute with the given `attributeId`, it can't be deleted. diff --git a/_docs_use-cases/use-case-consumption-delete-an-own-shared-attribute-and-notify-peer.md b/_docs_use-cases/use-case-consumption-delete-an-own-shared-attribute-and-notify-peer.md deleted file mode 100644 index 191f6ff2b..000000000 --- a/_docs_use-cases/use-case-consumption-delete-an-own-shared-attribute-and-notify-peer.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-delete-an-own-shared-attribute-and-notify-peer -published: true -title: "Delete an own shared Attribute and notify peer" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA23 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: deleteOwnSharedAttributeAndNotifyPeer - - description: - - feature category: Cross-Identity Attribute sharing - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: DELETE /api/v2/Attributes/Own/Shared/{id} - - published: default - - link: use-case-consumption-delete-an-own-shared-attribute-and-notify-peer -require: -required_by: -api_route_regex: ^DELETE /api/v2/Attributes/Own/Shared/{id}$ -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case allows you to delete an own shared Attribute, i.e. a [LocalAttribute]({%link _docs_integrate/data-model-overview.md %}#localattribute) with a `shareInfo`, that is owned by you. -It is created as a result of sharing the `content` of a RepositoryAttribute with a peer. - -## Parameters - -- The `attributeId` of the own shared Attribute you want to delete. - -## On Success - -- The own shared Attribute will be deleted. -- All predecessors of the own shared Attribute will be deleted. -- If the own shared Attribute was succeeded, the `succeeds` property of the successor will be set to undefined. -- If the `attributeId` relates to a [RelationshipAttribute]({%link _docs_integrate/data-model-overview.md %}#relationshipattribute) and there are shared copies of the own shared RelationshipAttribute or potential predecessors of it, the `shareInfo.sourceAttribute` of those emitted ThirdPartyRelationshipAttributes will be set to undefined. -- A [Notification]({%link _docs_integrate/data-model-overview.md %}#notification) with a [OwnSharedAttributeDeletedByOwnerNotificationItem]({%link _docs_integrate/data-model-overview.md %}#ownsharedattributedeletedbyownernotificationitem) is sent to the peer you shared the Attribute with, informing them that you deleted the Attribute. Technically, the peer shared Attribute at the peer's side and all predecessors will get a `deletionInfo` with `deletionStatus` `"DeletedByOwner"` and the time of receiving the Notification as `deletionDate`. -- The `notificationId` is returned. - -## On Failure - -- No Attribute can be deleted if you don't have a LocalAttribute with given `attributeId`. -- No Attribute can be deleted if the Attribute with given `attributeId` is not an own shared Attribute. diff --git a/_docs_use-cases/use-case-consumption-delete-attributelistener.md b/_docs_use-cases/use-case-consumption-delete-attributelistener.md deleted file mode 100644 index 9193fc686..000000000 --- a/_docs_use-cases/use-case-consumption-delete-attributelistener.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-delete-attributelistener -published: false -title: "Delete AttributeListener" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RAL3 - - component: Runtime - - layer: Consumption - - facade: - - function: - - description: - - feature category: Attribute automation - - tech category: AttributeListeners - - status: OPEN - - documentation status: - - comments: - - actor: Identity - - trigger: - - precondition: - - result: - - priority: LOW - - complexity: LOW - - size: S - - created_at: - - changed_at: - - api_route_regex: - - published: - - link: use-case-consumption-delete-attributelistener -require: -required_by: -# End automatic generation ---- diff --git a/_docs_use-cases/use-case-consumption-delete-identitymetadata.md b/_docs_use-cases/use-case-consumption-delete-identitymetadata.md index 9055ac577..eee924e3a 100644 --- a/_docs_use-cases/use-case-consumption-delete-identitymetadata.md +++ b/_docs_use-cases/use-case-consumption-delete-identitymetadata.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: DELETE /api/v2/IdentityMetadata + - api_route_regex: DELETE /api/core/v1/IdentityMetadata - published: default - link: use-case-consumption-delete-identitymetadata require: required_by: -api_route_regex: ^DELETE /api/v2/IdentityMetadata$ +api_route_regex: ^DELETE /api/core/v1/IdentityMetadata$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-delete-shared-attribute.md b/_docs_use-cases/use-case-consumption-delete-shared-attribute.md deleted file mode 100644 index 463ea7500..000000000 --- a/_docs_use-cases/use-case-consumption-delete-shared-attribute.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-delete-shared-attribute -published: false -title: "Delete shared Attribute" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA14 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: - - description: - - feature category: - - tech category: Attributes - - status: IDEA - - documentation status: - - comments: - - actor: Identity - - trigger: - - precondition: - - result: - - priority: HIGH - - complexity: MEDIUM - - size: M - - created_at: - - changed_at: - - api_route_regex: - - published: - - link: use-case-consumption-delete-shared-attribute -require: -required_by: -# End automatic generation ---- diff --git a/_docs_use-cases/use-case-consumption-execute-a-relationshipattributequery.md b/_docs_use-cases/use-case-consumption-execute-a-relationshipattributequery.md index ae28d1682..2fe0d0160 100644 --- a/_docs_use-cases/use-case-consumption-execute-a-relationshipattributequery.md +++ b/_docs_use-cases/use-case-consumption-execute-a-relationshipattributequery.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA9 + - id: RA17 - component: Runtime - layer: Consumption - facade: AttributesFacade @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Attributes/ExecuteRelationshipAttributeQuery + - api_route_regex: POST /api/core/v1/Attributes/ExecuteRelationshipAttributeQuery - published: default - link: use-case-consumption-execute-a-relationshipattributequery require: required_by: -api_route_regex: ^POST /api/v2/Attributes/ExecuteRelationshipAttributeQuery$ +api_route_regex: ^POST /api/core/v1/Attributes/ExecuteRelationshipAttributeQuery$ # End automatic generation --- @@ -42,7 +42,7 @@ api_route_regex: ^POST /api/v2/Attributes/ExecuteRelationshipAttributeQuery$ {% include properties_list.html %} -This use case is intended to execute an incoming [RelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#relationshipattributequery) (e.g. received by a ReadAttributeRequestItem) which returns a list of matching [Relationship Attributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute). +This use case is intended to execute an incoming [RelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#relationshipattributequery) which returns a list of matching [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute). ## Parameters @@ -50,7 +50,8 @@ This use case is intended to execute an incoming [RelationshipAttributeQuery]({% ## On Success -- Returns the `RelationshipAttributes` as [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) that match the given query. +- Returns the RelationshipAttributes as [OwnRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) or [PeerRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) that match the given query. + [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with `private` as `confidentiality` are never returned. ## On Failure diff --git a/_docs_use-cases/use-case-consumption-execute-a-thirdpartyrelationshipattributequery.md b/_docs_use-cases/use-case-consumption-execute-a-thirdpartyrelationshipattributequery.md index c15dc31d8..007bb7e38 100644 --- a/_docs_use-cases/use-case-consumption-execute-a-thirdpartyrelationshipattributequery.md +++ b/_docs_use-cases/use-case-consumption-execute-a-thirdpartyrelationshipattributequery.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA10 + - id: RA18 - component: Runtime - layer: Consumption - facade: AttributesFacade @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Attributes/ExecuteThirdPartyRelationshipAttributeQuery + - api_route_regex: POST /api/core/v1/Attributes/ExecuteThirdPartyRelationshipAttributeQuery - published: default - link: use-case-consumption-execute-a-thirdpartyrelationshipattributequery require: required_by: -api_route_regex: ^POST /api/v2/Attributes/ExecuteThirdPartyRelationshipAttributeQuery$ +api_route_regex: ^POST /api/core/v1/Attributes/ExecuteThirdPartyRelationshipAttributeQuery$ # End automatic generation --- @@ -51,7 +51,8 @@ It returns a list of matching [RelationshipAttributes]({% link _docs_integrate/d ## On Success -- Returns the RelationshipAttributes as [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) that match the given `query` and can, thus, be used as `content` for a ThirdPartyRelationshipAttribute. +- Returns the RelationshipAttributes as [OwnRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) or [PeerRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) that match the given `query`. + [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) with `private` as `confidentiality` are never returned. ## On Failure diff --git a/_docs_use-cases/use-case-consumption-execute-an-identityattributequery.md b/_docs_use-cases/use-case-consumption-execute-an-identityattributequery.md index c4033a102..43e53383d 100644 --- a/_docs_use-cases/use-case-consumption-execute-an-identityattributequery.md +++ b/_docs_use-cases/use-case-consumption-execute-an-identityattributequery.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA8 + - id: RA16 - component: Runtime - layer: Consumption - facade: AttributesFacade @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Attributes/ExecuteIdentityAttributeQuery + - api_route_regex: POST /api/core/v1/Attributes/ExecuteIdentityAttributeQuery - published: default - link: use-case-consumption-execute-an-identityattributequery require: required_by: -api_route_regex: ^POST /api/v2/Attributes/ExecuteIdentityAttributeQuery$ +api_route_regex: ^POST /api/core/v1/Attributes/ExecuteIdentityAttributeQuery$ # End automatic generation --- @@ -42,8 +42,7 @@ api_route_regex: ^POST /api/v2/Attributes/ExecuteIdentityAttributeQuery$ {% include properties_list.html %} -This use case is intended to execute an incoming -[IdentityAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#identityattributequery) (e.g. of a ReadAttributeRequestItem) which returns a list of matching [Identity Attributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute). +This use case is intended to execute an incoming [IdentityAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#identityattributequery) (e.g. of a ReadAttributeRequestItem) which returns a list of matching [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) of the current Identity. ## Parameters @@ -51,7 +50,7 @@ This use case is intended to execute an incoming ## On Success -- Returns the `IdentityAttributes` as [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) that match the given query. +- Returns the IdentityAttributes as [OwnIdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) that match the given query. ## On Failure diff --git a/_docs_use-cases/use-case-consumption-execute-an-iqlquery.md b/_docs_use-cases/use-case-consumption-execute-an-iqlquery.md index 8624e684c..f789cf16b 100644 --- a/_docs_use-cases/use-case-consumption-execute-an-iqlquery.md +++ b/_docs_use-cases/use-case-consumption-execute-an-iqlquery.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA16 + - id: RA19 - component: Runtime - layer: Consumption - facade: AttributesFacade @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Attributes/ExecuteIQLQuery + - api_route_regex: POST /api/core/v1/Attributes/ExecuteIQLQuery - published: default - link: use-case-consumption-execute-an-iqlquery require: required_by: -api_route_regex: ^POST /api/v2/Attributes/ExecuteIQLQuery$ +api_route_regex: ^POST /api/core/v1/Attributes/ExecuteIQLQuery$ # End automatic generation --- @@ -50,7 +50,7 @@ This use case executes an IQLQuery which returns a list of matching [IdentityAtt ## On Success -- Returns the IdentityAttributes as [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) that match the given query. +- Returns the IdentityAttributes as [OwnIdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) that match the given query. ## On Failure diff --git a/_docs_use-cases/use-case-consumption-get-attribute.md b/_docs_use-cases/use-case-consumption-get-attribute.md index b4e8b5f66..aea1ba2a0 100644 --- a/_docs_use-cases/use-case-consumption-get-attribute.md +++ b/_docs_use-cases/use-case-consumption-get-attribute.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA5 + - id: RA7 - component: Runtime - layer: Consumption - facade: AttributesFacade @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Attributes/{id} + - api_route_regex: GET /api/core/v1/Attributes/{id} - published: default - link: use-case-consumption-get-attribute require: required_by: -api_route_regex: ^GET /api/v2/Attributes/{id}$ +api_route_regex: ^GET /api/core/v1/Attributes/{id}$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-get-attributelistener.md b/_docs_use-cases/use-case-consumption-get-attributelistener.md deleted file mode 100644 index 4f1ec6c1d..000000000 --- a/_docs_use-cases/use-case-consumption-get-attributelistener.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-get-attributelistener -published: true -title: "Get AttributeListener" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RAL2 - - component: Runtime - - layer: Consumption - - facade: AttributeListenersFacade - - function: getAttributeListener - - description: - - feature category: Attribute automation - - tech category: AttributeListeners - - status: PRERELEASE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: Runtime - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: - - published: - - link: use-case-consumption-get-attributelistener -require: -required_by: -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case is intended to retrieve an [Attribute Listener]({% link _docs_integrate/data-model-overview.md %}#localattributelistener) by its id. - -## Parameter - -- The unique `id` identifying the Attribute Listener. - -## On Success - -- Returns the [LocalAttributeListener]({% link _docs_integrate/data-model-overview.md %}#localattributelistener) that corresponds to the `id`. - -## On Failure - -- There is no such Attribute Listener. diff --git a/_docs_use-cases/use-case-consumption-get-attributes.md b/_docs_use-cases/use-case-consumption-get-attributes.md index a95cd6064..2d0e5790e 100644 --- a/_docs_use-cases/use-case-consumption-get-attributes.md +++ b/_docs_use-cases/use-case-consumption-get-attributes.md @@ -11,7 +11,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA2 + - id: RA8 - component: Runtime - layer: Consumption - facade: AttributesFacade @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Attributes + - api_route_regex: GET /api/core/v1/Attributes - published: default - link: use-case-consumption-get-attributes require: required_by: -api_route_regex: ^GET /api/v2/Attributes$ +api_route_regex: ^GET /api/core/v1/Attributes$ # End automatic generation --- @@ -49,15 +49,16 @@ This use case is intended to query [LocalAttributes]({% link _docs_integrate/dat ## Parameters - `query` allows to specify the conditions for the returned LocalAttributes. In detail, the following keys may be used: + - `@type` describes the LocalAttribute subtype. - `createdAt` describes the time when the LocalAttribute was created. - - `parentId` can be used to find the child Attributes of a [complex IdentityAttribute]({% link _docs_integrate/attribute-introduction.md %}#complex-identityattributes). - - The fields of `content` can be used to describe the queried Attribute (either an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) - or a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute)). + - The fields of `content` can be used to describe the queried Attribute (either an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) or a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute)). - `succeeds` and `succeededBy` give information about the [succession state]({% link _docs_integrate/update-attributes-by-succession.md %}) of the LocalAttribute. - - The fields of the `shareInfo` describe if the LocalAttribute is shared with a peer and specify its [LocalAttributeShareInfo]({% link _docs_integrate/data-model-overview.md %}#localattributeshareinfo). - - The fields of the `deletionInfo` describe the [LocalAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#localattributedeletioninfo) of a shared LocalAttribute. - - `isDefault` states whether a RepositoryAttribute is the default for its value type. -- If `onlyValid` is set to `true`, LocalAttributes that exceed their validity frame defined by `validFrom` and `validTo` will not be returned. + - The fields of the `deletionInfo` describe the [EmittedAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#emittedattributedeletioninfo) or [ReceivedAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#receivedattributedeletioninfo) of an emitted or a received LocalAttribute. + - `wasViewedAt` describes the time when the LocalAttribute was firstly viewed. + - `isDefault` states whether an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) is the default for its value type. + - `peer` is the `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that emitted or received the LocalAttribute. + - `sourceReference` describes the `id` of the [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest) or [LocalNotification]({% link _docs_integrate/data-model-overview.md %}#localnotification) a LocalAttribute was sent with or received in. + - `initialAttributePeer` is a [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute) property which describes the `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with whom the peer has the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) in which context the source RelationshipAttribute exists. - If `hideTechnical` is set to `true`, RelationshipAttributes with `isTechnical` `true` will not be returned. ## On Success diff --git a/_docs_use-cases/use-case-consumption-get-attributetagcollection.md b/_docs_use-cases/use-case-consumption-get-attributetagcollection.md index 7b520d73d..c9a7ec388 100644 --- a/_docs_use-cases/use-case-consumption-get-attributetagcollection.md +++ b/_docs_use-cases/use-case-consumption-get-attributetagcollection.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA30 + - id: RA15 - component: Runtime - layer: Consumption - facade: AttributesFacade @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Attributes/TagCollection + - api_route_regex: GET /api/core/v1/Attributes/TagCollection - published: default - link: use-case-consumption-get-attributetagcollection require: required_by: -api_route_regex: ^GET /api/v2/Attributes/TagCollection$ +api_route_regex: ^GET /api/core/v1/Attributes/TagCollection$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-get-forwardingdetails-for-attribute.md b/_docs_use-cases/use-case-consumption-get-forwardingdetails-for-attribute.md new file mode 100644 index 000000000..6fa32e542 --- /dev/null +++ b/_docs_use-cases/use-case-consumption-get-forwardingdetails-for-attribute.md @@ -0,0 +1,64 @@ +--- +# Start automatic generation +permalink: use-case-consumption-get-forwardingdetails-for-attribute +published: true +title: "Get ForwardingDetails for Attribute" +type: use-case +toc: true +sidebar: + - title: "Integrate enmeshed" + nav: "docs_integrate" +properties: + - id: RA12 + - component: Runtime + - layer: Consumption + - facade: AttributesFacade + - function: getForwardingDetailsForAttribute + - description: + - feature category: Cross-Identity Attribute sharing + - tech category: Attributes + - status: DONE + - documentation status: DONE + - comments: + - actor: Identity + - trigger: REST API + - precondition: + - result: + - priority: n/a + - complexity: n/a + - size: n/a + - created_at: + - changed_at: + - api_route_regex: GET /api/core/v1/Attributes/{id}/ForwardingDetails + - published: default + - link: use-case-consumption-get-forwardingdetails-for-attribute +require: +required_by: +api_route_regex: ^GET /api/core/v1/Attributes/{id}/ForwardingDetails$ +# End automatic generation +--- + +{{properties.description}} + +{% include properties_list.html %} + +This use case allows you to retrieve a list of [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) for a given [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). +Since only the LocalAttribute subtypes [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute), and [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) represent forwardable Attributes, AttributeForwardingDetails can only exist for such LocalAttributes. + +## Parameters + +- The `attributeId` belonging to a LocalAttribute you would like to retrieve AttributeForwardingDetails of. +- `query` allows to specify the conditions for the returned AttributeForwardingDetails. In detail, the following keys may be used: + - `peer` describes the Identity the LocalAttribute is shared with. + - `sourceReference` describes the `id` of the [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest) or [LocalNotification]({% link _docs_integrate/data-model-overview.md %}#localnotification) the LocalAttribute was sent with. + - `sharedAt` describes the time when the LocalAttribute was shared. + - The fields of the `deletionInfo` describe the [EmittedAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#emittedattributedeletioninfo) of the AttributeForwardingDetails. + +## On Success + +- Returns a list of AttributeForwardingDetails for the LocalAttribute belonging to the given `attributeId` that match the query. + +## On Failure + +- No AttributeForwardingDetails can be returned if the `attributeId` correlates to an unknown LocalAttribute. +- No AttributeForwardingDetails can be returned if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-get-identitymetadata.md b/_docs_use-cases/use-case-consumption-get-identitymetadata.md index c9c393198..d3471b6c3 100644 --- a/_docs_use-cases/use-case-consumption-get-identitymetadata.md +++ b/_docs_use-cases/use-case-consumption-get-identitymetadata.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/IdentityMetadata + - api_route_regex: GET /api/core/v1/IdentityMetadata - published: default - link: use-case-consumption-get-identitymetadata require: required_by: -api_route_regex: ^GET /api/v2/IdentityMetadata$ +api_route_regex: ^GET /api/core/v1/IdentityMetadata$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-get-incoming-request.md b/_docs_use-cases/use-case-consumption-get-incoming-request.md index f4a4877ee..a8e1da5b0 100644 --- a/_docs_use-cases/use-case-consumption-get-incoming-request.md +++ b/_docs_use-cases/use-case-consumption-get-incoming-request.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Requests/Incoming/{id} + - api_route_regex: GET /api/core/v1/Requests/Incoming/{id} - published: default - link: use-case-consumption-get-incoming-request require: required_by: -api_route_regex: ^GET /api/v2/Requests/Incoming/{id}$ +api_route_regex: ^GET /api/core/v1/Requests/Incoming/{id}$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-get-outgoing-request.md b/_docs_use-cases/use-case-consumption-get-outgoing-request.md index 8ec6fcf0b..2d329e2f3 100644 --- a/_docs_use-cases/use-case-consumption-get-outgoing-request.md +++ b/_docs_use-cases/use-case-consumption-get-outgoing-request.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Requests/Outgoing/{id} + - api_route_regex: GET /api/core/v1/Requests/Outgoing/{id} - published: default - link: use-case-consumption-get-outgoing-request require: required_by: -api_route_regex: ^GET /api/v2/Requests/Outgoing/{id}$ +api_route_regex: ^GET /api/core/v1/Requests/Outgoing/{id}$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-get-own-shared-attributes.md b/_docs_use-cases/use-case-consumption-get-own-attributes-shared-with-peer.md similarity index 51% rename from _docs_use-cases/use-case-consumption-get-own-shared-attributes.md rename to _docs_use-cases/use-case-consumption-get-own-attributes-shared-with-peer.md index fb893bbe6..ac0d77fce 100644 --- a/_docs_use-cases/use-case-consumption-get-own-shared-attributes.md +++ b/_docs_use-cases/use-case-consumption-get-own-attributes-shared-with-peer.md @@ -1,21 +1,21 @@ --- # Start automatic generation -permalink: use-case-consumption-get-own-shared-attributes +permalink: use-case-consumption-get-own-attributes-shared-with-peer redirect_from: - - /use-case-consumption-get-attributes-shared-to-peer + - /use-case-consumption-get-own-shared-attributes published: true -title: "Get own shared Attributes" +title: "Get own Attributes shared with peer" type: use-case toc: true sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA4 + - id: RA10 - component: Runtime - layer: Consumption - facade: AttributesFacade - - function: getOwnSharedAttributes + - function: getOwnAttributesSharedWithPeer - description: - feature category: Cross-Identity Attribute sharing - tech category: Attributes @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Attributes/Own/Shared/Identity + - api_route_regex: GET /api/core/v1/Attributes/Own/Shared/{peer} - published: default - - link: use-case-consumption-get-own-shared-attributes + - link: use-case-consumption-get-own-attributes-shared-with-peer require: required_by: -api_route_regex: ^GET /api/v2/Attributes/Own/Shared/Identity$ +api_route_regex: ^GET /api/core/v1/Attributes/Own/Shared/{peer}$ # End automatic generation --- @@ -44,7 +44,9 @@ api_route_regex: ^GET /api/v2/Attributes/Own/Shared/Identity$ {% include properties_list.html %} -This use case is intended to retrieve Attributes that the current Identity shared to a peer as [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute). The LocalAttributes can be specified using a complex query. +This use case is intended to retrieve own Attributes that the current Identity shared to a peer as [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute). +The LocalAttributes can be specified using a complex query. +Since only the LocalAttribute subtypes [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) and [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) represent own Attributes, only such LocalAttributes can be fetched through this use case. ## Parameters @@ -53,15 +55,17 @@ This use case is intended to retrieve Attributes that the current Identity share - `createdAt` describes the time when the LocalAttribute was created. - The fields of `content` can be used to describe the queried Attribute (either an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) or a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute)). - - The fields of the `shareInfo` describe if the LocalAttribute is shared with a peer and specify its [LocalAttributeShareInfo]({% link _docs_integrate/data-model-overview.md %}#localattributeshareinfo). - - The fields of the `deletionInfo` describe the [LocalAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#localattributedeletioninfo) of a shared LocalAttribute. -- If `onlyValid` is set to `true`, LocalAttributes that exceed their validity frame defined by `validFrom` and `validTo` will not be returned. + However, it is not possible to query by `content.owner`, because the owner always refers to the current Identity. + - `sourceReference` describes the `id` of the [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest) or [LocalNotification]({% link _docs_integrate/data-model-overview.md %}#localnotification) the LocalAttribute was sent with. + - `wasViewedAt` describes the time when the LocalAttribute was firstly viewed. + - `isDefault` states whether an OwnIdentityAttribute is the default for its value type. + - The fields of the `deletionInfo` describe the [EmittedAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#emittedattributedeletioninfo) of the LocalAttribute. - If `hideTechnical` is set to `true`, RelationshipAttributes with `isTechnical` `true` will not be returned. - Optionally, `onlyLatestVersions` can be disabled, such that in case of [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) all versions will be returned. ## On Success -- Returns a list of [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) shared to the peer that matches the query. +- Returns a list of [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) shared to the peer that match the query. ## On Failure diff --git a/_docs_use-cases/use-case-consumption-get-ownidentityattributes.md b/_docs_use-cases/use-case-consumption-get-ownidentityattributes.md new file mode 100644 index 000000000..467df9db7 --- /dev/null +++ b/_docs_use-cases/use-case-consumption-get-ownidentityattributes.md @@ -0,0 +1,66 @@ +--- +# Start automatic generation +permalink: use-case-consumption-get-ownidentityattributes +redirect_from: + - /use-case-consumption-get-repositoryattributes +published: true +title: "Get OwnIdentityAttributes" +type: use-case +toc: true +sidebar: + - title: "Integrate enmeshed" + nav: "docs_integrate" +properties: + - id: RA9 + - component: Runtime + - layer: Consumption + - facade: AttributesFacade + - function: getOwnIdentityAttributes + - description: Fetches all OwnIdentityAttributes + - feature category: Normalized Attributes + - tech category: Attributes + - status: DONE + - documentation status: DONE + - comments: + - actor: Identity + - trigger: REST API + - precondition: + - result: + - priority: n/a + - complexity: n/a + - size: n/a + - created_at: + - changed_at: + - api_route_regex: GET /api/core/v1/Attributes/Own/Identity + - published: default + - link: use-case-consumption-get-ownidentityattributes +require: +required_by: +api_route_regex: ^GET /api/core/v1/Attributes/Own/Identity$ +# End automatic generation +--- + +{{properties.description}} + +{% include properties_list.html %} + +This use case is intended to return all [OwnIdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute). +In case of [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}), by default only the latest version will be returned. +The OwnIdentityAttributes can be specified using a complex query. + +## Parameters + +- `query` allows to specify the conditions for the returned OwnIdentityAttributes. In detail, the following keys may be used: + - `createdAt` describes the time when the OwnIdentityAttribute was created. + - The fields `content.value.@type` and `content.tags` can be used to describe the queried [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute). + - `isDefault` states whether an OwnIdentityAttribute is the default for its value type. + - `wasViewedAt` describes the time when the OwnIdentityAttribute was firstly viewed. +- Optionally, `onlyLatestVersions` can be disabled, such that in case of [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) all versions will be returned. + +## On Success + +- An array of [OwnIdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) will be returned. It contains all OwnIdentityAttributes that match the query. + +## On Failure + +- No OwnIdentityAttributes can be returned if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-get-peer-shared-attributes.md b/_docs_use-cases/use-case-consumption-get-peer-attributes.md similarity index 50% rename from _docs_use-cases/use-case-consumption-get-peer-shared-attributes.md rename to _docs_use-cases/use-case-consumption-get-peer-attributes.md index b2eee445e..203713f46 100644 --- a/_docs_use-cases/use-case-consumption-get-peer-shared-attributes.md +++ b/_docs_use-cases/use-case-consumption-get-peer-attributes.md @@ -1,21 +1,21 @@ --- # Start automatic generation -permalink: use-case-consumption-get-peer-shared-attributes +permalink: use-case-consumption-get-peer-attributes redirect_from: - - /use-case-consumption-get-attributes-of-peer + - /use-case-consumption-get-peer-shared-attributes published: true -title: "Get peer shared Attributes" +title: "Get peer Attributes" type: use-case toc: true sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA3 + - id: RA11 - component: Runtime - layer: Consumption - facade: AttributesFacade - - function: getPeerSharedAttributes + - function: getPeerAttributes - description: - feature category: Cross-Identity Attribute sharing - tech category: Attributes @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Attributes/Peer/Shared/Identity + - api_route_regex: GET /api/core/v1/Attributes/Peer/{peer} - published: default - - link: use-case-consumption-get-peer-shared-attributes + - link: use-case-consumption-get-peer-attributes require: required_by: -api_route_regex: ^GET /api/v2/Attributes/Peer/Shared/Identity$ +api_route_regex: ^GET /api/core/v1/Attributes/Peer/{peer}$ # End automatic generation --- @@ -44,7 +44,9 @@ api_route_regex: ^GET /api/v2/Attributes/Peer/Shared/Identity$ {% include properties_list.html %} -This use case is intended to retrieve Attributes that a peer has shared with the current Identity as [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute). The LocalAttributes can be specified using a complex query. +This use case is intended to retrieve Attributes that a peer has shared with the current Identity as [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute). +The LocalAttributes can be specified using a complex query. +Since only the LocalAttribute subtypes [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute), [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute), and [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute) represent retrieved Attributes, only such LocalAttributes can be fetched through this use case. ## Parameters @@ -53,9 +55,11 @@ This use case is intended to retrieve Attributes that a peer has shared with the - `createdAt` describes the time when the LocalAttribute was created. - The fields of `content` can be used to describe the queried Attribute (either an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) or a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute)). - - The fields of the `shareInfo` describe if the LocalAttribute is shared with a peer and specify its [LocalAttributeShareInfo]({% link _docs_integrate/data-model-overview.md %}#localattributeshareinfo). - - The fields of the `deletionInfo` describe the [LocalAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#localattributedeletioninfo) of a shared LocalAttribute. -- If `onlyValid` is set to `true`, LocalAttributes that exceed their validity frame defined by `validFrom` and `validTo` will not be returned. + However, it is not possible to query by `content.owner`, because the owner always refers to the peer. + - `sourceReference` describes the `id` of the [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest) or [LocalNotification]({% link _docs_integrate/data-model-overview.md %}#localnotification) the LocalAttribute was received in. + - `initialAttributePeer` is a ThirdPartyRelationshipAttribute property which describes the `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with whom the peer has the [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) in which context the source RelationshipAttribute exists. + - `wasViewedAt` describes the time when the LocalAttribute was firstly viewed. + - The fields of the `deletionInfo` describe the [ReceivedAttributeDeletionInfo]({% link _docs_integrate/data-model-overview.md %}#receivedattributedeletioninfo) of the LocalAttribute. - If `hideTechnical` is set to `true`, RelationshipAttributes with `isTechnical` `true` will not be returned. - Optionally, `onlyLatestVersions` can be disabled, such that in case of [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) all versions will be returned. diff --git a/_docs_use-cases/use-case-consumption-get-repositoryattributes.md b/_docs_use-cases/use-case-consumption-get-repositoryattributes.md deleted file mode 100644 index 793154c66..000000000 --- a/_docs_use-cases/use-case-consumption-get-repositoryattributes.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-get-repositoryattributes -published: true -title: "Get RepositoryAttributes" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA22 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: getRepositoryAttributes - - description: Fetches all RepositoryAttributes - - feature category: Normalized Attributes - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: GET /api/v2/Attributes/Own/Repository - - published: default - - link: use-case-consumption-get-repositoryattributes -require: -required_by: -api_route_regex: ^GET /api/v2/Attributes/Own/Repository$ -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case is intended to return all RepositoryAttributes. -RepositoryAttributes are own [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) with an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) as `content` that are classified by an undefined `shareInfo`. -In case of [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}), by default only the latest version will be returned. -The LocalAttributes can be specified using a complex query. - -## Parameters - -- `query` allows to specify the conditions for the returned LocalAttributes. In detail, the following keys may be used: - - `createdAt` describes the time when the LocalAttribute was created. - - The fields of `content` can be used to describe the queried IdentityAttribute. - - `isDefault` states whether a RepositoryAttribute is the default for its value type. -- Optionally, `onlyLatestVersions` can be disabled, such that in case of [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) all versions will be returned. - -## On Success - -- An array of [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) will be returned. It contains all RepositoryAttributes that match the query. - -## On Failure - -- No LocalAttributes can be returned if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-get-shared-versions-of-an-attribute.md b/_docs_use-cases/use-case-consumption-get-shared-versions-of-an-attribute.md deleted file mode 100644 index 478b8c58f..000000000 --- a/_docs_use-cases/use-case-consumption-get-shared-versions-of-an-attribute.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-get-shared-versions-of-an-attribute -redirect_from: - - /use-case-consumption-get-shared-versions-of-a-repositoryattribute -published: true -title: "Get shared versions of an Attribute" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA27 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: getSharedVersionsOfAttribute - - description: - - feature category: Cross-Identity Attribute sharing - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: GET /api/v2/Attributes/{id}/Versions/Shared - - published: default - - link: use-case-consumption-get-shared-versions-of-an-attribute -require: -required_by: -api_route_regex: ^GET /api/v2/Attributes/{id}/Versions/Shared$ -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case allows you to retrieve a list of shared [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#lcoalattribute) for a given source Attribute. -In case of [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute) a list comprising of own shared IdentityAttributes for the specified RepositoryAttribute is returned. -In case of [RelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) the list contains ThirdPartyRelationshipAttributes you re-shared based on the specified RelationshipAttribute. - -## Parameters - -- The `attributeId` belonging to a LocalAttribute you would like to know all shared versions of -- Optionally the returned LocalAttributes can be limited to those shared with specific `peers`. -- `onlyLatestVersions` omits succeeded versions such that only the most recent version you shared per peer is returned. In detail, this means that if the `attributeId` given as input belongs to a LocalAttribute, that already has successors you also shared with the peer, only the shared copy corresponding to the most recently shared successor will be returned. By default this is set to be `true`. - -## On Success - -- A list of shared LocalAttribute versions of the source Attribute belonging to the `attributeId` given as input is returned. -- If `peers` were specified, the list is limited to the entries shared with those peers. -- If `onlyLatestVersions` is disabled, all versions will be returned, even if they already have successors. - -## On Failure - -- No LocalAttributes can be returned if the `attributeId` correlates to an unknown LocalAttribute. -- No LocalAttributes can be returned if an empty list is provided for `peers`. -- No LocalAttributes can be returned if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-get-versions-of-an-attribute.md b/_docs_use-cases/use-case-consumption-get-versions-of-an-attribute.md index 96e5201ee..97b6f90e4 100644 --- a/_docs_use-cases/use-case-consumption-get-versions-of-an-attribute.md +++ b/_docs_use-cases/use-case-consumption-get-versions-of-an-attribute.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA19 + - id: RA13 - component: Runtime - layer: Consumption - facade: AttributesFacade @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Attributes/{id}/Versions + - api_route_regex: GET /api/core/v1/Attributes/{id}/Versions - published: default - link: use-case-consumption-get-versions-of-an-attribute require: required_by: -api_route_regex: ^GET /api/v2/Attributes/{id}/Versions$ +api_route_regex: ^GET /api/core/v1/Attributes/{id}/Versions$ # End automatic generation --- @@ -47,15 +47,15 @@ This use case allows you to retrieve a list of all those versions of the success ## Parameters -- The `attributeId` belonging to a LocalAttribute you would like to know all versions of +- The `attributeId` belonging to a LocalAttribute you would like to know all versions of. ## On Success -- If the `attributeId` refers to a RepositoryAttribute, a list of all versions of this RepositoryAttribute will be returned. -- If the `attributeId` refers to an own shared IdentityAttribute, a list of all versions of that Attribute shared with the same peer will be returned. -- If the `attributeId` refers to a peer shared IdentityAttribute, a list of all versions of that Attribute received from the peer will be returned. -- If the `attributeId` refers to a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), a list of all versions of that RelationshipAttribute will be returned. +- If the `attributeId` refers to an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), a list of all versions of this OwnIdentityAttribute will be returned. +- If the `attributeId` refers to a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute), a list of all versions of that Attribute received from the peer will be returned. +- If the `attributeId` refers to an [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) or a [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute), a list of all versions of this OwnRelationshipAttribute or PeerRelationshipAttribute will be returned. +- If the `attributeId` refers to a [ThirdPartyRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattribute), a list of all versions of that Attribute received from the peer will be returned. ## On Failure -- No Attributes can be returned, if the `attributeId` doesn't belong to a valid LocalAttribute. +- No Attributes can be returned if the `attributeId` doesn't belong to a valid LocalAttribute. diff --git a/_docs_use-cases/use-case-consumption-get-versions-of-attribute-shared-with-peer.md b/_docs_use-cases/use-case-consumption-get-versions-of-attribute-shared-with-peer.md new file mode 100644 index 000000000..b142aecca --- /dev/null +++ b/_docs_use-cases/use-case-consumption-get-versions-of-attribute-shared-with-peer.md @@ -0,0 +1,67 @@ +--- +# Start automatic generation +permalink: use-case-consumption-get-versions-of-attribute-shared-with-peer +redirect_from: + - /use-case-consumption-get-shared-versions-of-an-attribute +published: true +title: "Get versions of Attribute shared with peer" +type: use-case +toc: true +sidebar: + - title: "Integrate enmeshed" + nav: "docs_integrate" +properties: + - id: RA14 + - component: Runtime + - layer: Consumption + - facade: AttributesFacade + - function: getVersionsOfAttributeSharedWithPeer + - description: + - feature category: Cross-Identity Attribute sharing + - tech category: Attributes + - status: DONE + - documentation status: DONE + - comments: + - actor: Identity + - trigger: REST API + - precondition: + - result: + - priority: n/a + - complexity: n/a + - size: n/a + - created_at: + - changed_at: + - api_route_regex: GET /api/core/v1/Attributes/{id}/Versions/Shared + - published: default + - link: use-case-consumption-get-versions-of-attribute-shared-with-peer +require: +required_by: +api_route_regex: ^GET /api/core/v1/Attributes/{id}/Versions/Shared$ +# End automatic generation +--- + +{{properties.description}} + +{% include properties_list.html %} + +This use case allows you to retrieve a list of [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) versions shared with a given peer. +Since only the LocalAttribute subtypes [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute), [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute), and [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) represent forwardable Attributes, a list of shared versions can only be retrieved for such LocalAttributes. + +## Parameters + +- The `attributeId` belonging to a LocalAttribute you would like to know the versions shared with a specific peer of. +- The returned LocalAttribute versions are limited to those shared with a specific `peer`. +- `onlyLatestVersions` omits succeeded versions such that only the most recent version you shared with the peer is returned. + In detail, this means that if the `attributeId` given as input belongs to a LocalAttribute that already has successors you also shared with the peer, only the most recently shared successor will be returned. + By default this is set to be `true`. + +## On Success + +- A list of versions of the LocalAttribute belonging to the given `attributeId` shared with the specified `peer` is returned. +- If `onlyLatestVersions` is disabled, all versions shared with the peer will be returned, even if they already have successors. + +## On Failure + +- No LocalAttributes can be returned if the `attributeId` correlates to an unknown LocalAttribute. +- No LocalAttributes can be returned if the `attributeId` doesn't belong to an OwnIdentityAttribute, an OwnRelationshipAttribute, or a PeerRelationshipAttribute. +- No LocalAttributes can be returned if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-notify-peer-about-ownidentityattribute-succession.md b/_docs_use-cases/use-case-consumption-notify-peer-about-ownidentityattribute-succession.md new file mode 100644 index 000000000..4f9e9d2f6 --- /dev/null +++ b/_docs_use-cases/use-case-consumption-notify-peer-about-ownidentityattribute-succession.md @@ -0,0 +1,73 @@ +--- +# Start automatic generation +permalink: use-case-consumption-notify-peer-about-ownidentityattribute-succession +redirect_from: + - /use-case-consumption-notify-peer-about-repositoryattribute-succession +published: true +title: "Notify peer about OwnIdentityAttribute succession" +type: use-case +toc: true +sidebar: + - title: "Integrate enmeshed" + nav: "docs_integrate" +properties: + - id: RA22 + - component: Runtime + - layer: Consumption + - facade: AttributesFacade + - function: notifyPeerAboutOwnIdentityAttributeSuccession + - description: + - feature category: Cross-Identity Attribute sharing + - tech category: Attributes + - status: DONE + - documentation status: DONE + - comments: + - actor: Identity + - trigger: REST API + - precondition: + - result: + - priority: n/a + - complexity: n/a + - size: n/a + - created_at: + - changed_at: + - api_route_regex: POST /api/core/v1/Attributes/{attributeId}/NotifyPeer + - published: default + - link: use-case-consumption-notify-peer-about-ownidentityattribute-succession +require: +required_by: +api_route_regex: ^POST /api/core/v1/Attributes/{attributeId}/NotifyPeer$ +# End automatic generation +--- + +{{properties.description}} + +{% include properties_list.html %} + +If you [succeeded an OwnIdentityAttribute]({% link _docs_use-cases/use-case-consumption-succeed-an-ownidentityattribute.md %}), whose previous version you [shared with a peer]({% link _docs_use-cases/use-case-consumption-share-an-ownidentityattribute.md %}), you can decide to inform the peer about the succession. +If you do so, the peer will receive a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) via [Message]({% link _docs_integrate/data-model-overview.md %}#message), which handles the succession of their [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute). +This means, a new version of the PeerIdentityAttribute will be created and the predecessor will be updated to link to this successor in its `succeededBy` property. +Note that it is possible to notify a peer about the succession of an OwnIdentityAttribute you already shared with them, even if you didn't inform them about every previous version. +In this case, the `succeeds` field of the newly created PeerIdentityAttribute will link to the latest shared version. +Moreover, it is also possible to notify a peer about the succession of an OwnIdentityAttribute if this in turn is already succeeded again, in case you didn't notify the peer about a newer version, yet. + +## Parameters + +- `attributeId` of the OwnIdentityAttribute successor. +- The address of the `peer`. + +## On Success + +- The response returns a `predecessor` and a `successor` OwnIdentityAttribute, as well as the `notificationId` of the Notification sent to the peer. +- The `predecessor` is the OwnIdentityAttribute that was shared with the peer most recently. +- The `successor` is the OwnIdentityAttribute successor about which the peer is to be informed. + +## On Failure + +- The response cannot be created if the `peer` is unknown. +- The response cannot be created if the `attributeId` doesn't belong to an OwnIdentityAttribute. +- The response cannot be created if you already notified the peer about the succession of the OwnIdentityAttribute. +- The response cannot be created if you already shared the OwnIdentityAttribute successor or a newer version with the peer. +- The response cannot be created if you haven't shared any version of the OwnIdentityAttribute with the peer before or if the [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) of the latest previous version you have shared with the peer before have `"DeletedByRecipient"` as `deletionInfo.deletionStatus`. + To initially share an OwnIdentityAttribute, use the [Share OwnIdentityAttribute use case]({% link _docs_use-cases/use-case-consumption-share-an-ownidentityattribute.md %}). +- The response cannot be created if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-notify-peer-about-repositoryattribute-succession.md b/_docs_use-cases/use-case-consumption-notify-peer-about-repositoryattribute-succession.md deleted file mode 100644 index 8e8557531..000000000 --- a/_docs_use-cases/use-case-consumption-notify-peer-about-repositoryattribute-succession.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-notify-peer-about-repositoryattribute-succession -published: true -title: "Notify peer about RepositoryAttribute succession" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA18 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: notifyPeerAboutRepositoryAttributeSuccession - - description: - - feature category: Cross-Identity Attribute sharing - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: POST /api/v2/Attributes/{attributeId}/NotifyPeer - - published: default - - link: use-case-consumption-notify-peer-about-repositoryattribute-succession -require: -required_by: -api_route_regex: ^POST /api/v2/Attributes/{attributeId}/NotifyPeer$ -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -If you [succeeded a RepositoryAttribute]({% link _docs_use-cases/use-case-consumption-succeed-a-repositoryattribute.md %}), whose previous version you [shared with a peer]({% link _docs_use-cases/use-case-consumption-share-a-repositoryattribute.md %}), you can decide to inform the peer about the succession. -If you do so, the peer will receive a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) via [Message]({% link _docs_integrate/data-model-overview.md %}#message), which handles the succession of their peer shared [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute). -Also, the associated own shared IdentityAttribute at your side will be succeeded, i.e. a new version of the [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) will be created and the predecessor will be updated to link to this successor in its `succeededBy` property. -Note that it is possible to notify a peer about the succession of an IdentityAttribute you already shared with them, even if you didn't inform them about every previous version. -In this case the `succeeds` field of the newly created LocalAttribute will link to the latest shared version. -Moreover, it is also possible to notify a peer about the succession of an IdentityAttribute, if this in turn is already succeeded again, in case you didn't notify the peer about a newer version, yet. - -## Parameters - -- `attributeId` of the succeeded RepositoryAttribute. -- The address of the `peer`. - -## On Success - -- The response returns a `predecessor` and a `successor` LocalAttribute, as well as the `notificationId` of the Notification sent to the peer. -- The `predecessor` is an updated version of the own shared IdentityAttribute that was shared with the peer most recently. It has the `succeededBy` field set to the `successor`'s `id`. -- The `successor` is a new own shared IdentityAttribute version with the `content` of the succeeded RepositoryAttribute. Its `succeeds` property links to the `predecessor`. - -## On Failure - -- The response cannot be created if the `peer` is unknown. -- The response cannot be created if the `attributeId` belongs to a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute). -- The response cannot be created if the `attributeId` belongs to an IdentityAttribute with a `shareInfo`. -- The response cannot be created if you already notified the peer about the succession of the Attribute. -- The response cannot be created if you already shared this or a newer version of the RepositoryAttribute with the peer. -- The response cannot be created if you haven't shared a version of the Attribute with the peer before. To initially share a RepositoryAttribute, use the [ShareRepositoryAttribute use-case]({% link _docs_use-cases/use-case-consumption-share-a-repositoryattribute.md %}). -- The response cannot be created if the latest previous version you shared has a `deletionInfo` with `deletionStatus` other than `"DeletionRequestRejected"`. -- The response cannot be created if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-query-attributelisteners.md b/_docs_use-cases/use-case-consumption-query-attributelisteners.md deleted file mode 100644 index 39981b319..000000000 --- a/_docs_use-cases/use-case-consumption-query-attributelisteners.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-query-attributelisteners -published: true -title: "Query AttributeListeners" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RAL1 - - component: Runtime - - layer: Consumption - - facade: AttributeListenersFacade - - function: getAttributeListeners - - description: - - feature category: Attribute automation - - tech category: AttributeListeners - - status: PRERELEASE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: Runtime - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: - - published: - - link: use-case-consumption-query-attributelisteners -require: -required_by: -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case is intended to query all [Attribute Listeners]({% link _docs_integrate/data-model-overview.md %}#localattributelistener) -based on a query. - -## Parameter - -- The `query` optionally describes the searched Attribute Listeners. If no query is given all Attribute Listeners are returned. - -## On Success - -- Returns a list of [LocalAttributeListeners]({% link _docs_integrate/data-model-overview.md %}#localattributelistener) that match the query. - -## On Failure - -- The parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-query-incoming-requests.md b/_docs_use-cases/use-case-consumption-query-incoming-requests.md index 93b18b035..0be09f86d 100644 --- a/_docs_use-cases/use-case-consumption-query-incoming-requests.md +++ b/_docs_use-cases/use-case-consumption-query-incoming-requests.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Requests/incoming + - api_route_regex: GET /api/core/v1/Requests/incoming - published: default - link: use-case-consumption-query-incoming-requests require: required_by: -api_route_regex: ^GET /api/v2/Requests/incoming$ +api_route_regex: ^GET /api/core/v1/Requests/incoming$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-query-outgoing-requests.md b/_docs_use-cases/use-case-consumption-query-outgoing-requests.md index 30a21beb1..90d079394 100644 --- a/_docs_use-cases/use-case-consumption-query-outgoing-requests.md +++ b/_docs_use-cases/use-case-consumption-query-outgoing-requests.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Requests/Outgoing + - api_route_regex: GET /api/core/v1/Requests/Outgoing - published: default - link: use-case-consumption-query-outgoing-requests require: required_by: -api_route_regex: ^GET /api/v2/Requests/Outgoing$ +api_route_regex: ^GET /api/core/v1/Requests/Outgoing$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-reject-incoming-request.md b/_docs_use-cases/use-case-consumption-reject-incoming-request.md index 7bf5d5ff5..f2caab9e7 100644 --- a/_docs_use-cases/use-case-consumption-reject-incoming-request.md +++ b/_docs_use-cases/use-case-consumption-reject-incoming-request.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Requests/Incoming/{id}/Reject + - api_route_regex: PUT /api/core/v1/Requests/Incoming/{id}/Reject - published: default - link: use-case-consumption-reject-incoming-request require: required_by: -api_route_regex: ^PUT /api/v2/Requests/Incoming/{id}/Reject$ +api_route_regex: ^PUT /api/core/v1/Requests/Incoming/{id}/Reject$ # End automatic generation --- @@ -49,8 +49,7 @@ It is advised to [check if the incoming Request can be rejected](/use-case-consu ## Parameters - The `id` of the incoming LocalRequest. -- The decision for each individual [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitem) - expressed as the appropriate [Parameters defined in the Data Model]({% link _docs_integrate/data-model-overview.md %}deciderequestitemparameters). +- The decision for each individual [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitem) expressed as the appropriate [Parameters defined in the Data Model]({% link _docs_integrate/data-model-overview.md %}deciderequestitemparameters). ## On Success diff --git a/_docs_use-cases/use-case-consumption-share-a-repositoryattribute.md b/_docs_use-cases/use-case-consumption-share-a-repositoryattribute.md deleted file mode 100644 index 63610b8d3..000000000 --- a/_docs_use-cases/use-case-consumption-share-a-repositoryattribute.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-share-a-repositoryattribute -published: true -title: "Share a RepositoryAttribute" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA13 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: shareRepositoryAttribute - - description: - - feature category: Cross-Identity Attribute sharing - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: - - precondition: - - result: - - priority: - - complexity: - - size: - - created_at: - - changed_at: - - api_route_regex: - - published: default - - link: use-case-consumption-share-a-repositoryattribute -require: -required_by: -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -If you wish to share one of your private [IdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#identityattribute), called RepositoryAttributes, with a peer, this use case allows you to do so. -Internally, a [Request]({% link _docs_integrate/data-model-overview.md %}#request) with a [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) will be created and will be sent via [Message]({% link _docs_integrate/data-model-overview.md %}#message) to the peer. -Assuming your peer accepts the Request, at their side a peer shared IdentityAttribute will be created. -The corresponding [Response]({% link _docs_integrate/data-model-overview.md %}#response) informs you about their acceptance and creates a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) with a copy of the RepositoryAttribute's `content` you shared. -This own shared IdentityAttribute copy, however, in addition has a defined `shareInfo` property. -It stores information about the `peer` you shared the Attribute with, the `id` of the original RepositoryAttribute in the field `sourceAttribute`, and a reference to the Request used to share the Attribute. -Note that the own shared IdentityAttribute at your side and the peer shared IdentityAttribute at your peer's side are identical, except for the value in the `shareInfo.peer` field: on your side it will have the peer's address and on the peer's side it will have the `address` of your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). -Please note further, that this use case is meant to be used to share a version of a RepositoryAttribute for the first time. -If you have already shared another version of a succeeded Attribute with the peer and you want to let them know about the changes to its `value`, use the [NotifyPeerAboutRepositoryAttributeSuccession use-case]({% link _docs_use-cases/use-case-consumption-notify-peer-about-repositoryattribute-succession.md %}). - -## Parameters - -- The `attributeId` of your RepositoryAttribute. -- The address of the `peer`. -- Optionally `requestMetadata` as described in the [data model]({% link _docs_integrate/data-model-overview.md %}#request), except for the `id` and `items`, which are handled automatically. - -## On Success - -- The [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest) is returned, that is associated with the Request which was sent to the peer. - -## On Failure - -- The Request cannot be created if the `peer` is unknown. -- The Request cannot be created if the `attributeId` belongs to a RelationshipAttribute. -- The Request cannot be created if the `attributeId` belongs to an IdentityAttribute with a `shareInfo`. -- The Request cannot be created if the Attribute has already been shared with the peer and the own shared IdentityAttribute doesn't have `"DeletedByPeer"` or `"ToBeDeletedByPeer"` as `deletionInfo.deletionStatus`. -- The Request cannot be created if another version of the Attribute regarding succession has already been shared with the peer, unless the latest shared version has `"DeletedByPeer"` or `"ToBeDeletedByPeer"` as `deletionInfo.deletionStatus`. -- The Request cannot be created if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-share-an-ownidentityattribute.md b/_docs_use-cases/use-case-consumption-share-an-ownidentityattribute.md new file mode 100644 index 000000000..5ab03d938 --- /dev/null +++ b/_docs_use-cases/use-case-consumption-share-an-ownidentityattribute.md @@ -0,0 +1,71 @@ +--- +# Start automatic generation +permalink: use-case-consumption-share-an-ownidentityattribute +redirect_from: + - /use-case-consumption-share-a-repositoryattribute +published: true +title: "Share an OwnIdentityAttribute" +type: use-case +toc: true +sidebar: + - title: "Integrate enmeshed" + nav: "docs_integrate" +properties: + - id: RA3 + - component: Runtime + - layer: Consumption + - facade: AttributesFacade + - function: shareOwnIdentityAttribute + - description: + - feature category: Cross-Identity Attribute sharing + - tech category: Attributes + - status: DONE + - documentation status: DONE + - comments: + - actor: Identity + - trigger: + - precondition: + - result: + - priority: + - complexity: + - size: + - created_at: + - changed_at: + - api_route_regex: + - published: default + - link: use-case-consumption-share-an-ownidentityattribute +require: +required_by: +# End automatic generation +--- + +{{properties.description}} + +{% include properties_list.html %} + +If you wish to share one of your [OwnIdentityAttributes]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) with a peer, this use case allows you to do so. +Internally, a [Request]({% link _docs_integrate/data-model-overview.md %}#request) with a [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem) will be created and will be sent via [Message]({% link _docs_integrate/data-model-overview.md %}#message) to the peer. +Assuming your peer accepts the Request, at their side a [PeerIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#peeridentityattribute) will be created. +The corresponding [Response]({% link _docs_integrate/data-model-overview.md %}#response) informs you about their acceptance and creates [AttributeForwardingDetails]({% link _docs_integrate/data-model-overview.md %}#attributeforwardingdetails) associated with the OwnIdentityAttribute. + +Please note further, that this use case is meant to be used to share a version of an OwnIdentityAttribute for the first time. +If you have already shared another version of a succeeded Attribute with the peer and you want to let them know about the changes to its `value`, use the [Notify peer about OwnIdentityAttribute succession use case]({% link _docs_use-cases/use-case-consumption-notify-peer-about-ownidentityattribute-succession.md %}). +{: .notice--info} + +## Parameters + +- The `attributeId` of your OwnIdentityAttribute. +- The address of the `peer`. +- Optionally `requestMetadata` as described in the [data model]({% link _docs_integrate/data-model-overview.md %}#request), except for the `id` and `items`, which are handled automatically. + +## On Success + +- The [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest) is returned, that is associated with the Request which was sent to the peer. + +## On Failure + +- The Request cannot be created if the `peer` is unknown. +- The Request cannot be created if the `attributeId` doesn't belong to an OwnIdentityAttribute. +- The Request cannot be created if the OwnIdentityAttribute has already been shared with the peer and it doesn't have `"DeletedByRecipient"` or `"ToBeDeletedByRecipient"` as `deletionInfo.deletionStatus`. +- The Request cannot be created if another version of the OwnIdentityAttribute regarding succession has already been shared with the peer, unless the latest shared version has `"DeletedByRecipient"` as `deletionInfo.deletionStatus`. +- The Request cannot be created if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-succeed-a-relationshipattribute-and-notify-peer.md b/_docs_use-cases/use-case-consumption-succeed-a-relationshipattribute-and-notify-peer.md index f64bac91a..fa81362b4 100644 --- a/_docs_use-cases/use-case-consumption-succeed-a-relationshipattribute-and-notify-peer.md +++ b/_docs_use-cases/use-case-consumption-succeed-a-relationshipattribute-and-notify-peer.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA17 + - id: RA23 - component: Runtime - layer: Consumption - facade: AttributesFacade @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Attributes/{predecessorId}/Succeed + - api_route_regex: POST /api/core/v1/Attributes/{predecessorId}/Succeed - published: default - link: use-case-consumption-succeed-a-relationshipattribute-and-notify-peer require: required_by: -api_route_regex: ^POST /api/v2/Attributes/{predecessorId}/Succeed$ +api_route_regex: ^POST /api/core/v1/Attributes/{predecessorId}/Succeed$ # End automatic generation --- @@ -43,26 +43,27 @@ api_route_regex: ^POST /api/v2/Attributes/{predecessorId}/Succeed$ {% include properties_list.html %} This use case allows the owner to update a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute), while automatically handling the coherent versioning at both your and your peer's side. -[Succeeding an own RelationshipAttribute]({% link _docs_integrate/update-attributes-by-succession.md %}#succeeding-own-relationshipattributes), a new [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) with the updated `content` will be created at your side. +[Succeeding an OwnRelationshipAttribute]({% link _docs_integrate/update-attributes-by-succession.md %}#succeeding-own-relationshipattributes), a new [OwnRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#ownrelationshipattribute) with the updated `content` will be created at your side. In its `succeeds` property it links to the predecessing version, which in turn is also updated and links to the newly created version in its `succeededBy` property. Thus, a doubly linked list is established, ensuring every version to have not more that one predecessor or successor. Once the succession at your side is completed, a [Notification]({% link _docs_integrate/data-model-overview.md %}#notification) is sent automatically to your peer. -It triggers the succession of their peer shared RelationshipAttribute in the same manner as described above, such that both your succession chains match. +It triggers the succession of their [PeerRelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#peerrelationshipattribute) in the same manner as described above, such that both your succession chains match. ## Parameters -- `predecessorId`: the `id` of the LocalAttribute with the RelationshipAttribute `content` you want to succeed -- The updated `successorContent` limited to the `value`, `validFrom` and `validTo` properties of a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) that may be changed by a succession +- `predecessorId` is the `id` of the OwnRelationshipAttribute. +- The updated `successorContent` limited to the `value` property of a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) that may be changed by a succession. ## On Success -- The response returns a `predecessor` and a `successor` LocalAttribute, as well as the `notificationId` of the Notification sent to the peer. -- The `predecessor` is an updated version of the own shared RelationshipAttribute, having the `succeededBy` field set to the `successor`'s `id`. -- The `successor` is a new own shared RelationshipAttribute version with the specified `successorContent`. Its `succeeds` property links to the `predecessor`. +- The response returns a `predecessor` and a `successor` OwnRelationshipAttribute, as well as the `notificationId` of the Notification sent to the peer. +- The `predecessor` is an updated version of the OwnRelationshipAttribute, having the `succeededBy` field set to the `id` of the `successor`. +- The `successor` is a new OwnRelationshipAttribute version with the specified `successorContent`. + Its `succeeds` property links to the `predecessor`. ## On Failure -- The response cannot be created if the `predecessorId` doesn't belong to a valid own LocalAttribute with RelationshipAttribute `content`. -- The response cannot be created if the LocalAttribute belonging to the `predecessorId` already has a successor. -- The response cannot be created if the LocalAttribute belonging to the `predecessorId` has a `deletionInfo` with `deletionStatus` other than `"DeletionRequestRejected"`. +- The response cannot be created if the `predecessorId` doesn't belong to a valid OwnRelationshipAttribute. +- The response cannot be created if the OwnRelationshipAttribute belonging to the `predecessorId` already has a successor. +- The response cannot be created if the OwnRelationshipAttribute belonging to the `predecessorId` has a `deletionInfo` with `"DeletedByRecipient"` as `deletionInfo.deletionStatus`. - The response cannot be created if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-succeed-a-repositoryattribute.md b/_docs_use-cases/use-case-consumption-succeed-a-repositoryattribute.md deleted file mode 100644 index 300e3aac9..000000000 --- a/_docs_use-cases/use-case-consumption-succeed-a-repositoryattribute.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-consumption-succeed-a-repositoryattribute -published: true -title: "Succeed a RepositoryAttribute" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RA11 - - component: Runtime - - layer: Consumption - - facade: AttributesFacade - - function: succeedRepositoryAttribute - - description: - - feature category: Cross-Identity Attribute sharing - - tech category: Attributes - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: REST API - - precondition: - - result: - - priority: HIGH - - complexity: MEDIUM - - size: M - - created_at: - - changed_at: - - api_route_regex: POST /api/v2/Attributes/{predecessorId}/Succeed - - published: default - - link: use-case-consumption-succeed-a-repositoryattribute -require: -required_by: -api_route_regex: ^POST /api/v2/Attributes/{predecessorId}/Succeed$ -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -If the `value` of a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) changes, this can be replicated in enmeshed with this use case. -It allows you to [update the `content`]({% link _docs_integrate/update-attributes-by-succession.md %}) and keeps a coherent history of all versions by establishing a doubly linked list, using the [LocalAttribute's]({% link _docs_integrate/data-model-overview.md %}#localattribute) parameters `succeeds` and `succeededBy`. -Hence, every LocalAttribute may have exactly one predecessor and one successor. -In case you shared the preceeding version of the RepositoryAttribute, the corresponding own shared IdentityAttribute copy will only be succeeded, if you decide to [notify the peer]({% link _docs_use-cases/use-case-consumption-notify-peer-about-repositoryattribute-succession.md %}) of the respective shared IdentityAttribute about the succession. - -## Parameters - -- `predecessorId`: the `id` of the RepositoryAttribute you want to succeed -- The `successorContent` according to the parameters of an IdentityAttribute as described in the [data model]({% link _docs_integrate/data-model-overview.md %}#identityattribute), except for the `owner`, which is automatically set to the `address` of your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). - -## On Success - -- The response returns a `predecessor` and a `successor` LocalAttribute. -- The `predecessor` is an updated version of the RepositoryAttribute belonging to `predecessorId`, having the `succeededBy` field set to the `successor`'s `id`. -- The `successor` is a new RepositoryAttribute with the updated `successorContent`. Its `succeeds` property links to the `predecessor`. - -## On Failure - -- The response cannot be created, if the `predecessorId` belongs to a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute). -- The response cannot be created, if the `predecessorId` belongs to an IdentityAttribute with a `shareInfo`. -- The response cannot be created, if the LocalAttribute already has a successor. -- The response cannot be created, if the `successorContent` contains invalid changes, e.g. of the value type. -- The response cannot be created, if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-succeed-an-ownidentityattribute.md b/_docs_use-cases/use-case-consumption-succeed-an-ownidentityattribute.md new file mode 100644 index 000000000..1a9588c6b --- /dev/null +++ b/_docs_use-cases/use-case-consumption-succeed-an-ownidentityattribute.md @@ -0,0 +1,69 @@ +--- +# Start automatic generation +permalink: use-case-consumption-succeed-an-ownidentityattribute +redirect_from: + - /use-case-consumption-succeed-a-repositoryattribute +published: true +title: "Succeed an OwnIdentityAttribute" +type: use-case +toc: true +sidebar: + - title: "Integrate enmeshed" + nav: "docs_integrate" +properties: + - id: RA21 + - component: Runtime + - layer: Consumption + - facade: AttributesFacade + - function: succeedOwnIdentityAttribute + - description: + - feature category: Cross-Identity Attribute sharing + - tech category: Attributes + - status: DONE + - documentation status: DONE + - comments: + - actor: Identity + - trigger: REST API + - precondition: + - result: + - priority: HIGH + - complexity: MEDIUM + - size: M + - created_at: + - changed_at: + - api_route_regex: POST /api/core/v1/Attributes/{predecessorId}/Succeed + - published: default + - link: use-case-consumption-succeed-an-ownidentityattribute +require: +required_by: +api_route_regex: ^POST /api/core/v1/Attributes/{predecessorId}/Succeed$ +# End automatic generation +--- + +{{properties.description}} + +{% include properties_list.html %} + +If the `content.value` of an [OwnIdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) changes, this can be replicated in enmeshed with this use case. +It allows you to [update the `content`]({% link _docs_integrate/update-attributes-by-succession.md %}) and keeps a coherent history of all versions by establishing a doubly linked list, using the [OwnIdentityAttribute's]({% link _docs_integrate/data-model-overview.md %}#ownidentityattribute) parameters `succeeds` and `succeededBy`. +Hence, every OwnIdentityAttribute may have exactly one predecessor and one successor. +In case you shared the preceeding version of an OwnIdentityAttribute, the corresponding successor will only be shared if you decide to [notify the peer]({% link _docs_use-cases/use-case-consumption-notify-peer-about-ownidentityattribute-succession.md %}) about the succession. + +## Parameters + +- `predecessorId` describes the `id` of the OwnIdentityAttribute you want to succeed. +- The `successorContent` according to the parameters of an IdentityAttribute as described in the [data model]({% link _docs_integrate/data-model-overview.md %}#identityattribute), except for the `owner`, which is automatically set to the `address` of your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). + +## On Success + +- The response returns a `predecessor` and a `successor` OwnIdentityAttribute. +- The `predecessor` is an updated version of the OwnIdentityAttribute belonging to `predecessorId`, having the `succeededBy` field set to the `id` of the `successor`. +- The `successor` is a new OwnIdentityAttribute with the updated `successorContent`. + Its `succeeds` property links to the `predecessor`. + +## On Failure + +- The response cannot be created if the `predecessorId` doesn't belong to an OwnIdentityAttribute. +- The response cannot be created if the OwnIdentityAttribute already has a successor. +- The response cannot be created if the `successorContent` contains invalid changes, e.g. of the [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) `value.@type`. +- The response cannot be created if the parameters are malformed. diff --git a/_docs_use-cases/use-case-consumption-upsert-identitymetadata.md b/_docs_use-cases/use-case-consumption-upsert-identitymetadata.md index b36667ee2..ce68c1144 100644 --- a/_docs_use-cases/use-case-consumption-upsert-identitymetadata.md +++ b/_docs_use-cases/use-case-consumption-upsert-identitymetadata.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: PUT /api/v2/IdentityMetadata + - api_route_regex: PUT /api/core/v1/IdentityMetadata - published: default - link: use-case-consumption-upsert-identitymetadata require: required_by: -api_route_regex: ^PUT /api/v2/IdentityMetadata$ +api_route_regex: ^PUT /api/core/v1/IdentityMetadata$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-consumption-validate-an-iqlquery.md b/_docs_use-cases/use-case-consumption-validate-an-iqlquery.md index d55dda596..f13d3707f 100644 --- a/_docs_use-cases/use-case-consumption-validate-an-iqlquery.md +++ b/_docs_use-cases/use-case-consumption-validate-an-iqlquery.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RA26 + - id: RA20 - component: Runtime - layer: Consumption - facade: AttributesFacade @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Attributes/ValidateIQLQuery + - api_route_regex: POST /api/core/v1/Attributes/ValidateIQLQuery - published: default - link: use-case-consumption-validate-an-iqlquery require: required_by: -api_route_regex: ^POST /api/v2/Attributes/ValidateIQLQuery$ +api_route_regex: ^POST /api/core/v1/Attributes/ValidateIQLQuery$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-device-create-qr-code-for-file.md b/_docs_use-cases/use-case-device-create-qr-code-for-file.md index 7f860fe1a..d76d9f6ff 100644 --- a/_docs_use-cases/use-case-device-create-qr-code-for-file.md +++ b/_docs_use-cases/use-case-device-create-qr-code-for-file.md @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Files/{idOrReference} + - api_route_regex: GET /api/core/v1/Files/{idOrReference} - published: default - link: use-case-device-create-qr-code-for-file require: required_by: -api_route_regex: ^GET /api/v2/Files/{idOrReference}$ +api_route_regex: ^GET /api/core/v1/Files/{idOrReference}$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-device-create-token-qr-code-for-file.md b/_docs_use-cases/use-case-device-create-token-qr-code-for-file.md index fbddadc7c..b6515c763 100644 --- a/_docs_use-cases/use-case-device-create-token-qr-code-for-file.md +++ b/_docs_use-cases/use-case-device-create-token-qr-code-for-file.md @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Files/{id}/Token + - api_route_regex: POST /api/core/v1/Files/{id}/Token - published: default - link: use-case-device-create-token-qr-code-for-file require: required_by: -api_route_regex: ^POST /api/v2/Files/{id}/Token$ +api_route_regex: ^POST /api/core/v1/Files/{id}/Token$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-device-create-token-qr-code-for-own-relationshiptemplate.md b/_docs_use-cases/use-case-device-create-token-qr-code-for-own-relationshiptemplate.md index 49280382a..5402726fc 100644 --- a/_docs_use-cases/use-case-device-create-token-qr-code-for-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-device-create-token-qr-code-for-own-relationshiptemplate.md @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/RelationshipTemplates/Own/{id}/Token + - api_route_regex: POST /api/core/v1/RelationshipTemplates/Own/{id}/Token - published: default - link: use-case-device-create-token-qr-code-for-own-relationshiptemplate require: required_by: -api_route_regex: ^POST /api/v2/RelationshipTemplates/Own/{id}/Token$ +api_route_regex: ^POST /api/core/v1/RelationshipTemplates/Own/{id}/Token$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-accept-relationship-reactivation.md b/_docs_use-cases/use-case-transport-accept-relationship-reactivation.md index 02ec10da8..f21bb907e 100644 --- a/_docs_use-cases/use-case-transport-accept-relationship-reactivation.md +++ b/_docs_use-cases/use-case-transport-accept-relationship-reactivation.md @@ -29,12 +29,12 @@ properties: - size: - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Relationships/{id}/Reactivate/Accept + - api_route_regex: PUT /api/core/v1/Relationships/{id}/Reactivate/Accept - published: default - link: use-case-transport-accept-relationship-reactivation require: required_by: -api_route_regex: ^PUT /api/v2/Relationships/{id}/Reactivate/Accept$ +api_route_regex: ^PUT /api/core/v1/Relationships/{id}/Reactivate/Accept$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-accept-relationship.md b/_docs_use-cases/use-case-transport-accept-relationship.md index dc6ad9472..4ba08ed0d 100644 --- a/_docs_use-cases/use-case-transport-accept-relationship.md +++ b/_docs_use-cases/use-case-transport-accept-relationship.md @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Relationships/{id}/Accept + - api_route_regex: PUT /api/core/v1/Relationships/{id}/Accept - published: default - link: use-case-transport-accept-relationship require: required_by: -api_route_regex: ^PUT /api/v2/Relationships/{id}/Accept$ +api_route_regex: ^PUT /api/core/v1/Relationships/{id}/Accept$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md b/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md index 2df21a849..50cb4717c 100644 --- a/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md @@ -14,7 +14,7 @@ properties: - layer: Transport - facade: IdentityDeletionProcessFacade - function: cancelIdentityDeletionProcess - - description: Cancel an IdentityDeletionProcess that has status 'Approved' within grace period + - description: Cancel an IdentityDeletionProcess that has status 'Active' within grace period - feature category: Identity handling - tech category: IdentityDeletionProcesses - status: DONE @@ -41,19 +41,19 @@ required_by: {% include properties_list.html %} -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`. +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 `"Active"` 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. +This use case allows you to cancel an active IdentityDeletionProcess for your Identity within the grace period. This use case can be utilized by using the [Identity deletion cancellation command]({% link _docs_operate/connector-cli-operations.md %}#identity-deletion-cancellation-command) of the [Connector CLI operations]({% link _docs_operate/connector-cli-operations.md %}), but not by using the [Connector REST API]({% link _docs_integrate/access-the-connector.md %}#hosted-api-tooling-by-the-development-connector). {: .notice--info} ## On Success -- Changes the `status` of the IdentityDeletionProcess from `"Approved"` to `"Cancelled"`. +- Changes the `status` of the IdentityDeletionProcess from `"Active"` to `"Cancelled"`. - Returns the cancelled IdentityDeletionProcess. ## On Failure -- No IdentityDeletionProcess can be cancelled if none has `"Approved"` as `status` for this Identity. +- No IdentityDeletionProcess can be cancelled if none has `"Active"` as `status` for this Identity. diff --git a/_docs_use-cases/use-case-transport-check-if-relationship-can-be-created.md b/_docs_use-cases/use-case-transport-check-if-relationship-can-be-created.md index e47715222..14c1a3c1b 100644 --- a/_docs_use-cases/use-case-transport-check-if-relationship-can-be-created.md +++ b/_docs_use-cases/use-case-transport-check-if-relationship-can-be-created.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Relationships/CanCreate + - api_route_regex: PUT /api/core/v1/Relationships/CanCreate - published: default - link: use-case-transport-check-if-relationship-can-be-created require: required_by: -api_route_regex: ^PUT /api/v2/Relationships/CanCreate$ +api_route_regex: ^PUT /api/core/v1/Relationships/CanCreate$ # End automatic generation --- @@ -57,7 +57,7 @@ If the [Request Module]({% link _docs_explore/61-runtime.md %}#request-module) i - Returns a `result` that indicates if a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) can be created with the given parameters. - If the `isSuccess` property of the `result` has the value `true`, a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) can currently be created to the creator of the RelationshipTemplate. This would then initially have `"Pending"` as `status` until the creator of the RelationshipTemplate [accepts the Relationship]({% link _docs_use-cases/use-case-transport-accept-relationship.md %}). - If the `isSuccess` property of the `result` has the value `false`, no [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) can currently be created to the creator of the RelationshipTemplate. This can have various causes, for example: - - The `templateId` does not resolve to a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or the associated RelationshipTemplate was not cached correctly.<br> + - The `templateId` does not resolve to a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate).<br> - The [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) has already expired, which means that the timestamp specified in its `expiresAt` property has been exceeded.<br> - A [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"`, `"Active"`, `"Terminated"` or `"DeletionProposed"` as `status` already exists to the creator of the RelationshipTemplate. In particular, the initiation of a new Relationship is prevented if the potential initiator has already [decomposed the former Relationship]({% link _docs_integrate/terminate-relationships.md %}#decompose-a-relationship) to the RelationshipTemplate's creator, but the creator of the RelationshipTemplate has not yet decomposed it and still has the former Relationship with `"DeletionProposed"` as `status`.<br> - The [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) of the creator of the RelationshipTemplate is in deletion or has already been deleted.<br> diff --git a/_docs_use-cases/use-case-transport-create-challenge.md b/_docs_use-cases/use-case-transport-create-challenge.md index bf6aabe8f..4a793c6d2 100644 --- a/_docs_use-cases/use-case-transport-create-challenge.md +++ b/_docs_use-cases/use-case-transport-create-challenge.md @@ -29,11 +29,11 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Challenges + - api_route_regex: POST /api/core/v1/Challenges - published: - link: use-case-transport-create-challenge require: required_by: -api_route_regex: ^POST /api/v2/Challenges$ +api_route_regex: ^POST /api/core/v1/Challenges$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-create-device-onboarding-token.md b/_docs_use-cases/use-case-transport-create-device-onboarding-token.md deleted file mode 100644 index 56d8bc553..000000000 --- a/_docs_use-cases/use-case-transport-create-device-onboarding-token.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-transport-create-device-onboarding-token -published: true -title: "Create Device Onboarding Token" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RD5 - - component: Runtime - - layer: Transport - - facade: DevicesFacade - - function: createDeviceOnboardingToken - - description: - - feature category: Multi-device - - tech category: Devices - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: Runtime - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: - - published: default - - link: use-case-transport-create-device-onboarding-token -require: -required_by: -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case is deprecated and will be removed in the next major version. Please use the use case [Fill Device onboarding Token with new Device](use-case-transport-fill-device-onboarding-token-with-new-device) instead. -{: .notice--warning} - -This use case retrieves the [Token]({% link _docs_integrate/data-model-overview.md %}#token) of a not yet onboarded Device that corresponds to the given Device `id` in order to onboard the Device to the Identity. - -## Parameters - -- `id` of the Device. -- `expiresAt` is the ISODateTime the Token expires at. -- `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. - -## On Success - -- Returns the Token of the Device to onboard. - -## On Failure - -- The Device was already onboarded. -- In case of password protection of the Token, a `passwordProtection.password` that does not consist of 4 to 16 digits was specified, but the value of `passwordProtection.passwordIsPin` was nevertheless set to `true`. diff --git a/_docs_use-cases/use-case-transport-create-device.md b/_docs_use-cases/use-case-transport-create-device.md deleted file mode 100644 index e5338b236..000000000 --- a/_docs_use-cases/use-case-transport-create-device.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-transport-create-device -published: false -title: "Create Device" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RD1 - - component: Runtime - - layer: Transport - - facade: DevicesFacade - - function: createDevice - - description: - - feature category: Multi-device - - tech category: Devices - - status: DONE - - documentation status: - - comments: Internal - - actor: Identity - - trigger: Runtime - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: - - published: default - - link: use-case-transport-create-device -require: -required_by: -# End automatic generation ---- diff --git a/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md index 1f8a96b39..d834c9078 100644 --- a/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/RelationshipTemplates/Own + - api_route_regex: POST /api/core/v1/RelationshipTemplates/Own - published: default - link: use-case-transport-create-own-relationshiptemplate require: required_by: -api_route_regex: ^POST /api/v2/RelationshipTemplates/Own$ +api_route_regex: ^POST /api/core/v1/RelationshipTemplates/Own$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-create-own-token.md b/_docs_use-cases/use-case-transport-create-own-token.md index 0a5c47ce6..74a1ccd70 100644 --- a/_docs_use-cases/use-case-transport-create-own-token.md +++ b/_docs_use-cases/use-case-transport-create-own-token.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Tokens/Own + - api_route_regex: POST /api/core/v1/Tokens/Own - published: default - link: use-case-transport-create-own-token require: required_by: -api_route_regex: ^POST /api/v2/Tokens/Own$ +api_route_regex: ^POST /api/core/v1/Tokens/Own$ # End automatic generation --- @@ -48,7 +48,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) that - `content` an arbitrary JSON structure of the data to share via the Token. - `expiresAt` is the ISODateTime the Token expires at. -- `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored. +- `ephemeral` indicates if the Token should be ephemeral and thus not be stored in the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored. - `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. - `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. diff --git a/_docs_use-cases/use-case-transport-create-relationship-with-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-relationship-with-relationshiptemplate.md index 3a25bbd98..c61fabe4f 100644 --- a/_docs_use-cases/use-case-transport-create-relationship-with-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-relationship-with-relationshiptemplate.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Relationships + - api_route_regex: POST /api/core/v1/Relationships - published: default - link: use-case-transport-create-relationship-with-relationshiptemplate require: required_by: -api_route_regex: ^POST /api/v2/Relationships$ +api_route_regex: ^POST /api/core/v1/Relationships$ # End automatic generation --- @@ -61,7 +61,7 @@ To check whether a Relationship can be created without actually creating it, the ## On Failure -- The `templateId` does not resolve to a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or the associated RelationshipTemplate was not cached correctly. +- The `templateId` does not resolve to a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate). - The [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) has already expired, which means that the timestamp specified in its `expiresAt` property has been exceeded. - A [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"`, `"Active"`, `"Terminated"` or `"DeletionProposed"` as `status` already exists to the creator of the RelationshipTemplate. In particular, the initiation of a new Relationship is prevented if the potential initiator has already [decomposed the former Relationship]({% link _docs_integrate/terminate-relationships.md %}#decompose-a-relationship) to the RelationshipTemplate's creator, but the creator of the RelationshipTemplate has not yet decomposed it and still has the former Relationship with `"DeletionProposed"` as `status`. - The [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) of the creator of the RelationshipTemplate is in deletion or has already been deleted. diff --git a/_docs_use-cases/use-case-transport-create-token-for-file.md b/_docs_use-cases/use-case-transport-create-token-for-file.md index 8a572a41e..1b096d1ac 100644 --- a/_docs_use-cases/use-case-transport-create-token-for-file.md +++ b/_docs_use-cases/use-case-transport-create-token-for-file.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Files/{id}/Token + - api_route_regex: POST /api/core/v1/Files/{id}/Token - published: default - link: use-case-transport-create-token-for-file require: required_by: -api_route_regex: ^POST /api/v2/Files/{id}/Token$ +api_route_regex: ^POST /api/core/v1/Files/{id}/Token$ # End automatic generation --- @@ -48,7 +48,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a - `fileId` is the `id` of the File the Token should be created for. - Optionally, `expiresAt` can be specified, which describes the ISODateTime the Token expires at. -- Optionally, `ephemeral` can be specified, which indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for [RelationshipTemplates]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate), and don't need to be stored. +- Optionally, `ephemeral` can be specified, which indicates if the Token should be ephemeral and thus not be stored in the local database. This is especially useful for Tokens which are created regularly, e.g. for [RelationshipTemplates]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate), and don't need to be stored. - Optionally, `forIdentity` can be specified, which names the `address` of the only [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that will be able to load the Token from the Backbone. - Optionally, `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. diff --git a/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md index dbe3ecfc0..719f1579e 100644 --- a/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/RelationshipTemplates/Own/{id}/Token + - api_route_regex: POST /api/core/v1/RelationshipTemplates/Own/{id}/Token - published: default - link: use-case-transport-create-token-for-own-relationshiptemplate require: required_by: -api_route_regex: ^POST /api/v2/RelationshipTemplates/Own/{id}/Token$ +api_route_regex: ^POST /api/core/v1/RelationshipTemplates/Own/{id}/Token$ # End automatic generation --- @@ -50,7 +50,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a - `templateId` is the `id` of the RelationshipTemplate the Token should be created for. - `expiresAt` is the ISODateTime the Token expires at. -- `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored. +- `ephemeral` indicates if the Token should be ephemeral and thus not be stored in the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored. - `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. If the RelationshipTemplate is already personalized via its `forIdentity` property, the Token created from it must have the same personalization. - `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. If the RelationshipTemplate is already password protected via its `passwordProtection` property, the Token created from it must have the same password protection. diff --git a/_docs_use-cases/use-case-transport-decompose-relationship.md b/_docs_use-cases/use-case-transport-decompose-relationship.md index 180d920b3..7386712ce 100644 --- a/_docs_use-cases/use-case-transport-decompose-relationship.md +++ b/_docs_use-cases/use-case-transport-decompose-relationship.md @@ -29,12 +29,12 @@ properties: - size: - created_at: - changed_at: - - api_route_regex: DELETE /api/v2/Relationships/{id} + - api_route_regex: DELETE /api/core/v1/Relationships/{id} - published: default - link: use-case-transport-decompose-relationship require: required_by: -api_route_regex: ^DELETE /api/v2/Relationships/{id}$ +api_route_regex: ^DELETE /api/core/v1/Relationships/{id}$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-delete-device-which-is-not-onboarded-yet.md b/_docs_use-cases/use-case-transport-delete-device-which-is-not-onboarded-yet.md index 1e3bf9a12..418bf379d 100644 --- a/_docs_use-cases/use-case-transport-delete-device-which-is-not-onboarded-yet.md +++ b/_docs_use-cases/use-case-transport-delete-device-which-is-not-onboarded-yet.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RD7 + - id: RD4 - component: Runtime - layer: Transport - facade: DevicesFacade diff --git a/_docs_use-cases/use-case-transport-delete-file.md b/_docs_use-cases/use-case-transport-delete-file.md index a93bf3f1f..681e30aa7 100644 --- a/_docs_use-cases/use-case-transport-delete-file.md +++ b/_docs_use-cases/use-case-transport-delete-file.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: DELETE /api/v2/Files/{id} + - api_route_regex: DELETE /api/core/v1/Files/{id} - published: default - link: use-case-transport-delete-file require: required_by: -api_route_regex: ^DELETE /api/v2/Files/{id}$ +api_route_regex: ^DELETE /api/core/v1/Files/{id}$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-download-file.md b/_docs_use-cases/use-case-transport-download-file.md index da1d54bfa..6cf07bcf8 100644 --- a/_docs_use-cases/use-case-transport-download-file.md +++ b/_docs_use-cases/use-case-transport-download-file.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Files/{id}/Download + - api_route_regex: GET /api/core/v1/Files/{id}/Download - published: default - link: use-case-transport-download-file require: required_by: -api_route_regex: ^GET /api/v2/Files/{id}/Download$ +api_route_regex: ^GET /api/core/v1/Files/{id}/Download$ # End automatic generation --- @@ -43,7 +43,7 @@ api_route_regex: ^GET /api/v2/Files/{id}/Download$ {% include properties_list.html %} This use case allows to download the [File's]({% link _docs_integrate/data-model-overview.md %}#file) binary content that corresponds to the `fileId`. -As the File is not stored or cached within the Connector, the encrypted File is downloaded from the Backbone, decrypted and returned every time this use case is called. +As the File is not stored within the Connector, the encrypted File is downloaded from the Backbone, decrypted and returned every time this use case is called. An [uploaded own File]({% link _docs_use-cases/use-case-transport-upload-own-file.md %}) can be downloaded by this use case in any case. However, a File from a peer must first be [loaded]({% link _docs_use-cases/use-case-transport-load-file.md %}) before its actual content can be downloaded. diff --git a/_docs_use-cases/use-case-transport-fill-device-onboarding-token-with-new-device.md b/_docs_use-cases/use-case-transport-fill-device-onboarding-token-with-new-device.md index 6aaf4b136..9f66ecaab 100644 --- a/_docs_use-cases/use-case-transport-fill-device-onboarding-token-with-new-device.md +++ b/_docs_use-cases/use-case-transport-fill-device-onboarding-token-with-new-device.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RD10 + - id: RD7 - component: Runtime - layer: Transport - facade: DevicesFacade 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 2dc780265..1d9a183bd 100644 --- a/_docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md @@ -14,7 +14,7 @@ properties: - layer: Transport - facade: IdentityDeletionProcessFacade - function: getActiveIdentityDeletionProcess - - description: Get IdentityDeletionProcess that is in status 'Approved' + - description: Get IdentityDeletionProcess that is in status 'Active' - feature category: Identity handling - tech category: IdentityDeletionProcesses - status: DONE @@ -42,7 +42,7 @@ required_by: {% include properties_list.html %} 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 `"Approved"` as `status`. +An IdentityDeletionProcess is active if it has `"Active"` 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. diff --git a/_docs_use-cases/use-case-transport-get-attributes-for-relationship.md b/_docs_use-cases/use-case-transport-get-attributes-for-relationship.md index a4851eee8..45d833756 100644 --- a/_docs_use-cases/use-case-transport-get-attributes-for-relationship.md +++ b/_docs_use-cases/use-case-transport-get-attributes-for-relationship.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Relationships/{id}/Attributes + - api_route_regex: GET /api/core/v1/Relationships/{id}/Attributes - published: default - link: use-case-transport-get-attributes-for-relationship require: required_by: -api_route_regex: ^GET /api/v2/Relationships/{id}/Attributes$ +api_route_regex: ^GET /api/core/v1/Relationships/{id}/Attributes$ # End automatic generation --- @@ -42,7 +42,7 @@ api_route_regex: ^GET /api/v2/Relationships/{id}/Attributes$ {% include properties_list.html %} -Retrieve all [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattributes) that are related to the given Relationship id. +Retrieve all [LocalAttributes]({% link _docs_integrate/data-model-overview.md %}#localattribute) that are related to the given [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) `id`. ## Parameters diff --git a/_docs_use-cases/use-case-transport-get-currently-used-identity.md b/_docs_use-cases/use-case-transport-get-currently-used-identity.md index 916ba0bd4..ecd73653b 100644 --- a/_docs_use-cases/use-case-transport-get-currently-used-identity.md +++ b/_docs_use-cases/use-case-transport-get-currently-used-identity.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Account/IdentityInfo + - api_route_regex: GET /api/core/v1/Account/IdentityInfo - published: default - link: use-case-transport-get-currently-used-identity require: required_by: -api_route_regex: ^GET /api/v2/Account/IdentityInfo$ +api_route_regex: ^GET /api/core/v1/Account/IdentityInfo$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-get-device-onboarding-info.md b/_docs_use-cases/use-case-transport-get-device-onboarding-info.md deleted file mode 100644 index 5acb96115..000000000 --- a/_docs_use-cases/use-case-transport-get-device-onboarding-info.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-transport-get-device-onboarding-info -published: true -title: "Get Device Onboarding Info" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RD4 - - component: Runtime - - layer: Transport - - facade: DevicesFacade - - function: getDeviceOnboardingInfo - - description: - - feature category: Multi-device - - tech category: Devices - - status: DONE - - documentation status: DONE - - comments: - - actor: Identity - - trigger: Runtime - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: - - published: default - - link: use-case-transport-get-device-onboarding-info -require: -required_by: -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case is deprecated and will be removed in the next major version. Please use the use case [Fill Device onboarding Token with new Device](use-case-transport-fill-device-onboarding-token-with-new-device) instead. -{: .notice--warning} - -This use case retrieves the onboarding information a so far not-onboarded Device that corresponds to the given Device `id` in order to onboard the Device to the Identity. - -## Parameters - -- `id` of the Device. - -## On Success - -- Returns the onboarding information of the Device. - -## On Failure - -- The Device was already onboarded. diff --git a/_docs_use-cases/use-case-transport-get-device.md b/_docs_use-cases/use-case-transport-get-device.md index 3fa34e44d..c780e0cfd 100644 --- a/_docs_use-cases/use-case-transport-get-device.md +++ b/_docs_use-cases/use-case-transport-get-device.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RD3 + - id: RD2 - component: Runtime - layer: Transport - facade: DevicesFacade diff --git a/_docs_use-cases/use-case-transport-get-file-metadata.md b/_docs_use-cases/use-case-transport-get-file-metadata.md index 86152ea7b..fd975f86f 100644 --- a/_docs_use-cases/use-case-transport-get-file-metadata.md +++ b/_docs_use-cases/use-case-transport-get-file-metadata.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Files/{idOrReference} + - api_route_regex: GET /api/core/v1/Files/{idOrReference} - published: default - link: use-case-transport-get-file-metadata require: required_by: -api_route_regex: ^GET /api/v2/Files/{idOrReference}$ +api_route_regex: ^GET /api/core/v1/Files/{idOrReference}$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-get-message-by-messageid.md b/_docs_use-cases/use-case-transport-get-message-by-messageid.md index f18634938..4ce5525db 100644 --- a/_docs_use-cases/use-case-transport-get-message-by-messageid.md +++ b/_docs_use-cases/use-case-transport-get-message-by-messageid.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Messages/{id} + - api_route_regex: GET /api/core/v1/Messages/{id} - published: default - link: use-case-transport-get-message-by-messageid require: required_by: -api_route_regex: ^GET /api/v2/Messages/{id}$ +api_route_regex: ^GET /api/core/v1/Messages/{id}$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-get-relationship-by-address.md b/_docs_use-cases/use-case-transport-get-relationship-by-address.md index 22b8be62b..3ddb14330 100644 --- a/_docs_use-cases/use-case-transport-get-relationship-by-address.md +++ b/_docs_use-cases/use-case-transport-get-relationship-by-address.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Relationships + - api_route_regex: GET /api/core/v1/Relationships - published: default - link: use-case-transport-get-relationship-by-address require: required_by: -api_route_regex: ^GET /api/v2/Relationships$ +api_route_regex: ^GET /api/core/v1/Relationships$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-get-relationship-by-relationshipid.md b/_docs_use-cases/use-case-transport-get-relationship-by-relationshipid.md index 8e5737308..332771e5f 100644 --- a/_docs_use-cases/use-case-transport-get-relationship-by-relationshipid.md +++ b/_docs_use-cases/use-case-transport-get-relationship-by-relationshipid.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Relationships/{id} + - api_route_regex: GET /api/core/v1/Relationships/{id} - published: default - link: use-case-transport-get-relationship-by-relationshipid require: required_by: -api_route_regex: ^GET /api/v2/Relationships/{id}$ +api_route_regex: ^GET /api/core/v1/Relationships/{id}$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-get-relationshiptemplate.md b/_docs_use-cases/use-case-transport-get-relationshiptemplate.md index 77ef2169c..41b0400c3 100644 --- a/_docs_use-cases/use-case-transport-get-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-get-relationshiptemplate.md @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/RelationshipTemplates/{id} + - api_route_regex: GET /api/core/v1/RelationshipTemplates/{id} - published: default - link: use-case-transport-get-relationshiptemplate require: required_by: -api_route_regex: ^GET /api/v2/RelationshipTemplates/{id}$ +api_route_regex: ^GET /api/core/v1/RelationshipTemplates/{id}$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-get-synchronization-status-with-backbone.md b/_docs_use-cases/use-case-transport-get-synchronization-status-with-backbone.md index 86f8bc2d3..44d59162d 100644 --- a/_docs_use-cases/use-case-transport-get-synchronization-status-with-backbone.md +++ b/_docs_use-cases/use-case-transport-get-synchronization-status-with-backbone.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Account/SyncInfo + - api_route_regex: GET /api/core/v1/Account/SyncInfo - published: default - link: use-case-transport-get-synchronization-status-with-backbone require: required_by: -api_route_regex: ^GET /api/v2/Account/SyncInfo$ +api_route_regex: ^GET /api/core/v1/Account/SyncInfo$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-get-token-by-tokenid.md b/_docs_use-cases/use-case-transport-get-token-by-tokenid.md index e8567b42e..ab6327736 100644 --- a/_docs_use-cases/use-case-transport-get-token-by-tokenid.md +++ b/_docs_use-cases/use-case-transport-get-token-by-tokenid.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Tokens/{id} + - api_route_regex: GET /api/core/v1/Tokens/{id} - published: default - link: use-case-transport-get-token-by-tokenid require: required_by: -api_route_regex: ^GET /api/v2/Tokens/{id}$ +api_route_regex: ^GET /api/core/v1/Tokens/{id}$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md b/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md index cf252b559..d21908e52 100644 --- a/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md @@ -14,7 +14,7 @@ properties: - layer: Transport - facade: IdentityDeletionProcessFacade - function: initiateIdentityDeletionProcess - - description: Initiate an IdentityDeletionProcess that has status 'Approved' + - description: Initiate an IdentityDeletionProcess that has status 'Active' - feature category: Identity handling - tech category: IdentityDeletionProcesses - status: DONE @@ -42,16 +42,16 @@ required_by: {% include properties_list.html %} 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. +The generated IdentityDeletionProcess immediately has `"Active"` 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. This use case can be utilized by using the [Identity deletion initialization command]({% link _docs_operate/connector-cli-operations.md %}#identity-deletion-initialization-command) of the [Connector CLI operations]({% link _docs_operate/connector-cli-operations.md %}), but not by using the [Connector REST API]({% link _docs_integrate/access-the-connector.md %}#hosted-api-tooling-by-the-development-connector). {: .notice--info} ## On Success -- Creates an IdentityDeletionProcess with `"Approved"` as `status`. +- Creates an IdentityDeletionProcess with `"Active"` as `status`. - Returns the initiated IdentityDeletionProcess. ## On Failure -- No IdentityDeletionProcess can be initiated if there is already an active IdentityDeletionProcess, i.e. an IdentityDeletionProcess with `"Approved"` as `status`, for this Identity. +- No IdentityDeletionProcess can be initiated if there is already an active IdentityDeletionProcess, i.e. an IdentityDeletionProcess with `"Active"` as `status`, for this Identity. diff --git a/_docs_use-cases/use-case-transport-load-file.md b/_docs_use-cases/use-case-transport-load-file.md index a167fff3e..666a58bc6 100644 --- a/_docs_use-cases/use-case-transport-load-file.md +++ b/_docs_use-cases/use-case-transport-load-file.md @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Files/Peer + - api_route_regex: POST /api/core/v1/Files/Peer - published: default - link: use-case-transport-load-file require: required_by: -api_route_regex: ^POST /api/v2/Files/Peer$ +api_route_regex: ^POST /api/core/v1/Files/Peer$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-load-item-from-reference.md b/_docs_use-cases/use-case-transport-load-item-from-reference.md index 4f05bb9a9..7583b671c 100644 --- a/_docs_use-cases/use-case-transport-load-item-from-reference.md +++ b/_docs_use-cases/use-case-transport-load-item-from-reference.md @@ -1,6 +1,8 @@ --- # Start automatic generation permalink: use-case-transport-load-item-from-reference +redirect_from: + - use-case-transport-load-item-from-truncated-reference published: true title: "Load item from reference" type: use-case @@ -9,7 +11,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RU10 + - id: RU9 - component: Runtime - layer: Transport - facade: AccountFacade @@ -19,7 +21,7 @@ properties: - tech category: Account - status: QUESTIONS - documentation status: DONE - - comments: add redirect from /use-case-transport-load-item-from-truncated-reference as soon as that use case is deleted; rather somewhere else? + - comments: rather somewhere else? - actor: Identity - trigger: - precondition: @@ -43,6 +45,6 @@ required_by: This use case intends to load an entity by its `reference` received by a peer. Internally, it uses the specific use cases of each entity: -- If the `reference` refers to a [Token]({% link _docs_integrate/data-model-overview.md %}#token), it fetches the Token just like the [Load Token created by others]({% link _docs_use-cases/use-case-transport-load-token-created-by-others.md %}) use case. For example, if the `content` of the Token is a TokenContentDeviceSharedSecret, a DeviceOnboardingInfo is returned after the successful execution of the use case. A TokenContentDeviceSharedSecret is created by the [Create Device Onboarding Token]({% link _docs_use-cases/use-case-transport-create-device-onboarding-token.md %}) use case. +- If the `reference` refers to a [Token]({% link _docs_integrate/data-model-overview.md %}#token), it fetches the Token just like the [Load Token created by others]({% link _docs_use-cases/use-case-transport-load-token-created-by-others.md %}) use case. For example, if the `content` of the Token is a TokenContentDeviceSharedSecret, a DeviceOnboardingInfo is returned after the successful execution of the use case. - If the `reference` refers to a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate), it fetches the RelationshipTemplate just like the [Load RelationshipTemplate created by others]({% link _docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md %}) use case. - If the `reference` refers to a [File]({% link _docs_integrate/data-model-overview.md %}#file), it fetches the File just like the [Load File]({% link _docs_use-cases/use-case-transport-load-file.md %}) use case. diff --git a/_docs_use-cases/use-case-transport-load-item-from-truncated-reference.md b/_docs_use-cases/use-case-transport-load-item-from-truncated-reference.md deleted file mode 100644 index 11fd9cb50..000000000 --- a/_docs_use-cases/use-case-transport-load-item-from-truncated-reference.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -# Start automatic generation -permalink: use-case-transport-load-item-from-truncated-reference -published: true -title: "Load item from truncated reference" -type: use-case -toc: true -sidebar: - - title: "Integrate enmeshed" - nav: "docs_integrate" -properties: - - id: RU9 - - component: Runtime - - layer: Transport - - facade: AccountFacade - - function: loadItemFromTruncatedReference - - description: - - feature category: Share information over side-channel - - tech category: Account - - status: QUESTIONS - - documentation status: DONE - - comments: deprecated use /use-case-transport-load-item-from-reference instead; rather somewhere else? - - actor: Identity - - trigger: - - precondition: - - result: - - priority: n/a - - complexity: n/a - - size: n/a - - created_at: - - changed_at: - - api_route_regex: - - published: default - - link: use-case-transport-load-item-from-truncated-reference -require: -required_by: -# End automatic generation ---- - -{{properties.description}} - -{% include properties_list.html %} - -This use case is deprecated and will be removed in the next major version. Please use the use case [Load item from reference](use-case-transport-load-item-from-reference) instead. -{: .notice--warning} - -This use case intends to load an entity by its `reference` received by a peer. Internally, it uses the specific use cases of each entity: - -- If the `reference` refers to a [Token]({% link _docs_integrate/data-model-overview.md %}#token), it fetches the Token just like the [Load Token created by others]({% link _docs_use-cases/use-case-transport-load-token-created-by-others.md %}) use case. For example, if the `content` of the Token is a TokenContentDeviceSharedSecret, a DeviceOnboardingInfo is returned after the successful execution of the use case. A TokenContentDeviceSharedSecret is created by the [Create Device Onboarding Token]({% link _docs_use-cases/use-case-transport-create-device-onboarding-token.md %}) use case. -- If the `reference` refers to a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate), it fetches the RelationshipTemplate just like the [Load RelationshipTemplate created by others]({% link _docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md %}) use case. -- If the `reference` refers to a [File]({% link _docs_integrate/data-model-overview.md %}#file), it fetches the File just like the [Load File]({% link _docs_use-cases/use-case-transport-load-file.md %}) use case. diff --git a/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md b/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md index b5625b485..6f3847bbe 100644 --- a/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md +++ b/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/RelationshipTemplates/Peer + - api_route_regex: POST /api/core/v1/RelationshipTemplates/Peer - published: default - link: use-case-transport-load-relationshiptemplate-created-by-others require: required_by: -api_route_regex: ^POST /api/v2/RelationshipTemplates/Peer$ +api_route_regex: ^POST /api/core/v1/RelationshipTemplates/Peer$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-load-token-created-by-others.md b/_docs_use-cases/use-case-transport-load-token-created-by-others.md index 49ecbebb0..5c2ba3ac1 100644 --- a/_docs_use-cases/use-case-transport-load-token-created-by-others.md +++ b/_docs_use-cases/use-case-transport-load-token-created-by-others.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Tokens/Peer + - api_route_regex: POST /api/core/v1/Tokens/Peer - published: default - link: use-case-transport-load-token-created-by-others require: required_by: -api_route_regex: ^POST /api/v2/Tokens/Peer$ +api_route_regex: ^POST /api/core/v1/Tokens/Peer$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-query-devices.md b/_docs_use-cases/use-case-transport-query-devices.md index 38c0daed9..c1ac9ef79 100644 --- a/_docs_use-cases/use-case-transport-query-devices.md +++ b/_docs_use-cases/use-case-transport-query-devices.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RD2 + - id: RD1 - component: Runtime - layer: Transport - facade: DevicesFacade diff --git a/_docs_use-cases/use-case-transport-query-messages.md b/_docs_use-cases/use-case-transport-query-messages.md index 627296c64..84ad504d6 100644 --- a/_docs_use-cases/use-case-transport-query-messages.md +++ b/_docs_use-cases/use-case-transport-query-messages.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Messages + - api_route_regex: GET /api/core/v1/Messages - published: default - link: use-case-transport-query-messages require: required_by: -api_route_regex: ^GET /api/v2/Messages$ +api_route_regex: ^GET /api/core/v1/Messages$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-query-metadata-of-files.md b/_docs_use-cases/use-case-transport-query-metadata-of-files.md index 4ab8dd100..a4616ac71 100644 --- a/_docs_use-cases/use-case-transport-query-metadata-of-files.md +++ b/_docs_use-cases/use-case-transport-query-metadata-of-files.md @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Files + - api_route_regex: GET /api/core/v1/Files - published: default - link: use-case-transport-query-metadata-of-files require: required_by: -api_route_regex: ^GET /api/v2/Files$ +api_route_regex: ^GET /api/core/v1/Files$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-query-metadata-of-own-files.md b/_docs_use-cases/use-case-transport-query-metadata-of-own-files.md index ab72f754f..39d5499b8 100644 --- a/_docs_use-cases/use-case-transport-query-metadata-of-own-files.md +++ b/_docs_use-cases/use-case-transport-query-metadata-of-own-files.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Files/Own + - api_route_regex: GET /api/core/v1/Files/Own - published: default - link: use-case-transport-query-metadata-of-own-files require: required_by: -api_route_regex: ^GET /api/v2/Files/Own$ +api_route_regex: ^GET /api/core/v1/Files/Own$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-query-metadata-of-peer-files.md b/_docs_use-cases/use-case-transport-query-metadata-of-peer-files.md index 802224534..37224fd20 100644 --- a/_docs_use-cases/use-case-transport-query-metadata-of-peer-files.md +++ b/_docs_use-cases/use-case-transport-query-metadata-of-peer-files.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Files/Peer + - api_route_regex: GET /api/core/v1/Files/Peer - published: default - link: use-case-transport-query-metadata-of-peer-files require: required_by: -api_route_regex: ^GET /api/v2/Files/Peer$ +api_route_regex: ^GET /api/core/v1/Files/Peer$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-query-relationships.md b/_docs_use-cases/use-case-transport-query-relationships.md index 4764a7431..e60b59f48 100644 --- a/_docs_use-cases/use-case-transport-query-relationships.md +++ b/_docs_use-cases/use-case-transport-query-relationships.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/Relationships + - api_route_regex: GET /api/core/v1/Relationships - published: default - link: use-case-transport-query-relationships require: required_by: -api_route_regex: ^GET /api/v2/Relationships$ +api_route_regex: ^GET /api/core/v1/Relationships$ # End automatic generation --- @@ -48,7 +48,7 @@ This use case queries [Relationships]({% link _docs_integrate/data-model-overvie - `peer` is the enmeshed address of the peer. - `status` is the status of the Relationship. -- `template.id` is the id of the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) that was used to initiate the Relationship. +- `templateId` is the `id` of the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) that was used to initiate the Relationship. ## On Success diff --git a/_docs_use-cases/use-case-transport-query-relationshiptemplates.md b/_docs_use-cases/use-case-transport-query-relationshiptemplates.md index 0832ff445..c7ed08e6b 100644 --- a/_docs_use-cases/use-case-transport-query-relationshiptemplates.md +++ b/_docs_use-cases/use-case-transport-query-relationshiptemplates.md @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: GET /api/v2/RelationshipTemplates + - api_route_regex: GET /api/core/v1/RelationshipTemplates - published: default - link: use-case-transport-query-relationshiptemplates require: required_by: -api_route_regex: ^GET /api/v2/RelationshipTemplates$ +api_route_regex: ^GET /api/core/v1/RelationshipTemplates$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-regenerate-file-ownership-token.md b/_docs_use-cases/use-case-transport-regenerate-file-ownership-token.md index 23618e715..9c8c4cd6e 100644 --- a/_docs_use-cases/use-case-transport-regenerate-file-ownership-token.md +++ b/_docs_use-cases/use-case-transport-regenerate-file-ownership-token.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: PATCH /api/v2/Files/{id}/RegenerateOwnershipToken + - api_route_regex: PATCH /api/core/v1/Files/{id}/RegenerateOwnershipToken - published: default - link: use-case-transport-regenerate-file-ownership-token require: required_by: -api_route_regex: ^PATCH /api/v2/Files/{id}/RegenerateOwnershipToken$ +api_route_regex: ^PATCH /api/core/v1/Files/{id}/RegenerateOwnershipToken$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-reject-relationship-reactivation.md b/_docs_use-cases/use-case-transport-reject-relationship-reactivation.md index b604bf9c8..e67802aed 100644 --- a/_docs_use-cases/use-case-transport-reject-relationship-reactivation.md +++ b/_docs_use-cases/use-case-transport-reject-relationship-reactivation.md @@ -29,12 +29,12 @@ properties: - size: - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Relationships/{id}/Reactivate/Reject + - api_route_regex: PUT /api/core/v1/Relationships/{id}/Reactivate/Reject - published: default - link: use-case-transport-reject-relationship-reactivation require: required_by: -api_route_regex: ^PUT /api/v2/Relationships/{id}/Reactivate/Reject$ +api_route_regex: ^PUT /api/core/v1/Relationships/{id}/Reactivate/Reject$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-reject-relationship.md b/_docs_use-cases/use-case-transport-reject-relationship.md index 171373bdb..d9ff2c5b9 100644 --- a/_docs_use-cases/use-case-transport-reject-relationship.md +++ b/_docs_use-cases/use-case-transport-reject-relationship.md @@ -31,12 +31,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Relationships/{id}/Reject + - api_route_regex: PUT /api/core/v1/Relationships/{id}/Reject - published: default - link: use-case-transport-reject-relationship require: required_by: -api_route_regex: ^PUT /api/v2/Relationships/{id}/Reject$ +api_route_regex: ^PUT /api/core/v1/Relationships/{id}/Reject$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-request-relationship-reactivation.md b/_docs_use-cases/use-case-transport-request-relationship-reactivation.md index f7497ef41..b6a5449e4 100644 --- a/_docs_use-cases/use-case-transport-request-relationship-reactivation.md +++ b/_docs_use-cases/use-case-transport-request-relationship-reactivation.md @@ -29,12 +29,12 @@ properties: - size: - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Relationships/{id}/Reactivate + - api_route_regex: PUT /api/core/v1/Relationships/{id}/Reactivate - published: default - link: use-case-transport-request-relationship-reactivation require: required_by: -api_route_regex: ^PUT /api/v2/Relationships/{id}/Reactivate$ +api_route_regex: ^PUT /api/core/v1/Relationships/{id}/Reactivate$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-revoke-relationship-reactivation.md b/_docs_use-cases/use-case-transport-revoke-relationship-reactivation.md index 4fd3bbbef..9af02804c 100644 --- a/_docs_use-cases/use-case-transport-revoke-relationship-reactivation.md +++ b/_docs_use-cases/use-case-transport-revoke-relationship-reactivation.md @@ -29,12 +29,12 @@ properties: - size: - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Relationships/{id}/Reactivate/Revoke + - api_route_regex: PUT /api/core/v1/Relationships/{id}/Reactivate/Revoke - published: default - link: use-case-transport-revoke-relationship-reactivation require: required_by: -api_route_regex: ^PUT /api/v2/Relationships/{id}/Reactivate/Revoke$ +api_route_regex: ^PUT /api/core/v1/Relationships/{id}/Reactivate/Revoke$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-revoke-relationship.md b/_docs_use-cases/use-case-transport-revoke-relationship.md index d4b40e444..7ac17a633 100644 --- a/_docs_use-cases/use-case-transport-revoke-relationship.md +++ b/_docs_use-cases/use-case-transport-revoke-relationship.md @@ -29,12 +29,12 @@ properties: - size: - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Relationships/{id}/Revoke + - api_route_regex: PUT /api/core/v1/Relationships/{id}/Revoke - published: default - link: use-case-transport-revoke-relationship require: required_by: -api_route_regex: ^PUT /api/v2/Relationships/{id}/Revoke$ +api_route_regex: ^PUT /api/core/v1/Relationships/{id}/Revoke$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-send-message-to-recipients.md b/_docs_use-cases/use-case-transport-send-message-to-recipients.md index cd72e50c7..d46cfe498 100644 --- a/_docs_use-cases/use-case-transport-send-message-to-recipients.md +++ b/_docs_use-cases/use-case-transport-send-message-to-recipients.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Messages + - api_route_regex: POST /api/core/v1/Messages - published: default - link: use-case-transport-send-message-to-recipients require: required_by: -api_route_regex: ^POST /api/v2/Messages$ +api_route_regex: ^POST /api/core/v1/Messages$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-synchronize-datawallet-updates-to-backbone.md b/_docs_use-cases/use-case-transport-synchronize-datawallet-updates-to-backbone.md index 79dafbe4f..79b75c667 100644 --- a/_docs_use-cases/use-case-transport-synchronize-datawallet-updates-to-backbone.md +++ b/_docs_use-cases/use-case-transport-synchronize-datawallet-updates-to-backbone.md @@ -29,11 +29,11 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Account/Sync + - api_route_regex: POST /api/core/v1/Account/Sync - published: default - link: use-case-transport-synchronize-datawallet-updates-to-backbone require: required_by: -api_route_regex: ^POST /api/v2/Account/Sync$ +api_route_regex: ^POST /api/core/v1/Account/Sync$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md b/_docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md index c71027ac3..bec5e0e5a 100644 --- a/_docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md +++ b/_docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Account/Sync + - api_route_regex: POST /api/core/v1/Account/Sync - published: default - link: use-case-transport-synchronize-updates-of-backbone require: required_by: -api_route_regex: ^POST /api/v2/Account/Sync$ +api_route_regex: ^POST /api/core/v1/Account/Sync$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-terminate-relationship.md b/_docs_use-cases/use-case-transport-terminate-relationship.md index 6a8c0220a..c2c8005c8 100644 --- a/_docs_use-cases/use-case-transport-terminate-relationship.md +++ b/_docs_use-cases/use-case-transport-terminate-relationship.md @@ -29,12 +29,12 @@ properties: - size: - created_at: - changed_at: - - api_route_regex: PUT /api/v2/Relationships/{id}/Terminate + - api_route_regex: PUT /api/core/v1/Relationships/{id}/Terminate - published: default - link: use-case-transport-terminate-relationship require: required_by: -api_route_regex: ^PUT /api/v2/Relationships/{id}/Terminate$ +api_route_regex: ^PUT /api/core/v1/Relationships/{id}/Terminate$ # End automatic generation --- diff --git a/_docs_use-cases/use-case-transport-trigger-device-deletion-of-onboarded-device.md b/_docs_use-cases/use-case-transport-trigger-device-deletion-of-onboarded-device.md index 464c86e05..18bcf4eb1 100644 --- a/_docs_use-cases/use-case-transport-trigger-device-deletion-of-onboarded-device.md +++ b/_docs_use-cases/use-case-transport-trigger-device-deletion-of-onboarded-device.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RD8 + - id: RD5 - component: Runtime - layer: Transport - facade: DevicesFacade diff --git a/_docs_use-cases/use-case-transport-update-device.md b/_docs_use-cases/use-case-transport-update-device.md index 898df215e..04dd14e9f 100644 --- a/_docs_use-cases/use-case-transport-update-device.md +++ b/_docs_use-cases/use-case-transport-update-device.md @@ -9,7 +9,7 @@ sidebar: - title: "Integrate enmeshed" nav: "docs_integrate" properties: - - id: RD9 + - id: RD6 - component: Runtime - layer: Transport - facade: DevicesFacade diff --git a/_docs_use-cases/use-case-transport-upload-own-file.md b/_docs_use-cases/use-case-transport-upload-own-file.md index f2d98637a..aa6f99b52 100644 --- a/_docs_use-cases/use-case-transport-upload-own-file.md +++ b/_docs_use-cases/use-case-transport-upload-own-file.md @@ -29,12 +29,12 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Files/Own + - api_route_regex: POST /api/core/v1/Files/Own - published: default - link: use-case-transport-upload-own-file require: required_by: -api_route_regex: ^POST /api/v2/Files/Own$ +api_route_regex: ^POST /api/core/v1/Files/Own$ # End automatic generation --- @@ -55,7 +55,7 @@ In the latter case, the [Token for the File must be created]({% link _docs_use-c - Optionally, `expiresAt` can be specified, which describes the ISODateTime the File expires. - Optionally, a `title` can be provided for the File. - Optionally, a `description` can be provided for the File. -- Optionally, `tags` can be provided for the File. +- Optionally, `tags` can be provided for the File. If an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) with [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) as `value.@type` is created for the File during [transferring the ownership of the File to a peer]({% link _docs_integrate/exchange-files-using-attributes.md %}#transfer-the-ownership-of-a-file-to-a-peer), it will have these `tags` as well. For this reason, a tag is valid if it is contained in the [AttributeTagCollection]({% link _docs_integrate/data-model-overview.md %}#attributetagcollection) for the `value.@type` IdentityFileReference and starts with the prefix `bkb:` or if it starts with the custom tag prefix `x:` or `X:`, the prefix `urn:`, the prefix `language:` followed by a valid ISO 639 language code or the prefix `mimetype:` followed by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$`. ## On Success @@ -69,3 +69,4 @@ In the latter case, the [Token for the File must be created]({% link _docs_use-c - The parameters are malformed. - The file size is too big. +- Invalid `tags` were provided. A tag is invalid if it is neither contained in the [AttributeTagCollection]({% link _docs_integrate/data-model-overview.md %}#attributetagcollection) for the [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) `value.@type` [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) and starts with the prefix `bkb:` nor starts with the custom tag prefix `x:` or `X:`, the prefix `urn:`, the prefix `language:` followed by a valid ISO 639 language code nor the prefix `mimetype:` followed by a valid MIME type matching the pattern `^[a-z-*]+/[a-z-*]+$`. diff --git a/_docs_use-cases/use-case-transport-validate-challenge.md b/_docs_use-cases/use-case-transport-validate-challenge.md index dca1b7096..b40b89cbb 100644 --- a/_docs_use-cases/use-case-transport-validate-challenge.md +++ b/_docs_use-cases/use-case-transport-validate-challenge.md @@ -29,11 +29,11 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: POST /api/v2/Challenges/Validate + - api_route_regex: POST /api/core/v1/Challenges/Validate - published: - link: use-case-transport-validate-challenge require: required_by: -api_route_regex: ^POST /api/v2/Challenges/Validate$ +api_route_regex: ^POST /api/core/v1/Challenges/Validate$ # End automatic generation --- diff --git a/_includes/descr_createdAt b/_includes/descr_createdAt index dfbe2c951..a3c642ed2 100644 --- a/_includes/descr_createdAt +++ b/_includes/descr_createdAt @@ -1 +1 @@ -A timestamp that describes when the {{ include.class }} was created \ No newline at end of file +A timestamp that describes when the {{ include.class }} was created. \ No newline at end of file diff --git a/_includes/descr_expiresAt b/_includes/descr_expiresAt index a2ed7e64f..c13fb2012 100644 --- a/_includes/descr_expiresAt +++ b/_includes/descr_expiresAt @@ -1 +1 @@ -A timestamp that describes when the {{ include.class }} expires on the Backbone. An expired {{ include.class }} cannot be fetched from the Backbone anymore. However, the cached version of the {{ include.class }} on Connector and App will still be accessible. \ No newline at end of file +A timestamp that describes when the {{ include.class }} expires on the Backbone. An expired {{ include.class }} cannot be fetched from the Backbone anymore. However, the stored version of the {{ include.class }} on Connector and App will still be accessible. \ No newline at end of file diff --git a/assets/js/iql-demo.js b/assets/js/iql-demo.js index 4c71b0752..0d1169b75 100644 --- a/assets/js/iql-demo.js +++ b/assets/js/iql-demo.js @@ -4,11 +4,11 @@ "use strict"; (r.r(t), r.d(t, { attributes: () => n })); const n = [ - { value: { "@type": "PhoneNumber", value: "06221/215221" }, validFrom: "2011-01-01T00:00:00", validTo: "2013-01-01T00:00:00" }, - { value: { "@type": "PhoneNumber", value: "06221/553132" }, tags: ["emergency"], validFrom: "2021-02-03T00:00:00", validTo: "2024-01-01T00:00:00" }, + { value: { "@type": "PhoneNumber", value: "06221/215221" } }, + { value: { "@type": "PhoneNumber", value: "06221/553132" }, tags: ["emergency"] }, { value: { "@type": "Website", value: "https://enmeshed.eu" } }, - { value: { "@type": "GivenName", value: "Steven-Nicholas" }, validFrom: "2020-01-01T00:00:00", validTo: "2023-11-01T00:00:00" }, - { value: { "@type": "LastName", value: "O'Malley" }, validFrom: "2021-01-01T00:00:00", validTo: "2023-12-01T00:00:00" }, + { value: { "@type": "GivenName", value: "Steven-Nicholas" } }, + { value: { "@type": "LastName", value: "O'Malley" } }, { value: { "@type": "StreetAddress", @@ -43,9 +43,7 @@ "urn:xbildung-de:unesco:codeliste:isced2011=647", "content:edu.de.higher.certOfEnrolment", "language:es" - ], - validFrom: "2021-01-01T00:00:00", - validTo: "2023-01-01T00:00:00" + ] } ]; }, @@ -488,7 +486,6 @@ 46 === e.charCodeAt(fe) ? ((u = y), fe++) : ((u = a), 0 === ge && Ae(z)), u !== a && (s = Oe()) !== a ? (o = s) : ((fe = o), (o = a)); o !== a; - ) (n.push(o), (o = fe), @@ -541,7 +538,6 @@ (e.substr(fe, 2) === A ? ((o = A), (fe += 2)) : ((o = a), 0 === ge && Ae(H)), o === a && ((o = e.charAt(fe)), E.test(o) ? fe++ : ((o = a), 0 === ge && Ae(J)))); o !== a; - ) (n.push(o), e.substr(fe, 2) === x ? ((o = x), (fe += 2)) : ((o = a), 0 === ge && Ae(_)), @@ -559,7 +555,6 @@ (e.substr(fe, 2) === A ? ((n = A), (fe += 2)) : ((n = a), 0 === ge && Ae(H)), n === a && ((n = e.charAt(fe)), w.test(n) ? fe++ : ((n = a), 0 === ge && Ae(W)))); n !== a; - ) (r.push(n), e.substr(fe, 2) === x ? ((n = x), (fe += 2)) : ((n = a), 0 === ge && Ae(_)),