Variables

Définition d'une variable

Chaque fois qu'un utilisateur fournit une information qui doit être stockée par le bot, celle-ci est sauvegardée dans une variable nommée en tant que sa valeur. Elle peut être réutilisée plus tard dans la conversation ou envoyée à une API externe.

---

Différents types de variables fournis par le BMS Dydu

Le BMS fournit essentiellement deux types de variables en fonction de la sollicitation ou non de l'algorithme de matching NLP (traitement de langage naturel) de Dydu :

1. Variable en saisie libre. Elle capture et enregistre une information fournie directement par l'utilisateur pendant la conversation, peu importe le format des données (nombre, date, texte, etc.). Ce type de variable ne sera pas analysé par l'algorithme NLP de Dydu et il n'y a donc pas de matching.

2. Variable prédéfinie par défaut. Elle doit être utilisée en respectant le format prédéfini (nombre, date, texte, etc.). L'algorithme de matching analysera les données utilisateurs (données personnelles, comportementales ou événementielles) capturées dans ce type de variable pour fournir la réponse la plus appropriée issue de votre base de connaissances.

---

1. Variable en saisie libre

Comment utiliser une variable en saisie libre ?

Prenons l'exemple suivant : Un utilisateur veut déclarer un arrêt de maladie via le bot RH de son entreprise. Pour traiter la demande, le bot demande des informations personnelles à l’utilisateur.

Étapes à suivre :

1. Créez une connaissance comme vous le feriez habituellement. Dans la réponse, incitez l'utilisateur à fournir ces informations supplémentaires.

1. Cliquez sur le bouton + ("Ajouter une intention") en dessous de l'éditeur de la réponse et choisissez l'option "capturer la saisie utilisateur".

1. Donnez un nom pertinent à cette variable selon le type d'information qui sera capturée.

1. Puisque nous voulons également connaître le numéro de sécurité sociale de l'utilisateur, nous allons ajouter une autre variable en saisie libre que nous appellerons «num_secu».

Pour ce type de variable, il n'y a pas de vérification de format sur la valeur capturée.

Si les utilisateurs font une erreur ou fournissent intentionnellement une information erronée, les données seront enregistrées dans le BMS.

Si vous avez besoin de vérifier le format des données, nous vous conseillons d'utiliser des variables par défaut couplées à une condition de contexte.

Lors d'une saisie 'utilisateur, si l'utilisateur tape "+" devant sa saisie alors le "+" n'est pas conservé lors de la restitution du contenu de la variable.

Pour conserver le "+" utilisé au début de l'entrée, la variable qui stocke l'entrée doit contenir le terme "phone".

Exemple :

Si la variable, qui stocke la saisie libre, contient le terme "phone"

Alors, lorsque l'utilisateur passe par cette branche et saisi "[phone]", le contenu de la variable restitué sera "[phone]". Sinon (la variable, qui stocke la saisie libre, ne contient pas le terme "phone") le contenu restitué sera "33679305151" (le "+" est supprimé dans la restitution.

1. Enfin, imaginons que pour rassurer l'utilisateur que ses informations ont été bien enregistrées, le bot va résumer l'information recueillie en affichant la valeur de la variable dans sa réponse. Pour afficher une valeur de variable capturée dans une réponse, utilisez la syntaxe ${capture.NomdelaVariable}.

---

2. Variables prédéfinies par défaut

Lorsque vous éditez une connaissance, vous pouvez utiliser des variables prédéfinies pour récupérer les informations de l'utilisateur telles que le nom, le numéro de téléphone, l'âge ou la date.

Le BMS fournit quelques formats de variable par défaut :

• Entier: cette variable ne capture que les nombres entiers (pas de décimales). Notez que les nombres entiers écrits en lettres seront compris comme des nombres (par exemple : "vingt" sera compris comme "20").

• Nombre: cette variable capture des nombres. Les nombres entiers écrits en lettres seront compris comme des nombres.

• Alphanumérique: cette variable capture des lettres et/ou des nombres entiers (pas de décimales).

• Mail: cette variable capture une adresse e-mail selon ce format : {address}@{domain}.{com}

• URL: cette variable peut capturer une URL aux formats suivants : http://url.com / http://www.url.com / www.url.com.

• Date: cette variable capture une date aux formats suivants : 28/07/21 ou 28/07/2021.

  Vous pouvez également capturer des moments précis à l'aide du groupe Date - Date précise qui vous permettra ainsi de récupérer le jour, le mois, l'année... Pour cela, il vous suffit d'afficher les captures de cette manière : ${capture.date_dayofmonth} ${capture.date_month} ${capture.date_year}

• Numéro de téléphone: cette variable permet de capturer le numéro de téléphone aux formats suivants : 0601020304 / 06.01.02.03.04. S'il manque un chiffre, le numéro ne pourra pas être capturé.

Comment utiliser les variables prédéfinies ?

Ces variables sont accessibles via le WYSYWG (la zone d'édition) de la question d'utilisateur en cliquant sur et en descendant jusqu'à la fin de la liste jusqu'à ce que vous voyiez le groupe « spécial ».

Exemple d'utilisation des variables prédéfinies :

Une banque offre à ses clients un chatbot qui répond à des questions sur leur compte bancaire, comme le solde du compte à une date spécifique. Le chatbot récupère ces informations depuis la base de données interne de la banque et les renvoie à l'utilisateur. Dans ce cas d'usage, le gestionnaire du bot va utiliser une variable pour capturer la date et l’envoyer à l’API de la banque.

Les captures d'écran ci-dessous vous montrent comment cette conversation peut être configurée dans le BMS : (Pour simplifier, nous n'expliquons pas ici le fonctionnement de l'API pour récupérer les données de solde.)

TIPS :

• Utilisation d'une fonction de script du côté serveur ::

        ${displaySlots(capture.filtered_slots)}

Dans cet exemple, nous faisons une fonction js appelée qui prend un paramètre une capture. L' ${...} n'est pas nécessaire pour la capture.

• Pour une affectation de variable:

    ${mavariable:=....}

  • Pour assigner la valeur d'une variable dans une autre ou une valeur constante le ${...} n'est pas nécessaire :

      ${mavariable:=capture.autrevariable}
    
      ${mavariable:=valeur constante}

• Une affectation de variable à partir d'un retour de service web :

  ${service_staff:=${callapi.service_staff.staff}}

Nous devons mettre ${...} dans l'appel au service web.

• Affection de variable qui utilise un appel de fonctions javascript côté serveur nécessitant une capture en paramètres:

    no_tel:=${formatPhoneNumberWS(capture.phone_number)}}

---

3. Devenir expert sur les variables

Fonctions

Outre les variables, le Dydu BMS fournit également plusieurs fonctions par défaut.

Définition:

Une fonction est un morceau de code informatique nommé qui effectue une tâche spécifique.

Les fonctions reçoivent généralement des données en entrée et retournent le résultat du traitement effectué par la fonction en sortie.

Les fonctions peuvent être utilisées comme condition de contexte ou directement dans une réponse. Dans ce cas, la syntaxe à utiliser est légèrement différente de celle des variables : ${NomdelaVariable}.

Exemple :

Pour utiliser la fonction UserOS qui peut récupérer le système d'exploitation de l'utilisateur directement dans une réponse, la syntaxe à utiliser est :

Voici la liste des fonctions par défaut fournies par le BMS :

• ComputeDate(date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute[, date_periodparam]) : permet de calculer la date ;

• ComputeDateGetDays(date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute[, date_periodparam]) : permet de calculer le nombre de jours

• ComputeTime(date_daypart, date_hour, date_minute) : permet de calculer la date et l'heure précise ;

• DialogCurrentAnswer() : réponse du bot pour l'interaction en cours ;

• DialogCurrentConsultationSpace() : espace de consultation de la conversation en cours ;

• DialogCurrentDate() : date de la conversation en cours ;

• DialogCurrentMatches():

• DialogFinished() : conversation terminée ;

• DialogHistory() : historique de conversation ;

• IsDateBetween('YYYY-MM-DD', 'YYYY-MM-DD'[, dateToTest]) :

• IsDateDayAndHour ('XXXXX--', '----- XXXXXXXXXXXX ----') : signifie (dans cet exemple) du lundi au vendredi, de 8h à 21h ;

• KnowledgeAskFeedback() : indique si la satisfaction sur une connaissance est demandée (true, false) ;

• UserBrowser() : permet de récupérer le navigateur utilisé par l'utilisateur ;

• UserBrowserVersion() : permet de récupérer la version du navigateur utilisé par l'utilisateur ;

• UserLocalization ('AreaCode' | 'City' | 'CountryCode' | 'CountryName' | 'CountryName' | 'Latitude' | 'Longitude' | 'MetroCode' | 'RegionCode' | 'RegionName' | 'TimeZone' | 'ZipCode'): récupère l'une des données de localisation utilisateur suivantes en fonction de l'adresse IP : l'indicatif régional, le nom de la ville, le code ou le nom du pays, la latitude ou la longitude, le code du métro, le code ou le nom de la région, le fuseau horaire et le code postal.

Cas d'usage 1 : vous pouvez utiliser cette variable directement dans une réponse pour indiquer aux utilisateurs leur pays de résidence, par exemple. Pour ce faire, utilisez la syntaxe suivante dans la réponse ${UserLocalization ('Country')}. Cas d'usage 2 : si vous voulez envoyer un message personnalisé aux utilisateurs résidant en France, créez une condition de contexte UserLocalization ('Pays') vaut "France" et utilisez-la dans votre connaissance.

• UserOs(): récupère le système d'exploitation de l'utilisateur ET sa version (eg.macOS 10.15) ;

• UserOsFamily(): récupère le système d'exploitation de l'utilisateur sans la version (par exemple macOS) ;

• UserURL() : permet de capturer l'URL sur laquelle l'utilisateur se trouve actuellement.

Suites de choix

Vous pouvez créer des suites de choix, ce qui peut s'avérer nécessaire lorsque vous souhaitez enregistrer plusieurs informations à la suite. Vous pouvez ainsi demander à l'utilisateur son premier choix, son deuxième choix, son troisième choix, etc.

Lorsque vous posez une question à laquelle vous attendez une réponse par oui ou par non, vous pouvez utiliser les informations en insérant une variable et une condition de contexte que vous pourrez utiliser plus tard.

1. Créez une condition de contexte servant à exploiter une information. Dirigez-vous sur la page Contenu > Conditions de contexte

1. Éditez une connaissance (fenêtre bleue - phrase utilisateur).

2. Cliquez sur Options puis encore sur Options.

3. Dans le champ Modification des variables, insérez ${Principe_ok:=oui} pour la connaissance « oui » et ${Principe_ok:=non} pour la connaissances « non ».

Ainsi, une première partie de la suite de choix est terminée.

Vous pouvez également créer des connaissances à choix multiples tout en liant diverses questions à l'aide, par exemple, d'actions GUI où vous pouvez insérer du code JavaScript.

Variables "Dates"

Fonction	Paramètres par défaut	Type	Résultat
ComputeDate	ComputeDate (date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute [, date_periodparam])	Intervalle	[[2013-03-23 00:00:00,2013-03-24 23:59:59]]
			[[2013-04-02 00: 00: 00,2013-04-02 23:59:59], [2013-04-09 00: 00: 00,2013- 04-09 23:59:59], [2013-04-16 00: 00: 00,2013-04-16 23:59:59], [2013-04-23 00: 00: 00,2013-04- 23 23:59:59], [2013-04-30 00: 00: 00,2013-04-30 23:59:59]]
ComputeDateGetDays	ComputeDateGetDays (date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute [, date_periodparam])	Nombre jours	7
ComputeDateJP	ComputeDateJP (date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute [, date_periodparam])	Date	2013-03-18 20:30:00
ComputeDateJPF	ComputeDateJPF (date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute [, date_periodparam])	Date	Mercredi 6 n Novembre à 23h30
ComputeTime	ComputeTime(date_daypart, date_hour, date_minute)	Intervalle	[[20:30:00,23:59:59]]

Ainsi, le moteur de calcul utilise les paramètres renseignés et calcule la sortie.

Pour récupérer la date du jour, insérez ${ComputeDateJPF()}

Variables et groupes de formulation

Il est possible d'insérer des groupes de formulation en tant que variables. Dans notre exemple, l'objectif sera de récupérer le domaine d'innovation dans lequel se situe l'idée de l'utilisateur afin d'aboutir à une connaissance de ce type :

Pour ce faire, veuillez suivre les étapes suivantes :

1. Créez votre groupe de formulations. Dans notre exemple, le groupe de formulations est Domaine d'innovation.

2. Dirigez-vous sur la page des Connaissances et créez votre connaissance comme l'arbre de décision de notre exemple.

La connaissance « la robotique » ne constitue en réalité qu'un libellé par défaut auquel vous devez ajouter une formulation qui intégrera votre groupe de formulations.

1. Éditez la phrase utilisateur pour laquelle vous souhaitez ajouter votre groupe de formulations puis positionnez-vous sur le champ d'ajout d'une nouvelle formulation.

2. Cliquez sur l'icône et sélectionnez votre groupe de formulations créé au préalable.
3. Cliquez ensuite sur la petite flèche blanche située à droite de votre groupe de formulations.

1. Remplissez le champ Nom de la variable puis cliquez sur Mettre à jour. C'est le nom de cette capture que vous utiliserez ensuite pour récupérer l'information dans la fenêtre de réponse.

2. Complétez la fenêtre de réponse avec le nom de la capture correspondant à votre groupe de formulation (Voir étape précédente).

1. Cliquez sur Mettre à jour.

Ainsi, si l'utilisateur répond l'un des domaines intégrés au groupe de formulation, la capture permettra de récupérer le terme précis. Par ailleurs, si vous souhaitez suggérer des domaines et effectuer des liens cliquables vers la connaissance « la robotique », il vous faudra tout d'abord modifier cette connaissance et la configurer en accès direct.

Vous pouvez également créer les liens cliquables vers la même connaissance « la robotique ». Afin de personnaliser chaque lien et de récupérer l'information correcte, cliquez sur le bouton de l'éditeur HTML puis modifiez tous les title pour qu'il soit en adéquation avec le domaine que vous souhaitez afficher.

Il est possible d'avoir dans un groupe de formulation une variable qui a pour contrainte d'être entre deux entiers :

Variables pour les services Web

Cette partie couvrira des informations de type général. Si vous souhaitez accéder à des cas plus concrets d'utilisation des variables pour les services web, veuillez vous rendre sur cette page.

• Insérer une variable dans l'URL d'un service web

Vous pouvez insérer une variable dans l'URL de votre service web de cette manière : http://mon-domaine/abc/${}capture.mavariable/xyz

• Exploiter un retour de service web comme argument d'un script côté serveur

${arg2:=${callapi.monWS.json}}

${monscript(capture.mavariable,arg2)}

• Appel d'un script côté serveur depuis la page d'un service web

Sur certains champs, il est possible d'inscrire des variables faisant appel à un script côté serveur. Allez sur Contenus > Avancé > Variables > Ajouter nouvelle Configurations des variables globales

Notez que les affectations de variables avec des fonctions ou services web ne fonctionnent pas. Par exemple : ${mavariable:=FonctionJSCotéServeur(callapi.WebService.Variable)}

Dans ce cas, le code ne sera pas exécuté et la variable aura pour valeur la chaîne de caractère qui se trouve derrière.

• Insérer une variable issue d'un service web dans les templates de connaissance

Les variables issues des services web peuvent également être utilisées dans les templates de connaissance. Si une variable retourne du JSON dans le template, il vous faudra utiliser la méthode JSON.stringify() sinon le template ne sera pas appliqué.

Evénements internautes

Les événements internaute permettent de mémoriser une variable - typiquement l'occurrence d'un événement - pour une durée supérieure à celle du dialogue (cette durée est configurable au niveau du bot, et est soumise à la RGPD).

Un événement est identifié par son nom et contient, en plus de sa valeur, les identifiants du client et du bot ainsi que sa date de création.Pour créer un internaut event, allez sur Contenus > Conditions de contexte > Ajouter

Pour créer un internaut event, vous pouvez :

• Insérer une valeur directement :

  • ${internaut.myEvent:=eventValue}

• Appeler une autre expression :

  • ${internaut.myEvent:=callapi.ws.var}

  • ${internaut.myEvent:=capture.maValue}

• Lecture d'une variable de type internaut event

  • ${internaut.myEvent}

• Utiliser un événement internaute dans une condition de contexte. Pour utiliser un événement internaute comme condition de contexte, insérez-le de cette façon : internaute. myEvent. Par exemple :

• Utiliser les événements internaute dans la chatbox :

  • dydu.chatbox.addInternautEvent('NomInternautEvent', 'ValeurInternautEvent')

Utilisation des fonctions JS côté serveur en tant que paramètre :

Lors de l'utilisation d'une fonction JS, il est possible d'exploiter des chaînes de caractères, des entiers, des captures ou du json en paramètre.

• Les chaînes de caractères sont délimitées par des double guillemets : "exemple". Si un guillemet est contenu dans la chaîne de caractères, celui-ci doit être échappé de cette manière : ""exemple"".

• Les entiers n'ont pas besoin de délimitation : 10 ou -10 par exemple. En revanche, lors du passage à la fonction JS, les entiers sont transformés en chaîne de caractères : "10" ou "-10" sera transformé en argument de la fonction.

• Les objets et tableaux définis dans un format json valide sont exploités tels quels, en tant qu'objet. Si l'objet json n'est pas décryptable, il sera considéré et exploité comme une chaîne de caractères.

• Les captures peuvent être utilisées avec la syntaxe capture.nomVariable ou juste nomVariable, sans double guillemets délimitant le nom de la capture. La valeur de la capture sera alors utilisée. Les règles décrites précédemment seront appliquées pour définir le type de la variable.

Variables de la chatbox

Les internautes events vous permettent de garder en mémoire une variable - typiquement la survenue d'un événement - pendant une durée supérieure au temps de la conversation (cette durée est paramétrable au niveau de l'assistant, et est soumise au règlement RGPD):

• DYDU_LANGUAGE : correspond à la langue (fr, en, etc.) ;

• DYDU_CONSULTATION_SPACE : correspond à l'espace de consultation ;

• DYDU_BOT_ID : correspond à l'ID du bot ;

• DYDU_SERVLET_URL : correspond au serveur avec lequel le bot communique ;

• DYDU_BACKUP_SERVLET_URL : correspond au serveur de secours avec lequel le bot communique ;

• DYDU_QUALIFICATION_MODE : correspond au mode de qualification (true, false) pour marquer les conversations en tant que test.

Autres cas d'utilisation et informations générales

• Variables de type tableau

${montableau:=["blanc","noire"]}

${capture.montableau[0]} → cela affiche blanc

• Variables alpha

Cela permet de capturer :

• Les accents (ex : testé, hâte, etc.) ;

• Les tirets (ex : Jean-Paul) ;

• Les points (ex : jean.paul).

Attention : il est impossible de capturer les apostrophes (ex : l'eau) ainsi que les espaces (Jean Paul).

• Variables SAML

Lors d'une authentification SAML, il est possible d'enregistrer des variables sur l'utilisateur. Ces variables commencent par « auth_ ».