From c091430615a99ab14cb764cc62b7e22e3671c7e4 Mon Sep 17 00:00:00 2001 From: Milena Czierlinski Date: Mon, 30 Oct 2023 15:59:40 +0000 Subject: [PATCH 01/11] feat: add request and response introduction (cherry picked from commit ac2af3548f6670de992e4f6f8efbaff85ae121bf) --- _data/navigation.yml | 5 +- .../request-and-response-introduction.md | 4 +- .../request-and-response-introduction.md | 50 +++++++++++++++++++ ...CreateConsumptionAttributeRequestItem .svg | 1 + 4 files changed, 57 insertions(+), 3 deletions(-) create mode 100644 _includes/scenarios/integrate/request-and-response-introduction.md create mode 100644 assets/images/integrate/Requests - Handling of CreateConsumptionAttributeRequestItem .svg diff --git a/_data/navigation.yml b/_data/navigation.yml index aac23b6a3..bd118194d 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -85,7 +85,10 @@ docs_integrate: # url: /integrate/event-introduction - title: "Use Cases" url: /integrate/use-cases - + - title: Working with requests + children: + - title: "Request and Response introduction" + url: /integrate/request-and-response-introduction - title: Manage Requests children: - title: "Requests over Templates" diff --git a/_docs_integrate/request-and-response-introduction.md b/_docs_integrate/request-and-response-introduction.md index 6a6902c24..1abfe6435 100644 --- a/_docs_integrate/request-and-response-introduction.md +++ b/_docs_integrate/request-and-response-introduction.md @@ -1,8 +1,8 @@ --- # !!! Warning: Do not edit this file; any changes must be replicated in Excel !!! permalink: integrate/request-and-response-introduction -published: false -title: "Request and response introduction" +published: true +title: "Request and Response introduction" type: scenario toc: true properties: diff --git a/_includes/scenarios/integrate/request-and-response-introduction.md b/_includes/scenarios/integrate/request-and-response-introduction.md new file mode 100644 index 000000000..073163316 --- /dev/null +++ b/_includes/scenarios/integrate/request-and-response-introduction.md @@ -0,0 +1,50 @@ +You want to share Attributes with a contact or receive Attributes from them? +You need an authentication or a consent from a peer? +You wish to make edits to a Relationship or ensure the correctness of data? +All of these endeavors and more can be achieved by the means of Requests. +They are the main instrument when it comes to interacting with other Identities going beyond the simple exchange of messages. + +Requests are always associated with a specific Relationship, i.e. they are sent to exactly one other Identity. +Also, Responses are unique. +Once a Request is answered, it cannot be answered again, e.g. on another device, if the App is installed on multiple ones, having all received the Request. +This ensures an unambiguous functioning. + +## Types of Request- and ResponseItems + +The core of a [Request]({% link _docs_integrate/data-model-overview.md %}#request) is the [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitem). +It specifies what you want from the other Identity. +There are many different types all described in detail in the [Requests and RequestItems]({% link _docs_integrate/requests-and-requestitems.md %}) section. +Here, we just want to give a brief overview: + +- [AuthenticationRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#authenticationrequestitem)s can be used to request an authentication, e.g. for a login to a website +- [ConsentRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#consentrequestitem)s can be used to request a consent to an freely configurable text, e.g. to receive a newsletter +- [CreateAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#createattributerequestitem)s can be used to create an Identity- or RelationshipAttribute with a fixed value for a peer, e.g. a certificate +- [FreeTextRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#freetextrequestitem)s can be used to send a free text to a contact, that in turn can accept this with a free text as well +- [ProposeAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#proposeattributerequestitem)s can be used to ask the peer for Attributes, already suggesting answers, e.g. asking for an address and setting the country of the organization as default +- [ReadAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#readattributerequestitem)s can be used to ask a peer for Attributes, e.g. asking for an address +- [ShareAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#shareattributerequestitem)s can be used to share own IdentityAttributes with a contact, e.g. sharing the own DisplayName when requesting a new Relationship + +In case multiple RequestItems should be answered jointly, you can combine them to a [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup). +RequestItems or RequestItemGroups are then embedded in a Request, which can be sent to the other Identity. +This happens either via a Message (see [Requests over Messages]({% link _docs_integrate/requests-over-messages.md %})) or via a Template (see [Requests over Templates]({% link _docs_integrate/requests-over-templates.md %})). + +Once the other Identity receives a Request, they can decide whether they want to accept or reject the corresponding RequestItems or RequestItemGroups. +Consequently, the associated [ResponseItem]({% link _docs_integrate/data-model-overview.md %}#responseitem)s are created. +They can either be a [AcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#acceptresponseitem) or a special variant of it, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) or an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) in case the enmeshed Runtime detects a problem. +If additional information is necessary to accept a Request, e.g. an Attribute is queried with a ReadAttributeRequestItem, it is attached to the AcceptResponseItem. +In the given example, it will be a part of the returned ReadAttributeAcceptResponseItem. +For every RequestItem or RequestItemGroup, exactly one ResponseItem or [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) will be created, respectively. +The [Response]({% link _docs_integrate/data-model-overview.md %}#response), then, is wrapped in a [ResponseWrapper]({% link _docs_integrate/data-model-overview.md %}#responsewrapper), which holds additional information about the corresponding Request, so that it can be processed correctly once it is returned. + +## Example: Request-Response-Process for a CreateAttributeRequestItem + +Let's take a detailed look at an exemplary Request-Response-process for a CreateAttributeRequestItem. +Firstly, the sender creates a Request with a CreateAttributeRequestItem and sends it via a Message to the recipient. +This triggers the creation of a [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest) at their side. +If the recipient accepts the Request and the CreateAttributeRequestItem, a new own [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) will be created with the content of the CreateAttributeRequestItem. +Additionally, a shared LocalAttribute will be created, since this Attribute is shared with a contact, namely the sender of the Request. +Thereafter, a Response is returned to the sender, containing the status `accepted` alongside the corresponding Request. +Then, the sender will save them as a LocalRequest and, like the recipient, create a LocalAttribute with the content of the CreateAttributeRequestItem to store, as well. +The whole process is, also, depicted below. + +[![Request-Response-Process for CreateAttributeRequestItem]( {{ '/assets/images/integrate/Requests - Handling of CreateConsumptionAttributeRequestItem .svg' | relative_url }} )]( {{ '/assets/images/integrate/Requests - Handling of CreateConsumptionAttributeRequestItem .svg' | relative_url }} ) diff --git a/assets/images/integrate/Requests - Handling of CreateConsumptionAttributeRequestItem .svg b/assets/images/integrate/Requests - Handling of CreateConsumptionAttributeRequestItem .svg new file mode 100644 index 000000000..e2f022d13 --- /dev/null +++ b/assets/images/integrate/Requests - Handling of CreateConsumptionAttributeRequestItem .svg @@ -0,0 +1 @@ + \ No newline at end of file From 606221c550d11ad30bb68bbe39af8039c93e4ba1 Mon Sep 17 00:00:00 2001 From: Milena Czierlinski Date: Thu, 2 Nov 2023 11:01:08 +0000 Subject: [PATCH 02/11] fix: integrate comments --- .../request-and-response-introduction.md | 15 +++++++-------- ...se_process-for-CreateAttributeRequestItem.svg} | 0 2 files changed, 7 insertions(+), 8 deletions(-) rename assets/images/integrate/{Requests - Handling of CreateConsumptionAttributeRequestItem .svg => request-and-response_process-for-CreateAttributeRequestItem.svg} (100%) diff --git a/_includes/scenarios/integrate/request-and-response-introduction.md b/_includes/scenarios/integrate/request-and-response-introduction.md index 073163316..e7f13fae9 100644 --- a/_includes/scenarios/integrate/request-and-response-introduction.md +++ b/_includes/scenarios/integrate/request-and-response-introduction.md @@ -2,7 +2,7 @@ You want to share Attributes with a contact or receive Attributes from them? You need an authentication or a consent from a peer? You wish to make edits to a Relationship or ensure the correctness of data? All of these endeavors and more can be achieved by the means of Requests. -They are the main instrument when it comes to interacting with other Identities going beyond the simple exchange of messages. +They are the main instrument when it comes to interacting with other Identities going beyond the simple exchange of `Messages`. Requests are always associated with a specific Relationship, i.e. they are sent to exactly one other Identity. Also, Responses are unique. @@ -24,16 +24,15 @@ Here, we just want to give a brief overview: - [ReadAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#readattributerequestitem)s can be used to ask a peer for Attributes, e.g. asking for an address - [ShareAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#shareattributerequestitem)s can be used to share own IdentityAttributes with a contact, e.g. sharing the own DisplayName when requesting a new Relationship -In case multiple RequestItems should be answered jointly, you can combine them to a [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup). +In case multiple RequestItems should be answered jointly, e.g. to enhance the structure for the user, you can combine them to a [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup). RequestItems or RequestItemGroups are then embedded in a Request, which can be sent to the other Identity. -This happens either via a Message (see [Requests over Messages]({% link _docs_integrate/requests-over-messages.md %})) or via a Template (see [Requests over Templates]({% link _docs_integrate/requests-over-templates.md %})). +This happens either via a Template (see [Requests over Templates]({% link _docs_integrate/requests-over-templates.md %})) or via a Message (see [Requests over Messages]({% link _docs_integrate/requests-over-messages.md %})). Once the other Identity receives a Request, they can decide whether they want to accept or reject the corresponding RequestItems or RequestItemGroups. Consequently, the associated [ResponseItem]({% link _docs_integrate/data-model-overview.md %}#responseitem)s are created. -They can either be a [AcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#acceptresponseitem) or a special variant of it, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) or an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) in case the enmeshed Runtime detects a problem. -If additional information is necessary to accept a Request, e.g. an Attribute is queried with a ReadAttributeRequestItem, it is attached to the AcceptResponseItem. -In the given example, it will be a part of the returned ReadAttributeAcceptResponseItem. -For every RequestItem or RequestItemGroup, exactly one ResponseItem or [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) will be created, respectively. +They can either be [AcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#acceptresponseitem)s, [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem)s or [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem)s, in case the enmeshed Runtime detects a problem. +Additionally, there are specific AcceptResponseItems extending the actual AcceptResponseItem to answer to RequestItems demanding additional information, like the ReadAttributeRequestItem. +For every RequestItem or RequestItemGroup, there will be exactly one ResponseItem or [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) created, respectively. The [Response]({% link _docs_integrate/data-model-overview.md %}#response), then, is wrapped in a [ResponseWrapper]({% link _docs_integrate/data-model-overview.md %}#responsewrapper), which holds additional information about the corresponding Request, so that it can be processed correctly once it is returned. ## Example: Request-Response-Process for a CreateAttributeRequestItem @@ -47,4 +46,4 @@ Thereafter, a Response is returned to the sender, containing the status `accepte Then, the sender will save them as a LocalRequest and, like the recipient, create a LocalAttribute with the content of the CreateAttributeRequestItem to store, as well. The whole process is, also, depicted below. -[![Request-Response-Process for CreateAttributeRequestItem]( {{ '/assets/images/integrate/Requests - Handling of CreateConsumptionAttributeRequestItem .svg' | relative_url }} )]( {{ '/assets/images/integrate/Requests - Handling of CreateConsumptionAttributeRequestItem .svg' | relative_url }} ) +[![Request-Response-Process for CreateAttributeRequestItem]( {{ '/assets/images/integrate/request-and-response_process-for-CreateAttributeRequestItem.svg' | relative_url }} )]( {{ '/assets/images/integrate/request-and-response_process-for-CreateAttributeRequestItem.svg' | relative_url }} ) diff --git a/assets/images/integrate/Requests - Handling of CreateConsumptionAttributeRequestItem .svg b/assets/images/integrate/request-and-response_process-for-CreateAttributeRequestItem.svg similarity index 100% rename from assets/images/integrate/Requests - Handling of CreateConsumptionAttributeRequestItem .svg rename to assets/images/integrate/request-and-response_process-for-CreateAttributeRequestItem.svg From 1179e7ae831bc3d22590448b27267b4467b19cd2 Mon Sep 17 00:00:00 2001 From: Milena Czierlinski Date: Mon, 13 Nov 2023 13:45:58 +0000 Subject: [PATCH 03/11] feat: integrate comments, except examples and graphic --- .../request-and-response-introduction.md | 116 +++++++++++------- 1 file changed, 73 insertions(+), 43 deletions(-) diff --git a/_includes/scenarios/integrate/request-and-response-introduction.md b/_includes/scenarios/integrate/request-and-response-introduction.md index e7f13fae9..8ba94f121 100644 --- a/_includes/scenarios/integrate/request-and-response-introduction.md +++ b/_includes/scenarios/integrate/request-and-response-introduction.md @@ -1,49 +1,79 @@ -You want to share Attributes with a contact or receive Attributes from them? -You need an authentication or a consent from a peer? -You wish to make edits to a Relationship or ensure the correctness of data? -All of these endeavors and more can be achieved by the means of Requests. -They are the main instrument when it comes to interacting with other Identities going beyond the simple exchange of `Messages`. - -Requests are always associated with a specific Relationship, i.e. they are sent to exactly one other Identity. -Also, Responses are unique. -Once a Request is answered, it cannot be answered again, e.g. on another device, if the App is installed on multiple ones, having all received the Request. -This ensures an unambiguous functioning. - -## Types of Request- and ResponseItems - -The core of a [Request]({% link _docs_integrate/data-model-overview.md %}#request) is the [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitem). -It specifies what you want from the other Identity. -There are many different types all described in detail in the [Requests and RequestItems]({% link _docs_integrate/requests-and-requestitems.md %}) section. +Requests are the main instrument in enmeshed to interact with other Identities. +They enable various business processes, e.g. creating, sharing or receiving Attributes, asking a peer for authentication or consent, and much more. +Also, parts of a vaster business process can be implemented with them, like querying all personal information of a user to fill out a tax form. + +Requests are unique between Identities and can only be processed once by a single Identity, even across multiple devices associated with the same Identity. +One Request can have one Response, which responds to the complete Request and contains all the information the requestor needs. +The Request-Response flow allows to establish transactional behavior between Identities. + +Please note that there are some data structures used in the context of enmeshed, that also use the words "Request" and "Response" in their name, but do not correspond to the objects described on this page, e.g. [RelationshipChangeRequest]({% link _docs_integrate/data-model-overview.md %}#relationshipchangerequest) and [RelationshipChangeResponse]({% link _docs_integrate/data-model-overview.md %}#relationshipchangeresponse). + +## Requests + +### Structure of Requests + +A [Request]({% link _docs_integrate/data-model-overview.md %}#request) can be created by an Identity and sent to a peer to exchange information with them. +The prerequisite for this is an already existing Relationship to prevent mischievous usage. +Specifying the exact demands to the peer, [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitem)s are the core of the Request. +In case multiple RequestItems should be answered jointly, e.g. to enhance the structure for the user, they can be combined to a [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup). +After creating the Request, it can be transmitted either via a Template (see [Requests over Templates]({% link _docs_integrate/requests-over-templates.md %})) or via a Message (see [Requests over Messages]({% link _docs_integrate/requests-over-messages.md %})). + +### Types of RequestItems + +To extinguish different scenarios, how you would like to use Requests, there are different types of RequestItems tailored to them. +They are all described in detail on the [Requests and RequestItems]({% link _docs_integrate/requests-and-requestitems.md %}) page. Here, we just want to give a brief overview: - [AuthenticationRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#authenticationrequestitem)s can be used to request an authentication, e.g. for a login to a website -- [ConsentRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#consentrequestitem)s can be used to request a consent to an freely configurable text, e.g. to receive a newsletter +- [ConsentRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#consentrequestitem)s can be used to request a consent to a freely configurable text, e.g. to receive a newsletter - [CreateAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#createattributerequestitem)s can be used to create an Identity- or RelationshipAttribute with a fixed value for a peer, e.g. a certificate -- [FreeTextRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#freetextrequestitem)s can be used to send a free text to a contact, that in turn can accept this with a free text as well +- [FreeTextRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#freetextrequestitem)s can be used to send a free text to a contact, that in turn can accept it with a free text as well - [ProposeAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#proposeattributerequestitem)s can be used to ask the peer for Attributes, already suggesting answers, e.g. asking for an address and setting the country of the organization as default - [ReadAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#readattributerequestitem)s can be used to ask a peer for Attributes, e.g. asking for an address -- [ShareAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#shareattributerequestitem)s can be used to share own IdentityAttributes with a contact, e.g. sharing the own DisplayName when requesting a new Relationship - -In case multiple RequestItems should be answered jointly, e.g. to enhance the structure for the user, you can combine them to a [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup). -RequestItems or RequestItemGroups are then embedded in a Request, which can be sent to the other Identity. -This happens either via a Template (see [Requests over Templates]({% link _docs_integrate/requests-over-templates.md %})) or via a Message (see [Requests over Messages]({% link _docs_integrate/requests-over-messages.md %})). - -Once the other Identity receives a Request, they can decide whether they want to accept or reject the corresponding RequestItems or RequestItemGroups. -Consequently, the associated [ResponseItem]({% link _docs_integrate/data-model-overview.md %}#responseitem)s are created. -They can either be [AcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#acceptresponseitem)s, [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem)s or [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem)s, in case the enmeshed Runtime detects a problem. -Additionally, there are specific AcceptResponseItems extending the actual AcceptResponseItem to answer to RequestItems demanding additional information, like the ReadAttributeRequestItem. -For every RequestItem or RequestItemGroup, there will be exactly one ResponseItem or [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) created, respectively. -The [Response]({% link _docs_integrate/data-model-overview.md %}#response), then, is wrapped in a [ResponseWrapper]({% link _docs_integrate/data-model-overview.md %}#responsewrapper), which holds additional information about the corresponding Request, so that it can be processed correctly once it is returned. - -## Example: Request-Response-Process for a CreateAttributeRequestItem - -Let's take a detailed look at an exemplary Request-Response-process for a CreateAttributeRequestItem. -Firstly, the sender creates a Request with a CreateAttributeRequestItem and sends it via a Message to the recipient. -This triggers the creation of a [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest) at their side. -If the recipient accepts the Request and the CreateAttributeRequestItem, a new own [LocalAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) will be created with the content of the CreateAttributeRequestItem. -Additionally, a shared LocalAttribute will be created, since this Attribute is shared with a contact, namely the sender of the Request. -Thereafter, a Response is returned to the sender, containing the status `accepted` alongside the corresponding Request. -Then, the sender will save them as a LocalRequest and, like the recipient, create a LocalAttribute with the content of the CreateAttributeRequestItem to store, as well. -The whole process is, also, depicted below. - -[![Request-Response-Process for CreateAttributeRequestItem]( {{ '/assets/images/integrate/request-and-response_process-for-CreateAttributeRequestItem.svg' | relative_url }} )]( {{ '/assets/images/integrate/request-and-response_process-for-CreateAttributeRequestItem.svg' | relative_url }} ) +- [ShareAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#shareattributerequestitem)s can be used to share own Attributes with a contact, e.g. the DisplayName when requesting a new Relationship + +### Properties associated with Requests + +Each Request has an unambiguous `id`, enabling a clear assignment. +Also, a date can be specified, at which the Request expires and from when on it can't be answered anymore. +Furthermore, Requests, RequestItems and RequestItemGroups have the properties `title`, `description` and `metadata`. +While the former two may be used to express the demands of the Request in a human-readable manner to the recipient, the latter is meant for developers integrating with enmeshed to provide them with the opportunity to use their own process descriptors. +An example could be a key, coding the content of the Request, which helps to identfify the correct internal process at the time of receiving the Response. +The metadata content is not processed by enmeshed. +RequestItems and RequestItemGroups have the required `mustBeAccepted` property. +If it is enabled, the Request can't be accepted without accepting the respective RequestItems or RequestItemGroups. +Note that the `mustBeAccepted` property of a RequestItem inside a RequestItemGroup will only be assessed, if the RequestItemGroup itself is accepted. +By default RequestItems can be accepted automatically. +However, the sender may enforce a manual acceptance step using `requireManualDecision`. +Depending on the kind of RequestItem, additional properties may be available. + +## Responses + +### Structure of Responses + +Once the other Identity receives a Request, it can decide whether or not to accept it. +If so, a [Response]({% link _docs_integrate/data-model-overview.md %}#response) will be created, containing a [ResponseItem]({% link _docs_integrate/data-model-overview.md %}#responseitem) or [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) for every RequestItem or RequestItemGroup, respectively. +The Response, then, is wrapped in a [ResponseWrapper]({% link _docs_integrate/data-model-overview.md %}#responsewrapper), which holds additional information about the corresponding Request, so that it can be processed correctly once it is returned. + +### Types of ResponseItems + +There are three different categories of ResponseItems. +If a RequestItem is accepted, an [AcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#acceptresponseitem) will be created. +Depending on the kind of RequestItem, it might be a specific AcceptResponseItem, extending the actual AcceptResponseItem to answer to RequestItems demanding additional information. +For example, a ReadAttributeRequestItem is accepted using a [ReadAttributeAcceptResponseItem]({% link _docs_integrate/requests-and-requestitems.md %}#readattributerequestitem-response). +If a RequestItem is rejected, however, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) is created. +Lastly, in case the enmeshed Runtime detects a problem, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) is generated. + +### Properties associated with Responses + +Since each Response is associated with a specific Request, the corresponding `requestId` is indicated in the Response. +Its `result` property declares whether the Request was accepted or rejected. +Also, each ResponseItem has a `result` property, which value depends on the kind of ResponseItem and can either be `Accepted`, `Rejected` or `Error`. +In addition, RejectResponseItems and ErrorResponseItems may have a `code` and a `message` specified, providing more details about the rejection or error. +The ResponseWrapper holds additional information about the Request, namely its ID, the `requestSourceType`, i.e. if the Request was transmitted via a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or a [Message]({% link _docs_integrate/data-model-overview.md %}#message), and the `requestSourceReference`, containing its ID. + +## Some Examples + +
+ +
From 8cb7da7a01b9f7126b7e11e3099027f1b13d1fdd Mon Sep 17 00:00:00 2001 From: Milena Czierlinski Date: Mon, 13 Nov 2023 17:13:05 +0000 Subject: [PATCH 04/11] feat: add examples and graphics --- .../request-and-response-introduction.md | 42 +++++++++++++++---- 1 file changed, 35 insertions(+), 7 deletions(-) diff --git a/_includes/scenarios/integrate/request-and-response-introduction.md b/_includes/scenarios/integrate/request-and-response-introduction.md index 8ba94f121..1a5824dc0 100644 --- a/_includes/scenarios/integrate/request-and-response-introduction.md +++ b/_includes/scenarios/integrate/request-and-response-introduction.md @@ -10,27 +10,28 @@ Please note that there are some data structures used in the context of enmeshed, ## Requests +
+ ### Structure of Requests A [Request]({% link _docs_integrate/data-model-overview.md %}#request) can be created by an Identity and sent to a peer to exchange information with them. -The prerequisite for this is an already existing Relationship to prevent mischievous usage. Specifying the exact demands to the peer, [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitem)s are the core of the Request. In case multiple RequestItems should be answered jointly, e.g. to enhance the structure for the user, they can be combined to a [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup). After creating the Request, it can be transmitted either via a Template (see [Requests over Templates]({% link _docs_integrate/requests-over-templates.md %})) or via a Message (see [Requests over Messages]({% link _docs_integrate/requests-over-messages.md %})). ### Types of RequestItems -To extinguish different scenarios, how you would like to use Requests, there are different types of RequestItems tailored to them. +To extinguish different scenarios how to use Requests, there are various types of RequestItems tailored to them. They are all described in detail on the [Requests and RequestItems]({% link _docs_integrate/requests-and-requestitems.md %}) page. Here, we just want to give a brief overview: - [AuthenticationRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#authenticationrequestitem)s can be used to request an authentication, e.g. for a login to a website -- [ConsentRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#consentrequestitem)s can be used to request a consent to a freely configurable text, e.g. to receive a newsletter +- [ConsentRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#consentrequestitem)s can be used to request consent to a freely configurable text, e.g. to receive a newsletter - [CreateAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#createattributerequestitem)s can be used to create an Identity- or RelationshipAttribute with a fixed value for a peer, e.g. a certificate - [FreeTextRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#freetextrequestitem)s can be used to send a free text to a contact, that in turn can accept it with a free text as well - [ProposeAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#proposeattributerequestitem)s can be used to ask the peer for Attributes, already suggesting answers, e.g. asking for an address and setting the country of the organization as default - [ReadAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#readattributerequestitem)s can be used to ask a peer for Attributes, e.g. asking for an address -- [ShareAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#shareattributerequestitem)s can be used to share own Attributes with a contact, e.g. the DisplayName when requesting a new Relationship +- [ShareAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#shareattributerequestitem)s can be used to share own Attributes with a contact, e.g. the DisplayName ### Properties associated with Requests @@ -49,6 +50,8 @@ Depending on the kind of RequestItem, additional properties may be available. ## Responses +
+ ### Structure of Responses Once the other Identity receives a Request, it can decide whether or not to accept it. @@ -64,16 +67,41 @@ For example, a ReadAttributeRequestItem is accepted using a [ReadAttributeAccept If a RequestItem is rejected, however, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) is created. Lastly, in case the enmeshed Runtime detects a problem, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) is generated. +
+ ### Properties associated with Responses Since each Response is associated with a specific Request, the corresponding `requestId` is indicated in the Response. Its `result` property declares whether the Request was accepted or rejected. -Also, each ResponseItem has a `result` property, which value depends on the kind of ResponseItem and can either be `Accepted`, `Rejected` or `Error`. +Also, each ResponseItem has a `result` property itself, whose value depends on the kind of ResponseItem and can either be `Accepted`, `Rejected` or `Error`. In addition, RejectResponseItems and ErrorResponseItems may have a `code` and a `message` specified, providing more details about the rejection or error. -The ResponseWrapper holds additional information about the Request, namely its ID, the `requestSourceType`, i.e. if the Request was transmitted via a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or a [Message]({% link _docs_integrate/data-model-overview.md %}#message), and the `requestSourceReference`, containing its ID. +The ResponseWrapper holds additional information about the Request, namely its ID, the `requestSourceType`, i.e. if the Request was transmitted via a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or a [Message]({% link _docs_integrate/data-model-overview.md %}#message), and the `requestSourceReference`, containing the respective ID. + +## Examples -## Some Examples +### Required and optional RequestItems + +An organization has a Relationship with a customer and needs their consent to the privacy terms. +Additionally, the organization would like to know, if the customer is interested in optionally receiving a newsletter. +Thus, they send a Request, containing two ConsentRequestItems. +On the one hand, the RequestItem regarding consent to the Privacy Terms has the `mustBeAccepted` flag enabled, indicating that the Request can't be accepted without accepting this item. +On the other hand, the RequestItem regarding the Newsletter has the `mustBeAccepted` flag disabled. +Hence, the customer can freely choose whether or not they would like to give their consent to it. +Let's consider the case the Request and therefore the privacy terms are accepted, but the consent to the newsletter is denied. +The resulting Request-Response flow is depicted in the following graphic. +For simplicity some properties are omitted.
+### Working with RequestItemGroups + +At a job fair a company wants to offer a convenient way to get in touch with interested jobseekers. +For this, they provide a QR-code, linking to a RelationshipTemplate. +In its `content.onNewRelationship` property it holds a Request with two RequestItemGroups. +One of them contains Attributes the company shares with the peer, e.g. the company name. +The other contains Attributes it would like to query from the peer. +In this example they are the given and surname and optionally an e-mail address, following the [Integration example]({% link _docs_integrate/integration-example.md %}). +Now, an interested person can scan the QR-code, provide their information and send their Response inside a RelationshipCreationChangeRequest (note that this is not the kind of Request discussed on this page). +Once the company accepts the new Relationship, they can exchange messages or other data using enmeshed. +
From 9eb76507cf0312620f326bfac13a1bcc6a39dc9a Mon Sep 17 00:00:00 2001 From: Milena Czierlinski Date: Mon, 13 Nov 2023 17:15:33 +0000 Subject: [PATCH 05/11] fix: delete redundant svg --- ...quest-and-response_process-for-CreateAttributeRequestItem.svg | 1 - 1 file changed, 1 deletion(-) delete mode 100644 assets/images/integrate/request-and-response_process-for-CreateAttributeRequestItem.svg diff --git a/assets/images/integrate/request-and-response_process-for-CreateAttributeRequestItem.svg b/assets/images/integrate/request-and-response_process-for-CreateAttributeRequestItem.svg deleted file mode 100644 index e2f022d13..000000000 --- a/assets/images/integrate/request-and-response_process-for-CreateAttributeRequestItem.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file From db202bbf241c3a9d91fab18ec7fd8bf4e36f0669 Mon Sep 17 00:00:00 2001 From: Milena Czierlinski Date: Wed, 15 Nov 2023 14:11:21 +0000 Subject: [PATCH 06/11] fix: activate embedded lucidcharts --- .../integrate/request-and-response-introduction.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/_includes/scenarios/integrate/request-and-response-introduction.md b/_includes/scenarios/integrate/request-and-response-introduction.md index 1a5824dc0..9f2d8d85a 100644 --- a/_includes/scenarios/integrate/request-and-response-introduction.md +++ b/_includes/scenarios/integrate/request-and-response-introduction.md @@ -10,7 +10,7 @@ Please note that there are some data structures used in the context of enmeshed, ## Requests -
+
### Structure of Requests @@ -50,7 +50,7 @@ Depending on the kind of RequestItem, additional properties may be available. ## Responses -
+
### Structure of Responses @@ -67,7 +67,7 @@ For example, a ReadAttributeRequestItem is accepted using a [ReadAttributeAccept If a RequestItem is rejected, however, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) is created. Lastly, in case the enmeshed Runtime detects a problem, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) is generated. -
+
### Properties associated with Responses @@ -91,7 +91,7 @@ Let's consider the case the Request and therefore the privacy terms are accepted The resulting Request-Response flow is depicted in the following graphic. For simplicity some properties are omitted. -
+
### Working with RequestItemGroups @@ -104,4 +104,4 @@ In this example they are the given and surname and optionally an e-mail address, Now, an interested person can scan the QR-code, provide their information and send their Response inside a RelationshipCreationChangeRequest (note that this is not the kind of Request discussed on this page). Once the company accepts the new Relationship, they can exchange messages or other data using enmeshed. -
+
From 14e1b55e989da2bd0b941859c29aca314698b6b0 Mon Sep 17 00:00:00 2001 From: Milena Czierlinski Date: Tue, 28 Nov 2023 10:25:26 +0000 Subject: [PATCH 07/11] feat: add chapter about LocalRequests, LocalResponses --- .../request-and-response-introduction.md | 54 ++++++++++++++++++- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/_includes/scenarios/integrate/request-and-response-introduction.md b/_includes/scenarios/integrate/request-and-response-introduction.md index 9f2d8d85a..0392a48ee 100644 --- a/_includes/scenarios/integrate/request-and-response-introduction.md +++ b/_includes/scenarios/integrate/request-and-response-introduction.md @@ -35,7 +35,7 @@ Here, we just want to give a brief overview: ### Properties associated with Requests -Each Request has an unambiguous `id`, enabling a clear assignment. +A Request can have an unambiguous `id`, enabling a clear assignment, if the Request can be mapped to a specific [LocalRequest]({% link _docs_integrate/data-model-overview.md %}#localrequest). Also, a date can be specified, at which the Request expires and from when on it can't be answered anymore. Furthermore, Requests, RequestItems and RequestItemGroups have the properties `title`, `description` and `metadata`. While the former two may be used to express the demands of the Request in a human-readable manner to the recipient, the latter is meant for developers integrating with enmeshed to provide them with the opportunity to use their own process descriptors. @@ -77,8 +77,58 @@ Also, each ResponseItem has a `result` property itself, whose value depends on t In addition, RejectResponseItems and ErrorResponseItems may have a `code` and a `message` specified, providing more details about the rejection or error. The ResponseWrapper holds additional information about the Request, namely its ID, the `requestSourceType`, i.e. if the Request was transmitted via a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) or a [Message]({% link _docs_integrate/data-model-overview.md %}#message), and the `requestSourceReference`, containing the respective ID. +## LocalRequests and LocalResponses + +Requests and Responses as discussed above refer to the data structures that are exchanged between Identities. +Locally, each Identity stores them in LocalRequests and [LocalResponses]({% link _docs_integrate/data-model-overview.md %}#localresponse). +They contain additional metadata that is distinct for each Identity. +For example, a LocalRequest stores the address of the opposite Identity in the `peer` property and `isOwn` declares whether the Request was sent by you or received from the peer. +Moreover, a timestamp indicates when it was created and the current `status` is saved. +Also, the `id` of a LocalRequest will match its counterpart stored at the other Identity and the exchanged Request, stored in the field `content`, will have the same `id`, too. +The information about its Transport object, i.e. whether the Request was transmitted via Message or RelationshipTemplates and the associated ID, are denoted in the `source` property. +Lastly, as soon as available the corresponding `response` will be stored within the `LocalRequest`, comprising the Response's `content`, the timestamp when it was created and its `source`. + +### Process of sending Requests via Messages + +If you want to send a Request via Message, firstly you need to create a LocalRequest. +Its ID equals the one of the associated Request that is sent in a Message to your peer. +If the peer accepts the Request and reponds to it, at their side a LocalRequest will be created, having the same ID, however, opposite values for the fields `peer` and `isOwn`. +Also, a LocalResponse will be created and stored directly within the LocalRequest. +Then, a Message will transfer the Response wrapped in a ResponseWrapper back to you, where it can be mapped to your initially created LocalRequest. + +TODO: insert picture + +### Process of sending Requests via RelationshipTemplates + +Alternatively, you can transfer Requests via RelationshipTemplates. +To do so, you locally create the RelationshipTemplate and in the process the Request, however, no LocalRequest, yet. +Hence, the Request your peer receives also doesn't have an ID, yet. +Now, there are two possibilities: either you already have a Relationship with the peer or you wish to establish one, given the condition the peer accepts your Request. +For this, you formulate the Request in the `onExistingRelationship` or the `onNewRelationship` property of the RelationshipTemplate, respectively. +Note, however, that the `onNewRelationship` property is required and, therefore, must always be set, in order to avoid unstable behavior, e.g. if someone you don't have a Relationship with yet opens your RelationshipTemplate. + +Firstly, let's consider the case where you already have a Relationship with the peer. +Receiving your RelationshipTemplate, thus, at their side the `onExistingRelationship` property will be processed, containing your Request. +If the peer decides to accept and to respond to the Request, a LocalRequest will be created, comprising the LocalResponse. +Its content, i.e. the Response, is wrapped in a ResponseWrapper and sent via Message back to you. +Only now, a LocalRequest at your side will be created, having the same ID like its counterpart at your peer's side, since it was transmitted within the Response. +Also, the LocalResponse is stored directly within the LocalRequest, so that the LocalRequest you just created already has the status `accepted`. + +TODO: insert picture + +In the case where you don't have a Relationship with the peer yet, the `onNewRelationship` property of the RelationshipTemplate will be processed. +If the peer decides to accept and to respond to your Request, again a LocalRequest and LocalResponse will be created at their side. +However, the returned data differ. +Instead of a ResponseWrapper inside a Message, a Relationship is returned which is in the status `pending` for now. +It contains the RelationshipTemplate, as well as the changes the peer made to it, i.e. the created Request and Response. +Only after you accept the RelationshipCreationChangeRequest (not the kind of Request discussed on this page), the LocalRequest with LocalResponse is created at your side and the peer will receive the information about the status change via a `consumption.incomingRequestStatusChenged` [event]({% link _docs_integrate/connector-events.md %}). + +TODO: insert picture + ## Examples +TODO: Rework examples to include Message/RelationshipTemplate and LocalRequests/LocalResponses + ### Required and optional RequestItems An organization has a Relationship with a customer and needs their consent to the privacy terms. @@ -101,7 +151,7 @@ In its `content.onNewRelationship` property it holds a Request with two RequestI One of them contains Attributes the company shares with the peer, e.g. the company name. The other contains Attributes it would like to query from the peer. In this example they are the given and surname and optionally an e-mail address, following the [Integration example]({% link _docs_integrate/integration-example.md %}). -Now, an interested person can scan the QR-code, provide their information and send their Response inside a RelationshipCreationChangeRequest (note that this is not the kind of Request discussed on this page). +Now, an interested person can scan the QR-code, provide their information and send their Response inside a RelationshipCreationChangeRequest (note that this itself is not the kind of Request discussed on this page, however internally a LocalRequest is created and responded to right away). Once the company accepts the new Relationship, they can exchange messages or other data using enmeshed.
From e991b9f52e14914b3e1354dfffcfc9312898c3a9 Mon Sep 17 00:00:00 2001 From: Milena Czierlinski Date: Tue, 28 Nov 2023 16:30:47 +0000 Subject: [PATCH 08/11] feat: small adjustments --- .../request-and-response-introduction.md | 28 +++++++------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/_includes/scenarios/integrate/request-and-response-introduction.md b/_includes/scenarios/integrate/request-and-response-introduction.md index 0392a48ee..4793b83b4 100644 --- a/_includes/scenarios/integrate/request-and-response-introduction.md +++ b/_includes/scenarios/integrate/request-and-response-introduction.md @@ -10,7 +10,7 @@ Please note that there are some data structures used in the context of enmeshed, ## Requests -
+
### Structure of Requests @@ -50,7 +50,7 @@ Depending on the kind of RequestItem, additional properties may be available. ## Responses -
+
### Structure of Responses @@ -96,48 +96,40 @@ If the peer accepts the Request and reponds to it, at their side a LocalRequest Also, a LocalResponse will be created and stored directly within the LocalRequest. Then, a Message will transfer the Response wrapped in a ResponseWrapper back to you, where it can be mapped to your initially created LocalRequest. -TODO: insert picture - ### Process of sending Requests via RelationshipTemplates Alternatively, you can transfer Requests via RelationshipTemplates. To do so, you locally create the RelationshipTemplate and in the process the Request, however, no LocalRequest, yet. Hence, the Request your peer receives also doesn't have an ID, yet. Now, there are two possibilities: either you already have a Relationship with the peer or you wish to establish one, given the condition the peer accepts your Request. -For this, you formulate the Request in the `onExistingRelationship` or the `onNewRelationship` property of the RelationshipTemplate, respectively. -Note, however, that the `onNewRelationship` property is required and, therefore, must always be set, in order to avoid unstable behavior, e.g. if someone you don't have a Relationship with yet opens your RelationshipTemplate. +For this, you formulate the Request in the `content.onExistingRelationship` or the `content.onNewRelationship` property of the RelationshipTemplate, respectively. +Note, however, that the `content.onNewRelationship` property is required and, therefore, must always be set, in order to avoid unstable behavior, e.g. if someone you don't have a Relationship with yet opens your RelationshipTemplate. Firstly, let's consider the case where you already have a Relationship with the peer. -Receiving your RelationshipTemplate, thus, at their side the `onExistingRelationship` property will be processed, containing your Request. +Receiving your RelationshipTemplate, thus, at their side the `content.onExistingRelationship` property will be processed, containing your Request. If the peer decides to accept and to respond to the Request, a LocalRequest will be created, comprising the LocalResponse. Its content, i.e. the Response, is wrapped in a ResponseWrapper and sent via Message back to you. Only now, a LocalRequest at your side will be created, having the same ID like its counterpart at your peer's side, since it was transmitted within the Response. Also, the LocalResponse is stored directly within the LocalRequest, so that the LocalRequest you just created already has the status `accepted`. -TODO: insert picture - -In the case where you don't have a Relationship with the peer yet, the `onNewRelationship` property of the RelationshipTemplate will be processed. +In the case where you don't have a Relationship with the peer yet, the `content.onNewRelationship` property of the RelationshipTemplate will be processed. If the peer decides to accept and to respond to your Request, again a LocalRequest and LocalResponse will be created at their side. However, the returned data differ. Instead of a ResponseWrapper inside a Message, a Relationship is returned which is in the status `pending` for now. It contains the RelationshipTemplate, as well as the changes the peer made to it, i.e. the created Request and Response. -Only after you accept the RelationshipCreationChangeRequest (not the kind of Request discussed on this page), the LocalRequest with LocalResponse is created at your side and the peer will receive the information about the status change via a `consumption.incomingRequestStatusChenged` [event]({% link _docs_integrate/connector-events.md %}). - -TODO: insert picture +Only after you accept the RelationshipCreationChangeRequest (not the kind of Request discussed on this page), the LocalRequest with LocalResponse is created at your side and the peer will receive the information about the status change via a `consumption.incomingRequestStatusChanged` [event]({% link _docs_integrate/connector-events.md %}). ## Examples -TODO: Rework examples to include Message/RelationshipTemplate and LocalRequests/LocalResponses - ### Required and optional RequestItems An organization has a Relationship with a customer and needs their consent to the privacy terms. Additionally, the organization would like to know, if the customer is interested in optionally receiving a newsletter. -Thus, they send a Request, containing two ConsentRequestItems. +Thus, they send a Request via Message, containing two ConsentRequestItems. On the one hand, the RequestItem regarding consent to the Privacy Terms has the `mustBeAccepted` flag enabled, indicating that the Request can't be accepted without accepting this item. On the other hand, the RequestItem regarding the Newsletter has the `mustBeAccepted` flag disabled. Hence, the customer can freely choose whether or not they would like to give their consent to it. -Let's consider the case the Request and therefore the privacy terms are accepted, but the consent to the newsletter is denied. +Let's consider the case the Request and, therefore, the privacy terms are accepted, but the consent to the newsletter is denied. The resulting Request-Response flow is depicted in the following graphic. For simplicity some properties are omitted. @@ -151,7 +143,7 @@ In its `content.onNewRelationship` property it holds a Request with two RequestI One of them contains Attributes the company shares with the peer, e.g. the company name. The other contains Attributes it would like to query from the peer. In this example they are the given and surname and optionally an e-mail address, following the [Integration example]({% link _docs_integrate/integration-example.md %}). -Now, an interested person can scan the QR-code, provide their information and send their Response inside a RelationshipCreationChangeRequest (note that this itself is not the kind of Request discussed on this page, however internally a LocalRequest is created and responded to right away). +Now, an interested person can scan the QR-code, provide their information and send their Response inside a RelationshipCreationChangeRequest. Once the company accepts the new Relationship, they can exchange messages or other data using enmeshed.
From 66e810135a9f950534288e55e83d5214b9d53a6d Mon Sep 17 00:00:00 2001 From: Milena Czierlinski Date: Fri, 12 Jan 2024 14:55:01 +0000 Subject: [PATCH 09/11] feat: adjust to changes in data model overview --- .../request-and-response-introduction.md | 42 ++++++++++--------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/_includes/scenarios/integrate/request-and-response-introduction.md b/_includes/scenarios/integrate/request-and-response-introduction.md index 4793b83b4..f0cca83af 100644 --- a/_includes/scenarios/integrate/request-and-response-introduction.md +++ b/_includes/scenarios/integrate/request-and-response-introduction.md @@ -15,7 +15,7 @@ Please note that there are some data structures used in the context of enmeshed, ### Structure of Requests A [Request]({% link _docs_integrate/data-model-overview.md %}#request) can be created by an Identity and sent to a peer to exchange information with them. -Specifying the exact demands to the peer, [RequestItem]({% link _docs_integrate/data-model-overview.md %}#requestitem)s are the core of the Request. +Specifying the exact demands to the peer, [RequestItems]({% link _docs_integrate/data-model-overview.md %}#requestitems) are the core of the Request. In case multiple RequestItems should be answered jointly, e.g. to enhance the structure for the user, they can be combined to a [RequestItemGroup]({% link _docs_integrate/data-model-overview.md %}#requestitemgroup). After creating the Request, it can be transmitted either via a Template (see [Requests over Templates]({% link _docs_integrate/requests-over-templates.md %})) or via a Message (see [Requests over Messages]({% link _docs_integrate/requests-over-messages.md %})). @@ -25,15 +25,16 @@ To extinguish different scenarios how to use Requests, there are various types o They are all described in detail on the [Requests and RequestItems]({% link _docs_integrate/requests-and-requestitems.md %}) page. Here, we just want to give a brief overview: -- [AuthenticationRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#authenticationrequestitem)s can be used to request an authentication, e.g. for a login to a website -- [ConsentRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#consentrequestitem)s can be used to request consent to a freely configurable text, e.g. to receive a newsletter -- [CreateAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#createattributerequestitem)s can be used to create an Identity- or RelationshipAttribute with a fixed value for a peer, e.g. a certificate -- [FreeTextRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#freetextrequestitem)s can be used to send a free text to a contact, that in turn can accept it with a free text as well -- [ProposeAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#proposeattributerequestitem)s can be used to ask the peer for Attributes, already suggesting answers, e.g. asking for an address and setting the country of the organization as default -- [ReadAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#readattributerequestitem)s can be used to ask a peer for Attributes, e.g. asking for an address -- [ShareAttributeRequestItem]({% link _docs_integrate/requests-and-requestitems.md %}#shareattributerequestitem)s can be used to share own Attributes with a contact, e.g. the DisplayName +- [AuthenticationRequestItem]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem)s can be used to request an authentication, e.g. for a login to a website +- [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem)s can be used to request consent to a freely configurable text, e.g. to receive a newsletter +- [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem)s can be used to create an Identity- or RelationshipAttribute with a fixed value for a peer, e.g. a certificate +- [FreeTextRequestItem]({% link _docs_integrate/data-model-overview.md %}#freetextrequestitem)s can be used to send a free text to a contact, that in turn can accept it with a free text as well +- [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem)s can be used to ask the peer for Attributes, already suggesting answers, e.g. asking for an address and setting the country of the organization as default +- [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem)s can be used to ask a peer for Attributes, e.g. asking for an address +- [RegisterAttributeListenerRequestItem]({% link _docs_integrate/data-model-overview.md %}#registerattributelistenerrequestitem)s can be used to create LocalAttributeListeners, e.g. to be informed about the creation of a specific RelationshipAttribute of a partner organization +- [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem)s can be used to share own Attributes with a contact, e.g. the DisplayName -### Properties associated with Requests + ## Responses @@ -54,33 +55,36 @@ Depending on the kind of RequestItem, additional properties may be available. ### Structure of Responses -Once the other Identity receives a Request, it can decide whether or not to accept it. -If so, a [Response]({% link _docs_integrate/data-model-overview.md %}#response) will be created, containing a [ResponseItem]({% link _docs_integrate/data-model-overview.md %}#responseitem) or [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) for every RequestItem or RequestItemGroup, respectively. -The Response, then, is wrapped in a [ResponseWrapper]({% link _docs_integrate/data-model-overview.md %}#responsewrapper), which holds additional information about the corresponding Request, so that it can be processed correctly once it is returned. +Once the other Identity receives a Request, they can decide whether to accept or reject it. +Then, a [Response]({% link _docs_integrate/data-model-overview.md %}#response) will be created, containing a [ResponseItem]({% link _docs_integrate/data-model-overview.md %}#responseitem) or [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) for every RequestItem or RequestItemGroup, respectively. +The kind of ResponseItem depends on the decision of the Recipient, as well as on the kind of RequestItem. + + ### Types of ResponseItems There are three different categories of ResponseItems. If a RequestItem is accepted, an [AcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#acceptresponseitem) will be created. Depending on the kind of RequestItem, it might be a specific AcceptResponseItem, extending the actual AcceptResponseItem to answer to RequestItems demanding additional information. -For example, a ReadAttributeRequestItem is accepted using a [ReadAttributeAcceptResponseItem]({% link _docs_integrate/requests-and-requestitems.md %}#readattributerequestitem-response). -If a RequestItem is rejected, however, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) is created. -Lastly, in case the enmeshed Runtime detects a problem, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) is generated. +For example, a ReadAttributeRequestItem is accepted using a [ReadAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#readattributeacceptresponseitem).
-### Properties associated with Responses +If a RequestItem is rejected, however, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) is created. +Lastly, in case the enmeshed Runtime detects a problem, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) is generated. + + ## LocalRequests and LocalResponses Requests and Responses as discussed above refer to the data structures that are exchanged between Identities. -Locally, each Identity stores them in LocalRequests and [LocalResponses]({% link _docs_integrate/data-model-overview.md %}#localresponse). +Locally, each Identity stores them in [LocalRequests]({% link _docs_integrate/data-model-overview.md %}#localrequest) and [LocalResponses]({% link _docs_integrate/data-model-overview.md %}#localresponse). They contain additional metadata that is distinct for each Identity. For example, a LocalRequest stores the address of the opposite Identity in the `peer` property and `isOwn` declares whether the Request was sent by you or received from the peer. Moreover, a timestamp indicates when it was created and the current `status` is saved. From 4e68220c7c5f34cfca97b4f0c34adab6c14eb9f0 Mon Sep 17 00:00:00 2001 From: Milena Czierlinski Date: Mon, 15 Jan 2024 11:26:00 +0000 Subject: [PATCH 10/11] feat: rephrase several sections --- .../request-and-response-introduction.md | 81 ++++++++----------- 1 file changed, 34 insertions(+), 47 deletions(-) diff --git a/_includes/scenarios/integrate/request-and-response-introduction.md b/_includes/scenarios/integrate/request-and-response-introduction.md index f0cca83af..88c3d9ddd 100644 --- a/_includes/scenarios/integrate/request-and-response-introduction.md +++ b/_includes/scenarios/integrate/request-and-response-introduction.md @@ -2,11 +2,11 @@ Requests are the main instrument in enmeshed to interact with other Identities. They enable various business processes, e.g. creating, sharing or receiving Attributes, asking a peer for authentication or consent, and much more. Also, parts of a vaster business process can be implemented with them, like querying all personal information of a user to fill out a tax form. -Requests are unique between Identities and can only be processed once by a single Identity, even across multiple devices associated with the same Identity. -One Request can have one Response, which responds to the complete Request and contains all the information the requestor needs. +Requests are unique between Identities and can only be processed once by a single Identity, even across multiple devices associated with them. +Each Request can only have a single Response, which responds to the complete Request and contains all the information the requestor needs. The Request-Response flow allows to establish transactional behavior between Identities. -Please note that there are some data structures used in the context of enmeshed, that also use the words "Request" and "Response" in their name, but do not correspond to the objects described on this page, e.g. [RelationshipChangeRequest]({% link _docs_integrate/data-model-overview.md %}#relationshipchangerequest) and [RelationshipChangeResponse]({% link _docs_integrate/data-model-overview.md %}#relationshipchangeresponse). +Please note that there are some data structures used in the context of enmeshed, that also use the terms "Request" and "Response" in their name, but do not correspond to the objects described on this page, e.g. [RelationshipChangeRequest]({% link _docs_integrate/data-model-overview.md %}#relationshipchangerequest) and [RelationshipChangeResponse]({% link _docs_integrate/data-model-overview.md %}#relationshipchangeresponse). ## Requests @@ -21,6 +21,8 @@ After creating the Request, it can be transmitted either via a Template (see [Re ### Types of RequestItems + + To extinguish different scenarios how to use Requests, there are various types of RequestItems tailored to them. They are all described in detail on the [Requests and RequestItems]({% link _docs_integrate/requests-and-requestitems.md %}) page. Here, we just want to give a brief overview: @@ -34,21 +36,6 @@ Here, we just want to give a brief overview: - [RegisterAttributeListenerRequestItem]({% link _docs_integrate/data-model-overview.md %}#registerattributelistenerrequestitem)s can be used to create LocalAttributeListeners, e.g. to be informed about the creation of a specific RelationshipAttribute of a partner organization - [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem)s can be used to share own Attributes with a contact, e.g. the DisplayName - - ## Responses
@@ -59,73 +46,73 @@ Once the other Identity receives a Request, they can decide whether to accept or Then, a [Response]({% link _docs_integrate/data-model-overview.md %}#response) will be created, containing a [ResponseItem]({% link _docs_integrate/data-model-overview.md %}#responseitem) or [ResponseItemGroup]({% link _docs_integrate/data-model-overview.md %}#responseitemgroup) for every RequestItem or RequestItemGroup, respectively. The kind of ResponseItem depends on the decision of the Recipient, as well as on the kind of RequestItem. - - ### Types of ResponseItems There are three different categories of ResponseItems. If a RequestItem is accepted, an [AcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#acceptresponseitem) will be created. -Depending on the kind of RequestItem, it might be a specific AcceptResponseItem, extending the actual AcceptResponseItem to answer to RequestItems demanding additional information. -For example, a ReadAttributeRequestItem is accepted using a [ReadAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#readattributeacceptresponseitem). +Depending on the kind of RequestItem, it might be a specific AcceptResponseItem, extending the base AcceptResponseItem to answer to RequestItems demanding additional information. +For example, a ReadAttributeRequestItem is accepted using a [ReadAttributeAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#readattributeacceptresponseitem), additionally transmitting information about the respective Attribute.
If a RequestItem is rejected, however, a [RejectResponseItem]({% link _docs_integrate/data-model-overview.md %}#rejectresponseitem) is created. Lastly, in case the enmeshed Runtime detects a problem, an [ErrorResponseItem]({% link _docs_integrate/data-model-overview.md %}#errorresponseitem) is generated. +It will never be created manually. - +## Request-Response flow -## LocalRequests and LocalResponses +### LocalRequests and LocalResponses Requests and Responses as discussed above refer to the data structures that are exchanged between Identities. Locally, each Identity stores them in [LocalRequests]({% link _docs_integrate/data-model-overview.md %}#localrequest) and [LocalResponses]({% link _docs_integrate/data-model-overview.md %}#localresponse). -They contain additional metadata that is distinct for each Identity. -For example, a LocalRequest stores the address of the opposite Identity in the `peer` property and `isOwn` declares whether the Request was sent by you or received from the peer. -Moreover, a timestamp indicates when it was created and the current `status` is saved. -Also, the `id` of a LocalRequest will match its counterpart stored at the other Identity and the exchanged Request, stored in the field `content`, will have the same `id`, too. -The information about its Transport object, i.e. whether the Request was transmitted via Message or RelationshipTemplates and the associated ID, are denoted in the `source` property. -Lastly, as soon as available the corresponding `response` will be stored within the `LocalRequest`, comprising the Response's `content`, the timestamp when it was created and its `source`. +Note that the LocalResponse is stored within the respective LocalRequest, besides properties that are common for both peers like the [LocalRequestStatus]({% link _docs_integrate/data-model-overview.md %}#localrequeststatus) and others that are distinct for each Identity, e.g. the address of the peer or whether the Request was sent by you or received from the peer. -### Process of sending Requests via Messages +### Sending Requests via Messages -If you want to send a Request via Message, firstly you need to create a LocalRequest. -Its ID equals the one of the associated Request that is sent in a Message to your peer. +Requests can only be send via Message, if you already have an active Relationship with the recipient. +Otherwise, you need to utilize a [RelationshipTemplate](#sending-requests-via-relationshiptemplates). +{: .notice--info} + +If you want to send a [Request via Message]({% link _docs_integrate/requests-over-messages.md %}), firstly you need to create a LocalRequest. +Its ID equals the one of the associated Request that is sent in a [Message]({% link _docs_integrate/data-model-overview.md %}#message) to your peer. If the peer accepts the Request and reponds to it, at their side a LocalRequest will be created, having the same ID, however, opposite values for the fields `peer` and `isOwn`. Also, a LocalResponse will be created and stored directly within the LocalRequest. -Then, a Message will transfer the Response wrapped in a ResponseWrapper back to you, where it can be mapped to your initially created LocalRequest. +Then, a Message will transfer the Response wrapped in a [ResponseWrapper]({% link _docs_integrate/data-model-overview.md %}#responsewrapper) back to you, where it can be mapped to your initially created LocalRequest. + +You can find an [example for the Request-Response flow via Message](#working-with-required-and-optional-requestitems) below. -### Process of sending Requests via RelationshipTemplates +### Sending Requests via RelationshipTemplates -Alternatively, you can transfer Requests via RelationshipTemplates. -To do so, you locally create the RelationshipTemplate and in the process the Request, however, no LocalRequest, yet. +If you don't have a Relationship with the Recipient yet, the Request needs to be formulated within the `onNewRelationship` property of the [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent). +Otherwise, utilize the `onExistingRelationship` property. +{: .notice--info} + +Alternatively, you can transfer [Requests via RelationshipTemplates]({% link _docs_integrate/requests-over-templates.md %}). +To do so, you locally create the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) and in the process the Request, however, no LocalRequest will be created, yet. Hence, the Request your peer receives also doesn't have an ID, yet. Now, there are two possibilities: either you already have a Relationship with the peer or you wish to establish one, given the condition the peer accepts your Request. For this, you formulate the Request in the `content.onExistingRelationship` or the `content.onNewRelationship` property of the RelationshipTemplate, respectively. -Note, however, that the `content.onNewRelationship` property is required and, therefore, must always be set, in order to avoid unstable behavior, e.g. if someone you don't have a Relationship with yet opens your RelationshipTemplate. +Note, however, that the `content.onNewRelationship` property is required and, therefore, must always be set, in order to avoid unstable behavior, if someone you don't have a Relationship with opens the RelationshipTemplate. -Firstly, let's consider the case where you already have a Relationship with the peer. +Firstly, let's consider the case you already have a Relationship with the peer. Receiving your RelationshipTemplate, thus, at their side the `content.onExistingRelationship` property will be processed, containing your Request. If the peer decides to accept and to respond to the Request, a LocalRequest will be created, comprising the LocalResponse. Its content, i.e. the Response, is wrapped in a ResponseWrapper and sent via Message back to you. Only now, a LocalRequest at your side will be created, having the same ID like its counterpart at your peer's side, since it was transmitted within the Response. Also, the LocalResponse is stored directly within the LocalRequest, so that the LocalRequest you just created already has the status `accepted`. -In the case where you don't have a Relationship with the peer yet, the `content.onNewRelationship` property of the RelationshipTemplate will be processed. +In case you don't have a Relationship with the peer yet, opening the RelationshipTemplate, its `content.onNewRelationship` property will be processed. If the peer decides to accept and to respond to your Request, again a LocalRequest and LocalResponse will be created at their side. However, the returned data differ. Instead of a ResponseWrapper inside a Message, a Relationship is returned which is in the status `pending` for now. It contains the RelationshipTemplate, as well as the changes the peer made to it, i.e. the created Request and Response. Only after you accept the RelationshipCreationChangeRequest (not the kind of Request discussed on this page), the LocalRequest with LocalResponse is created at your side and the peer will receive the information about the status change via a `consumption.incomingRequestStatusChanged` [event]({% link _docs_integrate/connector-events.md %}). +You can find an [example for the Request-Response flow via RelationshipTemplate](#working-with-requestitemgroups) below. + ## Examples -### Required and optional RequestItems +### Working with required and optional RequestItems An organization has a Relationship with a customer and needs their consent to the privacy terms. Additionally, the organization would like to know, if the customer is interested in optionally receiving a newsletter. From a73316c30b0d6abec53bddfc816aeaa3a31fb4d4 Mon Sep 17 00:00:00 2001 From: Milena Czierlinski Date: Mon, 15 Jan 2024 11:49:27 +0000 Subject: [PATCH 11/11] feat: add more information for individual RequestItems --- .../request-and-response-introduction.md | 98 ++++++++++++++++--- 1 file changed, 85 insertions(+), 13 deletions(-) diff --git a/_includes/scenarios/integrate/request-and-response-introduction.md b/_includes/scenarios/integrate/request-and-response-introduction.md index 88c3d9ddd..438231815 100644 --- a/_includes/scenarios/integrate/request-and-response-introduction.md +++ b/_includes/scenarios/integrate/request-and-response-introduction.md @@ -21,20 +21,92 @@ After creating the Request, it can be transmitted either via a Template (see [Re ### Types of RequestItems - - To extinguish different scenarios how to use Requests, there are various types of RequestItems tailored to them. -They are all described in detail on the [Requests and RequestItems]({% link _docs_integrate/requests-and-requestitems.md %}) page. -Here, we just want to give a brief overview: - -- [AuthenticationRequestItem]({% link _docs_integrate/data-model-overview.md %}#authenticationrequestitem)s can be used to request an authentication, e.g. for a login to a website -- [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem)s can be used to request consent to a freely configurable text, e.g. to receive a newsletter -- [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem)s can be used to create an Identity- or RelationshipAttribute with a fixed value for a peer, e.g. a certificate -- [FreeTextRequestItem]({% link _docs_integrate/data-model-overview.md %}#freetextrequestitem)s can be used to send a free text to a contact, that in turn can accept it with a free text as well -- [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem)s can be used to ask the peer for Attributes, already suggesting answers, e.g. asking for an address and setting the country of the organization as default -- [ReadAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem)s can be used to ask a peer for Attributes, e.g. asking for an address -- [RegisterAttributeListenerRequestItem]({% link _docs_integrate/data-model-overview.md %}#registerattributelistenerrequestitem)s can be used to create LocalAttributeListeners, e.g. to be informed about the creation of a specific RelationshipAttribute of a partner organization -- [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem)s can be used to share own Attributes with a contact, e.g. the DisplayName + +#### 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. + +Examples: + +- Authentication for a login to a website +- Authentication for opening a door + +#### ConsentRequestItem + +With the [ConsentRequestItem]({% link _docs_integrate/data-model-overview.md %}#consentrequestitem) it is possible to request a consent of the peer to an arbitrary text and thus reach agreement on a certain non machine-processable context. + +To request an accept/reject decision from a peer to a free text, the ConsentRequestItem is used. + +Please do not use the ConsentRequestItem to submit tons of text to the peer Identity. It is meant to be a short consent or summary the user agrees to. Please move longer text to external websites. +The ConsentRequestItem is also not meant for contractual agreements. +{: .notice--info} + +Examples: + +- "I hereby confirm that I have read the privacy terms of this cloud service and agree to them." +- "The provided EULA has been read and agreed to." +- "Yes, I have backed up all of my data of this PC and you can wipe it." +- "I opt in to the newsletter." + +#### CreateAttributeRequestItem + +If you want to create Identity- 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. + +Examples: + +- Share the corporate E-Mail Address of the peer to the peer +- Send a certificate of the peer to the peer, so that the peer is able to easily share it +- Create a RelationshipAttribute for the peer + +#### FreeTextRequestItem + +With the [FreeTextRequestItem]({% link _docs_integrate/data-model-overview.md %}#freetextrequestitem) it is possible to send a free text to the peer. The peer itself can accept this with a free text as well. + +#### ProposeAttributeRequestItem + +The [ProposeAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#proposeattributerequestitem) is a combination of [ReadAttributeRequestItem](#readattributerequestitem) and [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. + +Examples: + +- Onboard an existing customer to enmeshed and propose the known private Attributes, like its name or address. +- Ask the user if a newsletter would be of interest and propose the opt-in. This could be stored as a RelationshipAttribute with owner = recipient and could then be changed by the recipient at will. + +#### 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. + +Examples: + +- Optional query of the BirthDate, to congratulate on birthdays +- Required query of the Age, to check if alcohol may be bought +- Required query of the StreetAddress, to send an invoice to the recipient + +#### RegisterAttributeListenerRequestItem + +This item is used to register a [Listener]({% link _docs_integrate/data-model-overview.md %}#localattributelistener) for a specific Attribute. The Listener will create a Request in status `Draft` if an Attribute was created that matches the given query and the user is able to send the Request to the creator of the [RegisterAttributeListenerRequestItem]({% link _docs_integrate/data-model-overview.md %}#registerattributelistenerrequestitem). + +Examples: + +- Asking for a specific RelationshipAttribute of a partner organization. + +#### 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. + +Examples: + +- Share own DisplayName. +- Share own Address. +- Share customer number of company A with company B. ## Responses