Composants de variable

Il s'agit des composants disponibles dans la catégorie Variable de l'éditeur de flux de dialogue basé sur YAML.

System.SetVariable

Le composant System.SetVariable définit la valeur d'une variable prédéfinie.

Propriété	Description	Obligatoire?
`variable`	Nom de la variable définie comme une des propriétés `context`. Il peut s'agir d'une variable définie pour une entité ou d'une valeur prédéfinie, telle qu'une chaîne.	Oui
`value`	Valeur cible, que vous pouvez définir comme littéral ou comme expression référençant une autre variable.	Oui

Vous pouvez également définir une valeur prédéfinie pour une variable à l'aide d'une expression Apache FreeMarker ou, comme illustré dans l'extippet suivant, d'un littéral. Pour des informations supplémentaires sur FreeMarker, voir ici.

setOAuthRedirectURL:
    component: "System.SetVariable"
    properties:
      variable: "redirectURL"
      value: "https://thatcompany.io/connectors/v2/tenants/5c824-45fd-b6a2-8ca/listeners/facebook/channels/78B5-BD58-8AF6-F54B141/redirect"
    transitions:
      ...

Consultez la page System.OAuthAccountLink.

Note

La structure de la réponse du moteur d'intention a été modifiée avec la version 21.12. Avant la version 21.12, les données utiles des données utiles FullEntityMatches et entityMatches de niveau supérieur de l'objet nlpResult incluaient des entités référencées par des éléments dans des entités composites, mais qui n'étaient pas directement associées à l'intention. À partir de la version 21.12, les données utiles des objets FullEntityMatches et EntityMatches n'incluent plus ces entités (elles se trouvent plutôt dans les objets d'élément d'entité composite de niveau inférieur). Par conséquent, les compétences mises à niveau vers la version 21.12 qui utilisent System.SetVariable pour définir des variables à l'aide des résultats contenus dans l'objet nlpResult à l'aide d'une syntaxe telle que iResult.value.entityMatches peuvent échouer, car les valeurs d'entité ne sont plus présentes. Pour assurer le fonctionnement continu des compétences - et suivre les meilleures pratiques - référencez les valeurs dans l'entité composite (<variable_name>.value.<item_name>) et utilisez les composants System.CommonResponse ou SystemResolveEntities au lieu du composant System.SetVariable.

System.ResetVariables

Ce composant réinitialise les valeurs des variables à zéro.

Ce composant ne nécessite aucune transition, mais vous pouvez, par exemple, faire revenir une transition à un état System.Intent pour permettre aux utilisateurs d'entrer de nouvelles valeurs.

Propriété	Description	Obligatoire?
`variableList`	Liste séparée par des virgules de variables devant être réinitialisées. Utilisez la notation avec point pour réinitialiser la valeur d'un élément particulier de la variable de l'entité composite, qui est déclarée comme variable de contexte (`expense` dans l'exemple suivant). `resetExpenseType: component: "System.ResetVariables" properties: variableList: "expense.Type" transitions: next: "resolveExpense"`	Oui

System.CopyVariables

Copie les valeurs de variable.

Définissez ce composant à l'aide des propriétés from et to comme dans l'extrait de code suivant, où la valeur est copiée dans un contexte d'utilisateur :

setupUserContext:
    component: "System.CopyVariables"
    properties:
      from: "lastQuestion,lastResponse"
      to: "user.lastQuestion,user.lastResponse"

Ce composant a besoin des deux propriétés, mais leurs définitions ne doivent pas obligatoirement se refléter l'une l'autre. Bien que vous puissiez définir à la fois from et to en tant que listes de variables, vous pouvez également définir from avec une seule variable et to en tant que liste. Si vous définissez une propriété to supplémentaire, elle hérite de la valeur de variable de la propriété from.

System.SetCustomMetrics

Utilisez ce composant pour instrumenter votre compétence pour le rapport Mesures personnalisées. Par exemple :

  insights:
    component: "System.SetCustomMetrics"
    properties:
      dimensions:
       - name: "Pizza Size"
         value: "${size}"
       - name: "Pizza Type"
         value: "${type}"
       - name: "Crust Type"
         value: "${crust}"
    transitions:
      next: "summarizeOrder"

Note

Vous pouvez définir plusieurs dimensions dans un seul état et définir jusqu'à six dimensions par compétence.

Attribut Description

name Nom de la dimension (50 caractères ou moins) tel qu'il apparaît dans le rapport Mesures personnalisées. Utilisez seulement des lettres, des chiffres et des espaces. N'utilisez pas de caractères spéciaux.

Attribut	Description
`name`	Nom de la dimension (50 caractères ou moins) tel qu'il apparaît dans le rapport Mesures personnalisées. Utilisez seulement des lettres, des chiffres et des espaces. N'utilisez pas de caractères spéciaux.
`value`	Vous pouvez définir la valeur de dimension en tant qu'expression FreeMarker ou chaîne de texte. Utilisez des expressions FreeMarker pour référencer une variable `context` déclarée pour une entité. Par exemple, pour une variable `crust: "PizzaCrust"`, la syntaxe est `"${crust}"`. La syntaxe pour référencer un élément d'entité de liste de valeurs dans une entité composite est `"${<composite bag entity name>.value.<item name>}"`. Par exemple, `"${pizza.value.Crust}".` Utilisez une chaîne pour suivre une valeur qui n'est pas définie par des variables dans la définition du flux de dialogue, mais qui suit d'autres aspects de l'utilisation des compétences. livechatTransfer: component: "System.AgentConversation" properties: ... transitions: actions: agentLeft: "livechatEndPrompt" expired: "livechatEndPrompt" error: "livechatHandleNoTransfer" next: "setInsightsCustomMetrics" setInsightsCustomMetrics: component: "System.SetCustomMetrics" properties: dimensions: - name: "Agent Transfer" value: "transferred" ... setInsightsCustomMetrics2: component: "System.SetCustomMetrics" properties: dimensions: - name: "Agent Transfer" value: "not transferred" transitions: return: "done"

value

Vous pouvez définir la valeur de dimension en tant qu'expression FreeMarker ou chaîne de texte.

Utilisez des expressions FreeMarker pour référencer une variable context déclarée pour une entité. Par exemple, pour une variable crust: "PizzaCrust", la syntaxe est "${crust}". La syntaxe pour référencer un élément d'entité de liste de valeurs dans une entité composite est "${<composite bag entity name>.value.<item name>}". Par exemple, "${pizza.value.Crust}".

Utilisez une chaîne pour suivre une valeur qui n'est pas définie par des variables dans la définition du flux de dialogue, mais qui suit d'autres aspects de l'utilisation des compétences.

livechatTransfer:
    component: "System.AgentConversation"
    properties:
...
    transitions:
      actions:
        agentLeft: "livechatEndPrompt"
        expired: "livechatEndPrompt"
        error: "livechatHandleNoTransfer"
      next: "setInsightsCustomMetrics"

  setInsightsCustomMetrics:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer"
        value: "transferred"
...

  setInsightsCustomMetrics2:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer"
        value: "not transferred"
    transitions:
       return: "done"

Exemple : Définition d'une dimension unique dans plusieurs États

L'extrait de code suivant illustre comment créer une dimension unique (Agent Transfer) à partir d'une série d'états System.SetCustomMetrics.

states:
  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
      optionsPrompt: "Do you want to"      
    transitions:
      actions:
        OrderPizza: "startOrderPizza"
        WelcomePizza: "startWelcome"
        LiveChat: "setInsightsCustomMetrics3"
        unresolvedIntent: "startUnresolved"

...

  setInsightsCustomMetrics:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Pizza Size"
        value: "${pizza.value.PizzaSize}"
      - name: "Pizza Type"
        value: "${pizza.value.PizzaTopping}"
      - name: "Pizza Crust"
        value: "${pizza.value.PizzaDough}"
      - name: "Agent Transfer"
        value: "No Agent Needed"
    transitions:
      next: "showPizzaOrder"

...
   
  startUnresolved:
    component: "System.Output"
    properties:
      text: "I didn't that get that. Let me connect you with support."
      keepTurn: true 
    transitions:
      next: "setInsightsCustomMetrics1"
      
### Transfer because of unresolved input ####

  setInsightsCustomMetrics1:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer"
        value: "Bad Input"
    transitions:
      next: "getAgent"

  maxError:
    component: "System.Output"
    properties:
      text: "OK, let's connect you with someone to help"
      keepTurn: true
    transitions:
      next: "setInsightsCustomMetrics2"
      
### Transfer because of Max Error"  ####

  setInsightsCustomMetrics2:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer"
        value: "Max Errors"
    transitions:
      next: "getAgent"
      
### Transfer because of direct request ####

  setInsightsCustomMetrics3:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer"
        value: "Agent Requested"
    transitions:
      next: "getAgent"

  getAgent:
    component: "System.AgentInitiation"

...

Chaque état System.SetCustomMetrics définit une catégorie différente pour la dimension Transfert d'agent. Le rapport Mesures personnalisées enregistre les données de ces mesures lorsque ces états sont inclus dans un flux d'exécution et, comme illustré dans l'exemple ci-dessus, sont nommés dans les transitions.

États de mesure personnalisés pour la dimension Transfert d'agent	Valeur	Utilisez
`setInsightsCustomMetrics`	Aucun agent nécessaire	Indique le nombre de conversations réussies où des commandes ont été passées sans aide.
`setInsightsCustomMetrics1`	Entrée incorrecte	Indique le nombre de conversations où l'entrée non résolue a entraîné le transfert des utilisateurs vers un agent humain.
`setInsightsCustomMetrics2`	Nombre maximal d'erreurs	Reflète le nombre de conversations où les utilisateurs ont été dirigés vers des agents humains parce qu'ils ont atteint le m
`setInsightsCustomMetrics3`	Agent demandé	Indique le nombre de conversations pour lesquelles les utilisateurs ont demandé un agent humain.

Exemple : Suivi des mesures sur la rétroaction d'utilisateur

Pour suivre les mesures de rétroaction, ajoutez les états System.SetCustomMetrics correspondants aux états de transition System.Feedback. Par exemple :

...
  getUserFeedback:
    component: "System.Feedback"
    properties: 
      threshold: 2
      maxRating: 5
      enableTextFeedback: true
      footerText: 
    transitions:
      actions:
        above: "PositiveFeedbackMetrics"
        below: "NegativeFeedbackMetrics"
        cancel: "CancelFeedbackMetrics"
        
        
  PositiveFeedbackMetrics:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Feedback Type"
        value: "Positive"
    transitions:
      next: "positiveFeedback"        
        
        
  positiveFeedback:
    component: "System.Output"
    properties:
      text: "Thank you for the ${system.userFeedbackRating.value}-star rating."
    transitions:
      return: "done"
      
  NegativeFeedbackMetrics:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Feedback Type"
        value: "Negative"
    transitions:
      next: "negativeFeedback"
      
  negativeFeedback:
    component: "System.Output"
    properties:
      text: "Thank you for your feedback."
    transitions:
      return: "done"
      
  CancelFeedbackMetrics:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Feedback Type"
        value: "Canceled"   
    transitions:
      next: "cancelFeedback"        
      
  cancelFeedback:
    component: "System.Output"
    properties:
      text: "Maybe next time."
    transitions:
      return: "done"