Componentes de Variável

Esses são os componentes disponíveis na categoria Variável do editor de fluxo de caixas de diálogo baseado em YAML.

System.SetVariable

O componente System.SetVariable define o valor de uma variável predefinida.

Propriedade Descrição 0brigatório?
variable O nome da variável definido como uma das propriedades context. Pode ser uma variável definida para uma entidade ou um valor predeterminado, como uma string. Sim
value O valor de destino, que você pode definir como literal ou como expressão que faz referência a outra variável. Sim
Você também pode definir um valor pré-determinado para uma variável usando uma expressão FreeMarker do Apache ou, conforme mostrado no snippet a seguir, um literal. Você pode saber mais sobre o FreeMarker aqui.
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:
      ...
Consulte System.OAuthAccountLink.
Observação

A estrutura da resposta do Mecanismo de Intenções foi alterada com a Release 21.12. Antes da Versão 21.12, o payload dos payloads FullEntityMatches e entityMatches de nível superior no objeto nlpResult incluía entidades que eram referenciadas por itens em entidades compostas, mas não estavam diretamente associadas à intenção. A partir da Release 21.12, os payloads dos objetos FullEntityMatches e EntityMatches não incluem mais essas entidades (eles podem ser encontrados nos objetos de item de repositório composto de nível inferior). Como resultado, as habilidades atualizadas para 21.12 que usam System.SetVariable para definir variáveis usando os resultados mantidos no objeto nlpResult usando sintaxe como iResult.value.entityMatches podem falhar porque os valores da entidade não estão mais presentes. Para garantir o funcionamento contínuo das habilidades - e seguir as melhores práticas - faça referência aos valores no repositório composto (<variable_name>.value.<item_name>) e use os componentes System.CommonResponse ou SystemResolveEntities em vez do componente System.SetVariable.

System.ResetVariables

Esse componente redefine os valores das variáveis como nulos.

Ele não exige transições, mas você pode, por exemplo, definir uma transição de volta para um estado System.Intent para permitir que os usuários informem novos valores.
Propriedade Descrição 0brigatório?
variableList Uma lista de variáveis separadas por vírgulas que precisam ser redefinidas.
Use a notação de ponto para redefinir o valor de um item de repositório específico no repositório composto, que é declarado uma variável de contexto (expense no exemplo a seguir).
resetExpenseType:
  component: "System.ResetVariables"
  properties:
    variableList: "expense.Type"
  transitions:
    next: "resolveExpense"
Sim

System.CopyVariables

Copia os valores da variável.

Defina esse componente usando as propriedades from e to como no seguinte trecho de código, em que o valor é copiado para um contexto do usuário:
setupUserContext:
    component: "System.CopyVariables"
    properties:
      from: "lastQuestion,lastResponse"
      to: "user.lastQuestion,user.lastResponse"
Este componente precisa das duas dessas propriedades, mas suas definições não precisam refletir umas nas outras. Embora você possa definir from e to como listas de variáveis, também pode definir from com uma única variável e to como lista. Se você definir uma propriedade adicional to, ela herdará o valor da variável da propriedade antecedente from.

System.SetCustomMetrics

Use este componente para instrumentar sua habilidade para o relatório Métricas Personalizadas. Por exemplo :
  insights:
    component: "System.SetCustomMetrics"
    properties:
      dimensions:
       - name: "Pizza Size"
         value: "${size}"
       - name: "Pizza Type"
         value: "${type}"
       - name: "Crust Type"
         value: "${crust}"
    transitions:
      next: "summarizeOrder"
Observação

Você pode definir várias dimensões em um único estado e pode definir até seis dimensões por habilidade.
Atributo Descrição
name O nome da dimensão (com 50 caracteres ou menos) conforme aparece no relatório Métricas Personalizadas. Só use letras, números e espaços. Não use caracteres especiais.
value Você pode definir o valor da dimensão como uma expressão FreeMarker ou uma string de texto.
  • Use expressões FreeMarker para fazer referência a uma variável context declarada para uma entidade. Por exemplo, para uma variável crust: "PizzaCrust", a sintaxe é "${crust}". A sintaxe para fazer referência a um item de entidade da lista de valores em um repositório composto é "${<composite bag entity name>.value.<item name>}". Por exemplo, "${pizza.value.Crust}".
  • Use uma string para rastrear um valor que não seja definido por variáveis na definição do fluxo de caixas de diálogo, mas que rastreie outros aspectos do uso da habilidade.
    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"

Exemplo: Definindo uma Dimensão Única em Vários Estados

O trecho de código a seguir ilustra como criar uma única dimensão (Agent Transfer) com base em uma série de estados 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"

... 

Cada estado System.SetCustomMetrics define uma categoria diferente para a dimensão Transferência do Agente. O relatório Métricas Personalizadas registra dados dessas métricas quando esses estados são incluídos em um fluxo de execução e, conforme ilustrado pela amostra acima, são nomeados nas transições.

Estados da Métrica Personalizada para Dimensão de Transferência do Agente Valor Usar
setInsightsCustomMetrics Nenhum Agente Necessário Reflete o número de conversas bem-sucedidas em que as prescrições foram inseridas sem assistência.
setInsightsCustomMetrics1 Entrada Inválida Reflete o número de conversões em que a entrada não resolvida resultou na transferência dos usuários para um agente ativo.
setInsightsCustomMetrics2 Erros Máximos Reflete o número de conversas em que os usuários foram direcionados a agentes vivos porque atingiram o m
setInsightsCustomMetrics3 Agente Solicitado Reflete o número de conversas em que os usuários solicitaram um agente ao vivo.

Exemplo: Rastreando Métricas no Feedback do Usuário

Para rastrear métricas de feedback, adicione os estados System.SetCustomMetrics correspondentes aos estados de transição System.Feedback. Por exemplo :
...
  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"