CreateWebInput States

A CreateWebInput state creates a new web input resource. A web input presents a set of options to designated respondents, who may select one to allow the flow run to proceed.

The CreateWebInput state does not pause the flow run. The run continues to the next state immediately after the web input resource is created. Use an AwaitWebInput state to pause the run until a response to the web input is received.

For an overview of the web input feature, see Web Inputs.

Fields

Type (required)

Must be "CreateWebInput".

Parameters (required)

An object that defines the web input to create. As in other state types, Parameters values may be provided statically in a flow definition or dynamically from the run’s state using either JSONPath references (.$) or expression syntax. The following fields are supported within Parameters:

Parameters.InputType (required)

The type of input to request. Currently, the only supported value is "Selection", which presents the respondent with a list of options to choose from.

Parameters.Options (required)

An array of objects defining the selectable choices. Each object must contain the following fields:

Value (required)

The JSON value to be supplied to the run when this option is selected.

Label (required)

A short display name to identify this option to respondents.

Description (optional)

A more lengthy, detailed explanation of this option, if required.

Parameters.Context (required)

An object providing display context shown to respondents. The following fields are supported:

Title (required)

A short title for the web input.

PresentationStyle (required)

Identifier for what type of context is being provided. Valid values are "Text" and "Table".

Text (required for Text-style)

Context describing the overall purpose of the web input. This should provide all relevant context for what the respondent is being asked approve, select, etc.

Rows (required for Table-style)

An array of objects, describing in tabular form the web input context. Each object must contain the following fields:

Field (required)

A short display name for this row.

Value (required)

The value to display for this row.

Parameters.RespondentUrns (required)

A list of principal URNs identifying the users or groups who are permitted to respond.

Parameters.ViewerUrns (optional)

A list of principal URNs identifying the users or groups who may view this web input without being able to respond. Defaults to an empty list.

InputPath (optional)

A JSONPath expression that selects a portion of the run’s state to pass as input to the state’s parameters. If omitted, the entire run state is passed as input.

ResultPath (optional)

A JSONPath expression indicating where the created web input resource will be placed in the run’s state. The result object includes a web_input_id field. If omitted, the default is $.

Catch (optional)

An array of error handling objects that specify how to handle errors that occur in this state. See Error Handling.

Next or End (one required)

Next specifies the name of the following state. End: true indicates that the run terminates after this state completes.

Examples

A web input in which the flow runner themselves must approve or deny the progression of their run.

{
  "CreateApprovalRequest": {
    "Type": "CreateWebInput",
    "Parameters": {
      "InputType": "Selection",
      "Options": [
        {
          "Value": "approve",
          "Label": "Approve"
        },
        {
          "Value": "deny",
          "Label": "Deny"
        }
      ],
      "Context": {
        "Title": "Approval Request",
        "PresentationStyle": "Text",
        "Text": "Please review and approve or deny the pending operation."
      },
      "RespondentUrns.=": "[`$._context.user_id`]"
    },
    "ResultPath": "$.web_input",
    "Next": "WaitForApproval"
  }
}

A web input in which a particular individual (e.g., a sysadmin) must approve or deny the progression of a run.

The individual’s Globus Identity UUID is statically provided in the flow definition.

  • In this example, we’ll use "00000000-1111-2222-3333-44444444444".

  • In practice, you should replace this with an actual identity UUID queried, for instance, using the Globus CLI: globus get-identities <email>.

Additionally, we’ll grant the runner the ability to see the web input that has been created.

{
  "CreateApprovalRequest": {
    "Type": "CreateWebInput",
    "Parameters": {
      "InputType": "Selection",
      "Options": [
        {
          "Value": "approve",
          "Label": "Approve",
          "Description": "Proceed with the operation."
        },
        {
          "Value": "deny",
          "Label": "Deny",
          "Description": "Cancel the operation."
        }
      ],
      "Context": {
        "Title": "Approval Required",
        "PresentationStyle": "Table",
        "Rows": [
          {
            "Field": "Requester",
            "Value.$": "$._context.email"
          },
          {
            "Field": "Flow Title",
            "Value.$": "$._context.flow_title"
          },
          {
            "Field": "Run Label",
            "Value.$": "$._context.run_label"
          }
        ]
      },
      "RespondentUrns": [
        "urn:globus:auth:identity:00000000-1111-2222-3333-44444444444"
      ],
      "ViewerUrns.=": "[`$._context.user_urn`]"
    },
    "ResultPath": "$.web_input",
    "Next": "WaitForApproval"
  }
}

A web input in which one member of a Globus group (e.g., a group of sysadmins) must approve or deny the progression of a run.

The group’s id must be statically included in the flow definition. In this demonstration, we’ll use "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee".

{
  "CreateApprovalRequest": {
    "Type": "CreateWebInput",
    "Parameters": {
      "InputType": "Selection",
      "Options": [
        {
          "Value": "approve",
          "Label": "Approve",
          "Description": "Proceed with the operation."
        },
        {
          "Value": "deny",
          "Label": "Deny",
          "Description": "Cancel the operation."
        }
      ],
      "Context": {
        "Title": "Approval Required",
        "PresentationStyle": "Table",
        "Rows": [
          {
            "Field": "Requester",
            "Value.$": "$._context.email"
          },
          {
            "Field": "Flow Title",
            "Value.$": "$._context.flow_title"
          },
          {
            "Field": "Run Label",
            "Value.$": "$._context.run_label"
          }
        ]
      },
      "RespondentUrns": [
        "urn:globus:groups:id:aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      ]
    },
    "ResultPath": "$.web_input",
    "Next": "WaitForApproval"
  }
}

A web input with a dynamically provided title in which the runner must select from a dynamically provided list of options. Dynamically provided here means that they were sourced from a previous state or from the run’s input rather than the flow definition itself.

Dynamically provided elements are constrained by the same rules as statically provided ones, so a flow which uses this state would need to ensure that: * Options are provided as an array of objects with a Value, Label, and optionally a Description. * Title is provided as a string of length > 1.

{
  "CreateApprovalRequest": {
    "Type": "CreateWebInput",
    "Parameters": {
      "InputType": "Selection",
      "Options.$": "$.previous_state.options",
      "Context": {
        "Title.$": "$.previous_state.title",
        "PresentationStyle": "Text",
        "Text": "Please select one of the following options."
      },
      "RespondentUrns.=": "[`$._context.user_id`]"
    },
    "ResultPath": "$.web_input",
    "Next": "WaitForApproval"
  }
}