Action Provider: Wait for User Option Selection

URL: https://actions.globus.org/weboption/wait_for_option [Introspect]

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

Synchronous / Asynchronous: Asynchronous

The Wait for User Option Selection Action Provider allows authors to solicit user input while a flow is running. The result is received back into the flow as the action provider output, which can be used to modify how the rest of the flow runs.

The action provider allows authors to configure custom URLs by which a single user input is registered. This makes it ideal for soliciting user input (e.g. to review the validity of a report) or to introduce a manual step that the flow must wait for the user to perform.

The action provider is also able to host a landing page that presents the configured options.

In the first mode, a list of options are created which are automatically selected by any access of a given option’s corresponding URL. 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 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. 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 on the landing page behaves the same as direct URL access 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 both modes, the landing page and associated options will become inaccessible once an option has been selected. 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.

Usage Example

The example below demonstrates how to use the action provider in a flow.

Features of the flow:

An email is sent to the user who started the flow with a link to the landing page hosted on the Web Option AP.
__Private_Parameters are used in the Notification Email AP state to ensure that the SMTP credentials are removed from logs and error messages.
A WaitTime is specified, giving the user 7 days (604,800 seconds) to select an option.
The _context.run_id variable is used to ensure that URLs hosted by the Web Option AP are unique. It appears as a JSON path (see the run_id.$ and url_prefix.$ keys) and as a variable used in string concatenation expressions (see the url_prefix.= keys).
A Choice state demonstrates how the results of the user’s selection can be used in-flow.

{
  "StartAt": "SendEmail",
  "States": {
    "NotificationEmail": {
      "Type": "Action",
      "ActionUrl": "https://actions.globus.org/notification/notify",
      "Parameters": {
        "body_mimetype": "text/html",
        "body_template": "<html><body>Please <a href=\"https://actions.globus.org/weboption/landing_page/${run_id}\">select an option</a>.</body></html>",
        "body_variables": {
          "run_id.$": "$._context.run_id"
        },
        "destination.$": "$._context.email",
        "sender": "reports@domain.example",
        "subject": "Select an option",
        "__Private_Parameters": [
          "send_credentials"
        ],
        "send_credentials": [
          {
            "credential_type": "smtp",
            "credential_value": {
              "hostname": "smtp.domain.example",
              "username": "email@domain.example",
              "password": "password_or_api_key",
              "port": "587"
            }
          }
        ]
      },
      "Next": "WebOption"
    },
    "WebOption": {
      "Type": "Action",
      "ActionUrl": "https://actions.globus.org/weboption/wait_for_option",
      "WaitTime": 604800,
      "Parameters": {
        "landing_page": {
          "url_suffix.$": "$._context.run_id"
        },
        "options": [
          {
            "name": "succeed",
            "description": "Allow the run to succeed",
            "url_suffix.=": "_context.run_id + '-succeed'",
            "completed_message": "The run will now succeed."
          },
          {
            "name": "fail",
            "description": "Force the run to fail",
            "url_suffix.=": "_context.run_id + '-fail'",
            "completed_message": "The run will now fail."
          }
        ]
      },
      "ResultPath": "$.result",
      "Next": "SucceedOrFail"
    },
    "SucceedOrFail": {
      "Type": "Choice",
      "Choices": [
        {
          "Variable": "$.result.details.name",
          "StringEquals": "succeed",
          "Next": "Succeed"
        }
      ],
      "Default": "Fail"
    },
    "Succeed": {
      "Type": "Pass",
      "End": true
    },
    "Fail": {
      "Type": "Fail",
      "Cause": "The user chose the 'fail' option."
    }
  }
}

Features of the input schema:

The schema enforces that the input is an empty object.

{
  "type": "object",
  "additionalProperties": false
}

No input is required to start this flow.

{}