Action Provider: Wait For User Selection

URL: https://actions.globus.org/weboption/wait_for_option

Scope: https://auth.globus.org/scopes/5fac2e64-c734-4e6b-90ea-ff12ddbf9653/weboption_wait_for_option

Synchronous / Asynchronous: Asynchronous

Flows or other clients which desire to provide users a method of selecting an option from a fixed set may use the Wait for User Option Selection Action Provider. The action provider can operate in one of two modes.

In the first mode, a list of options are created which are automatically selected by any access to a corresponding URLs. For each option, a name, a URL suffix, and a message or text which is returned in the HTTP response of the selection operation is provided. The URL suffix is registered with the Action Provider and is monitored at the URL https://actions.globus.org/weboption/option/<url_suffix>. Any HTTP access to the URL is considered a selection of that option among all the options defined by the input to the Action and the Action will transition to a SUCCEEDED status. Each of the options may be protected for access only via specific Globus identities by setting values on the selectable_by list. A direct HTTP access may present a Bearer token for authorization using the same scope as used for accessing the other operations on the action provider. If no access token is presented, the user will be re-directed to start an OAuth Flow using Globus Auth to authenticate access to the option URL.

In the second mode, in addition to monitoring the provided URL suffixes, a landing page may be hosted which will present the options to a user on a simple web page. The web page may be "skinned" with options for banner text, color scheme and icon as well as introductory text presented above the options. The options are specified in the same manner as in the first mode, but the page presents links which ease selection of those options for end-users. The landing page is also given a URL suffix, and the selection page will be present at https://actions.globus.org/weboption/landing_page/<url_suffix>. Selection of an option within the landing page behaves the same as direct selection of an option via its URL as described above. Similar to individual options, the landing page can be protected by setting a selectable_by list. As the landing page is intended for use via a browser, it will always start a OAuth Flow to authenticate the user. If selectable_by is set on the landing page but not on any of the individual options, the options inherit the same selectable_by value defined on the landing page for that Action.

In either mode, once an option has been selected, none of the url suffixes, nor the landing page if configured, in the initial request, will be responded to by the action provider: they will return the HTTP not found (error) status 404. Upon completion, the body of the status will include the name and the url suffix for the selected option. The body may also include input on the HTTP data passed when the option’s URL was accessed including the query parameters and the body. To include those in the status, flags are set on the definition of the option.

Example Input for Creating Options
{
    "options": [
        {
            "name": "b",
            "url_suffix": "option_b",
            "completed_message": "Thank you for selecting 'b'"
        },
        {
            "name": "default",
            "url_suffix": "option_a",
            "completed_message": "Thank you for selecting the default option"
        }
    ]
}
Example Input for Creating Options on a Landing Page
{
    "landing_page": {
        "url_suffix": "landing_page",
        "header_background": "darkred",
        "header_icon_link": "http://example.com",
        "header_text": "Hey, Make a choice",
        "page_title": "Look at my title",
        "preamble_text": "Please make a very careful decision"
    },
    "options": [
        {
            "name": "b",
            "description": "This is option b",
            "url_suffix": "option_b_new",
            "completed_message": "Thank you for selecting 'b'"
        },
        {
            "name": "default",
            "description": "This is the default option",
            "url_suffix": "option_a_new",
            "completed_message": "Thank you for selecting the default option"
        }
    ]
}
Example Input for Creating Options on a Landing Page Limiting Selection
{
    "landing_page": {
        "url_suffix": "landing_page",
        "header_background": "darkred",
        "header_icon_link": "http://example.com",
        "header_text": "Hey, Make a choice",
        "page_title": "Look at my title",
        "preamble_text": "A summary of the user's input...",
        "include_text_input_form": true,
        "text_input_form_prompt": "Please provide your reason",
        "display_options_as": "link",
        "selectable_by": [
            "urn:globus:auth:identity:c5ab1c3d-b812-4ef9-acb6-4d84c58db4de"
        ]
    },
    "options": [
        {
            "name": "Yes",
            "description": "Allow the submission",
            "url_suffix": "yes",
            "completed_message": "The submission will be allowed"
        },
        {
            "name": "No",
            "description": "Reject the submission",
            "url_suffix": "no",
            "completed_message": "The submission will be rejected"
        },
        {
            "name": "Maybe",
            "description": "Request the user to re-submit",
            "url_suffix": "maybe",
            "completed_message": "The user will be required to update their submission"
        }
    ]
}