Crea una scheda di configurazione per un passaggio

Questa guida spiega come creare una scheda di configurazione che consenta agli utenti di personalizzare e fornire input per un passaggio in Google Workspace Studio.

In generale, per creare una scheda di configurazione, devi creare un'interfaccia della scheda come faresti per qualsiasi altro componente aggiuntivo di Google Workspace. Per assistenza nella creazione di interfacce di schede di configurazione, consulta quanto segue:

  • Il generatore di schede, uno strumento interattivo che ti aiuta a creare e definire le schede.
  • Scheda nella documentazione di riferimento dell'API Google Workspace Add-ons.
  • Servizio schede, un servizio Apps Script che consente agli script di configurare e creare schede.
  • Interfacce basate su schede nella documentazione per gli sviluppatori di componenti aggiuntivi di Google Workspace.

Alcuni widget delle schede hanno funzionalità e caratteristiche speciali specifiche di Workspace Studio, descritte in dettaglio in questa guida.

Definire una scheda di configurazione

Definisci una scheda di configurazione sia nel manifest di Apps Script sia nel codice.

L'esempio seguente mostra come creare una scheda di configurazione che chiede agli utenti di selezionare uno spazio Google Chat.

Modificare il file manifest

Nel file manifest, definisci 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"
          }
        }
      ]
    }
  }
}

Modifica il codice

Nel codice dell'applicazione, restituisci una scheda.

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

Configurare il completamento automatico per i widget di input

Puoi configurare il completamento automatico per i widget SelectionInput per aiutare gli utenti a scegliere da un elenco di opzioni. Ad esempio, se un utente inizia a digitare Atl per un menu che popola le città degli Stati Uniti, l'elemento può suggerire automaticamente Atlanta prima che l'utente finisca di digitare. Puoi completare automaticamente fino a 100 elementi.

I suggerimenti di completamento automatico possono provenire dalle seguenti origini dati:

  • Completamento automatico lato server:i suggerimenti vengono compilati da un'origine dati di terze parti o esterna che definisci.
  • Dati di Google Workspace:i suggerimenti vengono compilati a partire da fonti di Google Workspace, come utenti di Google Workspace o spazi di Google Chat.

Completamento automatico lato server

Puoi configurare un widget SelectionInput per completare automaticamente i suggerimenti da un'origine dati esterna. Ad esempio, puoi aiutare gli utenti a scegliere da un elenco di lead di vendita da un sistema di gestione dei rapporti con i clienti (CRM).

Per implementare il completamento automatico lato server, devi:

  1. Definisci l'origine dati:nel widget SelectionInput, aggiungi un DataSourceConfig che specifica un RemoteDataSource. Questa configurazione punta a una funzione Apps Script che recupera i suggerimenti di completamento automatico.
  2. Implementa la funzione di completamento automatico:questa funzione viene attivata quando l'utente digita nel campo di input. La funzione deve eseguire query sulla sorgente di dati esterni in base all'input dell'utente e restituire un elenco di suggerimenti.

L'esempio seguente mostra come configurare un widget SelectionInput per il completamento automatico lato server:

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

Gestire la richiesta di completamento automatico

La funzione specificata in setFunctionName (ad es. getAutocompleteResults) riceve un oggetto evento quando l'utente digita nel campo. Questa funzione deve:

  1. Controlla event.workflow.elementUiAutocomplete.invokedFunction per assicurarti che corrisponda al nome della funzione previsto.
  2. Recupera l'input dell'utente da event.workflow.elementUiAutocomplete.query.
  3. Esegui una query sull'origine dati esterna utilizzando la query.
  4. Restituisci fino a 100 suggerimenti nel formato richiesto.

L'esempio seguente mostra come implementare la funzione handleAutocompleteRequest() per restituire suggerimenti in base alla query dell'utente:

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

Considerazioni e limitazioni relative alle carte