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 devez créer une interface de fiche comme pour tout autre module complémentaire Google Workspace. Pour obtenir de l'aide concernant la création d'interfaces de cartes de configuration, consultez les ressources suivantes :

  • Card Builder, un outil interactif qui vous aide à créer et à définir des fiches.
  • Card dans la documentation de référence de l'API Google Workspace Add-ons.
  • Card Service, un service Apps Script qui permet aux scripts de configurer et de créer des fiches.
  • Interfaces basées sur des fiches dans la documentation pour les développeurs de modules complémentaires Google Workspace.

Certains widgets de cartes disposent de fonctionnalités et de caractéristiques spécifiques à Workspace Studio, 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 carte.

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 de saisie

Vous pouvez configurer la saisie semi-automatique pour les widgets SelectionInput 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 fini de saisir. Vous pouvez saisir automatiquement jusqu'à 100 éléments.

Les suggestions de saisie 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 proviennent de sources Google Workspace, comme les utilisateurs Google Workspace ou les espaces Google Chat.

Saisie semi-automatique côté serveur

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

Pour implémenter l'autocomplete côté serveur, vous devez :

  1. Définissez la source de données : dans le widget SelectionInput, ajoutez un DataSourceConfig qui spécifie un RemoteDataSource. Cette configuration pointe vers une fonction Apps Script qui récupère les suggestions de saisie semi-automatique.
  2. Implémentez 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 la saisie de l'utilisateur et renvoyer une liste de suggestions.

L'exemple suivant montre comment configurer un widget SelectionInput pour l'autocomplete 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érifiez que event.workflow.elementUiAutocomplete.invokedFunction correspond au nom de fonction attendu.
  2. Obtenez l'entrée de l'utilisateur à partir de event.workflow.elementUiAutocomplete.query.
  3. Interrogez la source de données externe à l'aide de la requête.
  4. Renvoie 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 cartes