Créer une fiche de configuration pour une étape

Ce guide explique comment créer une fiche de configuration qui permet aux utilisateurs de personnaliser une étape dans Google Workspace Studio et de fournir des entrées pour celle-ci.

En général, pour créer une fiche de configuration, vous créez une interface de fiche comme vous le feriez pour n'importe quel autre module complémentaire Google Workspace. Pour obtenir de l'aide sur la création d'interfaces de fiches de configuration, consultez les ressources suivantes :

Certains widgets de fiche disposent de fonctionnalités et de caractéristiques spécifiques à Workspace Studio, qui sont détaillées dans ce guide.

Définir une fiche de configuration

Définissez une fiche de configuration dans le fichier manifeste Apps Script et dans le code.

L'exemple suivant montre comment créer une fiche de configuration qui demande aux utilisateurs de sélectionner un espace Google Chat.

Modifier le fichier manifeste

Dans le fichier manifeste, définissez 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"
          }
        }
      ]
    }
  }
}

Modifier le code

Dans le code de l'application, renvoyez une fiche.

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

Configurer la saisie semi-automatique pour les widgets d'entrée

Vous pouvez configurer la saisie semi-automatique pour les SelectionInput widgets afin d'aider les utilisateurs à faire leur choix dans une liste d'options. Par exemple, si un utilisateur commence à saisir Atl pour un menu qui affiche les villes des États-Unis, votre élément peut suggérer automatiquement Atlanta avant que l'utilisateur ait terminé de saisir. Vous pouvez compléter automatiquement jusqu'à 100 éléments.

Les suggestions de saisie semi-automatique peuvent provenir des sources de données suivantes :

  • Saisie semi-automatique côté serveur : les suggestions sont générées à partir d'une source de données tierce ou externe que vous définissez.
  • Données Google Workspace : les suggestions sont générées à partir de sources Google Workspace, telles que les utilisateurs Google Workspace ou les espaces Google Chat.

Saisie semi-automatique côté serveur

Vous pouvez configurer un SelectionInput widget pour compléter automatiquement les suggestions à partir d'une source de données externe. Par exemple, vous pouvez aider les utilisateurs à faire leur choix dans une liste de prospects commerciaux à partir d'un système de gestion de la relation client (CRM).

Pour implémenter la saisie semi-automatique côté serveur, vous devez :

  1. Définir la source de données : dans le widget SelectionInput, ajoutez une DataSourceConfig qui spécifie une RemoteDataSource. Cette configuration pointe vers une fonction Apps Script qui récupère les suggestions de saisie semi-automatique.
  2. Implémenter la fonction de saisie semi-automatique : cette fonction est déclenchée lorsque l' utilisateur saisit du texte dans le champ de saisie. La fonction doit interroger votre source de données externe en fonction de l'entrée de l'utilisateur et renvoyer une liste de suggestions.

L'exemple suivant montre comment configurer un SelectionInput widget pour la saisie semi-automatique côté serveur :

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

Gérer la requête de saisie semi-automatique

La fonction spécifiée dans setFunctionName (par exemple, getAutocompleteResults) reçoit un objet d'événement lorsque l'utilisateur saisit du texte dans le champ. Cette fonction doit :

  1. vérifier que event.workflow.elementUiAutocomplete.invokedFunction correspond au nom de fonction attendu ;
  2. obtenir l'entrée de l'utilisateur à partir de event.workflow.elementUiAutocomplete.query ;
  3. interroger la source de données externe à l'aide de la requête ;
  4. renvoyer jusqu'à 100 suggestions au format requis.

L'exemple suivant montre comment implémenter la fonction handleAutocompleteRequest() pour renvoyer des suggestions en fonction de la requête de l'utilisateur :

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

Remarques et limites concernant les fiches