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 vous le feriez pour n'importe quel 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 des modules complémentaires Google Workspace.
- 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 un système de gestion de la relation client (CRM).
Pour implémenter l'autocomplete côté serveur, vous devez :
- Définissez la source de données : dans le widget
SelectionInput, ajoutez unDataSourceConfigqui spécifie unRemoteDataSource. Cette configuration pointe vers une fonction Apps Script qui récupère les suggestions de saisie semi-automatique. - 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 :
- Vérifiez que
event.workflow.elementUiAutocomplete.invokedFunctioncorrespond au nom de fonction attendu. - Obtenez l'entrée de l'utilisateur à partir de
event.workflow.elementUiAutocomplete.query. - Interrogez la source de données externe à l'aide de la requête.
- 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 ...
}
Saisie semi-automatique des données Google Workspace
Vous pouvez également remplir les suggestions de saisie semi-automatique à partir des données de l'environnement Google Workspace de l'utilisateur :
- Utilisateurs Google Workspace : remplissez les utilisateurs de la même organisation Google Workspace.
- Espaces Google Chat : remplissez les espaces Google Chat dont l'utilisateur est membre.
Pour configurer cela, définissez PlatformDataSource dans le widget SelectionInput, en spécifiant WorkflowDataSourceType sur USER ou SPACE.
Apps Script
// User Autocomplete
var multiSelect2 =
CardService.newSelectionInput()
.setFieldName("value2")
.setTitle("User Autocomplete")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setMultiSelectMaxSelectedItems(3)
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setType(CardService.WorkflowDataSourceType.USER)
))
);
// Chat Space Autocomplete
var multiSelect3 =
CardService.newSelectionInput()
.setFieldName("value3")
.setTitle("Chat Space Autocomplete")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setMultiSelectMaxSelectedItems(3)
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setType(CardService.WorkflowDataSourceType.SPACE)
))
);
Exemple : Combiner des types de saisie semi-automatique
L'exemple suivant montre une fonction onConfig qui crée une fiche avec trois widgets SelectionInput, illustrant l'autocomplete côté serveur, utilisateur et espace :
JSON
{
"timeZone": "America/Los_Angeles",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Autocomplete Demo",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "autocomplete_demo",
"state": "ACTIVE",
"name": "Autocomplete Demo",
"description": "Provide autocompletion in input fields",
"workflowAction": {
"inputs": [
{
"id": "value1",
"description": "A multi-select field with autocompletion",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"onConfigFunction": "onConfigAutocomplete",
"onExecuteFunction": "onExecuteAutocomplete"
}
}
]
}
}
}
Apps Script
function onConfigAutocompleteTest(event) {
// Handle autocomplete request
if (event.workflow && event.workflow.elementUiAutocomplete) {
return handleAutocompleteRequest(event);
}
// Server-side autocomplete widget
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)
))
)
);
// User autocomplete widget
var multiSelect2 =
CardService.newSelectionInput()
.setFieldName("value2")
.setTitle("User Autocomplete")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setMultiSelectMaxSelectedItems(3)
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setType(CardService.WorkflowDataSourceType.USER)
))
);
// Space autocomplete widget
var multiSelect3 =
CardService.newSelectionInput()
.setFieldName("value3")
.setTitle("Chat Space Autocomplete")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setMultiSelectMaxSelectedItems(3)
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setType(CardService.WorkflowDataSourceType.SPACE)
))
);
var sectionBuilder =
CardService.newCardSection()
.addWidget(multiSelect1)
.addWidget(multiSelect2)
.addWidget(multiSelect3);
var card =
CardService.newCardBuilder()
.addSection(sectionBuilder)
.build();
return card;
}
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
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();
}
Personnaliser les boutons du sélecteur de variables
Vous pouvez personnaliser le sélecteur de variables en définissant la taille et le libellé du bouton.
Taille du bouton
Pour définir la taille du bouton, utilisez setVariableButtonSize() avec l'une des énumérations VariableButtonSize suivantes :
UNSPECIFIED: valeur par défaut. Le bouton est compact dans le panneau latéral et en taille réelle dans les autres contextes.COMPACT: le bouton n'affiche qu'un signe plus (+).FULL_SIZE: le bouton affiche le libellé complet.
Texte du bouton
Pour définir le texte du bouton, utilisez setVariableButtonLabel().
Exemple de personnalisation du sélecteur de variables
L'exemple suivant montre comment configurer des widgets TextInput avec différentes tailles de bouton de sélection de variables et un libellé personnalisé.
-
Figure 1 : Personnalisation du bouton du sélecteur de variables sur le Web. -
Figure 2 : Personnalisation du bouton du sélecteur de variables dans un panneau latéral de module complémentaire.
Voici le fichier manifeste permettant de personnaliser les boutons du sélecteur de variables :
JSON
{
"timeZone": "America/Los_Angeles",
"dependencies": {},
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"oauthScopes": [
"https://www.googleapis.com/auth/script.locale"
],
"addOns": {
"common": {
"name": "Variable button customization",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "variable_picker_customization",
"state": "ACTIVE",
"name": "Variable Picker demo",
"description": "List all possible variable picker customization options",
"workflowAction": {
"onConfigFunction": "onUpdateCardConfigFunction",
"onExecuteFunction": "onUpdateCardExecuteFunction"
}
}
]
}
}
}
Voici le code permettant de personnaliser les boutons du sélecteur de variables :
Apps Script
function onUpdateCardConfigFunction(event) {
const textInput1 = CardService.newTextInput()
.setFieldName("value1")
.setTitle("Regular variable picker button")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
)
);
const textInput2 = CardService.newTextInput()
.setFieldName("value2")
.setTitle("Size: Unspecified")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
)
);
const textInput3 = CardService.newTextInput()
.setFieldName("value3")
.setTitle("Size: Full size")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.FULL_SIZE)
)
);
const textInput4 = CardService.newTextInput()
.setFieldName("value4")
.setTitle("Size: Compact")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.COMPACT)
)
);
const textInput5 = CardService.newTextInput()
.setFieldName("value5")
.setTitle("Custom button label")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonLabel("New button label!")
)
);
var cardSection = CardService.newCardSection()
.addWidget(textInput1)
.addWidget(textInput2)
.addWidget(textInput3)
.addWidget(textInput4)
.addWidget(textInput5)
.setId("section_1");
var card = CardService.newCardBuilder().addSection(cardSection).build();
return card;
}
function onUpdateCardExecuteFunction(event) {
}
Fonctionnalités spécifiques à Workspace Studio
Certains widgets de cartes disposent de fonctionnalités spécifiques à Workspace Studio, détaillées ici.
TextInput et SelectionInput
Les widgets TextInput et SelectionInput disposent des fonctionnalités spécifiques à Workspace Studio suivantes :
includeVariables: propriété booléenne qui permet aux utilisateurs de sélectionner des variables à partir des étapes précédentes. Pour que le sélecteur de variables s'affiche lors des étapes ultérieures, l'événement de départ et au moins une variable de sortie correspondante doivent être mappés à la variable.type: valeur énumérée qui complète automatiquement les suggestions. Les valeurs acceptées sont les suivantes :USER: fournit des suggestions de saisie semi-automatique pour les personnes figurant dans les contacts de l'utilisateur.SPACE: fournit des suggestions de saisie semi-automatique pour les espaces Google Chat dont l'utilisateur est membre.
Lorsque includeVariables et type sont définis, le champ de saisie combine leurs expériences. Les utilisateurs peuvent sélectionner une variable du type correspondant dans un menu déroulant et voir des suggestions de saisie automatique.
-
Figure 3 : Un utilisateur examine les suggestions de saisie semi-automatique lorsqu'il choisit un espace. -
Figure 4 : Un utilisateur sélectionne la variable de sortie d'une étape précédente dans le menu déroulant ➕ Variables.
Sélectionner une seule variable de sortie avec un menu à développer
Vous pouvez configurer un widget SelectionInput pour permettre aux utilisateurs de sélectionner une seule variable de sortie à partir d'une étape précédente à l'aide d'un menu à développer.
Lorsque vous définissez SelectionInputType sur OVERFLOW_MENU, le widget sert de sélecteur de variables dédié. Contrairement à l'utilisation de includeVariables avec TextInput, qui convertit les valeurs de variables en chaînes, OVERFLOW_MENU conserve le type de données d'origine de la variable sélectionnée.
Apps Script
const selectionInput = CardService.newSelectionInput()
.setFieldName("variable_picker_1")
.setTitle("Variable Picker")
.setType(
CardService.SelectionInputType.OVERFLOW_MENU
);
Permettre aux utilisateurs de combiner du texte et des variables de sortie
Vous pouvez configurer des widgets TextInput pour contrôler la façon dont les utilisateurs interagissent avec le texte et les variables de sortie à l'aide de setInputMode().
RICH_TEXT: permet aux utilisateurs de combiner du texte et des variables de sortie. Le résultat est une seule chaîne concaténée.PLAIN_TEXT: restreint l'entrée. Les utilisateurs peuvent saisir du texte ou sélectionner une seule variable de sortie. Si vous sélectionnez une variable, elle remplace le texte existant. Utilisez ce mode pour appliquer des types de données spécifiques définis dans le fichier manifeste.
L'image suivante montre deux widgets TextInput. La première est configurée en tant que RICH_TEXT et comporte du texte et une variable de sortie. La seconde est configurée en tant que PLAIN_TEXT et n'autorise qu'une variable de sortie.
-
Figure 5 : Widgets de saisie de texte configurés en tant que RICH_TEXTetPLAIN_TEXT.
Nous vous recommandons de définir explicitement le mode d'entrée pour tous les widgets TextInput.
Voici le fichier manifeste permettant de configurer les widgets TextInput avec différents modes de saisie :
JSON
{
"timeZone": "America/Toronto",
"dependencies": {},
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Text and output variable demo",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "richTextDemo",
"state": "ACTIVE",
"name": "Rich Text Demo",
"description": "Show the difference between rich text and plain text TextInput widgets",
"workflowAction": {
"inputs": [
{
"id": "value1",
"description": "First user input",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
},
{
"id": "value2",
"description": "Second user input",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"onConfigFunction": "onConfiguration",
"onExecuteFunction": "onExecution"
}
}
]
}
}
}
Voici le code permettant de configurer les widgets TextInput avec différents modes de saisie :
Apps Script
function onConfiguration() {
const input1 = CardService.newTextInput()
.setFieldName("value1")
.setId("value1")
.setTitle("Rich Text")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
)
// Set input mode to RICH_TEXT to allow mixed text and variables.
.setInputMode(CardService.TextInputMode.RICH_TEXT);
const input2 = CardService.newTextInput()
.setFieldName("value2")
.setId("value2")
.setTitle("Plain text")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
)
// Set input mode to PLAIN_TEXT to enforce single variable selection.
.setInputMode(CardService.TextInputMode.PLAIN_TEXT);
const section = CardService.newCardSection()
.addWidget(input1)
.addWidget(input2);
const card = CardService.newCardBuilder()
.addSection(section)
.build();
return card;
}
function onExecution(e) {
}
Remarques et limites concernant les cartes
La navigation par fiche, comme
popCard(),pushCard()etupdateCard(), n'est pas prise en charge dans les modules complémentaires qui étendent Workspace Studio.Lorsque
SelectionInputest utilisé dans un sélecteur de variables, les widgets ne sont compatibles qu'avec"type": "MULTI_SELECT". Ailleurs dans les cartes de configuration,SelectionInputaccepte toutes les valeurs deSelectionType.
Articles associés
- Créer une étape
- Variables d'entrée
- Valider une variable d'entrée
- Variables de sortie
- Consigner l'activité et les erreurs
- Objets d'événement Workspace Studio