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 lo siguiente:

  • El Creador de tarjetas, una herramienta interactiva que te ayuda a crear y definir tarjetas
  • Tarjeta 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 creen 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 crear una tarjeta de configuración que les solicita a los usuarios que seleccionen un espacio de Chat de Google.

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, muestra 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 Autocomplete para widgets de entrada

Puedes configurar Autocomplete para SelectionInput widgets para 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 los Estados Unidos, tu elemento puede sugerir automáticamente Atlanta antes de que el usuario termine de escribir. Puedes completar automáticamente hasta 100 elementos.

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

  • Autocompletado del servidor: Las sugerencias se completan a partir de una fuente de datos externa o de terceros que definas.
  • 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.

Autocompletado del servidor

Puedes configurar un SelectionInput widget para completar automáticamente las sugerencias de una fuente de datos externa. Por ejemplo, puedes ayudar a los usuarios a seleccionar una lista de clientes potenciales de ventas 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 SelectionInput widget, 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 autocompletado: 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 mostrar una lista de sugerencias.

En el siguiente ejemplo, se muestra cómo configurar un SelectionInput widget para el autocompletado 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 autocompletado

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. Verificar event.workflow.elementUiAutocomplete.invokedFunction para asegurarse de que coincida con el nombre de función esperado
  2. Obtener la entrada del usuario de event.workflow.elementUiAutocomplete.query
  3. Consultar la fuente de datos externa con la consulta
  4. Mostrar hasta 100 sugerencias en el formato requerido

En el siguiente ejemplo, se muestra cómo implementar la función handleAutocompleteRequest() para mostrar sugerencias según la consulta 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