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

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

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 y características especiales específicas de Workspace Studio, 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": "Chat space selector",
      "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": "onExecuteSpacePicker"
          }
        }
      ]
    }
  }
}

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() {

  const selectionInput = CardService.newSelectionInput()
    .setTitle("First Value")
    .setFieldName("chooseSpace")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            )
        )
    );

  const cardSection = CardService.newCardSection()
    .setHeader("Select Chat Space")
    .setId("section_1")
    .addWidget(selectionInput)

  var card = CardService.newCardBuilder()
    .addSection(cardSection)
    .build();

  return card;
}

function onExecuteSpacePicker(e) {
}

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 de 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 el autocompletado 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 autocompletado.
  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
  let autocompleteResponse = AddOnsResponseService.newUpdateWidget()
    .addSuggestion(
      query + " option 1",
      query + "_option1",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 1 bottom text"
    )
    .addSuggestion(
      query + " option 2",
      query + "_option2",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 2 bottom text"
    ).addSuggestion(
      query + " option 3",
      query + "_option3",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 3 bottom text"
    );

  const modifyAction = AddOnsResponseService.newAction()
    .addModifyCard(
      AddOnsResponseService.newModifyCard()
        .setUpdateWidget(autocompleteResponse)
    );

  return AddOnsResponseService.newRenderActionBuilder()
    .setAction(modifyAction)
    .build();
}

// 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 ...
}

Consideraciones y limitaciones de las tarjetas