Guía de inicio rápido: Crea un paso de calculadora con Google Apps Script

En esta guía de inicio rápido, se explica cómo crear un paso personalizado para Workspace Studio con Google Apps Script. El paso personalizado toma dos números y una operación aritmética como entrada, realiza el cálculo y genera el resultado.

Objetivos

• Crear un paso personalizado para Workspace Studio con Google Apps Script
• Implementar el paso personalizado en tu propia organización de Google Workspace
• Prueba el paso personalizado en Workspace Studio.

Requisitos previos

• Una Cuenta de Google con acceso a Workspace Studio

Configura la secuencia de comandos

Para configurar la secuencia de comandos, crea un nuevo proyecto de Apps Script y agrega el código de la guía de inicio rápido:

1. Haz clic en el siguiente botón para crear un proyecto de Apps Script nuevo:

   Crea el proyecto

2. Asigna un nombre al proyecto de Apps Script:

   1. Haz clic en Proyecto sin título.

   2. En Título del proyecto, escribe Calculator quickstart.

   3. Haga clic en Cambiar nombre.

3. Junto al archivo Code.gs, haz clic en Más more_vert > Cambiar nombre. Asígnale el nombre Calculator al archivo.

4. Reemplaza el contenido de Calculator.gs por el siguiente código. Este archivo define un paso personalizado para Google Workspace Studio llamado "Calculate" que toma dos números y una operación como entrada y devuelve el resultado del cálculo.

   Ver el código de Calculator.gs

   /**
    * This script defines a custom step for Google Workspace Studio.
    * The step, named "Calculate", takes two numbers and an operation as input
    * and returns the result of the calculation.
    *
    * The script includes functions to:
    *
    * 1.  Define the configuration UI for the step using Card objects:
    *
    *     - `onConfigCalculateFunction()`: Generates the main configuration card.
    *     - Helper functions like `pushCard()`, `saveButton()` to build card components.
    *
    * 2.  Handle the execution of the step.
    *
    *     - `onExecuteCalculateFunction()`: Retrieves inputs, performs the calculation,
    *       and returns outputs.
    *
    * To learn more, see the following quickstart guide:
    * https://developers.google.com/workspace/add-ons/studio/quickstart
    */
   
   /**
    * Creates an action response to push a new card onto the card stack.
    *
    * This function generates an action object that, when returned, causes the
    * provided card to be pushed onto the card stack, making it the currently
    * displayed card in the configuration UI.
    * @param {Object} card The Card object to push.
    * @return {Object} The action response object.
    */
   function pushCard(card) {
     return {
   
         "action": {
           "navigations": [{
               "push_card": card
             }
           ]
         }  };  
   }
   
   /**
    * Creates an action response to update the currently displayed card.
    *
    * This function generates an action object that, when returned, causes the
    * currently displayed card to be replaced with the provided card in the
    * configuration UI.
    * @param {Object} card The Card object to update.
    * @return {Object} The render actions object.
    */
   function updateCard(card) {
     return {
       "render_actions": {
         "action": {
           "navigations": [{
               "update_card": card
             }
           ]
         }
       }
     };
   }
   
   /**
    * Creates a button configuration object for saving the step.
    *
    * This function generates a button definition that, when clicked, triggers
    * a save action for the current step configuration.
    * @return {Object} The button widget object.
    */
   function saveButton() {
     return {
         "text": "Save",
         "onClick": {
           "hostAppAction" : {
             "workflowAction" : {
               "saveWorkflowAction" : {}
             }
           }
         },
       };
   }
   
   /**
    * Creates a button configuration object for a refresh action.
    *
    * This function generates a button definition that, when clicked, triggers
    * a function to refresh the current card.
    * @param {string} functionName The name of the Apps Script function to call on click.
    * @return {Object} The button widget object.
    */
   function refreshButton(functionName) {
     return {
         "text": "Refresh",
         "onClick": {
           "action" : {
             "function" : functionName
           }
         },
       };
   }
   
   
   /**
    * Generates and displays a configuration card for the sample calculation action.
    *
    * This function creates a card with input fields for two values and a dropdown
    * for selecting an arithmetic operation. The card also includes a "Save"
    * button to save the action configuration for the step.
    *
    * The input fields are configured to let the user select outputs from previous
    * steps as input values using the `hostAppDataSource` property.
    * This function is called when the user adds or edits the "Calculate" step in the UI.
    * @return {Object} The action response object containing the card to display.
    */
   function onConfigCalculateFunction() {
     var card = {
       "sections": [
         {
           "header": "Action sample: Calculate",
           "widgets": [
             {
               "textInput": {
                 "name": "value1",
                 "label": "First value",
                 "hostAppDataSource" : {
                   "workflowDataSource" : {
                     "includeVariables" : true
                   }
                 }
               }
             },
             {
               "selectionInput": {
                 "name": "operation",
                 "label": "Operation",
                 "type": "DROPDOWN",
                 "items": [
                   {
                     "text": "+",
                     "value": "+",
                   },
                   {
                     "text": "-",
                     "value": "-",
                   },
                   {
                     "text": "x",
                     "value": "x",
                   },
                   {
                     "text": "/",
                     "value": "/",
                   }
                 ]
               }
             },
             {
               "textInput": {
                 "name": "value2",
                 "label": "Second value",
                 "hostAppDataSource" : {
                   "workflowDataSource" : {
                     "includeVariables" : true
                   }
                 }
               }
             }
           ]
         }
       ]
     };
     return pushCard(card);
   }
   
   /**
    * Gets an integer value from variable data, handling both string and integer formats.
    *
    * This function attempts to extract an integer value from the provided variable data.
    * It checks if the data contains string values and, if so, parses the first string
    * as an integer. If integer values are present, it returns the first integer.
    * @param {Object} variableData The variable data object from the event.
    * @return {number} The extracted integer value.
    */
   function getIntValue(variableData) {
     if (variableData.stringValues) {
       return parseInt(variableData.stringValues[0]);
     }
     return variableData.integerValues[0];
   }
   
   /**
   * Returns output variables from a step.
   *
   * This function constructs an object that, when returned, sends the
   * provided variable values as output from the current step.
   * The variable values are logged to the console for debugging purposes.
   */
   function outputVariables(variableDataMap) {
    const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
      .setVariableDataMap(variableDataMap);
   
    const hostAppAction = AddOnsResponseService.newHostAppAction()
      .setWorkflowAction(workflowAction);
   
    const renderAction = AddOnsResponseService.newRenderActionBuilder()
      .setHostAppAction(hostAppAction)
      .build();
   
    return renderAction;
   }
   
   /**
    * Executes the calculation action based on the inputs from an event.
    *
    * This function retrieves input values ("value1", "value2") and the "operation"
    * from the event, performs the calculation, and returns the "result" and
    * "log" as output variables.
    * This function is called when the flow reaches this custom step.
    * @param {Object} event The event object passed by the runtime.
    * @return {Object} The output variables object.
    */
   function onExecuteCalculateFunction(event) {
    console.log("output: " + JSON.stringify(event));
    var calculatedValue = 0;
    var value1 = event.workflow.actionInvocation.inputs["value1"].integerValues[0];
    var value2 = event.workflow.actionInvocation.inputs["value2"].integerValues[0];
    var operation = event.workflow.actionInvocation.inputs["operation"].stringValues[0];
   
   
    if (operation == "+") {
      calculatedValue = value1 + value2;
    } else if (operation == "-") {
      calculatedValue = value1 - value2;
    } else if (operation == "x") {
      calculatedValue = value1 * value2;
    } else if (operation == "/") {
      calculatedValue = value1 / value2;
    }
   
    const variableDataMap = { "result": AddOnsResponseService.newVariableData().addIntegerValue(calculatedValue) };
   
    return outputVariables(variableDataMap);
   }

5. Haz clic en Configuración del proyecto settings y selecciona la casilla de verificación Mostrar el archivo de manifiesto "appsscript.json" en el editor.

6. Haz clic en Editor code, abre el archivo de manifiesto appsscript.json y reemplaza su contenido por el siguiente código:

   Ver el código de appsscript.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": "onConfigCalculateFunction",
               "onExecuteFunction": "onExecuteCalculateFunction"
             }
           }
         ]
       }
     }
   }

7. Haz clic en Guardar save.

Implementa y prueba tu paso

Para probar tu paso, configura una implementación de prueba para tu complemento, agrega el paso a un flujo y, luego, ejecuta el flujo.

1. Configura una implementación de prueba para tu complemento:

   1. Abre el proyecto de secuencia de comandos en el editor de Apps Script.
   2. Haz clic en Implementar > Implementaciones de prueba.
   3. Haz clic en Install.
   4. En la parte inferior, haz clic en Listo.

   Puedes permitir que otros usuarios prueben el complemento compartiendo el proyecto de Apps Script con su cuenta (se requiere acceso de edición). Luego, solicita a los usuarios que sigan los pasos anteriores.

   Una vez instalado, el complemento estará disponible de inmediato en Flows. Es posible que debas actualizar Flows antes de que aparezca el complemento. También debes autorizar el complemento antes de usarlo.

   Para obtener más información sobre las implementaciones de prueba, consulta Instala un complemento no publicado.

2. Abre Flows.

3. Crea un flujo que incluya tu paso:

   1. Haz clic en add Flujo nuevo.
   2. Selecciona cómo se inicia el flujo. Si tu paso requiere una variable de entrada, configúrala como parte del resultado del activador.
   3. Haz clic en addAgregar paso. Selecciona el paso que creaste o actualizaste, llamado Calculate.
   4. Configura el paso. Para el paso de cálculo, elige dos valores y una operación matemática. El paso se guarda automáticamente.
   5. Para probar el resultado de tu paso, agrega otro paso. Por ejemplo, para agregar un resultado a un mensaje de Google Chat, agrega el paso Notificarme en Chat de Chat. En Mensaje, haz clic en addVariables y selecciona el resultado de tu paso. Para el paso de cálculo, selecciona addVariables > Paso 2: Calcular > Resultado calculado. La variable aparece como un chip en el campo Mensaje.
   6. Haz clic en Activar. Tu flujo está listo para ejecutarse.

4. Ejecuta el flujo activando su activador. Por ejemplo, si tu flujo comienza según un programa, se ejecuta en la fecha y hora especificadas.

5. Verifica que el flujo se ejecute como se espera. Para consultar los registros, visita la pestaña Actividad del compilador de flujos. Para aprender a crear registros personalizados en la pestaña Actividad, consulta Registros de actividad.

Próximos pasos

Creaste y probaste correctamente un paso personalizado para Workspace Studio. Ahora puedes hacer lo siguiente:

• Sigue personalizando el paso con instrucciones para que Gemini te ayude a implementar una lógica más compleja.

• Crea una tarjeta de configuración para personalizar la configuración de los pasos.

• Registra la actividad y los errores para registrar y solucionar problemas de las ejecuciones de pasos.

• Revisa los objetos de evento para revisar la carga útil de JSON que los flujos envían y reciben a medida que se ejecutan los pasos.

• Prueba el codelab Crea pasos de inicio y de acción personalizados de Workspace Studio para crear un paso de inicio y un paso personalizados con Apps Script.