diff --git a/_docs_integrate/01-integrate-scenarios.md b/_docs_integrate/01-integrate-scenarios.md index 25304bd4a..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,7 +48,8 @@ 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 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 402a27768..824e5ff1a 100644 --- a/_docs_integrate/attribute-introduction.md +++ b/_docs_integrate/attribute-introduction.md @@ -22,13 +22,20 @@ 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 @@ -38,25 +45,45 @@ If the IdentityAttribute value type used is not sufficient to clearly characteri 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. 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) 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. +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). #### 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 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. +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 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} ### 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). +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**. #### RepositoryAttributes @@ -71,15 +98,29 @@ This can be done by using a suitable [Request]({% link _docs_integrate/data-mode #### Own shared and peer shared IdentityAttributes -When [exchanging the underlying IdentityAttribute of a RepositoryAttribute with a peer](#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 [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.
-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 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. ## 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. @@ -89,11 +130,19 @@ For information on how to establish Relationships, refer to the [Establish Relat ### 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). +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. #### Own shared and peer shared RelationshipAttributes @@ -103,9 +152,12 @@ The own shared RelationshipAttribute is the LocalAttribute of the `owner` of the
-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. +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. +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. @@ -128,33 +180,48 @@ Lastly, the `shareInfo.sourceAttribute` property of a received ThirdPartyRelatio ## 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 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. diff --git a/_docs_integrate/attribute-values.md b/_docs_integrate/attribute-values.md index f0cf84446..2cc244d7d 100644 --- a/_docs_integrate/attribute-values.md +++ b/_docs_integrate/attribute-values.md @@ -23,19 +23,28 @@ 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)). +These properties can (but don't have to) contain other Attribute Values. # 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. +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 @@ -43,7 +52,8 @@ 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. +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** @@ -58,7 +68,8 @@ A complex Attribute Value type which defines the affiliation of a person to an o 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. +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** @@ -74,7 +85,8 @@ It is not recommended to send an AffiliationOrganization to another Identity by 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. +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** @@ -88,7 +100,8 @@ It is not recommended to send an AffiliationRole to another Identity by its own. 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. +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** @@ -102,7 +115,8 @@ It is not recommended to send an AffiliationUnit to another Identity by its own. 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. +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** @@ -116,7 +130,8 @@ It is not recommended to send a BirthCity to another Identity by its own. Instea 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. +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} **Properties** @@ -143,7 +158,8 @@ The birth date of a natural person. 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. +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 | @@ -155,7 +171,8 @@ It is not recommended to send a BirthDay to another Identity by its own. Instead 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. +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 | @@ -165,7 +182,9 @@ It is not recommended to send a BirthMonth to another Identity by its own. Inste ## 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. @@ -193,7 +212,8 @@ The BirthPlace consists of the BirthCity and BirthCountry and can optionally inc 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. +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** @@ -207,7 +227,8 @@ It is not recommended to send a BirthState to another Identity by its own. Inste 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. +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 | @@ -217,7 +238,8 @@ It is not recommended to send a BirthYear to another Identity by its own. Instea ## 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** @@ -228,9 +250,11 @@ The Citizenship defines which country currently recognizes you as a citizen. Thu ## City -The name of a city. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). +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. +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** @@ -253,9 +277,11 @@ The CommunicationLanguage is an officially recognized language the person can co ## 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). +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. +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** @@ -285,7 +311,8 @@ A complex Attribute Value defining the components of a delivery box address. ## 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** @@ -364,9 +391,11 @@ The honorific suffix of a person, e.g. 'PhD' ## HouseNumber -A house number. This is usually used as part of a [`StreetAddress`](#streetaddress). +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. +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** @@ -378,7 +407,7 @@ It is not recommended to send a HouseNumber to another Identity by its own. Inst ## 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** @@ -400,7 +429,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** @@ -464,7 +495,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** @@ -492,9 +524,11 @@ The "Gender" Attribute Value type is currently being evaluated to ensure inclusi ## State -The name of a state. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). +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. +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** @@ -523,7 +557,8 @@ The statement allows a very generic digital mapping of facts 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) +It is not recommended to send a DigitalIdentityDescriptor to another Identity by its own. +Instead, send a [`statement`](#statement) {: .notice--warning} **Properties** @@ -538,7 +573,8 @@ It is not recommended to send a DigitalIdentityDescriptor to another Identity by 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) +It is not recommended to send a StatementAuthorityType to another Identity by its own. +Instead, send a [`statement`](#statement) {: .notice--warning} **Properties** @@ -552,7 +588,8 @@ It is not recommended to send a StatementAuthorityType to another Identity by it The evidence in [`StatementIssuerConditions`](#statementissuerconditions) -It is not recommended to send a StatementEvidence to another Identity by its own. Instead, send a [`statement`](#statement) +It is not recommended to send a StatementEvidence to another Identity by its own. +Instead, send a [`statement`](#statement) {: .notice--warning} **Properties** @@ -566,7 +603,8 @@ It is not recommended to send a StatementEvidence to another Identity by its own 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) +It is not recommended to send a StatementIssuerConditions to another Identity by its own. +Instead, send a [`statement`](#statement) {: .notice--warning} **Properties** @@ -584,7 +622,8 @@ It is not recommended to send a StatementIssuerConditions to another Identity by 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) +It is not recommended to send a object to another Identity by its own. +Instead, send a [`statement`](#statement) {: .notice--warning} **Properties** @@ -599,7 +638,8 @@ It is not recommended to send a object to another Identity by its own. Instead, 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) +It is not recommended to send a predicate to another Identity by its own. +Instead, send a [`statement`](#statement) {: .notice--warning} **Properties** @@ -613,7 +653,8 @@ It is not recommended to send a predicate to another Identity by its own. Instea 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) +It is not recommended to send a subject to another Identity by its own. +Instead, send a [`statement`](#statement) {: .notice--warning} **Properties** @@ -626,9 +667,11 @@ It is not recommended to send a subject to another Identity by its own. Instead, ## Street -A street name. This is usually used as part of a [`StreetAddress`](#streetaddress). +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. +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** @@ -679,9 +722,11 @@ The website of the person which can be used to get more information about the pe ## ZipCode -A zip code. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). +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. +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** @@ -693,11 +738,16 @@ It is not recommended to send a ZipCode to another Identity by its own. Instead, # 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** @@ -810,9 +860,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/create-attributes-for-peer.md b/_docs_integrate/create-attributes-for-peer.md index 3953fa550..8d37d70b5 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,25 +139,35 @@ 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}
@@ -150,11 +185,17 @@ If the underlying `attribute` of the accepted [CreateAttributeRequestItem]({% li ### 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,7 +287,9 @@ 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).
@@ -257,9 +304,13 @@ Note that each accepted CreateAttributeRequestItem leads to the creation of an a 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). -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 714667545..b0984deec 100644 --- a/_docs_integrate/create-attributes-for-yourself.md +++ b/_docs_integrate/create-attributes-for-yourself.md @@ -25,18 +25,23 @@ 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 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. -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 -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 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: ```jsonc { @@ -58,13 +63,20 @@ This is to prevent several latest RepositoryAttributes with the same `content.va ### Process of creating a RepositoryAttribute -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. 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 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. +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 %}).
### 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 { @@ -81,7 +93,8 @@ Assuming that the input value for the Connector's display name specified in the ### 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 { @@ -96,15 +109,23 @@ 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 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. ### 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 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. ## 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. In terms of nomenclature, this pair of LocalAttributes consists of one own shared RelationshipAttribute and one peer shared RelationshipAttribute. @@ -112,16 +133,27 @@ In terms of nomenclature, this pair of LocalAttributes consists of one own share ### 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 720660f30..c70d74912 100644 --- a/_docs_integrate/data-model-overview.md +++ b/_docs_integrate/data-model-overview.md @@ -29,25 +29,38 @@ 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: @@ -90,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 | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | @@ -109,7 +126,9 @@ A RelationshipTemplate serves two purposes: ## 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 | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | @@ -134,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 | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | @@ -147,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) @@ -183,7 +208,8 @@ 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 | @@ -231,7 +257,9 @@ Note, however, that at all times there can only be at most one **active Identity # 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: @@ -261,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 | | --------- | --------------------------------------- | ---------------------------------------------------------------- | @@ -309,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 | | --------- | ------------------------------- | ----------------------------------------------------------------- | @@ -336,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 | | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | @@ -517,7 +560,9 @@ AttributeTags occur within the `tagsForAttributeValueTypes` mapping of the [Attr # 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 @@ -540,7 +585,9 @@ You can also put multiple Items into a [RequestItemGroup](#requestitemgroup) in ### 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 @@ -556,7 +603,8 @@ For more information you should check out the section [AuthenticationRequestItem #### 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 | | ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -571,7 +619,8 @@ For more information you should check out the section [ConsentRequestItem of the #### 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 | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -583,7 +632,8 @@ For more information you should check out the section [CreateAttributeRequestIte #### 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 | | -------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -679,7 +729,8 @@ If StringFormFieldSettings are used as `settings` of a [FormFieldRequestItem](#f #### 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 | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -692,7 +743,8 @@ For more information you should check out the section [ProposeAttributeRequestIt #### 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. +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 | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -704,7 +756,8 @@ For more information you should check out the section [ReadAttributeRequestItem #### 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 | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -718,7 +771,8 @@ For more information you should check out the section [ShareAttributeRequestItem #### 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 | | -------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -866,7 +920,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 | | ------- | --------------------- | ----------------------------------------------------------------------- | @@ -884,7 +940,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 | | ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | @@ -954,11 +1011,14 @@ Internally, the succeeded version will then be created at the peer's side as suc ## 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 | | ----- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -969,7 +1029,8 @@ IdentityAttributes describe an Identity itself. Their values are strongly normal ### 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 | | --------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | @@ -982,11 +1043,16 @@ 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 | | --------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -998,7 +1064,11 @@ 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 | | ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | @@ -1032,7 +1102,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 @@ -1043,7 +1114,9 @@ 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 | | ---------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -1054,7 +1127,11 @@ If you want to query RelationshipAttributes the Recipient has in the context of ### 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 | | ---------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -1071,7 +1148,8 @@ If you want to query IdentityAttributes by their content, you can use the `IQLQu ## 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 | | ---------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -1092,7 +1170,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 | | -------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -1110,7 +1189,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 | | ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | diff --git a/_docs_integrate/delete-identities.md b/_docs_integrate/delete-identities.md index 23a5dcebb..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`. +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 @@ -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 9a4fb2ff0..c622cd497 100644 --- a/_docs_integrate/error-codes.md +++ b/_docs_integrate/error-codes.md @@ -23,7 +23,9 @@ 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 | | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/_docs_integrate/establish-relationships.md b/_docs_integrate/establish-relationships.md index cf1e1fa2d..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 `templateId=`. 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 `templateId` 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/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 98b519567..047341358 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. @@ -79,7 +80,8 @@ To do so, execute `POST /api/core/v1/Attributes` with the following payload: {% 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 @@ -148,7 +150,8 @@ 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/core/v1/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/core/v1/Requests/Outgoing/Validate$" %} @@ -177,7 +180,8 @@ Furthermore, we specify an expiration date, which is located in the future, and {% 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 @@ -188,13 +192,17 @@ For this, execute the `GET /api/core/v1/RelationshipTemplates/{id}` route (Accep ### 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 @@ -204,7 +212,8 @@ To do so, we [synchronize updates of the Backbone]({% link _docs_use-cases/use-c {% 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/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. +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/core/v1/Relationships$" %} @@ -223,7 +232,8 @@ Example: } ``` -{% 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 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/core/v1/Relationships/{id}/Accept$" %} @@ -231,7 +241,8 @@ Now the Relationship is in the `Active` state, so we can start to communicate wi 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 @@ -274,7 +285,9 @@ In order to fetch the Message, we need to synchronize the Connector with the Bac {% include rapidoc api_route_regex="^post /api/core/v1/Account/Sync$" %} -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. +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/core/v1/Messages$" %} @@ -282,7 +295,8 @@ 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/migration-from-v4-to-v5.md b/_docs_integrate/migration-from-v4-to-v5.md index 586b38ec6..052bd4594 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-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). - 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). +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. +- 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 %}) @@ -261,7 +339,8 @@ Taking [ThirdPartyRelationshipAttributes]({% link _docs_integrate/data-model-ove 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. 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-shared-versions-of-an-attribute.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 @@ -276,7 +355,8 @@ For this reason, when executing the Connector route `POST /api/v2/Attributes`, w ### 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 index 609db8569..fdd932120 100644 --- a/_docs_integrate/migration-from-v6-to-v7.md +++ b/_docs_integrate/migration-from-v6-to-v7.md @@ -38,9 +38,13 @@ The step-by-step instructions can be consulted to start the migration to version 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. + - 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). @@ -64,7 +68,9 @@ The step-by-step instructions can be consulted to start the migration to version - 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 `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. @@ -92,7 +98,8 @@ The step-by-step instructions can be consulted to start the migration to version - 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. +- 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 @@ -104,7 +111,9 @@ The step-by-step instructions can be consulted to start the migration to version ### 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: +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"; @@ -117,7 +126,8 @@ const connectorClient = ConnectorClient.create({ ### 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: +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. diff --git a/_docs_integrate/propose-attributes-to-peer.md b/_docs_integrate/propose-attributes-to-peer.md index c6108ad9e..4234be089 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,25 +143,36 @@ 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}
@@ -154,7 +187,8 @@ 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). @@ -173,16 +207,26 @@ The `id` of the already existing [LocalAttribute]({% link _docs_integrate/data-m 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 +290,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,7 +346,9 @@ 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 @@ -314,9 +365,13 @@ The `content` of the LocalAttribute is the Attribute that the Recipient has sent 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. -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 13a37936b..2787dee3c 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,38 +156,54 @@ 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, whose underlying `content` is given by the shared Attribute. @@ -183,11 +223,17 @@ In any case, the respective AcceptResponseItem will be included in the `items` p ### 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 { @@ -229,10 +275,13 @@ 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. -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 { @@ -262,7 +311,9 @@ 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).
@@ -277,9 +328,12 @@ A shared `attribute` that can be read from a ReadAttributeAcceptResponseItem is 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). 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. -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 dec7f5929..4957fdf8d 100644 --- a/_docs_integrate/request-and-response-introduction.md +++ b/_docs_integrate/request-and-response-introduction.md @@ -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: @@ -129,7 +137,11 @@ After the Recipient has responded to the FormFieldRequestItem, a suitable [Respo #### 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: @@ -146,7 +158,9 @@ After the Recipient has responded to the ProposeAttributeRequestItem, a suitable #### 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: @@ -163,7 +177,10 @@ After the Recipient has responded to the ReadAttributeRequestItem, a suitable [R #### 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: @@ -178,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: @@ -193,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 [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. +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 { @@ -277,7 +299,9 @@ This section gives an example of a [Request]({% link _docs_integrate/data-model- } ``` -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. @@ -286,13 +310,15 @@ The order in which the RequestItems are rendered corresponds to the order in whi
-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} diff --git a/_docs_integrate/request-one-time-consent-of-peer.md b/_docs_integrate/request-one-time-consent-of-peer.md index e13dbe461..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} @@ -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 @@ -85,12 +95,18 @@ Furthermore, the `requiresInteraction` property could be used to ensure that the } ``` -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 { @@ -114,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..63d115088 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,34 @@ 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 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. ### 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 [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. ## 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 ada24fb24..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=` 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=` 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." %} diff --git a/_docs_integrate/share-attributes-with-peer.md b/_docs_integrate/share-attributes-with-peer.md index 0efc4d897..89f792f51 100644 --- a/_docs_integrate/share-attributes-with-peer.md +++ b/_docs_integrate/share-attributes-with-peer.md @@ -30,14 +30,18 @@ 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 @@ -47,12 +51,16 @@ The latter means that the address of the Sender is contained in the `content.own 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. -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=
` 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=
` 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 | | ------------------------------------------------------------------------------------------------------- | ----------- | :----------------------------------------: | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -114,7 +122,9 @@ 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) 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 a [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) 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). ```jsonc { @@ -172,25 +182,35 @@ 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}
@@ -207,11 +227,17 @@ This will be contained within the `items` property of the [Response]({% link _do ### 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 { @@ -265,12 +291,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,7 +329,9 @@ 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).
@@ -314,9 +346,12 @@ Note that each accepted ShareAttributeRequestItem leads to the creation of an ap 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. -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 39688ee19..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). -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 7491c8cf7..bb3e69ec8 100644 --- a/_docs_integrate/update-attributes-by-succession.md +++ b/_docs_integrate/update-attributes-by-succession.md @@ -33,9 +33,13 @@ 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 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**. 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.