Request Items
All the RequestItems listed below inherit from the RequestItem and are therefore sharing its properties.
AuthenticationRequestItem
With this item 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
Properties
Name | Type | Description |
---|---|---|
@type |
"AuthenticationRequestItem" |
Specifies the type of the RequestItem for internal processing. |
Response Parameters
Item Properties
- To accept this RequestItem an AcceptResponseItem will be transferred.
- To reject this RequestItem a RejectResponseItem will be transferred.
- In case of an error an ErrorResponseItem will be transferred.
Parameters
- To accept this RequestItem you can send
{ "accept": true }
as parameters. - To reject this RequestItem you can send
{ "accept": false }
as parameters.
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.
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.
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.”
Properties
Name | Type | Description |
---|---|---|
@type |
"ConsentRequestItem" |
Specifies the type of the RequestItem for internal processing. |
consent |
string |
The textual consent the user needs to give. This is different to the title and description of the RequestItem, as the consent would be the actual statement the user agrees to. |
link |
string | undefined |
A link to a website which contains more information, like the EULA or privacy terms. |
Response Parameters
Item Properties
- To accept this RequestItem an AcceptResponseItem will be transferred.
- To reject this RequestItem a RejectResponseItem will be transferred.
- In case of an error an ErrorResponseItem will be transferred.
Parameters
- To accept this RequestItem you can send
{ "accept": true }
as parameters. - To reject this RequestItem you can send
{ "accept": false }
as parameters.
CreateAttributeRequestItem
If you want to create Identity- 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.
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
Properties
Name | Type | Description |
---|---|---|
@type |
"CreateAttributeRequestItem" |
Specifies the type of the RequestItem for internal processing. |
attribute |
IdentityAttribute | RelationshipAttribute |
The IdentityAttribute or RelationshipAttribute to create for the peer within the Identity of the peer. |
Response
Item Properties
-
To accept this RequestItem a
CreateAttributeAcceptResponseItem
will be transferred.Name Type Description @type
"CreateAttributeAcceptResponseItem"
The type of the ResponseItem. attributeId
string
The id of the created Attribute. - To reject this RequestItem a RejectResponseItem will be transferred.
- In case of an error an ErrorResponseItem will be transferred.
Parameters
- To accept this RequestItem you can send
{ "accept": true }
as parameters. - To reject this RequestItem you can send
{ "accept": false }
as parameters.
Combinations and usage scenarios
Attribute Type | Attribute Owner | Possible? | Automation | Examples/Reason |
---|---|---|---|---|
Identity | Sender | N | N/A |
Use ShareAttributeRequestItem instead. |
Identity | Recipient | Y | USER_DECISION |
University sends student his certificate (Propose would be inappropriate in this case, because the student should not be able to return his own value) |
Identity | <empty> |
Y | USER_DECISION |
An empty owner defaults to an Attribute with owner=<recipient> . This is needed for Requests inside of Relationship Templates, since you don’t know the Enmeshed Address of your peer before the Relationship is established. |
Relationship | Sender | Y | AUTO_ACCEPT |
Company sends new customer his customer number. |
Relationship | Recipient | Y | USER_DECISION |
With this combination the sender asks the recipient for the one-time permission to write a Relationship Attribute once AND the sender defined a value which can either be accepted and stored, or rejected. Thus, the user cannot change the value by itself. |
Relationship | <empty> |
Y | USER_DECISION |
An empty owner defaults to an Attribute with owner=<recipient> . This is needed for Requests inside of Relationship Templates, since you don’t know the Enmeshed Address of your peer before the Relationship is established. |
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.
Properties
Name | Type | Description |
---|---|---|
@type |
"FreeTextRequestItem" |
Specifies the type of the RequestItem for internal processing. |
freeText |
string |
The free text you want to send to the peer. |
Response Parameters
Item Properties
-
To accept this RequestItem a
FreeTextAcceptResponseItem
will be transferred.Name Type Description @type
"FreeTextAcceptResponseItem"
The type of the ResponseItem. freeText
string
The free text that is used to answer the RequestItem. - To reject this RequestItem a RejectResponseItem will be transferred.
- In case of an error an ErrorResponseItem will be transferred.
Parameters
-
To accept this RequestItem you can send the following parameters.
Name Type Description accept
true
freeText
string
The free text you want to send to the peer. -
To reject this RequestItem you can send
{ "accept": false }
as parameters.
ProposeAttributeRequestItem
The ProposeAttributeRequestItem is a combination of ReadAttributeRequestItem and 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.
Properties
Name | Type | Description |
---|---|---|
@type |
"ProposeAttributeRequestItem" |
Specifies the type of the RequestItem for internal processing. |
attribute |
IdentityAttribute | RelationshipAttribute |
The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute. |
query |
IdentityAttributeQuery | RelationshipAttributeQuery | ThirdPartyRelationshipAttributeQuery |
The structured query of the Attribute the sender would like to receive. |
Response
Item Properties
-
To accept this RequestItem a
ProposeAttributeAcceptResponseItem
will be transferred.Name Type Description @type
"ProposeAttributeAcceptResponseItem"
The type of the ResponseItem. attributeId
string
The id of the created Attribute. attribute
IdentityAttribute
|RelationshipAttribute
The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute.
The owner of the Attribute which is proposed can only be the recipient Identity. - To reject this RequestItem a RejectResponseItem will be transferred.
- In case of an error an ErrorResponseItem will be transferred.
Parameters
-
To accept this RequestItem you can send the following parameters.
-
If you want to create a new Attribute.
Name Type Description attribute
IdentityAttribute
|RelationshipAttribute
The IdentityAttribute or RelationshipAttribute that shall be created. -
If you want to use the proposed Attribute.
Name Type Description attribute
IdentityAttribute
|RelationshipAttribute
The IdentityAttribute or RelationshipAttribute that was provided in the RequestItem. -
If you want to use an existing Attribute.
Name Type Description existingAttributeId
string
The id of the Attribute to send.
-
-
To reject this RequestItem you can send
{ "accept": false }
as parameters.
Combinations and usage scenarios
Attribute Type | Attribute Owner | Possible? | Automation | Examples/Reason |
---|---|---|---|---|
Identity | Sender | N | N/A |
It makes no sense to propose own Attributes, use ShareAttributeRequestItem instead. |
Identity | Recipient | Y | USER_DECISION |
Company sends name and address to new customer during its onboarding process. |
Relationship | Sender | Y | USER_DECISION |
With this combination the sender gives the recipient the one-time permission to write a Relationship Attribute once AND the sender proposes a value which might make sense as a default. Example: Electricity provider asks new customer for the electricity meter number and proposes a known number |
Relationship | Recipient | Y | USER_DECISION |
With this combination the sender asks the recipient for the one-time permission to write a Relationship Attribute once AND the sender proposes a value which might make sense as a default. Example: Asking for a newsletter subscription |
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.
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
Properties
Name | Type | Description |
---|---|---|
@type |
"ReadAttributeRequestItem" |
Specifies the type of the RequestItem for internal processing. |
query |
IdentityAttributeQuery | RelationshipAttributeQuery | ThirdPartyRelationshipAttributeQuery |
The structured query of the Attribute the sender would like to receive. |
Response
Item Properties
-
To accept this RequestItem a
ReadAttributeAcceptResponseItem
will be transferred.Name Type Description @type
"ReadAttributeAcceptResponseItem"
The type of the ResponseItem. attributeId
string
The id of the returned Attribute. attribute
IdentityAttribute
|RelationshipAttribute
The IdentityAttribute or RelationshipAttribute that will be shared to the peer. - To reject this RequestItem a RejectResponseItem will be transferred.
- In case of an error an ErrorResponseItem will be transferred.
Parameters
-
To accept this RequestItem you can send the following parameters.
-
If you want to use an existing Attribute.
Name Type Description existingAttributeId
string
The id of the Attribute to send. -
If you want to create a new Attribute.
Name Type Description attribute
IdentityAttribute
|RelationshipAttribute
The IdentityAttribute or RelationshipAttribute that shall be created.
-
-
To reject this RequestItem you can send
{ "accept": false }
as parameters.
Combinations and usage scenarios
Attribute Type | Attribute Owner | Third Party | Possible? | Automation | Examples/Reason |
---|---|---|---|---|---|
Identity | Sender | N | N/A |
It makes no sense to read own IdentityAttributes. | |
Identity | Recipient | Y | USER_DECISION |
Company asks customer for its delivery address | |
Relationship | Sender | Y | USER_DECISION |
With this combination the sender gives the recipient the one-time permission to write a Relationship Attribute once Example: Electricity provider asks new customers for electricity meter number |
|
Relationship | Recipient | Y | USER_DECISION |
With this combination the sender asks the recipient for the one-time permission to write a Relationship Attribute Example: Company asks new customer to subscribe to the newsletter and proposes the subscription as default once |
|
Relationship | Recipient | Third Party | Y | USER DECISION / NOT ALLOWED - depending on confidentiality |
With this combination the sender requests a Relationship Attribute from a Relationship between the recipient and a third party. The Attribute must be owned by the recipient Example: A Social Network asks for Facebook privacy settings of a user to get senseful defaults of its own privacy settings |
Relationship | Third Party | Third Party | Y | USER DECISION / NOT ALLOWED - depending on confidentiality |
With this combination the sender requests a Relationship Attribute from a Relationship between the recipient and a third party which is owned by the third party Example: An online shop asks for the Payback Customer Id of a user to book the order on his account |
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.
Examples
- Share own DisplayName.
- Share own Address.
- Share customer number of company A with company B.
Properties
Name | Type | Description |
---|---|---|
@type |
"ShareAttributeRequestItem" |
Specifies the type of the RequestItem for internal processing. |
attribute |
IdentityAttribute | RelationshipAttribute |
The IdentityAttribute or RelationshipAttribute to share. This is not the LocalAttribute but the content data structure of the Attribute. The owner of the Attribute which should be shared can only be the sender Identity. |
sourceAttributeId |
string |
The id of the LocalAttribute which is the source of the shared Attribute. This will be used later to reference the sourceAttribute from its shared copy. |
Response
Item Properties
-
To accept this RequestItem a
RegisterAttributeListenerAcceptResponseItem
will be transferred.Name Type Description @type
"ShareAttributeAcceptResponseItem"
The type of the ResponseItem. attributeId
string
The id of the created Attribute. - To reject this RequestItem a RejectResponseItem will be transferred.
- In case of an error an ErrorResponseItem will be transferred.
Parameters
- To accept this RequestItem you can send
{ "accept": true }
as parameters. - To reject this RequestItem you can send
{ "accept": false }
as parameters.
Combinations and usage scenarios
Attribute Type | Attribute Owner | Possible? | Automation | Examples/Reason |
---|---|---|---|---|
Identity | Sender | Y | AUTO ACCEPT |
Company sends new customer the address of the company |
Identity | Recipient | N | N/A |
It makes no sense to share the Attribute to the recipient, because he already owns it. |
Identity | Third Party | N | N/A |
You cannot share an Attribute of which you are not the owner. |
Identity | <empty> |
Y | AUTO ACCEPT |
An empty owner defaults to an Attribute with owner=<sender> . |
Relationship | Sender | Y | USER DECISION / NOT ALLOWED (depending on confidentiality) |
A user can share own RelationshipAttributes of any Relationship to any other Relationship (if the confidentiality of the RelationshipAttribute is protected or public). Example: Share Customer ID from Company A with Company B (User is owner of RelationshipAttribute) |
Relationship | Recipient | N | N/A |
It makes no sense to share the Attribute to the recipient, because he already owns it. |
Relationship | Third Party | Y | USER DECISION / NOT ALLOWED (depending on confidentiality) |
A user can share RelationshipAttributes of any Relationship to any other Relationship (if the confidentiality of the RelationshipAttribute is protected or public). Example: Share Customer ID from Company A with Company B (Company A is owner of RelationshipAttribute), e.g. Payback number |
Relationship | <empty> |
Y | AUTO ACCEPT |
An empty owner defaults to an Attribute with owner=<sender> . |