Cómo compilar una tarjeta de configuración para un paso

Programa de la versión alfa de Gemini: Flows está disponible como parte del programa de la versión alfa de Gemini.

En esta guía, se explica cómo compilar una tarjeta de configuración que permita a los usuarios personalizar y proporcionar entradas para un paso en Google Workspace Flows.

En general, para crear una tarjeta de configuración, debes crear una interfaz de tarjeta como lo harías para cualquier otro complemento de Google Workspace. Si necesitas ayuda para crear interfaces de tarjetas de configuración, consulta los siguientes recursos:

• Card Builder, una herramienta interactiva que te ayuda a crear y definir tarjetas
• Card en la documentación de referencia de la API de complementos de Google Workspace
• Card Service, un servicio de Apps Script que permite que las secuencias de comandos configuren y compilen tarjetas.
• Interfaces basadas en tarjetas en la documentación para desarrolladores de complementos de Google Workspace

Algunos widgets de tarjetas tienen funciones especiales específicas de los flujos de Workspace, que se detallan en esta guía.

Define una tarjeta de configuración

Define una tarjeta de configuración en el manifiesto de Apps Script y en el código.

En el siguiente ejemplo, se muestra cómo compilar una tarjeta de configuración que les solicite a los usuarios que seleccionen un espacio de Google Chat.

Edita el archivo de manifiesto

En el archivo de manifiesto, define workflowElements.

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Sample add-on",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Chat space selector",
          "description": "Lets the user select a space from Google  Chat",
          "workflowAction": {
            "inputs": [
              {
                "id": "chooseSpace",
                "description": "Choose a Chat space",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigSpacePicker",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

Editar código

En el código de la aplicación, devuelve una tarjeta.

Apps Script

/**
* Generates and displays a configuration card to choose a Chat space
  */
function onConfigSpacePicker() {
  var card = {
    "sections": [
      {
        "header": "Choose a Chat space",
        "widgets": [
          {
            "selectionInput": {
              "name": "value1",
              "label": "First value",
              "type": "MULTI_SELECT",
              "platformDataSource": {
                "hostAppDataSource": {
                  "workflowDataSource": {
                    "includeVariables": true,
                    "type": "SPACE"
                  }
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

Configura la función de autocompletar para los widgets de entrada

Puedes configurar el autocompletado para los widgets de SelectionInput y ayudar a los usuarios a seleccionar opciones de una lista. Por ejemplo, si un usuario comienza a escribir Atl para un menú que completa ciudades en Estados Unidos, tu elemento puede sugerir automáticamente Atlanta antes de que el usuario termine de escribir. Puedes autocompletar hasta 100 elementos.

Las sugerencias de Autocomplete pueden provenir de las siguientes fuentes de datos:

• Autocompletado del servidor: Las sugerencias se propagan desde una fuente de datos externa o de terceros que tú defines.
• Datos de Google Workspace: Las sugerencias se completan a partir de fuentes de Google Workspace, como usuarios de Google Workspace o espacios de Google Chat.

Autocompletar del servidor

Puedes configurar un widget SelectionInput para que autocomplete sugerencias de una fuente de datos externa. Por ejemplo, puedes ayudar a los usuarios a seleccionar clientes potenciales de ventas de una lista de un sistema de administración de relaciones con clientes (CRM).

Para implementar la función de autocompletar del servidor, debes hacer lo siguiente:

1. Define la fuente de datos: En el widget SelectionInput, agrega un DataSourceConfig que especifique un RemoteDataSource. Esta configuración apunta a una función de Apps Script que recupera sugerencias de autocompletar.
2. Implementa la función de autocompletar: Esta función se activa cuando el usuario escribe en el campo de entrada. La función debe consultar tu fuente de datos externa según la entrada del usuario y devolver una lista de sugerencias.

En el siguiente ejemplo, se muestra cómo configurar un widget SelectionInput para la función de autocompletar del servidor:

Apps Script

// In your onConfig function:
var multiSelect1 =
  CardService.newSelectionInput()
    .setFieldName("value1")
    .setTitle("Server Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setRemoteDataSource(
          CardService.newAction().setFunctionName('getAutocompleteResults')
        )
    )
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setPlatformDataSource(
          CardService.newPlatformDataSource()
            .setHostAppDataSource(
              CardService.newHostAppDataSource()
                .setWorkflowDataSource(
                  CardService.newWorkflowDataSource()
                    .setIncludeVariables(true)
                ))
        )
    );

// ... add widget to card ...

Controla la solicitud de autocompletar

La función especificada en setFunctionName (p.ej., getAutocompleteResults) recibe un objeto de evento cuando el usuario escribe en el campo. Esta función debe hacer lo siguiente:

1. Verifica el event.workflow.elementUiAutocomplete.invokedFunction para asegurarte de que coincida con el nombre de la función esperada.
2. Obtén la entrada del usuario de event.workflow.elementUiAutocomplete.query.
3. Consulta la fuente de datos externa con la consulta.
4. Devuelve hasta 100 sugerencias en el formato requerido.

En el siguiente ejemplo, se muestra cómo implementar la función handleAutocompleteRequest() para devolver sugerencias basadas en la búsqueda del usuario:

Apps Script

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results based on the query
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // ... rest of your card building logic ...
}

Autocompletado de datos de Google Workspace

También puedes propagar sugerencias de autocompletar a partir de los datos del entorno de Google Workspace del usuario:

• Usuarios de Google Workspace: Se completan los usuarios dentro de la misma organización de Google Workspace.
• Espacios de Google Chat: Se completan los espacios de Google Chat de los que el usuario es miembro.

Para configurar esto, establece PlatformDataSource en el widget SelectionInput y especifica WorkflowDataSourceType como USER o SPACE.

Apps Script

// User Autocomplete
var multiSelect2 =
  CardService.newSelectionInput()
    .setFieldName("value2")
    .setTitle("User Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.USER)
            ))
    );

// Chat Space Autocomplete
var multiSelect3 =
  CardService.newSelectionInput()
    .setFieldName("value3")
    .setTitle("Chat Space Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            ))
    );

Ejemplo: Combinación de tipos de autocompletado

En el siguiente ejemplo, se muestra una función onConfig que crea una tarjeta con tres widgets SelectionInput, lo que demuestra la función de autocompletar del servidor, del usuario y del espacio:

Apps Script

function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // Server-side autocomplete widget
  var multiSelect1 =
    CardService.newSelectionInput()
      .setFieldName("value1")
      .setTitle("Server Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setRemoteDataSource(
            CardService.newAction().setFunctionName('getAutocompleteResults')
          )
      )
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setPlatformDataSource(
            CardService.newPlatformDataSource()
              .setHostAppDataSource(
                CardService.newHostAppDataSource()
                  .setWorkflowDataSource(
                    CardService.newWorkflowDataSource()
                      .setIncludeVariables(true)
                  ))
          )
      );

  // User autocomplete widget
  var multiSelect2 =
    CardService.newSelectionInput()
      .setFieldName("value2")
      .setTitle("User Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.USER)
              ))
      );

  // Space autocomplete widget
  var multiSelect3 =
    CardService.newSelectionInput()
      .setFieldName("value3")
      .setTitle("Chat Space Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.SPACE)
              ))
      );

  var sectionBuilder =
    CardService.newCardSection()
      .addWidget(multiSelect1)
      .addWidget(multiSelect2)
      .addWidget(multiSelect3);

  var card =
    CardService.newCardBuilder()
      .addSection(sectionBuilder)
      .build();
  return card;
}

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

Funciones específicas de Workspace Flows

Algunos widgets de tarjetas tienen funciones y características especiales específicas de los flujos de Workspace, que se detallan aquí.

TextInput y SelectionInput

Los widgets TextInput y SelectionInput tienen estas funciones específicas de los flujos de trabajo de Workspace:

• includeVariables: Es una propiedad booleana que permite a los usuarios seleccionar variables de pasos anteriores.
• type: Es un valor enumerado que autocompleta las sugerencias. Entre los valores admitidos, se incluyen los siguientes:
  • USER: Proporciona sugerencias de autocompletar para las personas en los contactos del usuario.
  • SPACE: Proporciona sugerencias de autocompletado para los espacios de Google Chat de los que el usuario es miembro.

Cuando se configuran includeVariables y type, el campo de entrada combina sus experiencias. Los usuarios pueden seleccionar una variable del type coincidente en un menú desplegable y ver sugerencias de autocompletar para ella.

• 

  Figura 1: Un usuario revisa las sugerencias de autocompletar cuando elige un espacio.

• 

  Figura 2: Un usuario selecciona la variable de salida de un paso anterior en el menú desplegable ➕Variables.

Consideraciones y limitaciones de las tarjetas

• La navegación con tarjetas, como popCard(), pushCard() y updateCard(), no se admite en los complementos que extienden los flujos.

• Cuando se usa SelectionInput en un selector de variables, los widgets solo admiten "type": "MULTI_SELECT". En otras partes de las tarjetas de configuración, SelectionInput admite todos los valores de SelectionType.

Temas relacionados

• Cómo crear un paso
• Variables de entrada
• Cómo validar una variable de entrada
• Variables de salida
• Registra la actividad y los errores
• Objeto de evento de Flows