Aries RFC 0509: Action Menu Protocol¶
- Authors: [Andrew Whitehead],[Stephen Curran],[John Court]
- Status: DEMONSTRATED
- Since: 2020-07-02
- Status Note: Implemented and demonstrated in the Aries Cloud Agent Python code base
- Supersedes:
- Start Date: 2020-06-24
- Tags: feature, protocol
- Protocol Name: action-menu
- Version: 1.0
- URI:
https://didcomm.org/action-menu/%VER
Summary¶
The action-menu protocol allows one Agent to present a set of heirarchical menus and actions to another user-facing Agent in a human friendly way. The protocol allows limited service discovery as well as simple data entry. While less flexible than HTML forms or a chat bot, it should be relatively easy to implement and provides a user interface which can be adapted for various platforms, including mobile agents.
Motivation¶
Discovery of a peer Agent's capabilities or service offerings is currently reliant on knowledge obtained out-of-band. There is no in-band DIDComm supported protocol for querying a peer to obtain a human freindly menu of their capabilities or service offerings. Whilst this protocol doesn't offer ledger wide discovery capabilities, it will allow one User Agent connected to another, to present a navigable menu and request offered services. The protocol also provides an interface definition language to define action menu display, selection and request submission.
Tutorial¶
Name and Version¶
action-menu
, version 1.0
Key Concepts¶
The action-menu protocol requires an active DIDComm connection before it can proceed. One Agent behaves as a requester
in the protocol whilst the other Agent represents a responder
. Conceptually the responder
presents a list of actions which can be initiated by the requester
. Actions are contained within a menu structure. Individual Actions may result in traversal to another menu or initiation of other Aries protocols such as a presentation request, an introduction proposal, a credential offer, an acknowledgement, or a problem report.
The protocol can be initiated by either the requester
asking for the root menu or the responder
sending an unsolicited root menu. The protocol ends when the requester
issues a perform
operation or an internal timeout on the responder
causes it to discard menu context. At any time a requester
can reset the protocol by requesting the root menu from a responder
.
Whilst the protocol is defined here as uni-directional (i.e requester
to responder
), both Agents may support both requester
and responder
roles simultaneously. Such cases would result in two instances of the action-menu protocol operating in parrallel.
Roles¶
There are two roles in the action-menu protocol: requester
and responder
.
The requester
asks the responder
for menu definitions, presents them to a user, and initiates subsequent action items from the menu through further requests to the responder
.
The responder
presents an initial menu definition containing actionable elements to a requestor
and then responds to subsequent action requests from the menu.
States¶
States for Requester¶
State | Description |
---|---|
null | No menu has been requested or received |
awaiting-root-menu | menu-request message has been sent and awaiting root menu response |
preparing-selection | menu message has been received and a user selection is pending |
done | perform message has been sent and protocol has finished. Perform actions can include requesting a new menu which will re-enter the state machine with the receive-menu event from the null state. |
States for Responder¶
State | Description |
---|---|
null | No menu has been requested or sent |
preparing-root-menu | menu-request message has been received and preparing menu response for root menu |
awaiting-selection | menu message has been sent and are awaiting a perform request |
done | perform message has been received and protocol has finished. Perform actions can include requesting a new menu which will re-enter the state machine with the send-menu event from the null state. |
Messages¶
menu¶
A requestor
is expected to display only one active menu per connection when action menus are employed by the responder
. A newly received menu is not expected to interrupt a user, but rather be made available for the user to inspect possible actions related to the responder
.
{
"@type": "https://didcomm.org/action-menu/%VER/menu",
"@id": "5678876542344",
"title": "Welcome to IIWBook",
"description": "IIWBook facilitates connections between attendees by verifying attendance and distributing connection invitations.",
"errormsg": "No IIWBook names were found.",
"options": [
{
"name": "obtain-email-cred",
"title": "Obtain a verified email credential",
"description": "Connect with the BC email verification service to obtain a verified email credential"
},
{
"name": "verify-email-cred",
"title": "Verify your participation",
"description": "Present a verified email credential to identify yourself"
},
{
"name": "search-introductions",
"title": "Search introductions",
"description": "Your email address must be verified to perform a search",
"disabled": true
}
]
}
Description of attributes¶
title
-- plain text string, should be displayed at the top of the menudescription
-- plain text string, should be shown in smaller text below the title barerrormsg
-- optional plain text string sent to indicate that the last perform request did not work as expected. The text should be presented to the user in the title sectionoptions
-- one or more available actions which theresponder
supports and may be requested in a perform message.disabled
-- optional indication that an option is unavailable due to certain requirements not yet being met
Quick forms¶
Menu options may define a form property, which would direct the requester
user to a client-generated form when the menu option is selected. The menu title should be shown at the top of the form, followed by the form description text if defined, followed by the list of form params
in sequence. The form should also include a Cancel button to return to the menu, a Submit button (with an optional custom label defined by submit-label
), and optionally a Clear button to reset the parameters to their default values.
{
"@type": "https://didcomm.org/action-menu/%VER/menu",
"@id": "5678876542347",
"~thread": {
"thid": "5678876542344"
},
"title": "Attendance Verified",
"description": "",
"options": [
{
"name": "submit-invitation",
"title": "Submit an invitation",
"description": "Send an invitation for IIWBook to share with another participant"
},
{
"name": "search-introductions",
"title": "Search introductions",
"form": {
"description": "Enter a participant name below to perform a search.",
"params": [
{
"name": "query",
"title": "Participant name",
"default": "",
"description": "",
"required": true,
"type": "text"
}
],
"submit-label": "Search"
}
}
]
}
When the form is submitted, a perform message is generated containing values entered in the form. The form
block may have an empty or missing params
property in which case it acts as a simple confirmation dialog.
Each entry in the params
list must define a name
and title
. The description
is optional (should be displayed as help text below the field) and the type
defaults to ‘text’ if not provided (only the ‘text’ type is supported at this time). Parameters should default to required
true, if not specified. Parameters may also define a default
value (used when rendering or clearing the form).
menu-request¶
In addition to menus being pushed by the responder
, the root menu can be re-requested at any time by the requestor
sending a menu-request.
perform¶
When the requestor
user actions a menu option, a perform message is generated. It should be attached to the same thread as the menu. The active menu should close when an option is selected.
The response to a perform message can be any type of agent message, including another menu message, a presentation request, an introduction proposal, a credential offer, an acknowledgement, or a problem report. Whatever the message type, it should normally reference the same message thread as the perform message.
{
"@type": "https://didcomm.org/action-menu/%VER/perform",
"@id": "5678876542346",
"~thread": {
"thid": "5678876542344"
},
"name": "obtain-email-cred",
"params": {}
}
Description of attributes¶
name
-- the menu option being requested. This is taken from thename
attribute of theoptions
array elements in the menuparams
-- optional dictionary containing any input parameters requested in a menu optionform
section. The dictionary key values are taken from thename
attributes ofparams
array elements in the menu optionform
.
Drawbacks¶
N/A
Rationale and alternatives¶
N/A
Prior art¶
There are several existing RFCs that relate to the general problem of "Discovery"
- Aries RFC 0031 : Discover Features Protocol 1.0 -- This RFC provides Aries Protocol discovery between two Agents but no direction on user interface display or action handling.
- Aries RFC 0214 : "Help Me Discover" Protocol -- This RFC introduces the concept of a query language protocol between agents to obtain "referal" to a third agent.
Unresolved questions¶
- There needs to be some consideration around how the protocol may terminate due to
responder
side timeouts since maintaining menu context for connections consumes resources. Adoption of Aries RFC 0035 : Report Problem Protocol 1.0 is a viable solution
Implementations¶
The following lists the implementations (if any) of this RFC. Please do a pull request to add your implementation. If the implementation is open source, include a link to the repo or to the implementation within the repo. Please be consistent in the "Name" field so that a mechanical processing of the RFCs can generate a list of all RFCs supported by an Aries implementation.
Name / Link | Implementation Notes |
---|---|
Aries Cloud Agent - Python | MISSING test results |