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.dataTypehas the propertybasicTypewhich defines the type of data. Valid values include:-
STRING: An alphanumeric string. -
INTEGER: A number. -
TIMESTAMP: A timestamp in the "milliseconds since Unix epoch" format. For example, November 27, 2025, 16:49:02 UTC is represented as1764262142988. -
BOOLEAN: Either true or false. -
EMAIL_ADDRESS: An email address in the formatdana@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"
:
"calculatorDemo"
,
"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
nameof each input widget must match its corresponding input variable'sidin the manifest file. - The input widget's cardinality must match the input variable's
cardinalityin the manifest file. - The input widget's data type must match the input variable's
dataTypein the manifest file. If the input variable has adataTypeof integer, it can't hold a string.
For help building card interfaces, see one of these options:
- The Card Builder : An interactive tool that you can use to build and define cards.
- Card : in the Google Workspace add-on API reference documentation.
- Card Service : An Apps Script service that lets scripts configure and build cards.
- Overview of Card-based interfaces : in the Google Workspace add-on developer documentation.
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 input fields are configured to let the user select outputs from previous
* workflow steps as input values using the `hostAppDataSource` property.
*/
function
onConfigCalculate
()
{
const
firstInput
=
CardService
.
newTextInput
()
.
setFieldName
(
"value1"
)
// "FieldName" must match an "id" in the manifest file's inputs[] array.
.
setTitle
(
"First Value"
)
.
setHostAppDataSource
(
CardService
.
newHostAppDataSource
()
.
setWorkflowDataSource
(
CardService
.
newWorkflowDataSource
()
.
setIncludeVariables
(
true
)
)
);
const
secondInput
=
CardService
.
newTextInput
()
.
setFieldName
(
"value2"
)
// "FieldName" must match an "id" in the manifest file's inputs[] array.
.
setTitle
(
"Second Value"
)
.
setHostAppDataSource
(
CardService
.
newHostAppDataSource
()
.
setWorkflowDataSource
(
CardService
.
newWorkflowDataSource
()
.
setIncludeVariables
(
true
)
)
);
const
selectionInput
=
CardService
.
newSelectionInput
()
.
setTitle
(
"operation"
)
.
setFieldName
(
"operation"
)
// "FieldName" must match an "id" in the manifest file's inputs[] array.
.
setType
(
CardService
.
SelectionInputType
.
DROPDOWN
)
.
addItem
(
"+"
,
"+"
,
false
)
.
addItem
(
"-"
,
"-"
,
true
)
.
addItem
(
"x"
,
"x"
,
false
)
.
addItem
(
"/"
,
"/"
,
false
);
const
sections
=
CardService
.
newCardSection
()
.
setHeader
(
"Action_sample: Calculate"
)
.
setId
(
"section_1"
)
.
addWidget
(
firstInput
)
.
addWidget
(
selectionInput
)
.
addWidget
(
secondInput
)
let
card
=
CardService
.
newCardBuilder
()
.
addSection
(
sections
)
.
build
();
return
card
;
}
Validate the input variable
As a best practice, validate that the user enters an appropriate value. See Validate an input variable .
