Aura Bot object, data types and models

• 1: auraCommand model
• 2: dialogContext model

1 - auraCommand model

auraCommand model

Introduction

An auraCommand is an structure to send intents directly to Aura. It includes specific messages consisting on pre-defined options that the user can select from Aura’s interface as part of the response to her request. These messages come from channels using Direct Line format. Currently, they correspond to notifications and suggestions.

The aura-bot recognizer in charge of auraCommand is aura-command-recognizer-middleware. This recognizer detects if the message matches auraCommand format and then processes the message and extract the intent and entities from it.

An auraCommand should be sent within the channelData of the request to aura-bot in an optional property called auraCommand.

AuraCommand property in channelData

It is the channelData property called AuraCommand, which value should fit an AuraCommand Model.

AuraCommand Model

Intent model

Entity model

Utm model

2 - dialogContext model

dialogContext model

Introduction

A dialogContext is a structure that facilitates the recognition of CardActions and prompts without the need of training.

It has the following characteristics:

• It can be autogenerated when a prompt is active.
• It can be autogenerated when there is a CardAction.
• It can be created manually in a dialog but with certain restrictions.
• It is stored in the conversation cache.
• It is processed by the dialog-context-recognizer-middleware.
• It is auto-generated and stored by the aura-bot adapter.
• It can be configured at channel level, prompt level and CardAction level.
• It facilitates the recognition of CardActions if a user, instead of pressing the button, types the button text.
• It facilitates the recognition of numbered lists either by ordinals or cardinals.
• It uses a proximity search algorithm.
• It solves the problems of the recognition of numbers and ordinals that the current Bot Framework prompt has.

Existing models

dialogContext model

Example:

"dialogContext": [
                    {
                        "text": "Hello",
                        "value": {
                            "intent": "intent.factotum-test.dialog-context",
                            "entities": [
                                {
                                    "entity": "greetings",
                                    "type": "ent.dialog-context",
                                    "score": 1
                                }
                            ]
                        }
                    },
                    {
                        "text": "Bye bye mi picolissima dama",
                        "value": {
                            "intent": "intent.factotum-test.dialog-context",
                            "entities": [
                                {
                                    "entity": "goodbyes",
                                    "type": "ent.dialog-context",
                                    "score": 1
                                }
                            ]
                        }
                    }
                ]

Channel model

The dialogContext model at the channel level applies to all dialog components.

This model has the highest priority, i.e., in case of conflict between models, the channel model has the highest weight.

This model is inside the responseOptions.dialogContext property. Check it in Aura channel model: ResponseOptions model.

An example is shown below:

channel: {
...
        responseOptions: {
            dialogContext: {
                normalizeTerms: true,
                disabled: false,
                disabledMerge: false,
                processFromClient: false,
                returnToClient: false,
                defaultListType: 'none',
                promptChoice: {
                    generate: 'never',
                    generateList: false
                },
                cardActions: {
                    generate: 'never',
                    generateList: false
                }
            }
        }
    },
...

Prompt model

The options of dialogContext for a prompt can be included inside the property validations of Prompt Options within its sub-property dialogContext.

When generating the list of options, the system takes into account two properties of the prompt: recognizeNumbers and recognizeOrdinals.

In these cases:

• If the prompt has recognizeNumbers=false and we have activated the list of options, only the ordinal values of each option will be generated.
• If the option recognizeOrdinals=false, then only the cardinal options will be generated.
• If both are set to false, no list items will be generated.

By default, the prompt has both properties set to true.

Example of prompt options:

{
  "Choices": [
    {
      "value": "Lunes",
      "synonyms": [
        "El lunes"
      ]
    },
    {
      "value": "martes"
    }
  ],
  "validations": {
    "dialogContext": {
      "enabled": true,
      "listType": "ordinal "
    }
  }
}

CardAction model

The options of dialogContext for a CardAction can be included inside the property channelData of button options, within the sub-property dialogContext.

{
  "buttons": [
    {
      "type": "postBack",
      "title": "Monday",
      "value": {
        "intent": "monday"
      },
      "channelData": {
        "dialogContext": {
          "enabled": true,
          "listType": "ordinalCardinal"
        }
      }
    },
    {
      "type": "postBack",
      "title": "Wednesday",
      "value": {
        "intent": "wednesday"
      },
      "channelData": {
        "dialogContext": {
          "enabled": true,
          "listType": "ordinalCardinal",
          "synonyms": [
            "X"
          ]
        }
      }
    }
  ]
}

Custom dialogContext

It is possible to add in the channelData a dialogContext manually. If the channel configuration allows it, this will be merged with the _dialogContext that is generated automatically.

The following rules must be taken into account when including our own dialogContext:

• Do not generate the list values, that is, do not add ordinals and/or cardinals, as this will be done by the system.
• The options of a custom dialogContext are included right at the top of the list.

How does dialogContext work?

The dialogContext flowchart includes two differentiate phases: recognition phase and build phase, described below.

Recognition phase

When validating if the user has entered a phrase that matches the dialogContext that we have generated from the previous answer, take into account that the comparison is done by proximity.

The match value will be reported in a score field that goes from 0 to 1. Valid values will be those that are greater or equal to a given threshold. For a dialogContext we have two thresholds.

• AURA_DIALOG_CONTEXT_THRESHOLD: Default threshold when comparing two strings. Default value: 0.80.
• AURA_DIALOG_CONTEXT_ORDINAL_CARDINAL_THRESHOLD: Threshold used in case dialogContext elements are in list form and also if the input phrase includes a number. By default, 0.95.
  This value is so high because if the user writes ‘11’ or ’the 11’, and there are only 5 elements in the list, the comparison could give us a very high value, since comparing 11 with 1 has a threshold higher than 0.80, which means that writing 11 would select the first option. To avoid this kind of cases when there are numbers in the user input and the list is enumerated, then the threshold should be stricter.

Another thing to take into account is that if the dialogContext does not get a valid match, if we have an active prompt choice, the system will override its recognizeNumbers and recognizeOrdinals properties, as long as we are working with enumerated elements.

This is done because when MS Bot Framework detects an ordinal number in a sentence, it ignores the rest of the sentence, which can lead to many errors. These values are restored every time the prompt is regenerated if it has not been resolved.

In the recognition phase, the dialogContext recognizer compares value to value, and in the case that one of them meets the conditions, the intention associated with the value is established. It also assigns to the input text the value expected by the prompt, in case there is one.

Example:

DialogContext

[
  {
    "text": "1|the 1|one|the one|first|the first|Monday",
    "value": {
      "intent": "monday"
    }
  },
  {
    "text": "2|the 2|two|the two|second|the second|Tuesday",
    "value": {
      "intent": "tuesday"
    }
  },
  {
    "text": "3|the 3|three|the three|third|the third|X|Wednesday",
    "value": {
      "intent": "wednesday"
    }
  },
  {
    "text": "4|the 4|four|the four|fourth|the fourth|Thursday",
    "value": "The Thursday"
  },
  {
    "text": "5|the 5|five|the five|fifth|the fifth|Friday",
    "value": "Friday"
  }
]

User Input: the 4

• In this case, as the list is numbered and the user has entered a number in his sentence, the selected threshold will be AURA_DIALOG_CONTEXT_ORDINAL_CARDINAL_THRESHOLD.
• The elements of each option will be compared with the user’s value:

   1 ≅ the 4  -> Score 0 
   the 1 ≅ the 4  -> Score 0.80
   ......
   the 4 ≅ the 4  -> Score 1.0   -> Option Selected 

• If the selected option has value, the value is assigned to the activity text. In other case, the assigned value is the last value of the text, in this case ‘Thursday’.
• If there is a prompt choice, the validations recognizeNumbers and recognizeOrdinals are set to false.

Build phase

The build phase is responsible for collecting the customized dialogContext (if any) and, in turn, for generating the dialogContext of the CardActions and Prompt in the different activities that make up the output message.

The enumeration of the elements depends on the configuration of the channel and the respective components. Once generated, it is stored in the user’s conversation cache.

The module in charge of this procedure is the Aura Bot Adapter.