Variable Components

System.SetVariable

The System.SetVariable component sets the value of a pre-defined variable.

Property	Description	Required?
`variable`	The name of the variable that’s defined as one of the `context` properties. This can be a variable defined for an entity or a predetermined value, like a string.	Yes
`value`	The target value, which you can define as a literal or as a expression that references another variable.	Yes

You can also set a predetermined value for a variable using an Apache FreeMarker expression or, as shown in the following snippet, a literal. You can find out more about FreeMarker here.

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:
      ...

See System.OAuthAccountLink.

Note

The structure of the response from the Intent Engine changed with Release 21.12. Prior to Release 21.12, the payload of the top-level FullEntityMatches and entityMatches payloads in the nlpResult object included entities that were referenced by items in composite bag entities, but were not directly associated with the intent. Starting with Release 21.12, the payloads of the FullEntityMatches and EntityMatches objects no longer include these entities (they can instead be found within the lower-level composite bag item objects). As a result, skills upgraded to 21.12 that use System.SetVariable to set variables using the results held in the nlpResult object using syntax like iResult.value.entityMatches may fail because the entity values are no longer present. To ensure the continued functioning of skills – and follow best practices – reference the values in the composite bag (<variable_name>.value.<item_name>) and use the System.CommonResponse or SystemResolveEntities components instead of the System.SetVariable component.

System.ResetVariables

This component resets the values of the variables to null.

This component doesn’t require any transitions, but you can, for example, set a transition back to a System.Intent state to allow users to input new values.

Property	Description	Required?
`variableList`	A comma-separated list of variables that need to be reset. Use dot notation to reset the value of a specific bag item in the composite bag, which is declared a context variable (`expense` in the following example). `resetExpenseType: component: "System.ResetVariables" properties: variableList: "expense.Type" transitions: next: "resolveExpense"`	Yes

System.CopyVariables

Copies the variable values.

Define this component using from and to properties as in the following snippet, where the value is copied to a user context:

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

This component needs both of these properties, but their definitions don’t have to mirror one another. While you can define both from and to as lists of variables, you can also define from with a single variable and to as a list. If you set an additional to property, it inherits the variable value of the proceeding from property.

System.SetCustomMetrics

Use this component to instrument your skill for the Custom Metrics report. For example:

  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

You can set multiple dimensions in a single state and you can define up to six dimensions per skill.

Attribute Description

name The name of the dimension (in 50 characters or less) as it appears in the Custom Metrics report. Use only letters, numbers, and spaces. Do not use special characters.

Attribute	Description
`name`	The name of the dimension (in 50 characters or less) as it appears in the Custom Metrics report. Use only letters, numbers, and spaces. Do not use special characters.
`value`	You can define the dimension value as either a FreeMarker expression or a text string. Use FreeMarker expressions to reference a `context` variable declared for an entity. For example, for a `crust: "PizzaCrust"` variable, the syntax is `"${crust}"`. The syntax for referencing an value list entity item in a composite bag is `"${<composite bag entity name>.value.<item name>}"`. For example, `"${pizza.value.Crust}".` Use a string to track a value that's not set by variables in the dialog flow definition, but is instead tracks other aspects of skill usage. 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

You can define the dimension value as either a FreeMarker expression or a text string.

Use FreeMarker expressions to reference a context variable declared for an entity. For example, for a crust: "PizzaCrust" variable, the syntax is "${crust}". The syntax for referencing an value list entity item in a composite bag is "${<composite bag entity name>.value.<item name>}". For example, "${pizza.value.Crust}".

Use a string to track a value that's not set by variables in the dialog flow definition, but is instead tracks other aspects of skill usage.

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"

Example: Setting a Single Dimension Across Multiple States

The following snippet illustrates how to create a single dimension (Agent Transfer) from a series of a System.SetCustomMetrics states.

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"

...

Each System.SetCustomMetrics state defines a different category for the Agent Transfer dimension. The Custom Metrics report records data for these metrics when these states are included in an execution flow, and as illustrated by the above sample, are named in the transitions.

Custom Metric States for Agent Transfer Dimension	Value	Use
`setInsightsCustomMetrics`	No Agent Needed	Reflects the number of successful conversations where orders were placed without assistance.
`setInsightsCustomMetrics1`	Bad Input	Reflects the number of converstaions where unresolved input resulted in users getting transferred to a live agent.
`setInsightsCustomMetrics2`	Max Errors	Reflects the number of conversations where users were directed to live agents because they reached the m
`setInsightsCustomMetrics3`	Agent Requested	Reflects the number of conversations where users requested a live agent.

Example: Tracking Metrics on User Feedback

To track feedback metrics, add corresponding System.SetCustomMetrics states to the System.Feedback transition states. For example:

...
  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"