Crea una scheda di configurazione per un passaggio

Questa guida spiega come creare una scheda di configurazione che consente 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 dei componenti aggiuntivi di Google Workspace.
  • Servizio Scheda, un servizio Apps Script che consente agli script di configurare e creare schede.
  • Interfacce basate su schede nella documentazione per gli sviluppatori dei 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 di 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"
          }
        }
      ]
    }
  }
}

Modificare 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 SelectionInput widget per aiutare gli utenti a selezionare 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 per il completamento automatico possono provenire dalle seguenti origini dati:

  • Completamento automatico lato server: i suggerimenti vengono compilati da un'origine dati esterna o di terze parti definita da te.
  • Dati di Google Workspace: i suggerimenti vengono compilati da origini di Google Workspace, come utenti di Google Workspace o spazi di Google Chat.

Completamento automatico lato server

Puoi configurare un SelectionInput widget per completare automaticamente i suggerimenti da un'origine dati esterna source. Ad esempio, puoi aiutare gli utenti a selezionare 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. Definire l'origine dati: nel SelectionInput widget, aggiungi un DataSourceConfig che specifichi un RemoteDataSource. Questa configurazione rimanda a una funzione Apps Script che recupera i suggerimenti per il completamento automatico.
  2. Implementare la funzione di completamento automatico: questa funzione viene attivata quando l' utente digita nel campo di immissione. La funzione deve eseguire una query sull'origine dati esterna in base all'input dell'utente e restituire un elenco di suggerimenti.

L'esempio seguente mostra come configurare un SelectionInput widget 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. Controllare event.workflow.elementUiAutocomplete.invokedFunction per assicurarsi che corrisponda al nome della funzione previsto.
  2. Recuperare l'input dell'utente da event.workflow.elementUiAutocomplete.query.
  3. Eseguire una query sull'origine dati esterna utilizzando la query.
  4. Restituire 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 delle schede