Utiliser les variables globales

1. Créez une variable ou utilisez le volet Variables pour ouvrir une variable existante.

2. Dans le volet Propriétés de la variable, sélectionnez Global (n’importe quelle rubrique peut y accéder).

   Le nom de la variable reçoit le préfixe Global., pour la différencier des variables de niveau rubrique. Par exemple, la variable UserName est affichée sous le nom Global.UserName.

3. Enregistrez la rubrique.

1. Sélectionnez la variable souhaitée.

2. Dans le volet Propriétés de la variable, sous Utilisation, sélectionnez Bot (n’importe quelle rubrique peut y accéder).

3. Le nom de la variable est marqué avec un préfixe bot., pour la différencier des variables au niveau de la rubrique. Par exemple, la variable UserEmail s’affiche maintenant sous le nom bot.UserEmail.

Lorsque vous composez un message dans un nœud Message ou un nœud Question, sélectionnez l’icône {x} pour afficher les variables disponibles pour la rubrique. Les variables globales s’affichent dans l’onglet Personnalisé, ainsi que les variables de rubrique. Les variables sont répertoriées dans l’ordre alphabétique.

Lorsque vous composez un message dans un nœud Message ou un nœud Question, sélectionnez l’icône {x} pour afficher les variables disponibles pour la rubrique. Les variables sont répertoriées par ordre alphabétique et toutes les variables globales apparaissent ensemble, car elles commencent toutes par bot..

Lorsque vous utilisez un nœud de condition, un nœud d’action de flux ou un nœud de compétence, vous voyez également les variables globales disponibles.

1. Sélectionnez la variable globale souhaitée dans le canevas de création ou dans le volet Variables.

2. Dans le volet Propriétés de la variable, dans la section Référence, sélectionnez Afficher toutes les références.

3. Basculez vers l’onglet Autre et sélectionnez n’importe quelle rubrique où la variable est utilisée pour accéder directement à cette rubrique et à ce nœud.

Sélectionnez la variable souhaitée sur le canevas de création. Le volet Propriétés de la variable apparaît.

• Pour accéder directement au nœud où la variable globale a été créée, sélectionnez Accéder à la source.

• Pour accéder à une rubrique qui utilise cette variable, sélectionnez la rubrique souhaitée dans la section Utilisé par.

Par défaut, la valeur d’une variable globale persiste jusqu’à la fin de la session. Le nœud Effacer les valeurs de variable réinitialise les valeurs des variables globales et est utilisé dans la rubrique système Réinitialiser la conversation. Lorsqu’une redirection déclenche cette rubrique (ou lorsque l’utilisateur saisit une phrase telle que « Recommencer »), toutes les variables globales sont réinitialisées.

Les variables globales sont accessibles à partir de n’importe quelle rubrique et leur valeur persiste tout au long d’une session.

La valeur n’est effacée que lorsque l’utilisateur de l’agent est redirigé vers la rubrique système Recommencer, ou lorsque l’utilisateur déclenche directement cette rubrique (par exemple, en tapant « Recommencer »). Dans ce cas, toutes les variables globales sont réinitialisées et n’ont pas de valeur.

Initialisation des variables globales

Si une variable globale est déclenchée avant d’être initialisée (ou « remplie »), l’agent déclenche automatiquement la partie de la rubrique où la variable globale est définie pour la première fois, même si c’est dans une autre rubrique, avant de revenir à la rubrique d’origine. Ce comportement permet à l’agent de remplir toutes les variables sans interrompre la conversation.

Par exemple, le client démarre la conversation sur la rubrique « Prise de rendez-vous », dans laquelle une variable globale bot.UserName est utilisée. Cependant, la variable bot.UserName est d’abord définie dans la rubrique « Bienvenue ».

Lorsque la conversation entre dans le vis de la rubrique « Prise de rendez-vous » où la variable bot.UserName est utilisée, l’agent bifurque en toute fluidité vers le nœud de question où bot.UserName a été définie pour la première fois.

Une fois que le client a répondu à la question, l’agent reprend la rubrique « Prise de rendez-vous ».

Comportement de la variable globale lors de l’implémentation d’actions via les flux ou les compétences Power Automate

Parfois, vous pouvez utiliser un flux ou une compétence pour initialiser ou remplir une variable.

Cependant, lorsqu’un utilisateur interagit avec l’agent, la variable peut être remplie plus tôt dans la conversation, ou vous pouvez avoir déjà défini les variables en externe.

Dans ce cas, le flux ou la compétence s’exécute et remplit toujours la variable, en remplaçant tout ce qui était précédemment stocké dans la variable.

Pour vous assurer que l’agent démarre une conversation avec un certain contexte, vous pouvez utiliser une variable globale et définir sa valeur à partir d’une source externe. Supposons que votre site nécessite que les utilisateurs se connectent. Si vous stockez le nom d’un utilisateur dans une variable globale et que vous la transmettez à votre agent, celui-ci peut accueillir les clients par leur nom avant qu’ils ne commencent à taper leur première question. Un autre exemple de scénario consiste à transmettre le contexte de Dynamics 365 Customer Service à un agent afin qu’il puisse démarrer la conversation en sachant ce que le client veut réaliser.

Pour éviter toute latence indésirable, vous pouvez spécifier combien de temps votre agent peut attendre une valeur. Vous pouvez également définir une valeur par défaut à utiliser lorsque la source externe ne répond pas en temps voulu.

1. Créez une rubrique dédiée pour contenir la configuration de toutes les variables destinées à être définies à partir de sources externes. Vous pouvez nommer cette rubrique « Définir des variables de contexte » par exemple. Cette rubrique n’est pas utilisée à d’autres fins, elle n’a donc pas besoin d’avoir de phrases déclencheurs définies.

2. Ajoutez un nœud Définir une valeur de variable à votre rubrique dédiée.

3. Sous Définir une variable, ouvrez le sélecteur de variables, puis sélectionnez Créer une variable.

4. Sélectionnez le nom par défaut de la nouvelle variable. Le volet Propriétés de la variable apparaît.

5. Remplacez le nom par défaut par un nom qui correspond exactement au nom de la variable transmise depuis le système externe.

6. Sous Utilisation, sélectionnez Global (n’importe quelle rubrique peut y accéder) et Les sources externes peuvent définir des valeurs.

7. Sous Référence, sélectionnez les trois points (⋮) dans le coin supérieur droit et sélectionnez Obtenir la valeur de ce nœud s’il est vide.

8. (Facultatif) Définissez un délai d’expiration, en millisecondes. Cette valeur détermine la durée pendant laquelle votre agent peut attendre que la variable soit définie par une source externe avant d’expirer et de continuer avec la valeur par défaut que vous avez définie dans le nœud Définir une valeur de variable. Ce paramètre est pertinent dans les scénarios où la variable dépend d’un processus long ou asynchrone, mais où votre agent doit respecter une latence maximale pour garantir une bonne expérience utilisateur.

   Pour les variables provenant de Omnicanal pour Customer Service, nous suggérons une valeur de 10 secondes (10 000 ms) comme temps d’attente maximal.

9. Dans le nœud Définir une valeur de variable, entrez la valeur par défaut à utiliser si le délai d’expiration est atteint. Au moment de l’exécution, votre agent s’attend à des valeurs avec le même type de données. Si vous souhaitez que cette valeur par défaut soit une chaîne vide, utilisez Text("") comme formule.

   

10. Pour toutes les autres valeurs qui devraient provenir d’un système externe, ajoutez d’autres nœuds Définir une valeur de variable à votre rubrique dédiée et configurez les variables globales requises de la même manière.

Ainsi configuré, votre agent est prêt à être testé. Lorsque l’agent est appelé, au lieu d’attendre indéfiniment que toutes les variables soient remplies, votre agent peut immédiatement commencer à envoyer tous les messages qui ne dépendent pas des variables transmises. Lorsque votre agent tente d’accéder à une variable définie en externe, il est suspendu jusqu’à ce que la valeur arrive ou que le délai expire. En savoir plus sur l’optimisation des agents pour réduire la latence.

Vous pouvez définir une variable globale de manière à l’initialiser à partir d’une source externe. Cette action permet à l’agent de démarrer la conversation avec un certain contexte.

Par exemple, un client affiche une conversation de l’agent à partir de votre site web, et le site connaît déjà le nom du client. Vous laissez l’agent connaître le nom de l’utilisateur avant de commencer la conversation, et l’agent peut avoir une conversation plus intelligente avec le client sans avoir à demander à nouveau son nom.

1. Sélectionnez la variable globale souhaitée.

2. Dans le volet Propriétés de la variable, sélectionnez Les sources externes peuvent définir des valeurs.

Si vous incorporez votre agent dans une simple page web, vous pouvez ajouter des variables et leurs définitions à l’URL de l’agent. Ou bien, si vous souhaitez un peu plus de contrôle, vous pouvez utiliser un bloc de code <script> pour appeler et utiliser les variables par programmation.

Le nom de la variable dans la chaîne de requête de l’URL doit correspondre au nom de la variable globale sans le préfixe Global.. Par exemple, une variable globale Global.UserName serait appelée UserName dans la requête.

Les exemples qui suivent utilisent une déclaration de base pour les variables. Dans un scénario de production, vous pouvez transmettre en tant que paramètre de requête ou définition de variable une autre variable qui stocke déjà le nom de l’utilisateur (par exemple, si vous avez le nom d’utilisateur d’un script de connexion).

Ajoutez les variables et leurs définitions à l’URL de l’agent tant que paramètres de chaîne de requête au format botURL?variableName1=variableDefinition1&variableName2=variableDefinition2.

Par exemple :

• Vous avez une variable globale nommée Global.UserName.
• L’URL de votre agent est https://web.powerva.microsoft.com/webchat/bots/12345.
• Pour transmettre le nom de l’utilisateur au démarrage d’une conversation de l’agent sur votre site web, joignez la chaîne de requête UserName= en tant que : https://web.powerva.microsoft.com/webchat/bots/12345?UserName=Ana.

Le nom du paramètre est insensible à la casse. username=Ana fonctionne également dans cet exemple.

Vous pouvez ajouter les variables et leurs définitions si vous intégrez votre agent dans une simple page Web ou vous pouvez utiliser un bloc de code <script> pour appeler et utiliser des variables par programmation.

Dans les exemples décrits ici, une simple déclaration est faite pour les variables. Dans un scénario de production, vous pouvez transmettre en tant que paramètre de requête ou définition de variable une autre variable qui stocke déjà le nom de l’utilisateur (par exemple, si vous avez le nom d’utilisateur d’un script de connexion).

1. Ajoutez les variables et leurs définitions à l’URL de l’agent en tant que paramètres de chaîne de requête (au format botURL?variableName1=variableDefinition1&variableName2=variableDefinition2), par exemple :

   • Vous avez une variable globale nommée bot.UserEmail.
   • L’URL de votre agent est https://web.powerva.microsoft.com/webchat/bots/12345.
   • Pour transmettre le nom d’utilisateur lors du démarrage d’une conversation de l’agent sur un site Web, vous pouvez joindre la chaîne de requête UserEmail= sous la forme : https://web.powerva.microsoft.com/webchat/bots/12345?UserEmail=Ana@contoso.com.

2. Le nom du paramètre est insensible à la casse. Ça signifie que useremail=Ana@contoso.com fonctionne également dans cet exemple.

1. Dans la section <script> de la page où vous avez votre agent, définissez les variables comme suit, en remplaçant variableName1 pour le nom de variable sans le préfixe Global. et variableDefinition1 pour la définition. Séparez plusieurs variables par des virgules (,).

      const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
        if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
          dispatch({
             type: "WEB_CHAT/SEND_EVENT",
             payload: {
               name: "pvaSetContext",
               value: {
                  "variableName1": "variableDefinition1",
                  "variableName2": "variableDefinition2"
               }
             },
           });
         }
           return next(action);
       });
   

2. Dans votre section <script>, appelez le store lors de l’intégration de votre agent, comme dans l’exemple suivant où store est appelé juste avant l’endroit où styleOptions est appelé (vous devez remplacer le BOT_ID par l’ID de votre agent) :

   const BOT_ID = "12345-5678";
   const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
   fetch(theURL)
       .then(response => response.json())
       .then(conversationInfo => {
           window.WebChat.renderWebChat(
               {
                   directLine: window.WebChat.createDirectLine({
                       token: conversationInfo.token,
                   }),
                   store,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })
       .catch(err => console.error("An error occurred: " + err));
   

1. Dans la section <script> de la page où vous avez votre agent, définissez les variables comme suit, en remplaçant variableName1 pour le nom de variable sans le préfixe bot. et variableDefinition1 pour la définition. Séparez plusieurs variables par des virgules ,.

      const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
        if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
          dispatch({
             type: "WEB_CHAT/SEND_EVENT",
             payload: {
               name: "pvaSetContext",
               value: {
                  "variableName1": "variableDefinition1",
                  "variableName2": "variableDefinition2"
               }
             },
           });
         }
           return next(action);
       });
   

2. Dans votre section <script>, appelez le store lors de l’intégration de votre agent, comme dans l’exemple suivant où store est appelé juste avant l’endroit où styleOptions est appelé (vous devez remplacer le BOT_ID par l’ID de votre agent) :

   const BOT_ID = "12345-5678";
   const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
   fetch(theURL)
       .then(response => response.json())
       .then(conversationInfo => {
           window.WebChat.renderWebChat(
               {
                   directLine: window.WebChat.createDirectLine({
                       token: conversationInfo.token,
                   }),
                   store,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })
       .catch(err => console.error("An error occurred: " + err));