Recopila datos con una variable de entrada

En esta guía, se explica cómo crear una variable de entrada.

Para ejecutarse, los pasos requieren cierta información. Por ejemplo, para enviar un correo electrónico, se requiere una dirección de correo electrónico. Para proporcionar esta información necesaria, define variables de entrada. Una vez definidas, las variables de entrada suelen ser establecidas por el usuario en la tarjeta de configuración de un paso mientras el usuario configura el paso.

Define la variable de entrada en dos lugares: el archivo de manifiesto del complemento y en el código con una tarjeta de configuración en la que los usuarios pueden ingresar valores para las variables de entrada.

Cómo definir la variable de entrada en el archivo de manifiesto

En el archivo de manifiesto, especifica las variables de entrada con el array inputs[]. Cada elemento del array inputs[] tiene estas propiedades:

  • id: Es el identificador único de una variable de entrada. Para permitir que el flujo asocie un elemento de entrada de la tarjeta de configuración con esta variable de entrada, debe coincidir con el nombre del elemento de tarjeta correspondiente.
  • description: Es una descripción de la variable de entrada que se mostrará a los usuarios finales.
  • cardinality: Cantidad de valores permitidos. Los valores posibles son los siguientes:
    • SINGLE: Solo se permite un valor.
  • dataType: Es el tipo de valores aceptados. dataType tiene la propiedad basicType, que define el tipo de datos. Estos son algunos de los valores válidos:
    • STRING: Es una cadena alfanumérica.
    • INTEGER: Es un número.
    • TIMESTAMP: Es una marca de tiempo en formato ISO 8601. Por ejemplo, en ISO 8601, el 15 de marzo de 2025 se representa como 2025-03-15.
    • BOOLEAN: Puede ser verdadero o falso.
    • EMAIL_ADDRESS: Una dirección de correo electrónico en el formato dana@example.com

En el siguiente ejemplo, se definen tres variables de entrada para un paso de calculadora. Las primeras dos variables de entrada son números enteros y la tercera es una operación aritmética.

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"
          }
        }
      ]
    }
  }
}

Cómo definir la variable de entrada en el código

El código del paso incluye una función llamada onConfigFunction() que devuelve una tarjeta de configuración que define un widget de tarjeta de entrada para cada variable de entrada definida en el array inputs[] del archivo de manifiesto.

Los widgets de entrada definidos en la tarjeta de configuración tienen los siguientes requisitos:

  • El name de cada widget de entrada debe coincidir con el id de la variable de entrada correspondiente en el archivo de manifiesto.
  • La cardinalidad del widget de entrada debe coincidir con la cardinality de la variable de entrada en el archivo de manifiesto.
  • El tipo de datos del widget de entrada debe coincidir con el dataType de la variable de entrada en el archivo de manifiesto. Si la variable de entrada tiene un dataType de número entero, no puede contener una cadena.

Para obtener ayuda para crear interfaces de tarjetas, consulta una de las siguientes opciones:

  • Card Builder: Es una herramienta interactiva que puedes usar para crear y definir tarjetas.
  • Card: En la documentación de referencia de la API del complemento de Google Workspace
  • Card Service: Es un servicio de Apps Script que permite que las secuencias de comandos configuren y compilen tarjetas.
  • Descripción general de las interfaces basadas en tarjetas: En la documentación para desarrolladores de complementos de Google Workspace

En el siguiente ejemplo, se muestra una tarjeta de configuración para cada widget de entrada definido en Define la variable de entrada en el archivo de manifiesto.

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
      }]
    }
  };
}

Valida la variable de entrada

Como práctica recomendada, valida que el usuario ingrese un valor adecuado. Consulta Cómo validar una variable de entrada.