Integrate enmeshed

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 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 terms “Request” and “Response” in their name, but do not correspond to the objects described on this page, e.g. RelationshipChangeRequest and RelationshipChangeResponse.

Requests

Structure of Requests

A Request can be created by an Identity and sent to a peer to exchange information with them. Specifying the exact demands to the peer, 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. After creating the Request, it can be transmitted either via a Template (see Requests via RelationshipTemplates) or via a Message (see Requests via Messages).

Types of RequestItems

To extinguish different scenarios how to use Requests, there are various types of RequestItems tailored to them.

AuthenticationRequestItem

With the 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.

Depending on whether the AuthenticationRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it:

After the Recipient has responded to the AuthenticationRequestItem, a suitable ResponseItem is generated and transferred to the Sender of the Request:

ConsentRequestItem

With the 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.

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.

Possible examples are:

  • “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.”

Depending on whether the ConsentRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it:

After the Recipient has responded to the ConsentRequestItem, a suitable ResponseItem is generated and transferred to the Sender of the Request:

CreateAttributeRequestItem

If you want to create IdentityAttributes or RelationshipAttributes for the peer, the CreateAttributeRequestItem can be used. Please have a look at the 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 guide.

Depending on whether the CreateAttributeRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it:

After the Recipient has responded to the CreateAttributeRequestItem, a suitable ResponseItem is generated and transferred to the Sender of the Request:

DeleteAttributeRequestItem

If you want to request the deletion of an own Attribute from a peer, the DeleteAttributeRequestItem must be used.

Depending on whether the DeleteAttributeRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it:

After the Recipient has responded to the DeleteAttributeRequestItem, a suitable ResponseItem is generated and transferred to the Sender of the Request:

FreeTextRequestItem

With the FreeTextRequestItem it is possible to send a free text to the peer. The peer itself can accept this with a free text as well.

Depending on whether the FreeTextRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it:

After the Recipient has responded to the FreeTextRequestItem, a suitable ResponseItem is generated and transferred to the Sender of the Request:

ProposeAttributeRequestItem

The ProposeAttributeRequestItem is a combination of a ReadAttributeRequestItem and a 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 guide.

Depending on whether the ProposeAttributeRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it:

After the Recipient has responded to the ProposeAttributeRequestItem, a suitable ResponseItem is generated and transferred to the Sender of the Request:

ReadAttributeRequestItem

If you want to query an Identity’s Attributes this is done with the 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 guide.

Depending on whether the ReadAttributeRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it:

After the Recipient has responded to the ReadAttributeRequestItem, a suitable ResponseItem is generated and transferred to the Sender of the Request:

RegisterAttributeListenerRequestItem

This item is used to register a Listener 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. Possible examples are:

  • Asking for a specific RelationshipAttribute of a partner organization.

Depending on whether the RegisterAttributeListenerRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it:

After the Recipient has responded to the RegisterAttributeListenerRequestItem, a suitable ResponseItem is generated and transferred to the Sender of the Request:

ShareAttributeRequestItem

If you want to share the own DisplayName and possibly other Attributes this is done with the 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 guide.

Depending on whether the ShareAttributeRequestItem is to be accepted or rejected, its Recipient has different parameters to choose from for responding to it:

After the Recipient has responded to the ShareAttributeRequestItem, a suitable ResponseItem is generated and transferred to the Sender of the Request:

Responses

Structure of Responses

Once the other Identity receives a Request, they can decide whether to accept or reject it. Then, a Response will be created, containing a ResponseItem or 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 will be created. 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, additionally transmitting information about the respective Attribute.

If a RequestItem is rejected, however, a RejectResponseItem is created. Lastly, in case the enmeshed Runtime detects a problem, an ErrorResponseItem is generated. It will never be created manually.

Request-Response flow

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. Note that the LocalResponse is stored within the respective LocalRequest, besides properties that are common for both peers like the 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.

Sending Requests via Messages

Requests can only be send via Message, if you already have an active Relationship with the Recipient. Otherwise, you need to utilize a RelationshipTemplate.

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.

You can find an example for the Request-Response flow via Message below.

Sending Requests via RelationshipTemplates

If you don’t have a Relationship with the Recipient yet, the Request needs to be formulated within the onNewRelationship property of the RelationshipTemplateContent. Otherwise, utilize the onExistingRelationship property.

Alternatively, you can transfer Requests via RelationshipTemplates. To do so, you locally create the 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, if someone you don’t have a Relationship with opens the RelationshipTemplate.

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 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.

You can find an example for the Request-Response flow via RelationshipTemplate below.

Examples

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. 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. 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. 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.