Collect data with an input variable

This guide explains how to create an input variable.

To run, steps require certain information. For example, sending an email requires an email address. To provide steps this necessary information, define input variables. Once defined, input variables are typically set by the user on a step's configuration card while the user sets up the step.

Define the input variable in two places: the add-on's manifest file, and in code with a configuration card where users can enter values for input variables.

Define the input variable in the manifest file

In the manifest file, specify input variables with the inputs[] array. Each item in the inputs[] array has these properties:

  • id: Unique identifier for an input variable. To allow the flow to associate a configuration card input element with this input variable, must match the name of the corresponding card element.
  • description: A description of the input variable to display to end users.
  • cardinality: How many values are permitted. Possible values are:
    • SINGLE: Only one value is permitted.
  • dataType: The type of values accepted. dataType has the property basicType which defines the type of data. Valid values include:
    • STRING: An alphanumeric string.
    • INTEGER: A number.
    • TIMESTAMP: A timestamp in the ISO 8601 format. For example, in ISO 8601, March 15, 2025 is represented as 2025-03-15.
    • BOOLEAN: Either true or false.
    • EMAIL_ADDRESS: An email address in the format dana@example.com.

The following example defines three input variables for a calculator step. The first two input variables are integers, and the third is a arithmetic operation.

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Calculator",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Calculate",
          "description": "Asks the user for two values and a math operation, then performs the math operation on the values and outputs the result.",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "value1",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "value2",
                "description": "value2",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "operation",
                "description": "operation",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "outputs": [
              {
                "id": "result",
                "description": "Calculated result",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculate",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

Define the input variable in code

The step's code includes a function called onConfigFunction() that returns a configuration card that defines one input card widget for each input variable defined in the manifest file's inputs[] array.

The input widgets defined in the configuration card have the following requirements:

  • The name of each input widget must match its corresponding input variable's id in the manifest file.
  • The input widget's cardinality must match the input variable's cardinality in the manifest file.
  • The input widget's data type must match the input variable's dataType in the manifest file. If the input variable has a dataType of integer, it can't hold a string.

For help building card interfaces, see one of these options:

The following example returns a configuration card for each input widget defined in Define the input variable in the manifest file.

Apps Script

/**
 * Generates and displays a configuration card for the sample calculation step.
 *
 * This function creates a card with input fields for two values and a drop-down
 * for selecting an arithmetic operation. The card also includes a "Save"
 * button to save the step configuration for the workflow.
 *
 * The input fields are configured to let the user select outputs from previous
 * workflow steps as input values using the `hostAppDataSource` property.
 */
function onConfigFunction() {
  var card = {
    "sections": [
      {
        "header": "Step example: Calculate",
        "widgets": [
          {
            "textInput": {
              "name": "value1", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "First value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "selectionInput": {
              "name": "operation", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Operation",
              "type": "DROPDOWN",
              "items": [
                {
                  "text": "+",
                  "value": "+",
                },
                {
                  "text": "-",
                  "value": "-",
                },
                {
                  "text": "x",
                  "value": "x",
                },
                {
                  "text": "/",
                  "value": "/",
                }
              ]
            }
          },
          {
            "textInput": {
              "name": "value2", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Second value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

Validate the input variable

As a best practice, validate that the user enters an appropriate value. See Validate an input variable.