Aura – aura-bot

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot architecture

Description of Aura Bot architecture and starting components

Introduction to Bot Framework service

A bot is an application, particularly an HTTP server, that allows interaction with users in a conversational way. Different means of interaction are available, such as text, cards with images, video or audio and speech.

Users interact with the bot through a given channel, that is the final application used directly by the users. For instance, the bot can be accessible from Facebook, WhatsApp or from any private application, such as My O2 or Mi Movistar. Every message exchanged between the user and the bot is called an activity.

Microsoft Bot Framework Service, that is the main component of Azure Bot Service, is responsible for sending the user’s request to the particular bot instance, in this case, to the corresponding instance of aura-bot. Channels communicating with a bot should include additional information required by this specific bot to handle the message in the body of the request, i.e., in the activity. aura-bot provides a definition of the channelData field of the activity, so channels are able to send and receive this information needed to handle Aura use cases.

aura-bot, as a bot based on Microsoft Bot Framework, understands different types of activities. The most basic types of activities used by aura-bot are:

Message: Means to transmit the user’s needs to the bot.
Event: Events are in charge of the end-to-end communication between aura-bot and channels. They are managed by the incoming-event-middleware.
ConversationUpdate: Activity that describes a change in conversation’s members, description, existence, etc.

Communication between BotFramework Service and aura-bot is based on HTTP. BotFramework Service sends an HTTP POST request to the bot, with the incoming activity from the user. The bot should respond with a 200 HTTP status code to this request. In aura-bot, this is executed before going on with the processing of the activity, so the echo message of the user is returned before the activity generated as an answer. These activities are sent to BotFramework Service as HTTP POST request, that is responded with 200 HTTP status code, too.

Once an activity arrives at the bot, the HTTP server should pass it to the BotFramework Adapter, that starts the activity processing.

At this moment, a turn starts, that refers to all the steps done from the moment that an activity enters the bot until all the answer activities are returned to the user. Each turn lays on a TurnContext, that holds all the information about the current activity. Bot Framework automatically includes in the TurnContext object some information, but aura-bot extends this object with extra information that makes it easier to provide a response to the user.

Please, check detailed information about Microsoft Bot Framework Service and the related SDK.

Aura Bot core architecture

The following diagram shows all the components running in any aura-bot instance. They are shown as they are loaded during bot start-up.

Legend
Blue boxes: singleton components Yellow boxes within them: components that are handled the same way Middlewares: - M: mandatory ones - O: optional, executed only if they are properly configured Execution mode: - F: execution flow stops when middleware fails - T: execution continues when middleware fails

Aura Bot messages flowchart

As explained before, messages are a type of activities that manage requests from the users: aura-bot receives a request from a user and provides an answer back.

The following diagram include the messages flow through aura-bot.

Aura Bot starting components and modules: Aura orchestrator

Currently, aura-bot includes an orchestrator that controls how the system is loaded and indicates which components and modules are required for the bot start-up.

The orchestrator handles a sorted array of components that must implement a series of methods that may receive the bot configuration if necessary. Modules are then initialized asynchronously, although they were synchronous.

This behavior simplifies both the definition of the singleton modules and how the orchestrator initializes them, with a minimum loss of performance during start-up.

        const orderedModules = [ModuleA, ModuleB, ModuleC];
        // Instantiate the Service App.
        const appOrchestrator = new Orchestrator();
        // Add configuration, that will be required by almost all other modules
        appOrchestrator.setConfigurationManager(Configuration);
        // Add the dependent modules in order.
        appOrchestrator.addModules(sortedModules);
        // Initiate the App.
        await appOrchestrator.init();

The orchestrator module is created during the server start-up with the following parameters:

ConfigurationManager:

Class that handles aura-bot configuration, that is the component in charge of loading the environment variables.

Singleton Modules:

They are: MiniBotServiceMock, AuraChannelsConfiguration, AuraMongoDb.Connector, KpiHandler, HttpMonkeyPatcher, PluginManager, LocaleManager, AuraCacheManagement, AuraBotServer.

These modules are loaded in the given order. If any of these modules does not start correctly, aura-bot does not start. Otherwise, AuraBotServer is up and running at the end of the process. All these modules are available all along the bot.

MiniBotServiceMock is only started if the bot is running locally through Aura minibot.

How to define singleton modules in Aura

In order to develop a new singleton module that can be used by aura-bot both internally and during the dialog execution, developers should keep in mind the following issues:

All modules added to the orchestrator need and publish a static variable called instance, that holds the singleton instance of that module.
Modules must have a public static method: init, that could be async or not depending on the needs of the module start-up. This method creates the singleton instance (and sets it to then instance variable). This method should only be called once by module or must throw an exception. It is only called by the orchestrator.
It is also recommended to provide an empty private constructor that avoids the creation of new instances of the module.

An example of implementation is shown below:

export class Class1 {
    public static instance: Class1;
    private constructor() {
        // Stuff here...
    }
    public static async init(config: Configuration): Promise<Class1 > {
        if (!Class1 .instance) {
            Class1 .instance = new Class1 ();
            // More stuff here

            return Class1 .instance;
        } else {
            throw new Error('An instance of Class1  already exists');
        }
    }
}

To use any of these modules:

Import its dependency.
Access the module instance property and call the required method.

The following example shows how to get a text translated by the LocaleManager.

import { LocaleManager } from '@telefonica/aura-utilities/lib/aura-locale-manager';
…
LocaleManager.instance.getText('errors:error.invalidScopes', auraUser, corr);

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

HTML5 attachments

Types of HTML attachments for Microsoft Bot Framework

Introduction

HTML attachments are a set of models whose main property is that the content of the elements to render are composed of HTML5 tags.

Aura’s HTML5 attachment template is used to send HTML5 snippets as a response template.

Custom Attachment Model

The custom attachment model contains a free format model.

Bot Framework Attachment Properties

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description
contentType	string	Content type name. Value: `application/vnd.telefonica.aura.html.custom`
content	AuraHtmlCustomContent	Model of the object where the HTML5 is
version	string	Attachment model version model
name	string	Attachment name (optional)

Aura HTML Custom Content

Property	Type	Description
containers	HTMLContainer[]	Array of containers where the HTML data is sent

HTML container

The HTML container contains an identifier and the content of HTML.

Content may be self-contained or referenced. If it is self-contained, the property data will contain the HTML. Otherwise, the property url-data will contain the URL to download the HTML.

Property	Type	Description
id	string	Identifier of tag where the content data will be placed.
encoded	EncodedFormat	How the HTML5 code is encoded in `data` properties. Values: `none`, `base64` or `zip`
data	string	HTML5 data.
url-data	string	URL where the HTML to assign to the given container id should be downloaded. The encoded field in this case is ignored.
content-type	string	Type of source: `html`, `javascript`, `css` or `json`. - If url-data has a URL, the AuraSDK will insert: . `<link href="[url-data]" rel="stylesheet" type="text/css" />` for css. . `<script src="[url-data]"></script>` for js. - If you do not use the Aura SDK, you must insert it manually. Default value: `html` Note: Javascript content cannot be unloaded once loaded into the browser, unless you reload the page or iframe.

Encoded Formats

Property	Description
none	The data is sent in HTML format
base64	The data is encoded in Base64
zip	The data is compressed in zip format

Example

{
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.html.custom",
      "version": "1.0.0",
      "content": {
        "containers": [
          {
            "id": "id-background",
            "url-data":"https://telepizza.com/containers/background?id=334"
          },
          {
            "id": "id-footer",
            "encoded": "base64",
            "data":"PGgyPkhUTUwgTGlua3M8L2gyPgo8cD5IVE1MIGxpbmtzIGFyZSBkZWZpbmVkIHdpdGggdGhlIGEgdGFnOjwvcD4KCjxhIGhyZWY9Imh0dHBzOi8vd3d3Lnczc2Nob29scy5jb20iPlRoaXMgaXMgYSBsaW5rPC9hPg=="
          }
        ]
      }
    }
  ]
}

Building Aura response through HTML5

To include HTML content in Aura’s responses, two conditions must be satisfied:

First, generate a response with an attachment whose content has the HTML code.
Second, the client must support the model of this type of attachments.

Check how to add attachments into messages in MS Bot Framework.

Generate Response with an HTML5 attachment

In order to generate responses with HTML content, it is necessary to follow the model created for it: Attachment Models.

To do this, simply generate an message attachment with the new model.

For example, if we want to send the word “Hello World” in HTML format:

Generate the necessary HTML code: Hello World! .
Include this code inside the model and assign a container to it, so that the client knows in which part of the webpage he must go. The assignation of a container is mandatory and needs the target Id of HTML element where the content will be rendered.

var message = new Message(session)
    .addAttachment({
        contentType: "application/vnd.telefonica.aura.html.custom",
	  version: "1.0.0"
        content: {
		containers:[
		{
			id: "aura-body",
			data: "<span> Hello World! <span>"
		}
	     ]
	   }
	});

The content can be encoded to avoid problems with HTML code characters or to compress content if it is large. To inform the client of the type of encoding, use the encoded property.

var message = new Message(session)
    .addAttachment({
        contentType: "application/vnd.telefonica.aura.html.custom",
	  version: "1.0.0"
        content: {
		containers:[
		{
			id: "aura-body",
			encoded: "base64",
			data: "PHNwYW4+IEhlbGxvIFdvcmxkISA8c3Bhbj4="
		}
	     ]
	   }
  });

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura bot latencies dashboard

Information provided by Aura bot latencies dashboard

Introduction

Aura bot latencies dashboard monitors outbound and inbound latencies on the request and responses handled directly by aura-bot.

The available metrics are defined in the following sections, corresponding to request errors and latency for requests, Microsoft APIs, Kernel APIs, Cognitive APIs, aura-services APIs and other APIs.

Request error

Request error graph shows the number of errors rate, aggregated by one minute.

Graph metrics

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="aura-bot",status=~"4..|500"}[1m]))

Graph visual

Request latency

Request latency graph shows latency rate for outgoing traffic, aggregated by one minute.

Graph metrics

sum by (path,kubernetes_namespace)(rate(outgoing_request_duration_seconds_sum{app="aura-bot"}[1m]))

Graph visual

Microsoft APIs latency

Microsoft APIs latency graph shows mean latency rate for the different Microsoft APIs used.

Graph metrics

Currently, there are three monitored Microsoft endpoints:

Direct Line endpoint

sum by (path,kubernetes_namespace)(rate(outgoing_request_duration_seconds_sum{app="aura-bot",host=~"directline.botframework.com"}[1m]))/
sum by (path,kubernetes_namespace)(rate(outgoing_request_duration_seconds_count{app="aura-bot",host=~"directline.botframework.com"}[1m]))

Microsoft auth endpoint

sum by (path,kubernetes_namespace)(rate(outgoing_request_duration_seconds_sum{app="aura-bot",host=~"login.microsoftonline.com"}[1m]))/
sum by (path,kubernetes_namespace)(rate(outgoing_request_duration_seconds_count{app="aura-bot",host=~"login.microsoftonline.com"}[1m]))

Blob storage endpoint

sum (label_replace(outgoing_request_duration_seconds_sum{app="aura-bot",host=~"aura.*blob.core.windows.net",path=~"/aura-temporary-resources/.*"},"path_set","$1","path","/aura-temporary-resources/.*")) by (path_set,kubernetes_namespace) / 
sum (label_replace(outgoing_request_duration_seconds_count{app="aura-bot",host=~"aura.*blob.core.windows.net",path=~"/aura-temporary-resources/.*"},"path_set","$1","path","/aura-temporary-resources/.*")) by (path_set,kubernetes_namespace)

Graph visual

Kernel APIs latency

Kernel APIs latency graph shows mean latency rate for the different Kernel APIs used.

Graph metrics

Currently, there are four monitored Kernel endpoints (more can be added if necessary for a given environment):

Kernel auth endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="aura-bot",host=~"auth.*"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="aura-bot",host=~"auth.*"}[1m]))

Kernel subscribed products endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="aura-bot",host=~"api.*",path=~"/subscribed_products/.*"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="aura-bot",host=~"api.*",path=~"/subscribed_products/.*"}[1m]))

Kernel user profile endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="aura-bot",host=~"api.*",path=~"/userprofile/.*"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="aura-bot",host=~"api.*",path=~"/userprofile/.*"}[1m]))

Kernel invoicing enpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="aura-bot",host=~"api.*",path=~"/invoicing/.*"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="aura-bot",host=~"api.*",path=~"/invoicing/.*"}[1m]))

Graph visual

Cognitive APIs latency

Cognitive APIs latency graph shows mean latency rate for the different cognitive APIs used.

Graph metrics

Currently, there are three monitored Cognitive endpoints:

Domain classifier endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="aura-bot",host=~"api-.*",path=~"/auracognitive/v3/domain_classifier/.*"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="aura-bot",host=~"api-.*",path=~"/auracognitive/v3/domain_classifier/.*"}[1m]))

Mplus resolution endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="aura-bot",host=~"api-.*",path=~"/auracognitive/v3/mplus_resolution/.*"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="aura-bot",host=~"api-.*",path=~"/auracognitive/v3/mplus_resolution/.*"}[1m]))

Suggestions endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="aura-bot",host=~"api-.*",path=~"/auracognitive/v3/suggestions/.*"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="aura-bot",host=~"api-.*",path=~"/auracognitive/v3/suggestions/.*"}[1m]))

Graph visual

Aura-services APIs latency

Graph metrics

sum by (path,kubernetes_namespace)(rate(outgoing_request_duration_seconds_sum{app="aura-bot", path=~"/aura-services/.*"}[1m]))/
sum by (path,kubernetes_namespace)(rate(outgoing_request_duration_seconds_count{app="aura-bot", path=~"/aura-services/.*"}[1m]))

Graph visual

Other APIs latency

Other APIs latency graph shows mean latency rate for traffic directed to other APIs different from those above, aggregated by one minute.

Graph metrics

Currently, the only API monitored is Genesys API:

sum (label_replace(outgoing_request_duration_seconds_sum{app="aura-bot",path=~"/genesys/.*"},"path_set","$1","path","/genesys/.*")) by (path_set,kubernetes_namespace) / sum (label_replace(outgoing_request_duration_seconds_count{app="aura-bot",path=~"/genesys/.*"},"path_set","$1","path","/genesys/.*")) by (path_set,kubernetes_namespace)

Graph visual

Service API

Service API graph shows mean latency rate for the main endpoint on aura-bridge, that receives requests from Direct Line and aura-bridge. Aggregated by one minute.

Graph metrics

sum by (path,kubernetes_namespace)(rate(http_request_duration_seconds_sum{path=~"/api/messages"}[1m]))/
sum by (path,kubernetes_namespace)(rate(http_request_duration_seconds_count{path=~"/api/messages"}[1m]))

Graph visual

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot main dialog

Description of the main dialog, one Aura Bot core dialog that maps the recognized intent with a specific dialog

Introduction

The main dialog is one of the aura-bot core dialogs in charge of routing from the recognized intention of the user to the specific dialog that provides the functionality required in an intended channel.

main dialog extends ComponentDialog, as all the rest of the dialogs. It is an internal dialog that contains all the intents-to-dialog routing map. It is loaded during the AuraBotserver start-up to be injected as a property in aura-bot and used after each intent recognition to execute the selected dialog.

At this stage, it is both instantiated and initialized, through these steps:

First, the whole list of plugins to be loaded in the system are passed to the dialog.
It also counts on the instance of the Aura BotFramework adapter, used during this start-up phase.
Then the WaterfallDialog with all the steps managed by the main dialog is added to the dialog.
After that, it is initialized:
- A RoutingMap is created.
- All the configured plugins are registered:
  - First of all, internal dialogs are included as dialogs: context-filter dialog and suggestions dialog.
  - Then, all the plugins configured in plugins-config are looped to add the routes of all their dialogs in the RoutingMap property of the main dialog, used during the activities processing to map the recognized intent to the corresponding dialog.

During the activity processing, the ActivityHandler calls MainDialog.run method to handle the incoming activity (in the form of a TurnContext), that passes it through the dialog system. If no dialog is active, it starts the default dialog. If there is any error in the TurnContext, the processing stops here and is sent to the channel.

At this stage, the main dialog is in charge of:

Routing the recognized intent to the dialog that handles it for the current channel.
Update Aura Context information of the current activity to include the dialog information.
If the dialog includes a contextFilter that fits the user’s context, then the dialog executed is the internal context-filter dialog.
If the user’s context does not match with the contextFilter of the dialog or the dialog does not have any contextFilter, then the next step of the main dialog is executed to validate if the Kernel accessToken of the user includes the scopes and purposes needed to execute the dialog.
- If the accessToken has no permissions to access it, then an error is returned, notifying the channel that the user has not consented aura-bot to access the specific API.
- If authorization is correct, then the specific dialog is executed.
When it ends, the next step of the main dialog is executed to check whether or not the dialog needs suggestions. If the dialog is configured to send suggestions and the user’s settings support them, then the internal SuggestionsDialog is executed.
When it ends, the main dialog also ends and an outgoing message flow is started.

Find here detailed information regarding the Routing Manager.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot utilities

Description of aura-bot-utilities

Introduction

aura-bot-utilities is a package belonging to aura-common-utilities that includes utilities for handling different tasks over aura-bot.

Find more information in the Github repository:
https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-bot-utilities/

How to install aura-bot-utilities package

$ git clone https://github.com/Telefonica/aura-common-utilities.git

$ cd aura-common-utilities/packages/aura-bot-utilities

How to import an utility from this package

To import an utility from the aura-bot-utilities package, execute the following command:

import { ... } from '@telefonica/aura-bot-utilities/lib/[*utility-name*]';

For example:

import { generateAttachment, getReference, getTextFromResolution } from '@telefonica/aura-bot-utilities/lib/aura-bot-library-util';

Available utilities

List of utilities in the aura-bot-utilities package:

aura-bot-common utility includes useful utilities to handle conversations both in aura-bot and in the dialogs.
aura-bot-kpis utility simplifies how KPI entities are handled in aura-bot and aura-groot.
aura-bot-library-util utility for developing aura-bot libraries and dialogs.
aura-minibot-service utility simplifies how aura-minibot and aura-minigroot are generated.
aura-movistar-libraries utility that contains utilities to be used in dialogs for Movistar channels.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura authentication flow

Description of the authentication flow for Aura users

The authentication validation process

Before starting a conversation with aura-bot, the channel needs to set a valid auraId and a fresh DirectLine token, if accessing via Direct Line, that should be sent as authorization header of bearer type in the request to the bot.

Find further information about Direct Line request in MS DirectLine API description.

Authentication validation in aura-bot consists of two phases:

Validate that the Direct Line token is a valid one, generated by the bot instance running behind aura-bot.
Validate the Aura credentials of the user, currently only based on Kernel authentication. If request authentication fails, the message is no longer processed, and an unauthenticated error response is returned to the channel.

An Aura channel should send its auraId in the from.id field of the request to the bot. Once the Direct Line token has been validated, aura-bot reads the from.id field to validate it:

Firstly, aura-bot checks if the auraId exists in the AuraUsers database and, if exists, then goes on with the authentication in Kernel.
- If the channel allows anonymous users: In the happening that the received auraId does not exist in the AuraUsers database, then the user is marked as anonymous and the Kernel authentication validation is not launched.
- If the channel does not allow anonymous users, then an UNAUTHENTICATED error is sent to the channel, informing that the Kernel authentication process must be relaunched before going on.
Kernel authentication validation:
- A new fresh Kernel accessToken is requested for the userId and authorizationId related to the auraId.
- If the authorizationId is invalid or no longer exists in Kernel, then an UNAUTHENTICATED error is sent to the channel, informing that the Kernel authentication process must be relaunched before going on.
- Then a fresh Kernel introspect token is requested, so deeper information about the user identities and permissions for aura-bot is obtained.
- Finally, the Kernel UserProfile info is obtained and processed to obtain further information about the user’s contract, for instance, its subscription type.
- After that, all this information is stored in a cache during the time when Kernel accessToken is valid. During this period, the authentication validation process is avoided.
- Besides, all this information is set in the AuraUser model and stored in the conversation context of the bot to be available during the rest of the conversation messages processing.

The authentication process is managed by the fourth-platform-authorization-middleware.

Users data storage

Authenticated users

Users database

When a user authenticates with the basic authentication mechanism of a channel, the user’s information is created/updated in MongoDB and aura-bot accesses it through the aura-authentication-api API Aura Services API published in Kernel.

For instance, in WhatsApp, when the user authenticates with SMS-OTP, her information is stored in AuraUsers database.

Local cache

It is the node cache that each pod has with information from the users.

The information is saved on each request and expires in 5 minutes, configurable via AURA_USER_LOCAL_CACHE_TTL environment variable.

Remote cache

Mongo cache with aura-bot users’ information. It is shared by all pods.

The information is saved on each request and expires in 1 hour, configurable via AURA_MONGODB_BOT_COLLECTION_CACHES_INDEX_TTL environment variable.

Anonymous users

Local cache

Node cache to store anonymous users’ information, who are accessing each pod.

The information expires in 5 minutes, configurable via AURA_USER_LOCAL_CACHE_TTL environment variable.

Both types of users

BotFramework conversational cache

This is the conversational cache of BotFramework, which is called internally in aura-bot persistentData.

It is a MongoDB cache with three parts: ConversationData, UserData and AuthData. Therefore, as this section is related to users’ information, it is stored in the last two sections.

Find more information about cache module.

How does the authenticated user’s cache expire?

The expiration of the cache depends on different factors:

The TTL of each cache element.
Kernel accessToken is no longer valid.
If the accountRemovalTimestamp of the conversational cache is greater than the timestamp of the cache

Authentication process flowchart

The following flowchart shows the authentication process:

Authentication steps

getUserData()

This function gets the user’s data from AuraUsers database, accessing through the Aura Services API published in Kernel.

If the endpoint returns a 404 error, null is returned by the function because in this case the user is anonymous, but it depends on the channel configuration to mark it as an error, if the channel does not support anonymous users ( for example, novum-mytelco channel), or as a valid anonymous users, for channels that allowed them (such as WhatsApp or Aura Webclient).

If other error is returned, the function throws an error and the authentication flow ends.

In the normal flow, the endpoint returns a user and the function returns a AuraUserModel object:

{
   "userAuraId":"c2aa81f0-abd9-444f-b7cb-47c179f10556",
   "userAuraIdGlobal":"d065dba31c79090a9e3c5afa94558d0c39ffa90c8e136931a5a12069418efad5",
   "userChannel":{
      "id":"45494a5b-835a-4fff-a813-b3d2be529dbe",
      "dialogs":[

      ],
      "outputMessageFormat":null,
      "allowAnonymous":null,
      "name":null,
      "shortName":null,
      "fpaAuthIntegrated":null
   },
   "authorizationId":"",
   "userPhoneNumber":"+34600000003",
   "userClientId":"up24456789",
   "timestamp":1575366984,
   "userPhoneType":null,
   "userSubscriptionType":null,
   "userAccessToken":null,
   "introspectScopes":null,
   "userProfile":null,
   "userType":null,
   "userAccountNumber":null
}

getChannelConfiguration()

This method returns an ChannelConfiguration object. This function tries to obtain the channel configuration by the channelId or channelName passed as parameters.

{
  "dialogLibraries": [
    {
      "name": "common",
      "dialogs": [
        {
          "id": "greetings",
          "allowAnonymous": true,
          "triggerConditions": [
            {
              "intent": "intent.common.greetings"
            }
          ]
        }
      ]
    }
  ],
  "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
  "name": "novum-mytelco",
  "nlp": {
    "enabled": true,
      "enabled": true
    }
  },
  "prefix": "nov",
  "requestOptions": {
    "requestOptionsVersion": {
      "1": {
        "channel": "directline"
      }
    }
  },
  "responseOptions": {
    "dialogContext": {
      "cardActions": {
        "generate": "always",
        "generateList": true
      },
      "defaultListType": "ordinalCardinal",
      "disabled": false,
      "normalizeTerms": true,
      "processFromClient": true,
      "promptChoice": {
        "generate": "always",
        "generateList": true
      },
      "returnToClient": false
    }
  },
  "security": {
    "authPurposes": "customer-self-service identify-customer aura-technical-problems-purpose",
    "channelId": "novum-mytelco"
  }
}

getInitialUserType()

This method returns an initial approach of the userType, because at this point some user types cannot be inferred.

Depending on the channel configuration and the user returned by getUserData(), there are four possible scenarios:

getUserData() returns a valid user
- The user has userType
  - User.userType is returned
- The user does not have userType
  - Undefined is returned
getUserData() returns null
- The channel allows anonymous
  - Anonymous is returned
- The channel does not allow anonymous
  - Unauthenticated is returned

At this point, we can have three different flows:

If the user is anonymous, it is returned with the minimal data available.
If the user is unauthenticated and the channel have integrated auth, getIntegratedAuthIntent() is called but if the channel does not have integrated auth, an error is returned and the authentication ends.
If the user is undefined or other type, it starts the flow to obtain the data from Kernel.

getIntegratedAuthIntent() (Only unauthenticated users)

This method returns the intent to redirect to the integrated authentication.

This intent is returned in user.redirectIntent provided by the authentication function.

getUserAccessToken()

This method constructs the options object with scopes, purposes, authorizationId, deviceId, security.channelId and userId. Afterwards, it makes the request and obtain the token.

If an error occurs, the function will throw an error and the authentication ends with error.

security.channelId is added when requesting the jwt-bearer.

getUserProfile()

This method returns the user profile from Kernel. If there is any error, it will be thrown and the authentication will end with error.

{
    "id": "up24456789",
    "name": "ESP - Usuario de Prueba 2 - prepago",
    "id_document": {
      "country": "ESP",
      "type": "NIF",
      "value": "712724440A"
    },
    "identities": [
      {
        "type": "phone_number",
        "id": "+34600000003",
        "services": ["mobile_prepaid"],
        "roles": ["owner", "admin"]
      }
    ]
}

getAnonymousUserProfile()

This method returns the user profile from Kernel, for anonymous users. If there is any error, it will be thrown and the authentication will end with error.

[
  {
    "identities": [
      {
        "roles": [
          "owner"
        ],
        "id": "12SIME16",
        "services": [
          "authentication"
        ],
        "type": "uid"
      },
      {
        "roles": [
          "owner",
          "basic",
          "admin"
        ],
        "id": "+34680395460",
        "services": [
          "mobile_postpaid"
        ],
        "type": "phone_number"
      },
      {
        "roles": [
          "owner",
          "basic",
          "admin"
        ],
        "id": "+34911725467",
        "services": [
          "landline",
          "internet"
        ],
        "type": "phone_number"
      },
      {
        "id": "CD53D6C5285CB60DD8E50052C1DBFADDDA033613",
        "type": "uid",
        "roles": [
          "owner"
        ],
        "services": [
          "authentication"
        ]
      }
    ],
    "id": "CD53D6C5285CB60DD8E50052C1DBFADDDA033613"
  }
]

encodeAnonymousData()

This method sets the userId and auraIdGlobal for anonymous users. These values are needed to be stored in KPIs.

{
  "userId": "76661cf96c2bda27c4fb016627f2d74af1c3cee496b76cf5d7bc2b2ad8a38cb2",
  "auraIdGlobal": "8eeb101175bfe9c247e9d10669c0d1696e8034f8e1a12b25b54780e00de0e1c1!616e6f6e796d6f7573"
}

getAuraUserType()

This method returns the final userType and the userIdentity.

First of all, identities are filtered and only the type phone_number with services prepaid, postpaid, control, hybrid or internet are returned.
After that, we need to select the phone number of the user among the numbers filtered.
- If we have more than 1 number and userData do not have userPhoneNumber (the user has not been logged with phone number), the userType returned is multimsisdn and userIdentity is undefined.
- If there is only 1 phone number, userType is monomsisdn.
- If there are many phones but we also have userPhoneNumber in userData, this phone is searched in phones array and if found, the user is considered monomsisdn although it is multimsisdn.

Monomsisdn users return userType (prepaid, postpaid or control) and userIdentity filled:

{
   "type":"phone_number",
   "id":"+34600000003",
   "services":[
      "mobile_prepaid"
   ],
   "roles":[
      "owner",
      "admin"
   ],
   "phone_type":"mobile",
   "subscription_type":"prepaid",
   "identifier":"+34600000003"
}

getIntrospect()

This method returns the scopes, purposes and boundScopes for this user from Kernel.

{
   "scopes":[
      "event-low-data-read",
      "insights-data-usage-result-read",
      "mobile-balance-transfer-write",
      "auraid-read",
      "webviews-phone-number-read",
      ...
   ],
   "purposes":[
      "sim-upgrade-suggestion",
      "identify-customer",
      "customer-self-service",
      "aura-read-insight-events",
      "device-recommendations",
      "detect-abnormal-usage"
   ],
   "identifierBoundScopes":[

   ]
}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Base recognizer

Description of base-recognizer

Introduction

Recognizers are middlewares that inherit from the abstract class called BaseRecognizerMiddleware.

export abstract class BaseRecognizerMiddleware implements Middleware, Recognizer {
    protected name: string;
    protected id: string;
    protected type: RecognizerType;
    constructor(name: string, id: string, type?: RecognizerType) {
        this.type = type || RecognizerType.Asynchronous;
        this.name = name;
        this.id = id;
    }

The source code of this recognizer is included in Aura Bot Platform recognizers - Github repository.

base-recognizer parameters

Parameters	Type	Description
name	property	Name of the middleware.
id	property	Unique identifier for middleware.
type	property	Type of execution (async or sync) to execute the recognizer method.
recognize	method	Abstract method that must be implemented in the recognizer. If the recognizer detects an intent, it must save the intent result in the turn context.
onTurn	method	Private method executed when the activity is processed by the adapter.
processIntent	method	Protected method to process the intent and entities and store the intentResult and the intent in `AuraCommand` format.

IntentResult model

Name	Type	Description
text	string	Utterance sent to the recognizer.
alteredText	string	If the original text is changed due to mistakes such as spelling typos, the altered version is included here.
intents	Object	Map of intent names to an object with score is returned. Format: `[name: string]: {score: number;};`
entities	Entity	Entities recognized.
promptCheck	boolean	If `true`, the finalize-recognizers-middleware evaluates if exits a prompt in the stack and decides whether it needs to pop from the stack or continues.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot development troubleshooting

Resolution of common problems, fixes and enhancements in Aura Bot

Developing a dialogs library aka plugin

Issues with aura-bot-common and @hapy/joi

How to detect it

As all the plugins run inside the aura-bot-platform, they must share the very same version of the libraries that are used across all the modules within the bot.

This is quite important because some of the common libraries provide a kind of singleton access to shared information, needed both during the core steps executions and during the dialogs execution. If the versions are not the same, then the instances will not be the same and the dialogs will not find the information where it is expected.

It is important to understand how the dependencies are resolved in nodejs: npm dependency resolution.

How to solve it

To avoid it, the proposal is to lay on the bot dependencies and just configured in the plugin a minimal version:

For example, if the library allows all versions starting from 1.8.3 (without a major change) and the bot provides the 1.13.7 (which is fixed in the package-lock.json of aura-bot), then both components will use the same one.

Although it is not an internal library, almost the very same issue happens with @hapy/joi. Do not change the version provided by aura-bot, or there would be unexpected issues with the schema merging and validation.

Example of package.json plugin

Each global library has specific dependencies. Developers should access to the library and check its corresponding package.json file.

Check an example for the “bill” global library

    "dependencies": {
        "@telefonica/aura-bot-common": "7.24.0",
        "@telefonica/aura-bot-library-util": "7.26.0",
        "@telefonica/aura-locale-manager": "7.22.0",
        "@telefonica/aura-logging": "3.10.0",
        "@telefonica/invoicing-client": "2.15.0",
        "@telefonica/mobile-balance-client": "2.14.0",
        "botbuilder": "~4.13.3",
        "botbuilder-dialogs": "~4.13.3",
        "joi": "^17.6.0",
        "moment": "^2.29.3"
    },

Example of aura-bot-platform package.json file

⚠️ This section has only descriptive purposes, as dependencies are established by Aura Global Team and OBs cannot modify this file.

Check an example of the package.json file

        "dependencies": {
        "azure-storage": "^2.10.7",
        "@azure/storage-blob": "^12.12.0",
        "@telefonica/authentication-api-client": "1.15.0",
        "@telefonica/aura-behavior-manager": "7.26.0",
        "@telefonica/aura-bot-common": "7.24.0",
        "@telefonica/aura-bot-events-client": "1.13.0",
        "@telefonica/aura-bot-library-util": "7.26.0",
        "@telefonica/aura-channel-data-handler": "7.22.0",
        "@telefonica/aura-cognitive-client": "3.15.0",
        "@telefonica/aura-configuration": "7.21.0",
        "@telefonica/aura-configuration-api-client": "1.10.0",
        "@telefonica/aura-developer-tools": "7.26.0",
        "@telefonica/aura-http-monkey-patcher": "7.14.0",
        "@telefonica/aura-kpis2": "7.20.0",
        "@telefonica/aura-locale-manager": "7.22.0",
        "@telefonica/aura-logging": "3.10.0",
        "@telefonica/aura-makeup-index-manager": "7.18.0",
        "@telefonica/aura-models": "3.14.0",
        "@telefonica/aura-mongo-handler": "7.12.0",
        "@telefonica/aura-movistar-libraries-utilities": "7.26.0",
        "@telefonica/aura-nlp-client": "3.11.0",
        "@telefonica/aura-orchestrator": "2.7.0",
        "@telefonica/aura-storage-file-manager": "7.18.0",
        "@telefonica/aura-validate-apikey": "1.7.0",
        "@telefonica/baikal-sdk": "^0.10.1",
        "@telefonica/event-bus": "3.8.0",
        "@telefonica/aura-file-manager-client": "1.10.0",
        "@telefonica/movistar-plus-cognitive-client": "3.13.0",
        "@telefonica/spleen": "^1.4.0",
        "@telefonica/user-profile-client": "3.13.0",
        "@telefonica/aura-bot-bill-library": "7.27.0",
        "@telefonica/aura-bot-cognitive-library": "7.27.0",
        "@telefonica/aura-bot-common-library": "7.27.0",
        "@telefonica/aura-bot-disambiguation-library": "7.27.0",
        "@telefonica/aura-bot-generic-library": "7.28.0",
        "@telefonica/aura-bot-handover-library": "7.27.0",
        "@telefonica/aura-bot-linking-library": "7.27.0",
        "@telefonica/aura-bot-miscellaneous-library": "7.27.0",
        "@telefonica/aura-bot-mocks-library": "7.27.0",
        "@telefonica/aura-bot-none-library": "7.27.0",
        "@telefonica/aura-bot-onboarding-library": "7.27.0",
        "@telefonica/aura-bot-services-library": "7.27.0",
        "@telefonica/aura-bot-tv-library": "7.27.0",
        "architect": "^0.1.13",
        "body-parser": "^1.19.0",
        "botbuilder": "~4.13.3",
        "botbuilder-core": "~4.13.3",
        "botbuilder-dialogs": "~4.13.3",
        "dotenv": "^8.0.0",
        "express": "^4.17.1",
        "express-prom-bundle": "^6.4.1",
        "folder-hash": "^3.3.0",
        "genversion": "^3.0.2",
        "helmet": "6.1.3",
        "html-to-text": "^7.0.0",
        "http-status": "^1.5.0",
        "http-status-codes": "^2.2.0",
        "joi": "^17.6.0",
        "merge-deep": "^3.0.3",
        "mkdirp": "^1.0.3",
        "moment": "^2.29.3",
        "moment-timezone": "0.5.28",
        "mongodb": "^3.5.8",
        "node-cache": "^5.1.0",
        "prom-client": "^13.1.0",
        "replace": "^1.2.2",
        "semver": "^7.3.4",
        "superagent": "^8.0.4",
        "uuid": "3.3.3",
        "xregexp": "^4.2.4"
    },

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

General guidelines for building an Aura Bot dialog

Orderly steps for building a dialog over Aura Bot in a common scenario

Create the dialog’s file

The dialog is a .ts file that must be placed within the src/ folder of its library.
- Have you already created the library? Then, go ahead.
- If not, go to Build a new library section and create it.
Developers must create one .ts file for each dialog of the use case.
All dialogs must include these two mandatory components:

Parameter	Type	Comments
id	string	Dialog’s identifier
configuration	configuration	Global and specific dialog’s configuration is validated over aura-bot and passed to the dialog through the constructor, when instantiated.

The maximum size for an activity response may not exceed the maximum limit established by the Direct Line (MS) protocol under any circumstances. In case this happens, the answer is ignored and a generic text is returned to the user explaining that there are too many results.

📌 Best practices

When generating a new dialog, a general recommendation for developers is to copy another working dialog and use it as a template.
If the dialog’s code is too long or complex, it can be split into several files, in order to increase readability.
It is also a good practice to create utility files with code shared between dialogs in the same library.

The following sections include certain features that are useful for the generation of a dialog within Aura’s framework.

Management of dialogs are waterfall dialogs

The interaction with the user can be based on a single stage back-and-forth dialog (this is, the user asks Aura and Aura provides the appropriate answer back to the user) or, on the contrary, a multiple stage dialog. Currently, although the dialog is based on a single stage, all dialogs are built as waterfall dialogs.

For this purpose, you should use the Microsoft tool botbuilder-dialogs package, that contains functions to assist with the formatting of a message activity containing a list of choices.

Within its specific library, the dialog must implement the Microsoft Bot Framework 4 ComponentDialog class. Libraries have to import the dependency on “botbuilder-dialogs: “~4.13.3`. To avoid conflict in the versions of this library, aura-bot specifies the concrete version.

/**
 * Aura Bot dialog implementation for any class.
 */
export default class NameClassAuraBotDialog extends ComponentDialog {
    ...
}

As shown in the code below, the constructor must support the configuration, which includes both global and local variables (always validated variables) that the dialog can use. Additionally, the constructor can include auraDataAccessor as a second parameter. See details in Data saving in the same conversation.

    public static id: string = 'name-class-dialog';
    private configuration: Configuration;
 
    constructor(configuration: Configuration) {
        super(NameClassAuraBotDialog.id);
        this.configuration = configuration;
        // ID of child dialog that should be started anytime component is started.
        super.initialDialogId = NameClassAuraBotDialog.id;
        // Define the conversation flow using a waterfall model.
        super.addDialog(new WaterfallDialog(NameClassAuraBotDialog.id, [
            this.method1.bind(this),
            this.method2.bind(this)
            // ...
            this.methodN.bind(this)
        ]));
       }

If the dialog requires the use of prompts, please read Prompts treatment section for its declaration within the dialog file.

Retrieving data from clients

If the dialog’s conversational flow requires to fetch user’s data, the dialog code must include the specific instructions to call an API (Kernel API or external API). Therefore, at library’s level, it is required to import the client of the corresponding API. In case of Kernel APIs, please read the section Create or update an API client.

Basic utilities for building a dialog

The current section extracts specific procedures based on Microsoft Bot Framework 4 functionalities that are of particular importance for the generation of a dialog within aura-bot.

Localized text

const correlator = ContextUtils.getCorrelator(stepContext.context);
const auraUser: AuraUserBaseModel<any> = ContextUtils.getAuraUser(stepContext.context);
const text = this.localizer.getText('common:common.greetings.main', auraUser, correlator)

Code for localizing this id: common:common.greetings.main

Dialogs can include a localizer as an attribute that points to the single instance of the class that was initialized during aura-bot start-up. this.localizer = LocaleManager.instance;

Alternatively, you can use the getLiteral method from @telefonica/aura-bot-utilities/lib/aura-bot-library-util library without having to obtain user or correlator as follows: const text = getLiteral(context)('common:common.greetings.main')

Send a simple text

The example below shows how to send a simple localized text.

await stepContext.context.sendActivity(text);
return await stepContext.endDialog();

ℹ️ In BotBuilder v4, nothing is sent (text cannot be sent) in the endDialog, only that the current dialog is finished and the result of the dialog’s finalization.

Complex messages

There is big flexibility composing user’s messages. They can be built with MessageFactory using the Bot Framework, built by your own, combined, etc.

In this section, certain flags are included that can help the channel understand the conversation flow.

InputHint

InputHint allows building messages in different modes, indicating to the destination channel when it is waiting for new messages or not.

For more information, read InputHints enum Microsoft documentation.

AcceptingInput: bot is passively ready for input, but it is not waiting a response from the user. (Example: last message in the dialog)
ExpectingInput: bot is waiting a response from the user. (Example: when a prompt is sent)
IgnoringInput: bot is not ready to receive input. (Example: when several messages are sent together excepting the last one)

Add inputHint in the activity when it is necessary to change the default behavior:
messageOneOfFour.inputHint = InputHints.IgnoringInput

Be careful with the default value given in the activities, as it is not always the desired behavior.

When constructing a complex message to the user in which, for example, partial activities are joined with attachment cards for finally sending a prompt or some parts are built with Factory and others are not, it is necessary to make sure that the final message contains the desired InputHint. In this example, the result prompt has an invalid InputHint:

// Example with INVALID InputHint:
// the message variable will have acceptingInput as default.
const message: Partial<Activity> = MessageFactory.text('My text');
const cardActions: CardAction[] = options.map(q => ({
	type: ActionTypes.ImBack,
    value: q,
    title: q
}));
// the attachment variable will have acceptingInput as default
const attachment: Partial<Activity> = MessageFactory.attachment(
   CardFactory.heroCard(null, null, cardActions)
);
const promptOptions: PromptOptions = {
 	prompt: { ...message, ...attachment },
	choices: ChoiceFactory.toChoices(cardActions)
};
// Prompt will have acceptingInput. IT IS NOT VALID!

The example with a valid InputHint is shown below:

// Example with valid InputHint:
const message: Partial<Activity> = MessageFactory.text('My text');
message.inputHint = InputHints.ExpectingInput;
const cardActions: CardAction[] = options.map(q => ({
	type: ActionTypes.ImBack,
    value: q,
    title: q
}));
const attachment: Partial<Activity> = MessageFactory.attachment(
   CardFactory.heroCard(null, null, cardActions)
);
attachment.inputHint = InputHints.ExpectingInput;
const promptOptions: PromptOptions = {
 	prompt: { ...message, ...attachment },
	choices: ChoiceFactory.toChoices(cardActions)
};
// The prompt will have expectingInput as expected in a Prompt

HasMoreMessages flag

There is another legacy flag in channelData: hasMoreMessages (created in Aura) that indicates whether aura-bot will send more messages to the channel.

Currently, all channels should use batch-outgoing-message-middleware which stacks all the messages related to an incoming activity together with the Suggestions and automatically sets hasMoreMessages field to proper value (only when messages are processed in batch mode.

Note that even though the hasMoreMessages flag is sent in some cases (if in batch mode and channel is configured to do so), it is preferable to use the standard message property inputHint, that is always available and will be maintained in the future.

It is the recommended way to configure channels and aura-bot, so messages are properly marked up both with hasMoreMessages and the proper Microsoft Bot Framework field, inputHint.

Prompts treatment

ℹ️ Before facing this section, see how the special prompts recognition works in the prompt-check-recognizer-middleware.

The following list of prompt recognizers are available in Aura:

Attachment prompt: it asks for one or more attachments, such as a document or image.
Choice prompt: it asks for a choice among a set of options.
Date-time prompt: it asks for a date-time.
Number prompt: it asks for a number.
Text prompt: it asks for a general text input.
Custom prompt: prompt that can be personalized with different options.

Break prompt and NLP Recognition

When a dialog returns a prompt and thus is waiting for an action, then the user can choose one of the prompt answers or can decide to carry out another option.

In this second case, the prompt must be broken (if conditions are fulfilled) and the aura-bot main-dialog redirects to the new dialog.

By default, prompts have NLP recognition. When the user interacts with the prompt, the prompt-recognizer is executed and tries to recognize the user’s intention. But, also by default, if the None intent is recognized, it will not break the prompt.

To make the process of prompt breaking flexible, Aura provides a default behavior and offers flags that allow the default behavior to be changed. These flags should be added during the instantiation of the prompt:

disableRecognition: enabling this flag, NLP recognition is disabled, preventing to break the prompt. (It only affects to prompts without choices). Use: prompts without choices.
enableNone: enabling this flag, if NLP recognizer has recognized the None intent, this intent is allowed to break the prompt (by default, None intent can never break a prompt). Use: all types of prompts with NLP recognition.
useValueAsCommand: using this flag, the prompt choices are interpreted as text commands, and, when properly configured, the conversation flow is redirected to the intent defined by the command. Use: only with choice prompts.

These flags should be added in the validations attribute inside promptOptions.

For example, if a prompt wants to disable NLP recognition, it should be marked as follows:

const promptOptions: PromptOptions = { 
	prompt: description, 
	validations: { disableRecognition: true } 
}; 
return await stepContext.prompt('ID_PROMPT', promptOptions);

Disable ordinals and numbers recognition in prompt choices

To avoid the recognition of ordinals and numbers in prompts, two steps should be followed:

First, add the proper flags in promptOptions:

const promptOptions: PromptOptions = { 
  ...
  validations: { 
        findChoicesOptions: {
            recognizeNumbers: false,
            recognizeOrdinals: false
        }
    } 
};

After that, a new validation method should be added to the prompt:

getRetriesValidatorAndOverwriteRecognizerResult 
const connectPrompt = new ChoicePrompt('promptName', PromptUtils.getRetriesValidatorAndOverwriteRecognizerResult(0));

Retries handling in prompt choices

This section includes the procedure for managing prompt attempts. In the botbuilder-js code, the function continueDialog must include the following code in the Prompt class:

const recognized: PromptRecognizerResult<T> = await this.onRecognize(dc.context, state.state, state.options);
// Validate the return value
let isValid = false;
if (this.validator) {
    if (state.state['attemptCount'] === undefined) {
        state.state['attemptCount'] = 0;
    }
    isValid = await this.validator({
        context: dc.context,
        recognized: recognized,
        state: state.state,
        options: state.options,
        attemptCount: ++state.state['attemptCount']
    });
} else if (recognized.succeeded) {
    isValid = true;
}

// Return recognized value or re-prompt
if (isValid) {
    return await dc.endDialog(recognized.value);
} else {
    if (!dc.context.responded) {
        await this.onPrompt(dc.context, state.state, state.options, true);
    }

    return Dialog.EndOfTurn;
}

By default, the result of the internal recognition made by the prompt is the one that triggers the retry or the return of the result. In other words, if the recognition result fails, the prompt is shown N times.

To control the number of retries, it is required a validator function that allows to manage the attemptCount counter. For this purpose, aura-bot-common library provides a validator function: getRetriesValidator, to control the number of retries. For its use, it is necessary to send this function as a second parameters in the prompt:

// Create a prompt without retries:
const myPrompt = new ChoicePrompt(ID_PROMPT,PromptUtils.getRetriesValidator(0));

Note that this validation function (that the dialog developer can build on his own), gives total flexibility to modify parameters each time the user responds.

Choice prompts

The prompt type “choice” asks the user to choose from a list of options. In this situation, the prompt-recognizer tries to recognize the choice selected with the options provided. If there is no match, it executes the NLP recognition.

The process for executing a choice prompt is detailed below:

Declare the name of prompts to be used within the current dialog.

private promptsNames = {
    ACCESS_PERMISSION: 'access-permission',
    TERMS_AND_CONDITIONS: 'terms-and-conditions'
  };

Notify the parent dialog that a prompt (with a declared id) is to be used and set its style.

const connectPrompt = new ChoicePrompt(this.promptsNames.ACCESS_PERMISSION);
connectPrompt.style = ListStyle.heroCard;
super.addDialog(connectPrompt);

In a step of the waterfall dialog, define the prompt.

Create Choices:

// Choice options.
const choicesText: Choice[] = [
   {value: text1},
   {value: text2} ];
// Prompt with text.
const message: Partial<Activity> = MessageFactory.text('message');
const promptOptions: PromptOptions = {
   prompt: message,
   choices: ChoiceFactory.toChoices(choicesText)
};

Execute the prompt:

return await stepContext.prompt(this.promptsNames.ACCESS_PERMISSION, promptOptions);

An example to handle the result of the user’s action is shown below:

if (stepContext.result && stepContext.result.index === 0 ) {
 	// Save data
 	return await stepContext.next();
 } else {
 	// Cancel option
 	return await stepContext.endDialog();
 }

Use prompt values as commands

If the target is to provide as prompt options a series of commands to redirect to other dialogs, we can use the useValueAsCommand flag.

// create a list of intent commands to be used with the prompt
const actions = [
// REMARK: In this case, the trigger condition points to the same dialog, but it could point to ANY INTENT known to the bot,
// making it a versatile feature.
{ intent: 'intent.fake.something', entities: [{ entity: CommandChoices.FIRST_OPT, type: 'suggestion' }] },
{ intent: 'intent.fake.something2', entities: [{ entity: CommandChoices.SECOND_OPT, type: 'suggestion' }] }
];
const cardActions = CardFactory.actions(actions.map(a => {
    return {
      type: ActionTypes.ImBack,
      title: a.entities[0].entity,
      value: JSON.stringify(a)
     };
}));
const promptOptions: PromptOptions = { 
	choices: ChoiceFactory.toChoices(cardActions),                          
        prompt: 'This is an example of Choice prompt with command values', 
	validations: { useValueAsCommand: true } 
}; 
return await stepContext.prompt('ID_PROMPT', promptOptions);

Creating the prompt in this way, when the user selects one of the options, it automatically redirects to a new intent in the process of recognizing the user’s action, forcing the prompt dialog to be cleared when there is a match.

⚠️ If the option chosen is the None intent, the stack cleaning behavior remains the same as always with the non-default cases to break the prompt (See section Break prompt and NLP recognition) such as the flag of enableNone etc.

Use of prompts in bypass mode

In a dialog working in bypass mode, you can use prompts that can be created as usual in the dialog:

    public DEFAULT_RETRIES: number = 2;
    public promptsNames = {
        COMMAND_CHOICE_PROMPT: 'command-choice-prompt'
    };

    constructor(configuration: Configuration) {
        ....
        // adds the prompt dialog to the Dialogs Set
        this.customPrompt = new ChoicePrompt(this.promptsNames.COMMAND_CHOICE_PROMPT,
            PromptUtils.getRetriesValidator(this.DEFAULT_RETRIES));
        ...
    }

The prompt will be instantiated, when the bypass mode initializes.

    this.customPrompt = new ChoicePrompt(this.promptsNames.COMMAND_CHOICE_PROMPT, PromptUtils.getRetriesValidator(retries));
    // To change retries we need replace original dialog for prompt
    (this.dialogs as any).dialogs['command-choice-prompt'] = this.customPrompt;
    return await Bypass.initialize(
        context,
        parseFloat(timeoutMin),
        { value: '' },
        'test',
        BypassState.Bypass,
        closeWords
    );

The prompt can be sent to the user and its value retrieved in the dialog.

private async sendPrompt(stepContext: WaterfallStepContext): Promise<DialogTurnResult> {
        const choicesText: Choice[] = [
            { value: 'id-0001', action: { title: 'Option 1 (id-0001)', type: '', value: '' }, synonyms: [] },
            { value: 'id-0002', action: { title: 'Option 2 (id-0002)', type: '', value: '' }, synonyms: [] },
            { value: 'id-0003', action: { title: 'Option 3 (id-0003)', type: '', value: '' }, synonyms: [] },
            { value: 'id-0004', action: { title: 'Option 4 (id-0004)', type: '', value: '' }, synonyms: [] },
            { value: 'id-0005', action: { title: 'Option 5 (id-0005)', type: '', value: '' }, synonyms: [] }
        ];

        const promptOptions: PromptOptions = {
            prompt: 'Hello, select one option: write the number, cardinal, ordinal or text',
            choices: ChoiceFactory.toChoices(choicesText)
        };
        return await stepContext.prompt(this.promptsNames.COMMAND_CHOICE_PROMPT, promptOptions);
    }

    private async fallbackStep(stepContext: WaterfallStepContext): Promise<DialogTurnResult> {
        await stepContext.context.sendActivity(`Option selected: ${stepContext.result.value}`);
        return await stepContext.endDialog();
    }

Data saving between Waterfall steps

getDataActiveDialog and setDataActiveDialog from DialogUtil in the aura-bot-common library are used to keep data between steps of a waterfall.

⚠️ If it is required to send data to another dialog, this method cannot be used.

The following example saves data in DATA_KEY as key: DialogUtils.setDataActiveDialog(stepContext, 'DATA_KEY', data);

In the dialog code, it should use the DialogUtils utility to recover those parameters with the key DATA_KEY:

const data: any = DialogUtils.getDataActiveDialog(stepContext, 'DATA_KEY'); (context.activeDialog.state[keyData] can be used as well directly.)

Read dialog settings

When in aura-bot flow the main-dialog has routed a dialog to be started, it is launched with dialogSetting parameters:
return await stepContext.beginDialog(idDialog, dialogSetting);

To receive configuration parameters when a dialog is started, the DialogUtils utility should be used to recover those parameters with the key options:
dialogSetting = DialogUtils.getDataActiveDialog(stepContext, 'options');

In the following example, the channel data is being routed:

{
   "name":"issues",
   "dialogs":[
      {
         "id":"issue-create",
         "suggestions":true,
         "triggerConditions":[
            {
               "intent":"intent.issue.repair",
               "contextFilters":[
                  {
                     "name":"Example redirect to greetings from issues",
                     "type":"type",
                     "conditions":"'1' eq '1'",
                     "true":{
                        "name":"Test",
                        "breakDialogExecution":true,
                        "breakFilterEval":true,
                        "redirectToIntent":"intent.common.greetings",
                        "suggestions":true
                     }
                  }
               ]
            }
         ]
      }
   ]
}

Conditions of contextFilter are always be fulfilled so intentResult will be “greetings” while originalIntent will be “issue” (if there is no contextFilter, intentResult would be “issue”). Therefore, this is the structure of dialogSetting:

Replacing a dialog

A dialog can replace another dialog by breaking its current flow. For this purpose, the command replaceDialog is used and it is necessary to know the identifier of the library and the dialog destination.

A basic example is shown below:

return await stepContext.replaceDialog(`${ID_LIBRARY}:${ID_DIALOG_DESTINATION}`);

If the destination dialog does not expect any dialogSettings, the above example would be valid.

If it is necessary for the destination dialog to receive data from the original dialog, the developer must include the appropriate instructions for sending and receiving the required parameters. However, in order to maintain consistency with the established protocol for sending dialogSettings from the main dialog, it is recommended to maintain id, originalIntent and intentResult structure.

Two case examples are shown below:

Case A: Simple dialog replacement:

const currentDialogSettigns = DialogUtils.getDataActiveDialog(stepContext, 'options');
const destinationDialogSettings =
      {
          id: ID_DIALOG_DESTINATION,
          originalIntent: currentDialogSettings.intentResult,
          intentResult: {intent: INTENT_DESTINATION},
          ...
          others :?
          ...
      }
return await stepContext.replaceDialog(`${ID_LIBRARY}:${ID_DIALOG_DESTINATION}`,destinationDialogSettigns );

In this example, destinationDialogSettings can be optional and is not sent to Handover (in fact, real Handover dialog is not using these settings).

Case B: Replace a dialog where there is a contextFilter In this case, if the dialog needs to replace itself, it is necessary to send the same dialogSettings that was sent by the main dialog:

const currentDialogSettings = DialogUtils.getDataActiveDialog(stepContext, 'options');
return await stepContext.replaceDialog(`${ID_LIBRARY}:${ID_DIALOG_DESTINATION}`,currentDialogSettings );

Data saving in the same conversation

auraDataAccessor can be the second parameter of the constructor. The command auraDataAccessor?: auraDataAccessor allows accessing to the conversation data, certain user data, etc.

auraDataAccessor has the following schema:

export interface AuraDataAccessor {
    conversationDataAccessor: StatePropertyAccessor;
    dialogStateAccessor: StatePropertyAccessor<DialogState>;
    userAuthDataAccessor: StatePropertyAccessor;
    userDataDataAccessor: StatePropertyAccessor;

Logs management

For a proper analysis of the code, it is very important to use logs correctly. The field corr refers to the correlator, which has to be set in all cases in order to follow up the requests.

The correlator can be retrieved through a functionality of the commons library: ContextUtils.getCorrelator(context). It is necessary to send the current context (in a Waterfall step, it should be stepContext.context).

this.logger.info({
     msg: 'Message',
     corr: ContextUtils.getCorrelator(context)
});

There are cases in which the correlator does not exist because aura-bot is in start process, configuration, make-up, etc. In these cases, the assigned field is no-correlator. In debug and info mode, it can include new fields in order to organize and improve the data.

An example is shown below:

this.logger.debug({
     msg: 'Cognitive Services API response',
     corr: ContextUtils.getCorrelator(context),
     NEW_FIELD: value
});

The following example is useful to write error logs:

logger.error({ 
      corr: ContextUtils.getCorrelator(context), 
      error: error.message, 
      msg: 'Server cannot be closed', 
      stck: error 
});

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Build the use case logic: use cases development over Aura Bot

Guidelines for every step included in the development of a use case over Aura Bot, from building the dialog that models the conversational flow with the user and fetches the required data to its deployment in order to make the experience available for Aura users

Process at a glance

Bot
start-up

First time with aura-bot?
. Install aura-bot
. Configure aura-bot

Develop uc logic

. Develop an aura-bot library/dialog
. Test the dialog
. Build the response for Aura users

Package and
test use case

. Package the developed use case
. Test locally to evaluate its performance

Deploy
use case

. Make certain key checks before deployment
. Finally, deploy the developed use case

Use cases in WhatsApp

. Follow the general guidelines, but also check the specific extra steps

Introduction

The documents included in this section show the detailed processes for the development of use cases over aura-bot, with guidelines for all the feasible scenarios that can appear at this stage.

The following figure schematically shows the general workflow for the development of a use case over aura-bot.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot components configuration

Configuration of Aura bot dialogs and middlewares

Configuration delivery to dialogs and middlewares

Configuration delivery to dialogs and middlewares is executed by the plugin manager.

aura-bot has the control to prepare and manage all configuration variables and make validations to get ready. In case that any validation fails, the set of libraries wrongly loaded will be shown and the bot will not start. If there is a problem with the scheme of an external library, the broken library should be extracted or fixed.

Configuration of libraries

The configuration of aura-bot libraries is fully defined in libraries configuration.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Debug with mocha and Typescript

How to test an Aura Bot dialog after its development: debug with mocha and Typescript

Introduction

When developing a use case, and once the use case dialog is built, it is required to test the dialog in order to verify its proper performance in terms of the conversational flow between the user and aura-bot.

The current section includes the guidelines to debug with mocha and Typescript for the execution of the unit tests. This corresponds to the stage Test an Aura Bot dialog within the use case development process over aura-bot.

For this purpose, Bot Framework v4 provides a Test Adapter that allows launching unit tests for the validation of a component performance (mainly a dialog, but it can also be used for other components such as middlewares).

The Test Adapter simulates sending messages from the user to the bot, therefore it requires to mock certain data required by the dialog logic (i.e., Kernel data). With this data, the Test Adapter checks that the conversational flow of the dialog is correct. Tests are executed during each Pull Request and must be passed in order to merge the PR.

Requisites

Add the following dependencies (or check that they are declared) in the package.json file, within the use case library.

An extract is shown below as an example.

"devDependencies": {
 "@types/mocha": "^6.2.0",
 "@types/chai": "^4.2.3",
 "@types/jest": "^24.0.20",
 "ts-node": "^8.4.1",
 "mocha": "^6.2.1",

📌 Find a complete example for the common library in the following Github link.

Debug configuration

The debug configuration is carried out using Visual Studio Code.

📄 For this purpose, read the Visual Studio Code documentation regarding launch configurations.

Debugging information is kept in the file launch.json, included in the folder .vscode of the developer’s workspace. The launch.json file must be included in the same root repository as the corresponding dialog to be tested.

Within this file, the field configuration must be filled with the following content:

{
    "type": "node",
    "request": "launch",
    "name": "Mocha All",
    "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
    "args": [
        "-r",
        "ts-node/register",
        "--timeout",
        "999999",
        "--colors",
        "${workspaceFolder}/src/**/*.spec.ts",
    ],
    "console": "integratedTerminal",
    "internalConsoleOptions": "neverOpen",
    "protocol": "inspector"
}

Execute tests in the Test Adapter

The Test adapter from Bot Framework 4 is used for executing unit tests. This adapter can be used to simulate sending messages from the user to aura-bot.

The following example sets up the test adapter and then executes a simple test:

const { TestAdapter } = require('botbuilder');

const adapter = new TestAdapter(async (context) => {
     await context.sendActivity(`Hello World`);
});

adapter.test(`hi`, `Hello World`)
       .then(() => done());

Adapter Test Method

At this stage, you can send something to the bot and check the response provided by it.

This is simply a wrapper around calls to send() and assertReply() methods.

adapter.test('hi', 'Hello World')
      .then(() => done());

@param userSays: text or activity simulating user’s input.
@param expected: expected text or activity sent by the bot as a reply to the user’s input.
@param description: (optional) description of the test case. If not provided, one is generated.
@param timeout: (optional) number of milliseconds to wait for the bot response. Default value: 3000.

 public test(
     userSays: string | Partial<Activity>,
     expected: string | Partial<Activity> | ((activity: Partial<Activity>, description?: string) => void),
     description?: string,
     timeout?: number
 ): TestFlow {
     return this.send(userSays)
         .assertReply(expected, description);
 }

An example is shown below:

 const { TestAdapter } = require('botbuilder');

 const adapter = new TestAdapter(async (context) => {
    if (context.text === 'hi') {
       await context.sendActivity(`Hello World`);
    } else if (context.text === 'bye') {
       await context.sendActivity(`Goodbye`);
    }
 });

 adapter.test(`hi`, `Hello World`)
        .test(`bye`, `Goodbye`)
        .then(() => done())
        .catch(e) => done(e));

Adapter Send and AssertReply methods

Send

This method sends something to aura-bot. It returns a new TestFlow instance which can be used to add additional steps for inspecting the bot reply and then sending additional activities.

📄 For further details, please check the corresponding the TestAdapter class documentation.

@param userSays: text or activity simulating user input.

public send(userSays: string | Partial<Activity>): TestFlow

assertReply

This method generates an assertion if the aura-bot response does not match the expected text/activity.

@param expected: expected text or activity from the bot. It can be a callback to inspect the response using custom logic.
@param description: (optional) description of the test case. If not provided, one is generated.
@param timeout: (optional) number of milliseconds to wait for a bot response. The default value is 3000.

public assertReply(expected: string | Partial<Activity> | estActivityInspector, description?: string, timeout?: number): TestFlow

An example is shown below:

 const { TestAdapter } = require('botbuilder');

 const adapter = new TestAdapter(async (context) => {
    if (context.text === 'hi') {
       await context.sendActivity(`Hello World`);
    } else if (context.text === 'bye') {
       await context.sendActivity(`Goodbye`);
    }
 });

 adapter.send(`hi`, 
        .assertReply(`Hello World`)
        .send(`bye`)
        .assertReply(`Goodbye`)
        .then(() => done())
        .catch(e) => done(e));

Check values in the current activity

Execute the following command: .assertReply(activity => assert.equal(activity.type, ActivityTypes.Message))

An example is shown below:

        await adapter.send('Hello')
           .assertReply(activity  => {
               assert(activity.attachments.length === 1);
               assert(activity.attachments[0].contentType === CardFactory.contentTypes.oauthCard);

               // send a mock EventActivity back to the bot with the token
               adapter.addUserToken(connectionName, activity.channelId, activity.recipient.id, token);

               let eventActivity = createReply(activity);
               eventActivity.type = ActivityTypes.Event;
               let from = eventActivity.from;
               eventActivity.from = eventActivity.recipient;
               eventActivity.recipient = from;
               eventActivity.name = "tokens/response";
               eventActivity.value = {
                   connectionName,
                   token
               };

               adapter.send(eventActivity);
           })
           .assertReply('Logged in.');

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot environment variables

Updated list of Aura Bot environment variables

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description	Modifiable by OB?
AURA_ACCESS_TOKEN_EXPIRATION_MARGIN	number	Time in milliseconds as margin to validate access token expiration. Default: `300000`.	NO
AURA_ACTIVATE_MINI_BOT	boolean	Flag to activate minibot mode. By default: `false`.	NO. Only valid during development to run Aura minibot.
AURA_ACTIVE_MIDDLEWARES	string	List of configurable middlewares. Order in list is not taken into account. Name/id middlewares cannot have spaces. Example: `BatchOutgoingMessage, Facebook`.	NO. Only guided by Global Team.
AURA_BOT_APIKEY_PATH	string	Path to validate channel APIKey authorization.	NO
AURA_HTTP_KEEP_ALIVE_MSECS	number	Number of milliseconds to keep alive HTTP connections. Used in HTTPMonkeyPatcher module.	NO
AURA_HTTP_KEEP_ALIVE	boolean	Boolean value that indicates the use of keep-alive in HTTP connections. Used in HTTPMonkeyPatcher module.	NO
AURA_HTTP_KEEP_MAX_SOCKETS	number	Maximum number of sockets. Used in HTTPMonkeyPatcher module.	NO
AURA_HTTP_GOT_REQUEST_LOG_ENABLED	boolean	Enable or disable the monkey patching of the HTTP and HTTPs modules using Got library. By default, `false`.	YES
AURA_HTTP_MAX_REQUEST_SIZE	string	Maximum size in bytes of the request body. It is a string because, the allowed values must indicate the units: 10 mb, 200 kb, etc. By default, `20 mb`.	YES, in order to decrease it if it is considered too high. For this purpose, both local and global Operations Teams must review it, because it could lead to DDoS attacks easily.
AURA_AUTHORIZATION_ENDPOINT	string	aura-authentication-api base endpoint.	NO. In any case, it must be the internal k8s URL pointing to the aura-authentication-api.
AURA_AUTHORIZATION_HEADER	string	Complete authorization header to be sent to aura-authentication-api, with the following format: `APIKEY xxxxxx`.	YES, but only if the previous APIKey was deprecated.
AURA_BRIDGE_ENDPOINT	string	Bridge endpoint that will be used by aura-bot to send the use cases responses.	NO
AURA_BRIDGE_ASYNC_CALLBACK_PATH	string	Bridge path that will be used by async-callback responses. Default value: `aura-services/v1/async-callback/notifications`.	NO
AURA_CHANNELDATA_CURRENT_VERSION	string	`channelData` version used internally by aura-bot. By default, `3`.	NO
AURA_CHANNELDATA_DEFAULT_VERSION	string	`channelData` version returned by default in all messages. By default, `1.0.0`.	NO
AURA_CHANNELDATA_RESPONSE_VALIDATION	boolean	Flag to indicate that response validation should be done. By default, `true`.	NO
AURA_CHANNELDATA_VALIDATION	boolean	Flag to indicate that request validation should be done. By default, `true`.	NO
AURA_CHANNELDATA_VALIDATION_VERSIONS	string	`channelData` versions that will be validated. By default, `3`.	NO
AURA_CHANNELDATA_VALIDATION_MIN_VERSION	string	Minimal version to validate. By default, `3`.	NO
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT	string	Complete URL where aura-bot should get the configuration of all the channels available in the environment. It should provide an array of channels fitting Aura channel model.	YES, but only if the generated sas token was
AURA_COGNITIVE_ENDPOINT	string	URL of Aura NLP API.	NO. In any case, it must be the internal k8s URL pointing to the `api-gw`.
AURA_DEFAULT_LOCALE	string	Culture code to be used by default in the current deployment: `de-de`, `en-gb`, `es-es`, `pt-br`.	NO
AURA_DEFAULT_TIME_ZONE	string	Default time zone. For example: `Europe/Madrid`	NO
AURA_DIALOG_CONTEXT_THRESHOLD	number	Minimal score to considered valid a `dialogContext` option. By default, `0.8`	NO without the advice of a language expert that validates the new threshold.
AURA_DIALOG_CONTEXT_ORDINAL_CARDINAL_THRESHOLD	number	Threshold that will be used in case the `dialogContext` elements are in list form and also if the input phrase has some number. By default, `0.95`	NO without the advice of a language expert that validates the new threshold. It must be deeply validated by the Global Team, in the happening of an error in the dialog context recognition.
AURA_DIALOG_CONTEXT_THRESHOLD_RELATION_UTTERANCE	number	If its value is greater than `0`, it will be used to evaluate the relationship between value and utterance by characters and tokens.	NO without the advice of a language expert that validates the new threshold. It must be deeply validated by the Global Team, in the happening of an error in the dialog context recognition.
AURA_ENCRYPTION_ALGORITHM	string	Encryption algorithm used to validate the APIKey.	NO. It would break database encrypted data and APIKey validation.
AURA_ENCRYPTION_IV_LENGTH	number	Size for the initialization vector used by the encryption algorithm that validates the APIKey	NO. It would break database encrypted data and APIKey validation.
AURA_ENCRYPTION_IV_POSITION	number	Position where to insert the initialization vector in the final string with the encrypted payload. Future use.	NO. It would break database encrypted data and APIKey validation.
AURA_EXTENDED_KPI_GENERIC_QUESTION_INTENT	string	Generic question intent used to extract options from entities field.	NO
AURA_EXTENDED_KPI_HANDOVER_DIALOG_PREFIX	string	Dialog prefix for handover dialog.	NO.
AURA_EXTENDED_KPI_REMOVE_HTML_TAGS	boolean	Flag that indicates if it is necessary or not to remove HTML tags from the text.	NO.
AURA_EXTENDED_KPI_SKIP_AURA_ACTION	boolean	Skip message if it is an `aura-action`.	NO.
AURA_ENCRYPTION_KEY	string	Encryption key or comma-separated list of encryption keys to be used in the environment. It is mainly used to decrypt the APIKeys.	NO. It would break database encrypted data and APIKey validation.
AURA_FILE_ENDPOINT	string	URL of the files microservice.	NO.
AURA_FP_AUTHSERVER_ENDPOINT	string	URL of the Kernel authentication server, used to get valid `access_token` or `introspect_token` to handle calls to Kernel data APIS. It MUST end with `/`	NO
AURA_FP_CLIENT_CRED_PURPOSES	string	Purposes used in 2-legged user profile queries in Kernel.	YES
AURA_FP_CLIENT_CRED_SCOPES	string	Scopes used in 2-legged user profile queries in Kernel	YES
AURA_FP_CLIENT_ID	string	Client ID to be logged in as Kernel application.	NO
AURA_FP_CLIENT_SECRET	string	Client password to be logged in as Kernel application.	NO
AURA_FP_ISSUER	string	URL of the endpoint serving Aura’s public key of the environment.	NO
AURA_FP_PRIVATE_KEY	string	Base64 encoded string of the private key of the environment.	NO
AURA_FP_USER_PROFILE_ENDPOINT	string	URL of Kernel UserProfile API.	NO
AURA_SHUTDOWN_GRACEFUL_TTL	number	Number of milliseconds to wait until all bot tasks are done before shutting each pod down. By default, `25000` (25 seconds)	NO
AURA_GATEWAY_API_ENDPOINT	URI string	Endpoint to access the locally deployed ATRIA aura-gateway-api	NO
AURA_GATEWAY_API_ISSUER_URL	string	Aura issuer URL. It is automatically fulfilled by the installer.	NO
AURA_INTENTS_NONE	string	None intents separated by commas. Default: `None,intent.none,intent.tv.none`. Used in the main-dialog.	YES. The default values are always added to the provided list.
AURA_INTERNAL_RETRIES	number	Number of retries for internal calls. By default: `1`	NO, except if requested.
AURA_KPI_FILE_PREFIX	string	String with the prefix used in the KPIs entities files of this service.	NO
AURA_KPIS_LOG_API_REQUEST_BODY	boolean	Flag to log or not the request body of the API calls. Default: `true`	YES. Once disabled, to enable run performance tests to validate if it is possible to write them.
AURA_KPIS_LOG_API_RESPONSE_BODY	boolean	Flag to log or not the response body of the API calls. Default: `true`	YES. Once disabled, to enable run performance tests to validate if it is possible to write them.
AURA_KPI_REMOVE_SPECIAL_CHARACTERS	string	Regular expression on removing special characters. Default:`\n\r`	NO
AURA_KPI_STORE_MODE	string	Destination of the KPIs entities files. Default: `blob`. If `file`, they will be stored locally in the instance, in the folder shown in `KPI_TO_DSV_LOCAL_FILES_DIRECTORY`. For development purposes. If `blob`, they will be stored remotely in the Azure blob container shown in `KPIS_STORE_CONTAINER`. Mandatory in environments running on k8s.	NO, only configurable when running the bot locally.
AURA_KPI_TO_DSV_CACHE_TTL	number	Number with the amount of milliseconds to cache existing requests to calculate their duration. Default: `1800`.	NO
AURA_KPI_TO_DSV_DELIMITER	string	Field delimiter to be used in KPIs entities files. Default: \|	NO. It will break all the analysis and processes running on top of these files.
AURA_KPI_TO_DSV_EXTENSION	string	The extension to be used in KPIs entities files. Default: `txt`	NO. If changed without changing aura-kpis-uploader, the files will not be uploaded to Kernel.
AURA_KPIS_BLOB_STORE_INTERVAL	number	Time interval in milliseconds to upload asyncrhonously logs to the `KPIS_STORE_CONTAINER`. Default: `60000`. Only needed if `KPI_STORE_MODE==blob`.	NO. In pre/production it must be `blob` so the files will be uploaded to Kernel instance afterwards. Setting `file` for development is recommended.
AURA_KPIS_STORE_CONTAINER	string	The name of the Azure Blob container to store KPIs entities files. By default, `aura-kpis`. It MUST be the same than the one configured in `KPIS_UPLOADER` module. Only needed if `KPI_STORE_MODE==blob`.	NO. If changed without changing aura-kpis-uploader, the files will not be uploaded to Kernel.
AURA_LOCALE_FOLDER	string	Full path to the local folder where locale files are stored. By default, `./locale`.	NO
AURA_LOCALE_FORCE_IMPORT	boolean	`true` if locale remote loading must be carried out although there were validation errors. By default, `false`.	YES
AURA_LOCALE_REMOTE_BACKUP	boolean	`true`, if after updating locale files with the remote version, a backup of the former local files should be stored in Azure Storage. By default, `false`.	YES
AURA_LOCALE_REMOTE_CONTAINER_PREFIX	string	Path within `AURA_LOCALE_REMOTE_CONTAINER` where the locale files are stored. By default, `locale`.	NO
AURA_LOCALE_REMOTE_CONTAINER	string	Name of the Azure Storage Blob Container where the locale files will be stored. By default, `static-resources`.	NO
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev`(more visual format). By default, `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in monitoring logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default, `INFO`.	YES, for development set it to `DEBUG`. In pre/production should be `INFO` or `ERROR`. For analysis of an issue in pre/production it may be changed to `DEBUG`.
AURA_LOGGING_EXTRA_TIME_METRICS	boolean	`true` if the time metrics should be logged in the monitoring logs. By default: `false`.	NO
AURA_MAX_ATTACHMENT_JSON_SIZE	number	Maximum size from which Aura response attachments will be zipped. By default, `10000` (10 KB)	NO
AURA_MAX_HISTORY_CHAT_ITERATIONS	number	Maximum number of messages saved in the history conversation.	YES
AURA_MICROSOFT_APP_ID	string	ID of the Microsoft bot application to be used in the deployment.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_APP_PASSWORD	string	Password of the Microsoft bot application to be used in the deployment.	NO. It must be changed by Operations Team.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCESS_KEY	string	Microsoft Storage password of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT	string	Microsoft Storage account of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO. It must be changed by Operations Team.
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Microsoft Storage account of the environment.	NO. It must be changed by Operations Team.
AURA_MICROSOFT_AZURE_STORAGE_CONFIGURATION_CONTAINER	string	Name of the container where basic bot configuration files are stored: Mongo indexes descriptor, aura-behavior-manager configuration, etc. By default, `aura-configuration`.	NO
AURA_MICROSOFT_AZURE_STORAGE_SUGGESTION_TABLE_TTL	number	Number of seconds to store the users’ suggestions. By default, `86400` (one day).	NO
AURA_MICROSOFT_AZURE_STORAGE_SUGGESTION_TABLE	string	Name of the Azure Storage table where users’ sent suggestions will be stored. By default, `AuraUserSuggestionTable`	NO
AURA_MICROSOFT_CHANNEL_SERVICE	string	Microsoft Channel Service.	NO. It must be changed by Operations Team.
AURA_MICROSOFT_OPEN_ID_METADATA	string	Metadata used in Microsoft OpendId validation.	NO. It must be changed by Operations Team.
AURA_MIDDLEWARE_SPEAK_PROCESSOR	string	Used to enable speak property text substitution on the outgoing messages, to produce speakable text. Regular expression of substitution format example: `[["\\*"," asterisk "],["\\#"," hash "]]`	YES. Include all the needed changes to be done automatically between the written and the spoken text.
AURA_MIN_INTENT_SCORE_THRESHOLD_TO_CLEAN_STACK	number	Minimal score to clean the dialog stack in a prompt case. By default, `0.95`	NO. Environment configuration should be delivered with a validated threshold, currently `0`, meaning that any valid NLP result will break the prompt and move the user to the new dialog. Do not change it without validating it with Aura Global Team.
AURA_MONGODB_BOT_COLLECTION_CACHES_INDEX_TTL	number	Number of seconds to keep the user’s data available in aura-bot cache. By default, `3600`.	NO
AURA_MONGODB_BOT_COLLECTION_CACHES	string	MongoDB collection name where aura-bot will store the remote caches used during request processing. By default, `aura-caches`.	NO
AURA_MONGODB_BOT_COLLECTION_CONTEXT_INDEX_TTL	number	Number of seconds to keep the context data available in aura-bot context cache. By default, `3600`.	NO
AURA_MONGODB_BOT_COLLECTION_CONTEXT	string	MongoDB collection name where aura-bot will store the context of the users. By default, `aura-context`.	NO
AURA_MONGODB_BOT_DATABASE	string	MongoDB database name where aura-bot will store all the data needed to handle requests. By default, `aura-bot`.	NO
AURA_MONGODB_CACHE_TTL	number	Lifetime of cache used by aura-behavior-manager. It MUST be disabled in PRE and PRO environments. By default, `3600` seconds (1h).	YES, only for development environments.
AURA_MONGODB_CACHE_DATABASE	string	Database used in cache of aura-behavior-manager. By default, `aura-bot-caches`.	YES, only for development environments.
AURA_MONGODB_CACHE_COLLECTION_DL	string	Collection used in cache of aura-behavior-manager. By default, `dev-cache`.	YES, only for development environments.
AURA_MONGODB_CACHE_INDEX_DL	string	Index used in TwoLevelsCache of aura-behavior-manager. By default, `id`.	YES, only for development environments.
AURA_MONGODB_PASSWORD	string	MongoDB password to access `AURA_MONGODB_BOT_DATABASE` in `AURA_MONGODB_URI`.	NO
AURA_MONGODB_POOL_SIZE	number	Number of connections available in MongoDB pool. By default, `60`.	NO
AURA_MONGODB_SSL	boolean	`true` if access to `AURA_MONGODB_URI` is `SSL`. By default, `false`.	NO
AURA_MONGODB_URI	string	MongoDB URI of the server handling. `AURA_MONGODB_BOT_DATABASE`.	NO
AURA_MONGODB_USERNAME	string	MongoDB username to access `AURA_MONGODB_BOT_DATABASE` in `AURA_MONGODB_URI`.	NO
AURA_MONGODB_MAX_POOL_SIZE	number	Maximum number of connections in the MongoDB pool. By default, `60`.	NO
AURA_MONGODB_MIN_POOL_SIZE	number	Minimum number of connections in the MongoDB pool. By default, `2`.	NO
AURA_MONGODB_MAX_IDLE_TIME_MS	number	Maximum idle time in milliseconds for connections in the MongoDB pool. By default, `30000` (30 seconds).	NO
AURA_MONGODB_RETRY_WRITES	boolean	`true` if retry writes are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_RETRY_READS	boolean	`true` if retry reads are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_HEARTBEAT_FREQUENCY_MS	number	Frequency in milliseconds of the heartbeat in the MongoDB connection. By default, `2000` (2 seconds).	NO
AURA_MONGODB_SERVER_SELECTION_TIMEOUT_MS	number	Timeout in milliseconds for server selection in the MongoDB connection. By default, `5000` (5 seconds).	NO
AURA_MONGODB_SOCKET_TIMEOUT_MS	number	Timeout in milliseconds for socket operations in the MongoDB connection. By default, `45000` (45 seconds).	NO
AURA_CONNECTION_TIMEOUT_MS	number	Timeout in milliseconds for establishing a connection to the MongoDB server. By default, `10000` (10 seconds).	NO
AURA_MONGODB_READ_PREFERENCE	string	Read preference for the MongoDB connection. By default, `primaryPreferred`. Possible values: `primary`, `primaryPreferred`, `secondary`, `secondaryPreferred`, `nearest`.	NO
AURA_PHONE_COUNTRY_CODE	string	Two letters ISO-3166 country code to obtain phonenumber without country prefix. It must be one of `BR`, `DE`, `ES`, `UK`.	YES, if the expected country code is not correctly configured.
AURA_PROMETHEUS_REGEX	string	Stringified object that contains regex to apply to prometheus paths in order to group equivalent requests in prometheus. Example: `'{"subscribed_products/$1/users//products": "/subscribed_products\\/(v\\d)\\/users\\/.\\/products/"}'`. By default: `'{}'`	YES
AURA_PRESUGGESTIONS_INTENT	string	Intent that forces to ask for pre-suggestions in the suggestions dialog. By default: `'intent.getOnboarding'`	NO, only if another intent was configured to obtain presuggestions.
AURA_REQUEST_ENABLE_NAGLE	boolean	Boolean to enable Nagle. By default: `false`.	NO
AURA_REQUEST_TIMEOUT	number	Number of milliseconds to wait for a request. By default: `30000`, 30 seconds.	YES, in case of network issues.
AURA_RETRIES_CODES	string[]	Array of strings with error codes. By default: [‘ECONNRESET’].	NO, except if requested.
AURA_SEED_ID	string	Seed used to generate userIds for anonymous users.	NO
AURA_ROOT_INTENT	string	Default intent that aura-bot sets if it has not been possible to determine the user’s intention during recognition/routing process. By default, the `none` intent will be returned.	NO
AURA_SERVER_PORT	number	Port where aura-bot will be listening to requests. By default, `8080`.	NO
AURA_SERVICE_ENVIRONMENT	string	Type of environment: `'DEV', 'PRE', 'PRO'`. By default, `DEV`. It is used during locale translation, to get the correct text reference and, in development environments, to allow aura-behavior-manager execution.	NO
AURA_SERVICE_URL_DIRECTLINE	string	Default URL for Direct Line services. By default, `https://directline.botframework.com/`.	NO
AURA_STATIC_RESOURCE_ENDPOINT	string	URL of the server publishing aura-bot static resources.	NO
AURA_STATIC_RESOURCE_SAS_TOKEN	string	Credentials to access the server publishing aura-bot static resources.	NO. Only if Operations Team needs to change it.
AURA_SUGGESTIONS_V3_NUMBER	number	Number of suggestions configured to be returned in channelData version 3. By default, `5`.	No, only changed if the Global Team or the LCDO Dev Team requires it.
AURA_SUPERAGENT_DEADLINE_TIMEOUT	number	Number of milliseconds to wait until the `superagent` deadline timeout, as specified here. It is optional and, by default, it is not configured.	No, only changed if the Global Team or the LCDO Dev Team requires it.
AURA_SUPERAGENT_RESPONSE_TIMEOUT	number	Number of milliseconds to wait until the `superagent` response timeout, as specified here. It is optional and, by default, it is not configured.	No, only changed if the Global Team or the LCDO Dev Team requires it.
AURA_SUPERAGENT_RETRY_ATTEMPTS	number	Number of retry attempts (not counting the first attempt) to be applied on `superagent` requests, as specified here. It is optional and, by default, it is not configured.	No, only changed if the Global Team or the LCDO Dev Team requires it.
AURA_TEMPORARY_REMOTE_CONTAINER	string	Container to upload temporary resources. By default, `aura-temporary-resources`	NO
AURA_TERMS_AND_CONDITIONS_API_KEY	string	APIKey to call Aura Terms and Conditions API.	NO
AURA_TERMS_AND_CONDITIONS_ENDPOINT	string	Aura Terms and Conditions API basic endpoint.	NO
AURA_TERMS_AND_CONDITIONS_EXPIRATION	number	Terms and conditions expiration time. By default, `86400000` (1 day).	NO, only changed if the Global Team requires it.
AURA_URL_SAS_EXPIRATION	number	Expiration time for sas URLs generated for temporary resources. By default, `600` (minutes).	YES if LCDO or Operations Team prefer another duration time.
AURA_USER_ENCRYPT_CACHE	boolean	`true` to encrypt data stored in users’ cache. By default, `true`.	NO
AURA_USER_LOCAL_CACHE_TTL	number	Number of seconds to keep the user’s data available in aura-bot users’ local cache. By default, `300` sec.	NO
AURA_VERSION	string	Number of the Aura release being executed.	NO
AURA_HTTP_PATHS_LOG_DISABLED	string	HTTP paths separated by commas which requests would not be logged. By default: `aura-kpis,static-resources`. Used in http-monkey-patcher.	YES, if there is a path that should not be logged. The default values are always added to the provided list.
DEV_AURA_BOT_BEHAVIOR_CRON_PATTERN	string	Cron pattern to set the refresh time of aura-behavior-manager configuration. By default, `/5 * * *` (every 5 minutes). It is only valid for development environments.	YES, in development environments.
DEV_AURA_BOT_BEHAVIOR_MICROSOFT_AZURE_STORAGE_SETTINGS_FILE	string	Name of the configuration file route used by aura-behavior-manager. By default, `aura-bot/aura-bot-behavior-manager.json`. It is only valid for development environments.	YES, in development environments
DEV_AURA_BEHAVIOR_MANAGER_ACTIVE	boolean	Flag to indicate whether or not aura-behavior-manager module should be activated in the current deployment. It is only valid for development environments.	YES, in development environments.
AURA_KPIS_BLOB_TIME_WAIT_IF_EXISTS	number	Time to wait in milliseconds if the KPIs blob exists to avoid duplicate headers. By default: `1000`.	YES

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

General guidelines for locales management

The aim of this document is to describe how locales are handled by Aura Bot services for the following components: aura-groot, aura-authentication-api, aura-bridge, aura-bridge-outbound.

⚠️ Remember that hot swapping of aura-bot locales must be done through the aura-configuration-updater

Introduction

The objective of the current document is to describe the hot swapping process to update POEditor texts in Aura without service outage, both for global and local use cases. Hereinafter, we will refer it as hot swapping process.

For each type of use cases, the process uses different projects and has a different scope, as shown in the following table.

Global use cases	Local use cases
- Aura POEditor global project (owned by Aura Global Team)	- Aura POEditor local project (owned by L-CDO Team)
- Scope: edition of texts	- Scope: edition of texts and definition of resources

In both cases, the texts correspond to PRE and PRO resources in POEditor.

Follow the orderly guidelines in the succeeding sections:

⚠️ If you have local use cases, you must carry out the process included in this document for update POEditor texts each time a new version of your local use cases is deployed.

Previous steps

Previous steps include the management of POEditor itself for the edition of texts and, depending on the use case type, the generation of resources. These tasks are fully defined in the corresponding documents:

Global Use Cases > Edition of POEditor texts
Local Use Cases > Edition of POEditor texts and generation of resources (references)

Generation of POEditor token

Once the texts have been modified in POEditor, it is necessary to have a Read-only API Token in order to import them into aura-bot.

Global Use Cases: developers should request the read-only API Token to the APE Team.
Local Use Cases: developers should request the read-only API Token to the local responsible of POEditor project.

The reading token is obtained from the POEditor website, where the OB edits the texts.

Figure 1. Add readonly API token

Figure 2. API access

Importing locale files with aura-locale-importer tool

We recommend using aura-locale-importer tool, a utility developed by Aura Global Team that allows to handle the importation and exportation of locale files with POEditor.

Install aura-locale-importer tool:
1.1. Log in NPM to download the private NPM package dependencies. You can log in with user/password or using the token:
- User/password -> npm login
- Token -> Add the token to your environment variables on your machine. Follow the guidelines for mac/linux.
1.2. Install the npm application globally in the host. You can use two equivalent commands for installing the latest available version:
npm install –g @telefonica/aura-locale-importer or
npm i @telefonica/aura-locale-importer -g
Copy in a local directory the file containing the locale resources to be updated (JSON file from aura-bot/locale/ directory). If there is no file, the aura-locale-importer tool will generate one.
Get full locale files to be uploaded:
```
$ aura-locale-importer -u -l <language-country> -j <POEditor project> -b <my-library> -d <local-directory> -m library -f –t <token>
```
Where:
- -l <language-country>: country translation e.g., es-es, de-de, en-gb. If this field is empty, the system will import every translation file.
- -j <POEditor project>: POEditor project to be used:
- For global use cases: aura-bot project (global project)
- For local use cases: name of the OB’s local project
- -b <my-library>: specific libraries to be uploaded in the hot swapping process. For example: fill this parameter with authentication for aura-authentication-api, or fill it with bridge for aura-bridge.
- -d <local-directory>: local directory where result files will be imported.
- -f: this parameter forces the files overwriting.
- -m library: it indicates the way of working. For the current release, it must be library.
- -t <token>: read-only API token to access to POEditor.
Here, developers can follow two different processes:

a. Define it in the environment variable $POEDITOR_TOKEN in the host running the process. In this case, this command should not be included here.

b. Add it in the current command within -t <token>

An example for a local use case in Germany is shown below:
- This command will generate all the locale files that fulfil the conditions established in the parameters above:
```
`$ aura-locale-importer -u -l de-de -j Aura-Bot-De -d ./locale -m library -f –t f9023005c8792e57d3593511b69c300e`
```
- This command lists the content of the locale folder in Aura Bot project. $ ls .locale
The output will be: de-de.json

Locale files uploading

This process requires certain previous steps, as all the resources and texts (from the bot core, global use cases or local use cases) must be merged together during the make-up process.

Access the Azure blob container static-resources in your intended environment, where the JSON file with your resources and texts is. This file will be in the following paths, depending on the component:

For aura-authentication-api:
static-resources/authentication/locale/<aura-version>/<language-country>.json
For aura-bridge:
static-resources/aura-bridge/locale/<aura-version>/<language-country>.json

It is recommended to use Azure Storage Explorer in order to easily access this file.

Figure 3. Updating locale files to Azure

Download this file for its edition.
Add the new content from the imported locale files to the downloaded files or replace the specific content.

For example, you can add a new resource from the imported file (Section 4.3.) to the end of the file downloaded from Azure (Step 1). Or you could replace one of the texts appearing in the downloaded file (Step 1) with one of the new texts shown in the imported file.
Validate the JSON format through the online tool JSONLint.
Upload again the JSON file into the corresponding Azure blob container (depending on the component, the locale file must be in a different container as explained in step 1). Depending on the component, the files should be loaded into a different folder. In case the folder in that path does not exist, please create it manually.

⚠️ It is recommended to make a backup copy before overwriting.
If you want to keep previous versions of the JSON files as a backup during testing, you must remove the JSON extension from the file name to prevent these files from also being imported into Aura. For example:
❌ <language-country>.json.backup
✔️ <language-country>.backup

This assures that only one JSON file is present for each language.

Make modifications available

Check LocaleManager configuration

Check the configuration of the component to be updated, aura-authentication-api or aura-bridge, following LocaleManager configuration, for instance:
$ kubectl –n <aura-ns> edit cm <authentication-api|aura-bridge>

⚠️ Firstly, read the document connecting to Kubernetes to know how to operate with Kubernetes in your environment.

Where:

<aura-ns> is aura namespace, with the following format: aura-<OB>-<environment>
The specific value for <aura-ns> is an output for the installation process and can be found in the path _output_install/*info.json, in the field services_namespace.

This will open a text editor (such as vi) showing the whole config map of the specified pod.

The servers aura-authentication-api and aura-bridge count on a series of environment variables that manage the process. Developers should check several items, shown in the following screenshots for both servers.

You have the right Aura version: variable AURA_VERSION.
Verify the values for the Azure Storage account: variable AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT.

Figure 4. Check LocaleManager configuration

The definition of these variables is shown below:

AURA_VERSION: string with the semantic versioning of Aura to be read from the remote blob container. By default, it takes the version packaged originally in the docker image (7.0.0. in the case of Heroes). It is required to put a correct value, to be sure that the container is loading the correct set of files.
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT: string with the name of the Azure Storage account related to the given aura deployment.

Restart the corresponding pod/pods

For the Kubernetes version 1.15 onwards, the following command must be launched for restarting the corresponding pod/pods.

If developers have modified the locale file for aura-bridge, they will need to restart aura-bridge pods.
The same applies for changes made in aura-authentication-api, its pod should only be restarted in case you modified the locale file in the folder for this component.

kubectl version >= 1.15: 
$ kubectl rollout restart deployment [authentication-api, aura-bridge]

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Get started with Aura Bot

Guidelines including how to create a bot service, different approaches to install Aura Bot and procedure for its configuration

Related documents
📃 Aura Bot Platform descriptive documentation

Introduction

ℹ️ First time using Aura Bot? Go ahead with this section.

aura-bot architecture is a modular one and has been designed in order to fulfil an essential requisite of configurability and extensibility for Aura deployment if a customized Aura behavior is needed.

This section is mainly intended to developers interested in the installation and configuration of aura-bot.

Create a bot service

⚠️ This task must be carried out only once by an aura-bot developer

Follow the guidelines in Microsoft documentation: Create a bot with Azure Bot Service.
Save the value of the following variables from the created bot:

"AURA_MICROSOFT_APP_ID":"YOUR ID", 
"AURA_MICROSOFT_APP_PASSWORD":"YOURPASS",

Install Aura Bot

Developers can install aura-bot following two different approaches:

Aura minibot
Aura minibot is a tool intended for testing purposes in local environment. It is highly recommended to use Aura minibot to get familiar with aura-bot when developing simple use cases. Learn how to install and work with Aura minibot.
Full Aura Bot
If you want to install locally a fully functional working instance of aura-bot, go to the full Aura Bot section.

Configure Aura Bot

How to start a basic Aura Bot configuration

We recommend to use Kubernetes for the management of the environment variables required for the bot configuration.

Developers can use the process explained below:

Access with kubeconfig

The jq JSON processor can be used to decode all the private variables (developers should install it and get sure it is added to the OS PATH).

Set the KUBECONFIG file (provided by DevOps) through the following command: export KUBECONFIG=<name of the file provided>
To check all the available environments, use: kubectl get ns
Download all the environment variables and join them in a unique file:

( kubectl -n <env name> cm aura-bot -o json | jq.exe -r ".data|to_entries|map(\"\(.key)=\(.value|tostring)\")|.[]" ; kubectl -n <env name> get secret aura-bot -o json | jq.exe -r ".data|to_entries|map(\"\(.key)=\(.value|tostring|@base64d)\")|.[]" ) > <env name>

Where: <env name> is the name space selected on step 2 (kubectl get ns)

ℹ️ Base 64 decodification requires a jq version from 1.6 onwards

Copy this file into the project folder (wherever you are storing .env files).
Enable forwarding from your local address (localhost) to the kubernetes aura-configuration-api deployment.

kubectl --namespace <env name> port-forward deployments/aura-configuration-api 8999:8999

Point AURA_CHANNELS_CONFIGURATION_API_ENDPOINT to previously forwarded service: http://localhost:8999/aura-services/v2/configuration.
Highly Recommended: if using Visual Studio Code, you could add these objects to your launch.json file to be able to run the make-up process in debug mode and change certain variables without directly modifying aura-configuration-api channels information and/or (according to AURA_MAKEUP_FILES_DESTINATION variable) the bot-response.json file.

[
  {
    "type": "node",
    "request": "launch",
    "name": "name of the script",
    "program": "${workspaceFolder}/lib/index.js",
    "console": "integratedTerminal",
    "outFiles": [
      "${workspaceFolder}/lib/**/*.js"
    ],
    "env": {
      "CONFIG_FILE": "your .env file path",
      "AURA_MICROSOFT_APP_ID": "YOUR ID",
      "AURA_MICROSOFT_APP_PASSWORD": "YOURPASS",
      "AURA_LOGGING_FORMAT": "dev",
      "AURA_LOGGING_LEVEL": "DEBUG"
    }
  },
  {
    "type": "node",
    "request": "launch",
    "name": "makeup",
    "program": "${workspaceFolder}/lib/make/makeup-cli.js",
    "outFiles": [
      "${workspaceFolder}/lib/**/*.js"
    ],
    "env": {
      "CONFIG_FILE": "your .env file path",
      "AURA_LOGGING_FORMAT": "dev",
      "AURA_LOGGING_LEVEL": "DEBUG",
      "AURA_MAKEUP_MODE": "local"
    },
    "console": "integratedTerminal"
  }
]

In case the adjustment of the value for certain variables is required, modify directly the file launch.json, as explained before.

Example of environment configuration

As an example, the main configuration file (.env.PRO) can be defined as follows:

AURA_DEFAULT_LOCALE=es-ar
AURA_SERVER_PORT=8080

All environment variables with their description can be found at the following link Aura Bot Platform environment variables

In case aura-bot is started using the following command:
CONFIG_FILE=./env/.env.PRO AURA_DEFAULT_LOCALE=es-es npm start
Then, the aura-bot instance would use the following configuration variables and values:

AURA_DEFAULT_LOCALE would take the value es-es since it is set as an environment variable and has the highest priority.
AURA_SERVER_PORT would take the value 8080 since it is set in the main configuration file, and not as an environment variable.
AURA_LOGGING_LEVEL would take the value INFO since it is set in the configuration schema definition and nowhere else (default value).

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Handling channelData versions

Description of components that make Aura Bot capable of working with different channelData versions.

UML diagram

@startuml
title ChannelData handling diagram
actor User
participant AuraGroot
participant ChannelDataValidatorMiddleware #76bbe7
participant AuraBot #ebdff7
participant Routing #ebdff7
participant MainDialog #1add4d
participant Dialog #1c733b
participant OutgoingChannelDataNormalizerMiddleware #73c1c3
participant Adapter #1bcad5
participant AuraChannelDataHandler #ebba65
User -> AuraGroot: User request
AuraGroot -> ChannelDataValidatorMiddleware: request reaches validation middleware
alt AURA_CHANNELDATA_VALIDATION === true
    ChannelDataValidatorMiddleware -> AuraChannelDataHandler: isValidatableVersion checks if channelData request version is validatable
    AuraChannelDataHandler -> ChannelDataValidatorMiddleware: isValidatableVersion returns if version is valid
    alt isValidatableVersion === true
        ChannelDataValidatorMiddleware -> AuraChannelDataHandler: getRequestValidator validates channelData request
        AuraChannelDataHandler -> ChannelDataValidatorMiddleware: getRequestValidator returns validation
    end
end
ChannelDataValidatorMiddleware -> AuraBot
AuraBot -> MainDialog: Route to main dialog
MainDialog -> Routing: MainDialog routing step
alt channelDataRequest <= v3
    Routing -> Routing: Add information to triggerCondition
end
alt channelDataRequest >= v3
    Routing -> Routing: Add information to triggerCondition (intent.vX)
end
Routing -> MainDialog: checkLegacyDialogStep check if a conversion to legacy channel data is needed
alt channelDataRequest <= v3
    MainDialog -> AuraChannelDataHandler: getNormalized normalizes request to supported aura-bot channelData
end
MainDialog -> Dialog: Reach dialog by intent if exists
alt channelDataRequest === v3 && channelDataVersion === v3
    Dialog -> AuraChannelDataHandler: formatChannelDataV3 formats response to be compatible with v3 version
    AuraChannelDataHandler -> Dialog: formatChannelDataV3 returns formatted v3 channelData
end
Dialog -> OutgoingChannelDataNormalizerMiddleware: Pass activity formed in dialog to outgoingMiddlewares
alt channelDataRequest <= v3
    OutgoingChannelDataNormalizerMiddleware -> AuraChannelDataHandler: getNormalized Normalizes activity (output) and request (input) to be compatible with supported aura-bot version
    AuraChannelDataHandler -> OutgoingChannelDataNormalizerMiddleware: getResponseChannelData Gets original response channel data
end
OutgoingChannelDataNormalizerMiddleware -> Adapter: Middleware's pipeline is finished and result is received by the adapter
alt AURA_CHANNELDATA_RESPONSE_VALIDATION === true
    Adapter -> AuraChannelDataHandler: isValidatableVersion checks if channelData response version is validatable
    AuraChannelDataHandler -> Adapter: isValidatableVersion returns if version is valid
    alt isValidatableVersion === true
        Adapter -> AuraChannelDataHandler: getResponseValidator gets validation for the response version
    end
end
alt channelDataRequest >= v3
    Adapter -> Adapter: Add version parameter to response.
end
alt channelDataRequest < v3
    Adapter -> Adapter: getResponseChannelData gets transformed channel data from correct version (removes version field)
end
Adapter -> AuraBot: Activity is processed and ready to be sent
AuraBot -> User: Bot response
@enduml

Version Format

The version format will be a semantic versioning, (MAJOR.MINOR.PATCH). However, aura-bot will work exclusively with the MAJOR version: If a customer sends the version 3.1.0, for Aura the version is 3.

Aura will keep the original version from the request in the response. That is, if the client sends version 3.0.0, but Aura is currently working with version 3.5.1 as Aura works with the older one, there is no problem and Aura will keep the version that the client sent, 3.0.0, in the response.

For versions greater or equal to 3.0.0, aura-bot accepts either SemVer versioning (3.0.0) or major versioning (3) in channelData.version property.

Request channelData validation

The channeldata-validator-middleware executes request channelData validations. aura-bot receives the request which contains information about the channelData version. With that information, different validations are made.

More information regarding validations being made and utilities that used for this flow can be found in channelData validation.

Aura Bot channelData versions behavior

aura-bot is able to work with channelData versions v1, v2 and v3.
If a channel does not specify the version, it is assumed to be working with version v1.
Version v2 was specific for living-apps, and version v3 is the first version of the normalized channelDatamodel.
Use cases created for channelData version v1 will not be able to execute dialogs created with the v3 model and vice versa.

Intent format for v3

The format for intents in channelData version v3 only changes internally.

Therefore, when defining an intent, it is not necessary to specify its version, the dialog loading system will do it internally.

Dialog configuration

From channelData v3 onwards, it is necessary to specify the version to be used in the channelData dialogs.

If no version is specified, it is understood that they work in v1 mode for classic use cases.

If you want to work with the channelData normalized version (v3), specify it in the use case dialog configuration file.

Example:


{
  "name": "packageLibTest",
  "dialogs": [
    {
      "id": "channel-data-V3-dialog-example",
      "channelDataVersion": "v3",   <-  It's mandatory specific version for ChannelData v3
      "triggerConditions": [
        {
          "intent": "intent.factotum-test.channel-data-model"
        }
      ]
    }
  ]
}

When a dialog has specified its channelData version through the channelDataVersion property, it can only be executed if the client has specified that version in the request. Otherwise, the system will return an “I don’t understand you”.

A client can have two dialogs for the same use case with different versions, but it is mandatory that the names of the dialogs are different. The intents must be called exactly the same for v3 and for others, as the format of the intents is set internally and it is not necessary to specify anything.


{
  "name": "packageLibTest",
  "dialogs": [
    {
      "id": "channel-data-V1-dialog-example",
      "triggerConditions": [
        {
          "intent": "intent.factotum-test.channel-data-model"
        }
      ]
    }
  ]
}

This configuration contains the same intent as the previous one, but the dialog is for channelData version v1, as its version has not been set. It should be noted that if you set a version channelDataVersion: v1 it will also work in v1 mode.

Routing to version v3

Loading Dialogs configuration

The first step to set the intents to their proper version must be done during the dialogs loading. This is done inside the aura-configuration package in the document channels-configuration-current.ts.


    private buildAuraChannel(channelConfiguration: ChannelConfiguration): ChannelConfiguration {
        ........

        // NORMALIZATION. Assign the intent to the channel Data Version
        channelConfiguration.dialogLibraries?.forEach((library) => {
            library.dialogs.forEach((dialog) => {
                const channelDataVersion = this.getChannelDataVersionMajor(dialog.channelDataVersion);
                if (channelDataVersion > 2) {
                    dialog.triggerConditions.forEach((triggerCondition) => {
                        triggerCondition.intent = this.getIntentByChannelDataVersion(triggerCondition.intent, dialog.channelDataVersion);
                    });
                }
            });
        });

        .......

Routing configuration

Intents whose dialogs have the property channelDataVersion with a value greater than or equal to v3 will name their intents with the corresponding version.

Example:

“channelDataVersion”: “v3” -> intent.[intent_name].v3
“channelDataVersion”: “v2” -> intent.[intent_name]
“channelDataVersion”: “v1” -> intent.[intent_name]
“No channelDataVersion” -> intent.[intent_name]

For the previous example, the dialog routing would be as follows:

“intent.factotum-test.channel-data-model.v3” -> Routing -> “channel-data-V3-dialog-example”
“intent.factotum-test.channel-data-model” -> Routing -> “channel-data-V1-dialog-example”

Establishment of intent versioning in recognizers

When a channel sets a version of the channelData greater or equal to v3, the routing step will set intent format in getIntentByChannelDataVersion(), which can be found in aura-configuration.

  public static setIntentResult(context: TurnContext, intentResult: any, utterance: string, promptCheck: boolean,
        ......
        intentResult.intent = AuraChannelsConfiguration.instance.getIntentByChannelDataVersion(intentResult.intent, ChannelDataUtils.getChannelDataVersion(context));
        ......
    }

Routing to v3 dialog

Once the routing and the recognizers steps are executed, based of the result obtained, it will be routed to a v3 dialog if channelDataVersion: "v3" and there is match in the recognized intent.

Dialogs in v3

Currently, only certain dialogs have been migrated to channelData v3 version,as specified in the following sections.

Greetings v3 dialog

Greetings dialog, which is included in common library, has been migrated to v3.

For more information about this implementation, check Create/migrate a dialog to channelData v3.

didntUnderstand special case

There is a particular case: a request needs a V3 dialog and this is not implemented. In this case, None dialog should be triggered.

At the moment, None has not being migrated to v3 so this type of requests are redirected to bot’s fallback case didntUnderstand.

This occurs due to routing appending v3 to None intent and not finding a match. This case returns an activity with the resource core:core.cancel

Prompt case

In this particular case, the last message processed by the dialog must have the channelData correct version.

Firstly, the prompt is displayed to the user going through the mainDialog, but user’s response to that prompt does not follow the same path.

During this stage, channelData is converted into v3 for compatibility with aura-bot core.

If the dialog is in version v1, channelData will not need to be modified, so the channeldata-validator-middleware will check if the dialog is legacy and will convert its response channelData to v1.

Outgoing middlewares

Once aura-bot responds, this response is being processed by certain middlewares that work in v3 version. Hence, there are two possible flows:

User is requesting a v1 dialog In this case, the response from the v1 dialog is converted into v3 immediately after the activity is created.

Once the activity is being processed by the middleware’s pipeline, it is converted from v3 to v1 by the outgoingchannelDataNormalizer middleware, that performs the same actions in reverse order than incomingchannelDataNormalizer middleware.

Once the activity is being processed by the middleware’s pipeline, it is converted from v3 to v1 in the Aura BotFramework adapter.
User is requesting a v3 dialog In this case, the response from the v3 dialog is already in the current supported version, so there is no need to merge to other version.

Adapter

Before sending the response to the user, there are a number of extra steps which are performed inside the Aura BotFramework adapter.

channelData validation

As done in the request stage, there is another validation in the response, before sending the resulting activity to the user, checking if the sent schema is valid for the activity version.

Find more information about which validations are made and utilities used for this flow in channelData validations.

Activity merging

For more information about how channelData merges are processed, check channelData mapping.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

HTML5

Description of HTML5 model supported by Aura

Introduction

Hypertext Markup Language revision 5 (HTML5) is markup language for the structure and presentation of World Wide Web content.

Aura Platform supports HTML5 model, therefore, it is possible to develop experiences that include HTML content in the response.

HTML5 components

There are two main components in the HTML5 model:

HTML attachments: set of models whose main property is that the content of the elements to render are composed of HTML5 tags.
HTML5 custom tags: different types of custom tags generated to send commands to Aura.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Incoming Event middleware

Description of incoming-event-middleware, executed in event activity types.

Introduction

The incoming-event-middleware is in charge of managing events, that is, activities for the end-to-end communication between aura-bot and channels.

Channels can send events to aura-bot to inform about any relevant event happening on their side.
In particular, aura-bridge sends an event to aura-bot, when the transformation from bot activity to WhatsApp message fails, that is handled by this middleware.

When aura-bot receives an event, this middleware prevents the execution of the rest of the middlewares by completing the request flow.

There are two types of events:

Log type: the channel asks aura-bot to log certain information

emptyResponse type: Event sent by the bot when no response activity is sent. Currently, it is internally used for aura-bot towards aura-bridge.

export enum TypeEvent {
    /**
     * Log event
     */
    Log = 'log',
    /**
     * Directline empty response event (Event sent by the bot when no response activity is sent)
     */
    EmptyResponse = 'emptyResponse'
}

This middleware is executed once the HTTP request arrives at the server to the POST /api/messages endpoint and the Direct Line authentication executed by the Adapter is successful.

It is a Turn middleware, so it is executed during turn initialization. It is only executed if the type of the activity is event. In this case, the middleware records the KPIs and updates the context.

The source code of this middleware is included in Aura Bot Platform middlewares - Github repository.

Incoming Event flow diagram

The incoming-event-middleware flowchart is included below:

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Internal API clients

Description of internal API clients implemented and used by aura-bot

Introduction

Internal API clients in Aura are associated with Aura servers. They are automatically generated and published with changes in the API definition of its server during the CI execution, the developer does nothing to update it.

The self-generated clients are clients automatically generated and published with changes in the API definition of its server during the CI execution, the developer does nothing to update it.

Almost all servers developed by the aura-bot team belong to this set, but not all. For instance, aura-bridge client, as its complete swagger is built out of the different partial swaggers of aura-bridge core and all its plugins, is generated and stored in aura-clients repository instead of in aura-bridge repository, as would happen with the self-generated clients.

Aura cognitive client

This client provides a set of classes to interact with the Telefónica Cognitive Service. It implements version 3.4.0.

These classes are:

DomainClassifierApi: interaction with Telefónica’s Domain Classifier Cognitive Service. This service is no longer used by aura-bot, because the updated version is the one available in aura-nlp-client.
InsightsResolutionApi: interaction with Telefónica’s Insights Resolution Classifier Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.
SuggestionsApi: interaction with Telefónica’s Suggestions Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.
NotificationsFilterApi: interaction with the Telefónica’s NotificationFilter Cognitive Service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-cognitive-client/

📄 Access this API client in the Github repository: aura-cognitive-client

Movistar+ cognitive client

This client provides a set of classes to interact with the Movistar+ cognitive Service.

These classes are:

MovistarPlusCognitiveClient: Interaction with Movistar+ Resolution Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.
MovistarPlusCognitiveStatusClient: Interaction with Movistar+ Resolution Status Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/movistar-plus-cognitive-client/

Aura NLP client

This client implements the internal NLP API that provides access to the aura-bot nlp-recognizer-middleware. It implements the client for the 3.0.0. version of the API.

It provides access to DomainClassifierApi: interaction with Telefónica’s Domain Classifier Cognitive Service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-nlp-client/

📄 Access the aura-nlp API definition

Aura authentication client (autogenerated)

This client implements the internal authentication API that provides access to the Aura user’s service. It implements the client for the 2.2.0. version of the API and provides access to UsersApi.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/authentication-api-client/

📄 Access the aura-authentication-api API definition

Find more information in the Github repository:

Aura File Manager client

This client implements the internal API that provides access to the aura-file-manager component. It implements the client for the 2.2.0. version of the API and provides access to the File Manager API, microservice responsible of handling attached files storage and validations at channel level.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-file-manager-client/

📄 Access the aura-file-manager API definition

Aura Configuration Client

This client implements the API that provides access to the aura-configuration-api component. It implements the client for the 2.3.0. version of the API.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-configuration-api-client/

📄 Access the aura-configuration-api API definition

Aura Bridge client

The aura-bridge client contains a set of endpoints that support aura-bridge, that is, Aura component in charge of adapting the communication protocol between aura-groot and certain external channels, such as Whatsapp, that cannot implement the Direct Line protocol.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-bridge-client/

📄 Access the aura-bridge API definition

Aura Complex Logic client

This client implements the API that provides access to the aura-complex-logic component in Aura.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/complex-logic-client/

📄 Access the aura-complex-logic API definition

Aura Gateway API client

This client implements the API that provides access to the aura-gateway-api service in Aura.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-gateway-api-client/

📄 Access the aura-gateway-api API definition

Agents Manager API client

This client implements the API that provides access to the agents-manager service in Aura.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-agents-manager-client/

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot recognizers

Description of the different Aura Bot recognizers, components in charge of the identification of the user’s intention

What are Aura Bot recognizers?

Recognizers in aura-bot are a specific type of middlewares that are executed in a certain stage of the message flow. They are in charge of the recognition of the user’s intention based on the data sent in the request.

Recognizers inherit from the abstract class called BaseRecognizerMiddleware.

There are two types of recognizers, internal and external:

Internal recognizers

aura-bot own components that are able to recognize the intention of the user directly from the incoming message. Currently, they are:

External recognizers

Responsible for calling an external API to obtain an intention.
Currently, the only external recognizer is nlp-recognizer-middleware, in charge of detecting the intention of the user from all the training of the environment.

Apart from the ones mentioned above, the finalize-recognizers-middleware is in charge of finalizing the recognition process.

Recognizers are executed sequentially in the order previously defined during the bot start-up.

Recognizers flow

The following figure shows the execution flowchart for aura-bot recognizers, including the recognizers included in aura-bot by default. They are executed sequentially.

If one specific recognizer has obtained an intention, then the flow redirects to the finalize-recognizers-middleware, that provides the result to aura-bot in order to trigger the corresponding dialog.
If the recognizer in execution does not get the intention, then the flow continues and the succeeding recognizer is executed.
As can be seen in the flowchart, the last recognizer to be executed is the external one, nlp-recognizer-middleware. This is because aura-bot should only request it if no other recognizer gets the intention of the user.
The finalize-recognizers-middleware is in charge of deciding, in case there is any active prompt, whether to continue with the prompt or to remove the prompt from the dialog stack and process the attempt to start a new dialog otherwise.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Single messages response format

Description of the single message format, that allows sending a batch of messages at once

Introduction

The single message format consists on a way to send a batch of messages at once (in one single activity). Both the sender and the receiver should be capable of handling it, that is, “merging” several messages into a single one when sending, and do the reverse process when receiving.

When a channel enables singleMessage activity, it has to be prepared to process the activities sent, as they are not standard. This means doing the reverse process done in the bot, taking a single message and process every activity contained within as if they would have come one by one. Note that if the content type is application/vnd.telefonica.aura.message.single.zip, the content must be unzipped first.

Configuration

To enable single message functionality in a channel, it must be configured with singleMessage property set to true.

This property belongs to Aura channel model: ResponseOptionsVersionParameters model.

Following is an example configuration of one channel with enabled singleMessage:

[
  (...)
  {
    "responseOptions": {
      "versions": {
        "v1": {
          "singleMessage": true,
        } 
      }
    },
    "channel_id": "1234",
    "name": "example"
    (...)
  }
  (...)
]

How does single message format work?

If we want to send two simple messages, by default they will be processed as a batch, as explained in batch messages format, in order to ensure inputHint is correct.

We will, in this example, send two activities:

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "text": "Primer mensaje",
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "ignoringInput"
}

and

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "text": "Segundo mensaje",
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "acceptingInput"
}

However, if we active the single message mode as explained before (singleMessage: true) and try to send the same two messages in a batch, we will merge them together, in a container activity, and will send only this one:

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "acceptingInput",
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.message.single",
      "content": [
        {
          "type": "message",
          "recipient": {
            "id": "my-user",
            "name": "test-user"
          },
          "text": "Primer mensaje",
          "channelData": {
            "correlator": "5555",
            "answersCallback": "http://localhost:3000"
          },
          "inputHint": "ignoringInput"
        },
        {
          "type": "message",
          "recipient": {
            "id": "my-user",
            "name": "test-user"
          },
          "text": "Segundo mensaje",
          "channelData": {
            "correlator": "5555",
            "answersCallback": "http://localhost:3000"
          },
          "inputHint": "acceptingInput"
        }
      ],
      "name": "singleMessage"
    }
  ]
}

Note that all the activities in the batch are stored together in the content of one single attachment, with application/vnd.telefonica.aura.message.single content type and always inputHint set to acceptingInput. The channelData from the container activity (the outer-most), and therefore the correlator and dialogContext are copied from the last activity in the array (the last in the batch).

Single message mode (zipped)

If the content of a single message is big enough (specified in AURA_MAX_ATTACHMENT_JSON_SIZE env var, 10KB by default), the content will be zipped, and the content type will be application/vnd.telefonica.aura.message.single.zip.

With the previous example, we will send:

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "acceptingInput",
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.message.single.zip",
      "content": "eJztks1y0zAQx1/F6Bw7NnY+mhNMykxT6MAhDIdODmtpHYvYkiKtHUrww3DlNfpiSEmhDMxwgOGGTpb/uz/tx//2yAg/EFuw18395yfRC0e6i2DfyciAhQjedwJspHS07zDqNb//EhmLXDqwCRsxqUxHV1IFgtwqbaXarsI/r/EalMJmJbwmpE+iRir0gkPbS45vbeOVmsi4xXj8GJGUmioLLR603SVct+MA06pH64CkVmxxZDJQr/cf3z3PD8t6up5fTd9kl1V/8XISAxtGrLK6/R4InYVY9qCeSZEt7fJ68uqw81TlX/lRDomhOyMxtPQtOxMZZLM8zp9Oq7goOI8vsCziuchFXlTzNK34I6zz7Z0+TyzT3K316nfFfkpPp/AEujOB0KJzsD1NyiDs/ng5Dwu4BILQC9fWYgOkrSdWZcZhVk5inE8mcZEXGMM8z2Mh8pSnOMtmWe4RNbgbbfHmXJFjC7IdDsPo+GutQAS8bv3gfNhteE6Rv6zPcWBMI/lpfeNeiaSV3GqnK0o4WJHUaPV5y/Qw+bIj0iqgNsOwGbEGSgx+cd3WFxI47if/Aedo6L8B/8KA/8IxFTTOW2bzFZX1doo=",
      "name": "singleMessage"
    }
  ]
}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Users authentication

Description of users’ authentication process in Aura Bot. Discover the different types of users and how they can authenticate in Aura

Introduction

aura-bot supports different types of users, each of them with access to specific services and use cases:

Authenticated users
Anonymous users

In the authentication process, aura-bot carries out the following summarized steps:

Obtains information from the users
Validates it
If the validation is successful, and depending on the type of user, aura-bot allows accessing to different services
Stores the user’s data

The detailed process is described in users’ authentication flow.

The authentication of a user implies the acceptance of Terms and Conditions, which are handled by aura-bot.

In certain scenarios (use cases) where the user is unauthenticated, it is required to redirect specific intents that need authentication. Find here the complete information regarding login redirections.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura users types

Description of the different users types existing in Aura

Introduction

Aura supports different types of users: authenticated and anonymous, each of them with access to specific services and use cases. The following sections include detailed information about each type.

Authenticated users

Aura securely knows the identity of the users, as they must have successfully completed the authentication flow.

They can be classified into different groups regarding their type of subscription. This classification depends on the different countries, but in general terms, there are three main types of authenticated users: postpaid, prepaid, hybrid / control.

Authenticated users can access any use case in Aura, providing that the use case supports authenticated users or the specific subscription type of the user, defined through context filters.

In case the authorization process of an Aura user fails:

If the channel does not allow anonymous users, then the request is marked as failed and a status with the unauthenticated error is returned to the channel. This indicates that the channel should relaunch the authentication of the user to get a valid auraId.

Anonymous users

Anonymous users are unauthenticated users but with authorized access to certain Aura’s use cases: to those which support the anonymous user’s type. In every case, Aura’s experience is different for each type of users.

Within anonymous users, there is a specific type named identifiable users in which the channel auraId univocally identifies a user in the channel.

It also depends on the channel, as different Aura channels can support both types of users (anonymous-identifiable and authenticated) or only authenticated ones.

Due to some restrictions in Kernel, from Kiss release onwards, anonymous users also have userId and auraGlobalId. These fields, in contrast to authenticated users, are not obtained from Kernel but auto-generated by aura-bot and aura-authentication-api in some cases, to be stored in KPIs. The values are generated to maintain the same value between channels to allow the user identification if possible.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot as a skill

aura-bot is Aura’s neuronal network in charge of core features in Aura Virtual Assistant. Find in the current documents the description of this component, its architecture, components and processes.

Aura Virtual Assistant component

Introduction

aura-bot is an HTTP server, based on Microsoft Bot Framework. It is built in Typescript using the node.js SDK of Bot Framework. As an HTTP server, it uses Express.js.

aura-bot is Aura’s neuronal network, where it can be considered as a Bot Development Platform itself. In the recent distributed architecture, aura-bot is the only skill on the system that handles all requests, although the new entry point to the system is now the root bot called aura-groot, that redirects all requests to the only skill in order to access Aura through diverse communication channels and interacts with every Aura system or component in order to provide Aura users with the intended answer or requested service.

The following flowchart shows the complete conversational process executed by aura-bot.

Aura Bot functionalities

The main functionalities in charge of aura-bot are users’ sign up, authentication validation process and conversational process.

Apart from them, there are other processes managed by aura-bot that can be executed in order to customize the bot, activate other components, etc.

Find here all the information related to Aura Bot processes.

Aura Bot components

aura-bot components can be classified into different categories:

Aura Bot Platform components, which are components aura-bot has as a BotFramework bot: dialogs, middlewares, recognizers, Bot framework adapter, Activity Handler, etc.
Other components that have been developed within aura-bot to provide it with a specific functionality, such as plugin manager or routing manager.
Moreover, the databases used by aura-bot.

Find detailed information of all of them in Aura Bot components.

Aura Bot Platform repository

The repository aura-bot-platform has a folder layout inside the src folder, to organize the code according to functionality groups.

In the src root folder, only main files should be placed, such as index.ts, or main server file server.ts (it was app.ts in aura-bot).

src/bots

At the beginning, only the file aura-bot.ts is hold here, that is the main ActivityHandler (a kind of replace of previous UniversalBot).

In a near future, more Bot Builder adapters could be located here.

src/config

This folder contains files that load configurations and that are required in other places, such as channel configuration, environment variables, etc.

src/db

This folder contains files that manage and connect to databases, such as MongoDB.

src/events

The files handling events (such as ModuleObserver subclasses) should be placed in this folder.

src/dialogs

This folder contains the main dialog (main.ts) and custom prompts, as use case dialogs will be located in libraries, loaded as dependencies.

src/make

This folder contains the code related with joining all the library-specific data with global one during the make-up process.

src/middlewares

This folder contains abstract middleware base classes, and specific middleware implementation (final classes).

src/middlewares/recognizers

This folder contains all the recognizers, such as NLP recognizer, Aura Command recognizer, etc.

src/models

Files located within this folder will have exported types and interfaces required in different parts of the code (types and interfaces required only within a file could be self contained).

src/modules

This folder contains independent code blocks, that could be exported as a reusable packages if required in different components, such as cache manager, locale manager, etc.

src/plugin

This folder contains the modules in charge of loading plugins: charging dialogs, middlewares, delivery configuration for these components, etc.

src/routing

This folder contains the code related with intent-to-dialog routing, as this is not part of Bot Builder anymore.

src/utils

This folder contains utility classes and methods that are not part or any other block. We should maintain this folder organized and tidy, to avoid lots of unspecific files.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot core dialogs

Aura Bot core dialogs are internal global dialogs that are deployed within a specific Aura Platform release

Introduction

The following aura-bot core dialogs are global ones designed and developed by Aura Platform Team that are at the OBs’ disposal to build experiences in Aura. OBs cannot modify their logic but use them as they are.

These dialogs are deployed jointly with the corresponding Aura Platform release.

As intended for Aura global experiences, they are named below but fully described in the section Global use cases together with other global dialogs.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot make-up process

The current section describes the make-up processes that take place within Aura Bot

Introduction

The make-up process in aura-bot runs by using the following command:
npm run makeup

All the processes that are executed during the aura-bot make-up are detailed in the following sections.

Environments variables for Aura Bot make-up

Mandatory variables

Name
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY
AURA_DEFAULT_LOCALE
AURA_STATIC_RESOURCE_ENDPOINT
AURA_STATIC_RESOURCE_SAS_TOKEN
AURA_VERSION

Optional variables

These optional variables, together with their default values, are shown below. However, it can use some other optional variables, which can be checked out in the aura-bot make-up script in Github.

Name	Default value
AURA_MAKEUP_FILES_ORIGIN	blob
AURA_MAKEUP_FILES_DESTINATION	blob
AURA_AUTHORIZATION_HEADER
AURA_RESOURCES_PREFIX	’libraries'
AURA_SERVICE_ENVIRONMENT
AURA_MAKEUP_MODE	‘full’
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT
AURA_CONFIGURATION_CONTAINER	‘aura-configuration’
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT
AURA_CHANNELS_CONFIGURATION_BLOB	‘bot-response.json’
AURA_DIALOG_CONFIG_FILENAME	‘merged-dialog-config.json’
AURA_LOCAL_RESOURCES_PATH	’local-resources'
AURA_LOCAL_RESOURCES_PORT	3000

Load External Libraries

In this process, which is fully automated, the instance will be made-up, joining general configuration and i18n with library-specific ones.

The external libraries loaded by aura-bot are the different dialogs assigned to the use cases. This list of libraries is listed in the plugin-config.json file.

plugin-config.json

[
    "@telefonica/aura-bot-common-library",
    "@telefonica/aura-bot-disambiguation-library",
    "@telefonica/aura-bot-generic-library",
    {
        "exclude": [
            "./handover-genesys/handover-bypass-dialog",
            "./handover-genesys/handover-status-dialog"
        ],
        "packagePath": "@telefonica/aura-bot-handover-library"
    },
    "@telefonica/aura-bot-miscellaneous-library",
    "@telefonica/aura-bot-none-library",
    "@telefonica/aura-bot-onboarding-library",
    "@telefonica/aura-bot-tv-library",
    {
        "exclude": [
            "./wifi-check-connectivity-dialog",
            "./wifi-connect-to-guest-dialog",
            "./wifi-enable-disable-guest-dialog"
        ],
        "packagePath": "@telefonica/aura-bot-wifi-library"
    },
    "@telefonica/aura-bot-la-amazon",
    "@telefonica/aura-bot-la-iberia",
    "@telefonica/mi-movistar-beta",
    "@telefonica/generic-faq"
]

The make-up process is in charge of loading all these libraries and unifying the different resources they contain. Each environment contains the libraries associated with the required use cases.

Manage MongoDB Indexes

The indexes configuration file is in /settings/makeup/aura-bot-mongodb-indexes.json.

aura-bot-mongodb-indexes.json (partial)

{
  "databases": {
    "aura-bot": {
      "aura-version-control": {
        "version": 1,
        "removeIndex": [],
        "removeAllData": "",
        "indexes": [
          {
            "version": 1,
            "name": "idx_name",
            "keys": {
              "name": 1
            },
            "unique": true
          }
        ]
      },
      "aura-caches": {
        "version": 1,
        "removeIndex": [],
        "removeAllData": "",
        "indexes": [
          {
            "version": 1,
            "name": "idx_item_caches",
            "keys": {
              "item": 1
            },
            "unique": true
          },
          {
            "version": 1,
            "name": "idx_ttl_caches",
            "keys": {
              "lastAccess": 1
            },
            "expireAfterSeconds": 3600
          }
        ]
      },
      "aura-context": {
        "version": 1,
        "removeIndex": [],
        "removeAllData": "",
        "indexes": [
          {
            "version": 1,
            "name": "idx_aura_last_access",
            "keys": {
              "lastAccess": 1
            },
            "expireAfterSeconds": 3600
          }
        ]
      },
      "aura-external-kpi":
      .....

Once the make-up is executed, this file will be uploaded to the assigned repository [AURA-STORAGE]/aura-configuration/[AURA_VERSION]/aura-bot-mongodb-indexes.json. If this remote file exists, it has priority over the local file.

This configuration is assigned in the make-up process by means of the following model:

  const options: MakeupMongoIndexManagerOptions = {
        mongodbConfiguration: {
            AURA_MONGODB_URI: configuration.AURA_MONGODB_URI,
            AURA_MONGODB_DB_NAME: configuration.AURA_MONGODB_BOT_DATABASE,
            AURA_MONGODB_USERNAME: configuration.AURA_MONGODB_USERNAME,
            AURA_MONGODB_PASSWORD: configuration.AURA_MONGODB_PASSWORD,
            AURA_MONGODB_POOL_SIZE: configuration.AURA_MONGODB_POOL_SIZE,
            AURA_MONGODB_SSL: configuration.AURA_MONGODB_SSL
        },
        fileConfiguration: {
            containerName: 'aura-configuration',
            localPath: 'settings/makeup',
            remotePath: '',
            files: [{ name: 'aura-bot-mongodb-indexes.json', mimeType: 'application/json' }]
        },
        replaceLocalWithRemote: true,
        storageCredentials: {
            storageKey: configuration.AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY,
            storageName: configuration.AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT
        },
        uploadFromLocalToRemote: true,
        auraVersion: configuration.AURA_VERSION,
        ignoreDownloadErrors: true,
        ignoreUploadErrors: true,
        dataBaseSuffix: configuration.AURA_ENVIRONMENT_NAME
    }

Prepare Locale Resources

Each library may contain a settings/locale folder, with one or more i18n locale files (settings/locale/<lang>.json).

These locale files will be merged by language (in case of conflict, the latest loaded library overrides the previous one), and then merged with global locale files in aura-bot/locale/<lang>.json, taking precedence the global version in case of conflict.

All keys are sorted in resulting JSON files, to increase the readability.

For these local files to be merged, it is required to expose them in the locale property when registering the plugin. This will be done within the file index.ts, as shown in the following example:

import * as libraryUtil from '@telefonica/aura-bot-utilities/lib/aura-bot-library-util';
(...)
const settingsPath = path.resolve(__dirname, '..', 'settings');
register(null, {
    my_library: {
        locale: libraryUtil.readLocaleFolder(path.resolve(settingsPath, 'locale')),
        (...)
    }
});

The language resources in aura-bot are located in /locale/:

 de-de.json
 en-gb.json
 es-es.json
 pt-br.json

When starting aura-bot, these files are loaded remotely from [AURA-STORAGE]/static-resources/[AURA_VERSION]/locale/.

In the make-up process, the language resources of each loaded external library are merged into one file per language and then uploaded to Azure Storage using uploadFile method.

File example:

{
    "common:common.error.main": [
        "Aura no está disponible en estos momentos. Por favor, inténtalo un poco más tarde"
    ],
    "common:common.goodbyes.main": [
        "¡Hasta la vista!",
        "¡Hasta pronto! Espero haber podido ayudarte"
    ],
    "common:common.greetings.main": [
        "Hola, buenas",
        "Hola, estoy aquí para ayudarte"
    ]
}

Note that all the keys should start with the name of the library followed by a colon (":"). In the bot, this library name will be appended automatically, so only the last part of the key must be used in the dialogs.

Set Environment Variables

Each library may contain .env files within the folder settings or settings/{DEV|PRE|PRO} (some vars could have a specific value per environment).

If the AURA_SERVICE_ENVIRONMENT environment variable is set, the settings/.env file will be merged with settings/<AURA_SERVICE_ENVIRONMENT>/.env (taking precedence the env-specific values in case of conflict).

Every file is optional. After that, the resulting .env file from each library will be merged together and written down in aura-bot/.env.libraries. Note that this file has the lowest precedence when loading environmental variables in aura-bot.

Multiline values are escaped in order to allow the dotenv library to successfully read the values, even though it is recommended not using them.

For these .env files to be merged, it is required to expose them in the env property when registering the plugin. This will be done within the file index.ts, as shown in the following example:

import * as libraryUtil from '@telefonica/aura-bot-utilities/lib/aura-bot-library-util';
(...)
const settingsPath = path.resolve(__dirname, '..', 'settings');
register(null, {
    my_library: {
        env: libraryUtil.readEnv(settingsPath),
        (...)
    }
});

All the environment variables of each external library are merged together with the aura-bot environment variables and assigned as environment variables to the container or containers that will be in charge of raising their corresponding Pods in Kubernetes.

File example:

MYLIBRARY_VERSION=1.2.3
MYLIBRARY_ENDPOINT=https://my-library.test/v1
Note that to avoid conflicts, the env vars specific for a library should start with the library name in uppercase followed by an underscore ("_").

Prepare Remote Channel Config

Each library may contain dialog-config.json files or dialog-config.<AURA_BOT_DEFAULT_LOCALE>.json files.

The AURA_DEFAULT_LOCALE environment variable is required while AURA_SERVICE_ENVIRONMENT is optional. If AURA_SERVICE_ENVIRONMENT is set, these 4 files will be fetched and configuration is merged (the highest in the list means more priority in case of conflict):

(1) settings/<AURA_SERVICE_ENVIRONMENT>/dialog-config.<AURA_BOT_DEFAULT_LOCALE>.json
(2) settings/<AURA_SERVICE_ENVIRONMENT>/dialog-config.json
(3) settings/dialog-config.<AURA_DEFAULT_LOCALE>.json
(4) settings/dialog-config.json

In case AURA_SERVICE_ENVIRONMENT is not set, only #3 and #4 files are fetched and merged.

After that, the resulting dialog config from each library will be merged together. Then, the config is added to every channel in the config file pointed out by AURA_CHANNEL_CONFIGURATION_ENDPOINT (except the dialogs containing an only_in string array property, that are not added to channels not present in that property) replacing dialog_libraries from each channel. Then the resulting file is uploaded to Azure, replacing the previous one.

For these files to be merged, it is required to expose them in the config property when registering the plugin. This will be done within the file index.ts, as shown in the following example:

import * as libraryUtil from '@telefonica/aura-bot-library-util';
(...)
const settingsPath = path.resolve(__dirname, '..', 'settings');
register(null, {
    my_library: {
        config: libraryUtil.readDialogConfig(settingsPath),
        (...)
    }
});

Use onlyIn property

In some cases, the dialog configuration can differ among channels for the same country. In these cases, the onlyIn property must be used in the dialog-config.<AURA_DEFAULT_LOCALE>.json file:

{
    "name": "tv",
    "authorization": {
        "purposes": "customer-self-service",
        "scopes": "subscribed-products-user-read"
    },
    "dialogs": [
        {
            "id": "tv-carousel-info",
            "suggestions": false,
            "triggerConditions": [
                {
                    "intent": "intent.carousel.info"
                },
                {
                    "intent": "intent.tv.details"
                }
            ],
            "onlyIn": [
                "movistar-plus"
            ]
        }
   ]
}

This configuration file is built by merge each channel configuration from each external library and uploaded to [AURA-STORAGE]/aura-configuration/bot-response.json using uploadStringAsBlob and/or (according to AURA_MAKEUP_FILES_DESTINATION) uploading channel information in aura-configuration-api.

bot-response.json (partial)

[
  {
    "channel_id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
    "fpa_auth_purposes": "customer-self-service detect-abnormal-usage device-recommendations-v3 sim-upgrade-suggestion aura-read-insight-events identify-customer bolt-on-suggestion",
    "fpa_auth_scopes": "device-catalog:devices-read device-stock:stock-read",
    "name": "novum-mytelco",
    "nlp": {
      "enabled": true,
        "enabled": true
      }
    },
    "prefix": "nov",
    "dialogLibraries": [
      {
        "name": "generic",
        "dialogs": [
          {
            "id": "get-generic",
            "triggerConditions": [
              {
                "intent": "intent.greetings"
              }
            ]
          }
        ]
      },
      {
        "name": "bill",
        "dialogs": [
          {
            "id": "balance-check",
            "suggestions": true,
            "authorization": {
              "purposes": "customer-self-service",
              "scopes": "mobile-balance-read"
            },
            "triggerConditions": [
              {
                "intent": "intent.balance.check",
                "contextFilters": [
                  {
                    "name": "Anonymous redirect to linking",
                    "type": "type",
                    "conditions": "/type eq 'anonymous'",
                    "true": {
                      "name": "Anonymous redirect to linking",
                      "breakDialogExecution": true,
                      "breakFilterEval": true,
                      "redirectToIntent": "intent.account.linking",
                      "suggestions": false
                    }
                  },
                  {
                    "name": "user_type_multimsisdn_not_allowed",
                    "type": "user_type_filter",
                    "conditions": "/type eq 'multimsisdn'",
                    "true": {
                      "name": "user_type_not_allowed_action_true",
                      "breakDialogExecution": true,
                      "breakFilterEval": true,
                      "resource": "context-filter:multimsisdn-users-intent-not-allowed.text",
                      "suggestions": false
                    }
                  },
...

Process Resources

Each library may contain a resources folder with images or any other binary files. If present, those files are uploaded to Azure container pointed by AURA_SERVICE_ENVIRONMENT env var, within libraries/<library> virtual path.

This uploading process could last longer than the other make-up steps, so the process could throw errors after showing that the make-up process is finished (with pending uploading processes).

The following snippet shows how to use those files within the dialogs (it will take AURA_STATIC_RESOURCE_ENDPOINT and AURA_STATIC_RESOURCE_SAS_TOKEN env vars from the environment):

import * as libraryUtil from '@telefonica/aura-bot-library-util';
(...)
const wholeUrl = getResourcePath('my_library', 'icon.png');

If we need to retrieve an image with specific device resolution as coming in the imageSettings resolution field of activity channelData, we should use getImageUrl method as follows:

import { getImageUrl } from '@telefonica/aura-bot-library-util';
[...]
const wholeUrlWithResolution = getImageUrl(stepContext.context, 'my_library', 'icon.png', configuration);

In libraries, the resources path must be exposed in the resources property when registering the plugin. This will be done within the file index.ts, as shown in the following example:

register(null, {
    my_library: {
        resources: path.resolve(__dirname, '..', 'resources'),
        (...)
    }
});

In the aura-bot make-up process the resources of each external library are uploaded to Azure Storage so that they can be later consumed by them. Remote path: [AURA-STORAGE]/static-resources/libraries/[LIBRARY_NAME].

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot metrics

List of metrics available in Aura Bot

http_request_duration_seconds

This metric is intended to store the information related to all the incoming HTTP requests received by aura-bot.

It is stored as a Summary in Prometheus. So every sample, besides the defined labels, also includes its duration.

It measures the duration since the request lands in aura-bot until its HTTP response is returned, indicating to the client that Aura is processing the request to obtain a proper answer for the user.

The metric allows measuring the behavior of the requests from any given endpoint:

The number of requests during a time
The average/min/max duration of these requests

Labels:

method: HTTP method used by the request being stored (GET, POST, PUT, DELETE, etc.)
host: host and domain where the request is being sent
path: specific endpoint of the request
status_code: HTTP status code returned in the response

This metric was stored since Iron Maiden (7.2.0) release.

outgoing_request_duration_seconds

This metric is intended to store the information related to all the outgoing HTTP requests made by aura-bot.

It is stored as a Summary in Prometheus so every sample, besides the defined labels, also includes its duration.

This metric allows measuring the behavior of the requests to any given endpoint:

The number of requests during a time
The average/min/max duration of these requests

Labels:

method: HTTP method used by the request being stored (GET, POST, PUT, DELETE, etc.)
host: host and domain where the request is being sent
path: specific endpoint of the request
status: HTTP status code returned in the response

This metric was stored since Camela (5.0.0) release.

outgoing_message_duration_seconds

This metric is intended to store the number of Direct Line requests arriving to aura-bot.

It is stored as a Summary in Prometheus, so every sample, besides the defined labels, also includes its duration.

As aura-bot is an asynchronous server, the processing of a request does not end when the HTTP response is returned, but when the proper answer for the user is sent back to the client callback. This metric measures the duration since the request lands in aura-bot until the last message of its answer is sent to the client callback.

Labels:

path: specific endpoint of the request.
httpStatus: HTTP status code returned in the response.
originStatus: status sent by Direct Line in the body of the response in the happening of an error.
origin: specific host of the request.
channel: channel of the request.

This metric was stored since Iron Maiden (7.2.0) release.

aura_component_version

This metric is intended to store the number of aura-bot instances (pods) running each version of the code. It is stored as a Gauge in Prometheus.

Labels:

version: version field in the package.json file included in the running docker container.
component: name of the component that is writing the metric.

This metric was stored since Camela (5.0.0) release with the name of bot_version and updated to aura_component_version in Iron Maiden (7.2.0).

bot_request_version

This metric is intended to store the number of incoming requests to aura-bot depending on their channelData.version. It is stored as a Counter in Prometheus.

Labels:

version: channelData.version in the incoming request. If the incoming request has no version field, 1 will be set.

This metric was stored since Iron Maiden (7.2.0) release.

aura_server_unhandled_error

This metric is intended to store the number of unhandled errors happening in aura-bridge.

It is stored as a Counter in Prometheus.

Labels:

error: exception message that forced the unhandled error.

This metric was stored since Iron Maiden (7.2.0) release.

aura_token_generate

This metric is intended to store the information related to Kernel accessToken refreshments in aura-bridge. It is intended to make it possible to set an alarm in the happening of any error during refresh of the 2-legged accessToken needed to access Kernel WhatsApp APIs.

It is stored as a Summary.

Labels:

path: specific endpoint of the request.
httpStatus: HTTP status returned by Kernel in the response.
originStatus: status sent by Kernel in the body of the response in the happening of an error.
origin: channelId of the channel that needs the accessToken in Aura.
channel: channel of the request.

This metric was stored since Iron Maiden (7.2.0) release.

services_status

This metric is intended to store the number of success or errored checks of modules of the server. It is stored as a Counter in Prometheus.

Labels:

moduleId: Id of the module.
status: OK or ERROR

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Command recognizer middleware

Description of aura-command-recognizer-middleware, in charge of identifying Aura commands.

Introduction

aura-command-recognizer-middleware checks the auraCommand property inside an activity.

This component is able to identify the so-called auraCommands, recognizing the user’s intent and associated entities from the messages reaching an aura-bot instance.

By default, it is the recognizer with more priority. The score for the intent is always 1.0.

The source code of this recognizer is included in Aura Bot Platform recognizers - Github repository.

An example is shown below:

Incoming activity with an auraCommand

{
  "activity": {
    "channelData": {
      "auraCommand": {
        "type": "suggestion",
        "value": {
          "intent": "intent.usage.check",
          "entities":[{
            "type": "measure",
            "entity" : "megabytes"
          }]
        }
      }
    }
  }
}

Recognizer Result

{
  "text": "check data usage",
  "intents": 
    "intent.usage.check": {
      "score": 1.0
    }
  },
  "entities": [
    {
      "type": "measure",
      "entity": "megabytes"
    }
  ]
}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

aura-bot-library-util utility

aura-bot-library-util utility contains different utility files for aura-bot libraries

Introduction

aura-bot-library-util utility is an NPM library with utility functions provided by the Aura Bot Global Team to make it easier the development of dialogs in aura-bot.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-bot-utilities/src/aura-bot-library-util/

This library only contains utilities used in the dialogs, not needed by the bot itself.

To use it, just define the dependency with @telefonica/aura-bot-library-util in your package.json file. It is published as a private library in NPM, so request a valid NPM token to access it.

The utility files included in aura-bot-library-util utility are described in the following sections.

CurrencyUtils

aura-bot-library-util/currency-util.ts

getLocalizedCurrency

It returns money amounts formatted with country specific settings.

param	type	description	mandatory
locale	string	Country locale code	yes
amount	number	Total amount to be formatted	yes
currency	string	Country currency code	yes


    const amount: string = getLocalizedCurrency('es-es', 460.56, 'EUR');

    /* 460.56 € */

    const amount: string = getLocalizedCurrency('es-uy', 460.56, 'UYU');

    /* $ 461 */

Datautils

aura-bot-library-util/data-unit-util.ts

getDataAndUnit

It returns converted internet data amount and unit from bytes quantity, following the country specific settings.

param	type	description	mandatory
content	TurnContext	Step context	yes
configuration	Configuration	Dialog config variables	yes
data	number	Data amount	yes
forcePoint	boolean	It indicates if the decimals will be separated by points	no


    const [dataQt, dataUnit] = getDataAndUnit(context, config, 1536)
    const [dataQt, dataUnit] = getDataAndUnit(context, config, 1536, true)

    /*
     * Result depending on AURA_DEFAULT_LOCALE env var
     * pt-br - ['1,5', 'GB']
     * en-gb - ['1.50', 'GB']
    */

LocaleUtils

aura-bot-library-util/locale-util.ts

getLiteral

This intermediate method generates a getText function ready to receive resources keys and sequential params.

param	type	description	mandatory
context	TurnContext	step context	yes
library	string	libraryName	no


    /* If we need to convert only one text in function scope, we can use it as one line function */

    const text: string = getLiteral(context, 'services')('services.find.moreinfo', param1, param2);
    const text: string = getLiteral(context)('services:services.find.moreinfo', param1, param2);

    /* When we need to convert several texts in function scope for the same library,
    we can preassign result function to variable and proceed all along dialog step */

    const getServicesText: Function = getLiteral(context, 'services');

    const text: string = getServicesText('services.find.moreinfo', param1, param2);

    /* if we need to convert several texts in function scope for several libraries */

    const getText: Function = getLiteral(context);

    const text: string = getText('services:services.find.moreinfo', param1, param2);
    const errorText: string = getText('errors:error.notFound');

getTextByKeys

Factory function used mainly in graphs to retrieve converted text objects, avoiding redundancy.

param	type	description	mandatory
context	TurnContext	step context	yes
libraryName	string	libraryName	yes


    const getGraphText: Function = getTextByKeys(context, 'graphics');

    const texts: any = getGraphTexts(['of', 'remaining'], { unit: 'data.gb' })

    /* Output
        {
            of: 'graphics:of', // converted text,
            remaining: 'graphics:remaining', // converted text,
            unit: graphics:data.gb, // converted text
        }
    */

withLocale

It encapsulates all data we need to call LocaleManager instance getText method.

param	type	description	mandatory
context	TurnContext	step context	yes
fn	Function	function to be executed at the end	yes
library	string	libraryName	no

For instance, getLiteral function passes an inline arrow function to simply receive the params that the result function was invoked with:


    /**
     * handy method to retrieve text.
     *
     * @param  {TurnContext} context The dialog step context.
     * @param  {string} libraryName? Library name.
     */
    export function getLiteral(context: TurnContext, libraryName?: string) {
        return withLocale(
            context,
            ({ getText, library }: any, literal: string, ...args: any[]) => getText(`${library ? library + ':' : ''}${literal}`, args),
            libraryName
        );
    }

This way, we can compose any method that fits our dialog text composition specific needs. A trivial working code sample could be:


    const _getText: Function = withLocale(stepContext.context, intermediateFunc)

    function intermediateFunc({ getText }, obj: any, params: string[], isError?: boolean) {
        const finalTextKey: string = isError ? obj.error : obj.text;
        return getText(finalTextKey, params);
    }

    const obj = {
        text: 'services:services.some.text',
        error: 'errors:error.message.error'
    }

    const text: string = _getText(obj, ['first', 'second']);
    const errorText: string = _getText(obj, [], true);

getErrorMessage

It composes a full error message with fallback text when required.

param	type	description	mandatory
context	TurnContext	step context	yes
statusCode	number	request code, if existing	nullable
objErr	StatusCodeMessagesMap	Custom error messages	no

    export interface StatusCodeMessagesMap {
        default: string;
        code400?: string;
        code404?: string;
    }
    try {
        //Do stuff
    } catch (error) {
        const messageMap: StatusCodeMessageMap = {
            default: 'services:services.custom.error',
            code400: 'services:services.error.badRequest',
            code404: 'services:services.error.notFound'
        }

        const errorMessage: string = getErrorMessage(stepContext.context, error.code, messageMap)
    }

sendLoggerErrorAndActivity

It sends full logged error message activity.

param	type	description	mandatory
context	TurnContext	step context	yes
logger	any	log function	yes
objErr	StatusCodeMessagesMap	Custom error messages	yes
dialogId	string	Current dialog ID	yes
error	any	error to print	yes

    try {
        /* [...] */
    }  catch (error ) {

        const messageMap: StatusCodeMessageMap = {
            default: 'services:services.custom.error',
            code400: 'services:services.error.badRequest',
            code404: 'services:services.error.notFound'
        }


        sendLoggerErrorAndActivity(
            context,
            this.logger,
            messageMap,
            ServicesFindDialog.id,
            error
        )
    }

LibraryUtil

aura-bot-library-util/library-util.ts

excludeDialogs

It excludes dialogs provided in an array.

param	type	description	mandatory
dialogNames	string[]	Array with dialog’s ids	yes
options	any	Options to customize function behavior	yes

excludeDialogs(dialogNames: string[], options: any);

readLocaleFolder

Ir returns an object with locale name as key and file content as value.

param	type	description	mandatory
localePath	string	`localePath` Base path where locale files are looked for	yes

readLocaleFolder(localePath: string);

readEnv

It returns an object with env variables from current environment.

param	type	description	mandatory
configuration	any	Object with configuration information	yes
envPath	string	Path pointing to environment configuration	yes

readEnv(configuration: any, envPath: string);

readDialogConfig

It returns an object with dialog config from current environment.

param	type	description	mandatory
configuration	any	Object with configuration information	yes
configPath	string	Path pointing to dialog configuration	yes

readDialogConfig(configuration: any, configPath: string);

replaceToDialogByIntent

Given an intent, it replaces the current dialog by the intent that matches with it. This method triggers the main dialog and keeps the context-filter functionality in the replaced one.

param	type	description	mandatory
stepContext	WaterfallStepContext	step context	yes
intent	string	intent which the dialog will be triggered	yes

await replaceToDialogByIntent(stepContext: WaterfallStepContext, intent: string);

generateSasUrl

It generates and returns the URL of the blob resource, applying expiration.

param	type	description	mandatory
fileName	string	Blob file name	yes
remoteContainerPath	string	Full container’s path	yes
expiration	number	Expiration time in minutes	no
configuration	Configuration	Environment configuration	yes
correlator	string	Correlator	no

await generateSasUrl(fileName: string, remoteContainerPath: string,
    configuration: Configuration, corr?: string, expiration?: number);

uploadFileUrl

It uploads a file to Azure Storage from an URL.

param	type	description	mandatory
sourceUrlFile	string	URL that contains the file	yes
remoteFilePath	string	Blob remote path	yes
configuration	Configuration	Environment configuration	yes
correlator	string	Correlator	no
containerName	string	Storage container name	no

await uploadFileUrl(sourceUrlFile: string, remoteFilePath: string,
    configuration: Configuration, corr?: string, containerName?: string) ;

ResourcesUtils

aura-bot-library-util/resources-util.ts

getImageUrl

It intercalates supported resolution folder path into image path, following channel image resolution settings.

param	type	description	mandatory
context	TurnContext	step context	yes
libraryName	string	Library proper name	yes
url	string	Full path of the image default version in the library root folder	yes
configuration	Configuration	Env variables	yes

    // Current supported resolutions.
    enum SupportedResolutions {
        HDPI = 'hdpi',
        XHDPI = 'xhdpi',
        XXHDPI = 'xxhdpi',
        XXXHDPI = 'xxxhdpi'
    }

    // Taking channelData imageSettings resolution == xxxhdpi

    getImageUrl(context, 'services', 'images/default/imageName.png', configuration);

    // https://<storageUrl>/libraries/services/images/xxxhdpi/imageName.png?<params>

getResourcePath

It gets the whole resource path uploaded to blob-storage, that is accessible, to be included in cards.

param	type	description	mandatory
configuration	any	Env variables	yes
libraryName	string	Library proper name	yes
baseFilePath	string	Base file access path	yes

const uri: string = DialogUtils.getResourcePath('generic', resource, this.configuration);

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

auraCommand model

Description of the auraCommand model suitable for sending intents directly to Aura with no recognition stage

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.

Property	Type	Description
auraCommand	AuraCommand	This property contains an `auraCommand` object.

AuraCommand Model

Property	Type	Description
type	string	`AuraCommand` type: suggestion: used to send a common intent. The prefix of the intent must be `intent.`. Its the type by default. operation: It represents an intent that needs a context in Aura. The prefix of the intent must be `operation`. notification: It represents an intent generated by notification. The prefix must be `intent`. text: The value of the `auraCommand` contains directly a `string` with the text to be recognized by NLP. event: The value of the AuraCommand contains and event that aura-bot recognizes to carry out an action.
value	Intent model or string	Object intent or text.
utm	Utm model	Source that contains the AuraCommand.
actions	Action model	Array of actions.

Intent model

Property	Type	Description
intent	string	Name of the intent. If this name does not contain the prefix `intent.`, Aura will add the it.
entities	Entity model	Array with the entities. This array can be empty.

Entity model

Property	Type	Description
type	string	Name of the intent. If this name does not contain the prefix `intent.`, Aura will add it.
entity	string	Name of the entity. If this name does not contain the prefix `ent.` Aura will add it.
canon	string
score	float	Array with the entities. This array can be empty.

Utm model

Property	Type	Description
source	string	It identifies which site sent the traffic. In Aura, use the channel name.
medium	string	It identifies what type of link was used, such as cost per click or email. In Aura, use banner, button, etc.
campaign	string	It identifies a specific product, promotion or strategic campaign.
term	string	It identifies search terms.
content	string	It identifies what was specifically clicked to bring the user to the site, such as a banner ad or a text link.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Batch messages response format

Description of batch messages response format

Introduction

aura-bot has two working modes for sending messages: immediate mode and batch mode, than can be selected by channel configuration.

We can configure aura-bot in immediate or batch mode by channel, in the responseOptions.versions.vX.batchMessages property, where:

vX: channelData version (v3 for channelData 3.0.0).

Configuring it this way, we are able to send batch messages only in certain channels.

Immediate mode

In immediate mode, when a message is sent by a dialog or middleware, it is sent directly to the user (after executing the outgoing middlewares), without delays.

Batch mode

In batch mode, aura-bot intercepts and stores all the sending messages (after being processed by the outgoing middlewares), and sends them all at once on turn end.

When using batch mode and all the messages are gathered from the bot message queue and processed together to assure that the inputHint is correct in all of them, then the behavior is as follows: All but the last message is set to ignoringInput, as the specification says, and the last message maintains the status set by the dialog or, if it has not been defined (undefined), is set to acceptingInput. Note that if a dialog sends a prompt, it is its responsibility to send the proper inputHint, in this case expectingInput.

The activities array may contain messages for multiple channels, we can use the method filterByConversationId that returns activities classified by conversationId. This classification allows setting the inputHint correctly for each channel.

The legacy hasMoreMessages flag in channelData is also set when batch processing the messages, but this flag will disappear in near future.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Guidelines for building an Aura Bot library

Orderly steps for building a library in Aura Bot when developing a use case

Introduction

The customization of aura-bot is done through libraries: libraries in aura-bot are node.js packages, with a particular structure of folders and files that contain one or several dialogs, plus i18n strings, environment variables, configuration files and graphical resources. Libraries are deployed in the bot as plugins.

Within these libraries’ structure, developers are able to build extensions over aura-bot global components (dialogs) to be deployed in concrete scenarios where customized capabilities and functionalities are required, such as the development of a new use case.

The following sections include the detailed steps for building or modifying a library over aura-bot.

Build an Aura Bot library

When developing a local use case in Aura, you should:

✅ For local use cases generated from scratch: develop a new use case library
✅ For local use cases based on the customization of a global use case: modify existing use case library

We can have one or several libraries in one repository:

If the repository only contains one library, the root/ folder can be used. In this case, the folders of the library can be created directly from the root/ folder.
For example, for the src/ folder: [repository_name]/src
If the repository contains more than one library, a folder hierarchy is required. The working directory is:
For example, for the src/ folder: [repository_name]/[library name]/src

# Optional, only with multiple libraries in same repository (replace newlibrary with library name)
$ mkdir -p packages/newlibrary
$ cd packages/newlibrary
# Creates the src folder and move the dialog files inside
$ mkdir src

⚠️ The names of Aura global libraries are reserved. Therefore, both for the creation of a new local library or a customization of a global one, constructors must use a different name in order to avoid overlapping. We recommend to use the following structure for local libraries’ names: [local_library_name]-[OB]

⚠️ The library name must be exactly the same in all its associated files.

At this stage, you should build the structure of your library repository, with all the required folders and files.

📌Practical tip
Use a global library as template, copy it and edit the corresponding folders and files for your use case.
You can use: https://github.com/Telefonica/aura-bot-libraries/tree/master/packages/bill. This library will be used as an example throughout the document.

The recommended order is detailed below:

Copy in the root of the library the generic required files as identical copies: .gitignore, .npmignore, tsconfig.json and tslint.json.
Create a package.json containing a plugin block with the name of the service this plugin will provide.
ℹ️ Detailed guidelines: Section package.json
A README.md file will be also desirable, explaining the library.
Create one file within src/ folder for each dialog (parts common to several dialogs could share utility clases, as usual).
ℹ️ Detailed guidelines: Use case dialogs Now, copy here your dialog or code the it as explained in General guidelines for building an Aura Bot dialog.
Create an index.ts file, that will register all the dialogs when loading the plugin.
ℹ️ Detailed guidelines: index.ts

After publishing or npm linking the package (or npm packing), this plugin could be loaded from aura-bot by declaring the package name in the plugin configuration array. Additionally, any of the dialogs could be excluded from the load. A simple plugin configuration file could be:

[
    "@telefonica/aura-bot-bill-library",
    "@telefonica/aura-bot-common-library",
    {
        "packagePath": "@telefonica/aura-bot-other-library",
        "exclude": [
            "./first-dialog"
        ]
    }
]

Note that the object format (with packagePath) is optional. When no options are passed to the plugin, we could just use a string with the name of the package. When there are more options (like exclude array), the object format must be used. So, these two configuration files are equivalent:

[
    "@telefonica/aura-bot-bill-library",
    "@telefonica/aura-bot-common-library"
]

and

[
    {
        "packagePath": "@telefonica/aura-bot-bill-library"
    },
    {
        "packagePath": "@telefonica/aura-bot-common-library"
    }
]

Aura bot libraries repository

A library in aura-bot must contain a fixed structure of folders and files, both mandatory or optional.

These elements can differ for different environments, deploys or channels.

Folder / Files	Content
src/	- `<dialog-name>.ts` files: Files containing the dialogs logic - `index.ts` file: Registration of dialogs in the library. Declaration of locale, config and `.env` files of the library. - `configuration-schema.ts`: schema for library-specific configuration variables - Unit tests for each dialog: `<dialog-name>.spec.ts`
settings/	- `locale` folder: Definition of text resources for Aura response - `dialog-config.json`: Mapping of intents with dialogs within the library; definition of context filters - `.env` files: Definition of environment variables associated with the library
resources/	Optional folder including files for composing Aura response
package.json	File that contains a plugin block with the name of the service this plugin provides
package-lock.json	File including the versioning control Do not modify it
Other files	`.gitignore`, `.npmignore`, `tsconfig.json` and `tslint.json` Copy them in the root library as identical copies and do not modify them
Readme.md	Optional file with information regarding the library

src/ folder

Working directory: [repository_name]/src/ or [repository_name]/[library name]/src/
This folder must contain three different types of files:

src/ content	Mandatory/Optional
File(s) containing the use case dialog(s): `<dialog-name>.ts`	Mandatory
`index.ts` file	Mandatory
`configuration-schema.ts`	Optional

📌Practical tip Check the src/ folder in our global library: https://github.com/Telefonica/aura-bot-libraries/tree/master/packages/bill/src

Use case dialogs

Dialogs are .ts files containing the dialog logic. Bot developers must generate the associated dialog(s) for their use case following the guidelines defined in General guidelines for building an Aura Bot dialog.

Afterwards, remember that all the developed dialogs must be tested.

index.ts file

index.ts file registers all the dialogs in the library.

Once the use case dialog is developed, edit this file with the corresponding values for each field explained below:

let dialogNames: names of all the dialogs included in the library.
register:
- <libraryName>: library name.
- dialogs: it points to the dialogs declared in let dialogNames.
- locale: the locale files must be exposed in the locale property when registering the plugin in order to be merged (during the make-up process).
- env: the .env files must be exposed in the env property when registering the plugin in order to be merged (during the make-up process).
- config: the config files must be exposed in the config property when registering the plugin in order to be merged (during the make-up process).
- configSchema: declaration of specific variables for the use case included in the configuration-schema.ts file.
- resources: it indicates the path (__dirname) where the resources folder, containing the resources used in the use case, is included: resources: path.resolve(__dirname, '..', 'resources')

A complete example can be found below for the library generic:

  import * as path from 'path';
import * as libraryUtil from '@telefonica/aura-bot-utilities/lib/aura-bot-library-util';
import configurationSchema from './configuration-schema';


export = function setup(options: any, imports: any, register: (err: Error, result: any) => void) {
    let dialogNames = [
        './generic-dialog'
    ];
    // If there is an array of dialogs to disable, remove from dialog array
    libraryUtil.excludeDialogs(dialogNames, options);
    // Register that this plugin has been fully loaded
    const settingsPath = path.resolve(__dirname, '..', 'settings');
    register(null, { resources: path.resolve(__dirname, '..', 'resources')
        generic: {
            dialogs: dialogNames.map(dialogName => require(dialogName)),
            locale: libraryUtil.readLocaleFolder(path.resolve(settingsPath, 'locale')),
            env: libraryUtil.readEnv(settingsPath),
            config: libraryUtil.readDialogConfig(settingsPath),
            configSchema: configurationSchema,
            resources: path.resolve(__dirname, '..', 'resources')
        }
    });
};

configuration-schema.ts

Optional file for the validation of schemas from the library-specific configuration variables required for the use case. When the bot loads all the plugins, it verifies that the schemas provided by the library fulfil the conditions established in the current file.

The orderly process for editing this file is defined below:

Declare the library-specific configuration variables in the .env configuration file starting with the library name: [library_name]_[variable_name]. This file includes the values of these variables.
For these variables, include in the configuration-schema.ts restrictions, default values, checking, etc. in order to validate them. During the during the make-up process, the content of the different configuration-schema.ts files for each library will be automatically uploaded into a .env.libraries file.

You can create a schema (using @hapi/joi) and specify the name of the library-specific variable as shown in the following example:

import joi from 'joi';

const configurationSchema = {
    LIBRARYNAME_DEFAULT_GREETINGS: joi.string().default('hello'),
    LIBRARYNAME_COMMON_COUNT_GREETINGS: joi.number().default(1800)
};

export default configurationSchema;

settings/ folder

Working directory: [repository_name]/src/ or [repository_name]/[library name]/src/
This folder must contain three different types of files:

settings/ content	Mandatory/Optional
`locale`folder	Optional
`dialog-config.json` file	Mandatory
`.env`configuration files	Optional

📌Practical tip Check the settings/ folder in our global library: https://github.com/Telefonica/aura-bot-libraries/tree/master/packages/bill/settings

locale/ folder

Each library may contain (optionally) a settings/locale folder, with one or more locale files with the format: settings/locale/dialog-config.<culture_code>.json

The content of this file corresponds to the text resources, both from aura-bot core or text of Aura response for a specific use case. This content can be generated using POEditor, which handles the different messages that the bot shows to the customer and to adapt them to a specific language.

Find detailed information for the generation of texts included in Aura response in Build Aura response: POEditor texts.

⚠️ These files must be generated during the building up of a dialog, as they must be included in the unit tests for the dialogs.

An example of this file is shown below:

[
  "common:common.goodbyes.main": [
        "See you soon.",
        "See you soon."
    ],
    "common:common.greetings.main": [
        "Hello. How can I help?"
    ],
    "common:common.thankyous.main": [
        "Happy to help",
        "Happy to help."
    ]
}

dialog-config.json

dialog-config.json is a mandatory file that maps each intent with a dialog from the library. Therefore, the dialog is launched if the intent is recognized. Moreover, the file defines the suitability of the use case and allows the definition of context filters.

Each library must contain a dialog-config.json file that can be general or defined per language and OB. This general configuration could be merged (with higher priority) with a specific file per language and OB: dialog-config.<AURA_DEFAULT_LOCALE>.json where AURA_DEFAULT_LOCALE contains the culture code to be used by default in the current deployment: en-gb, es-es, etc.

The dialog-config.json file follows the DialogLibrary model, excepting for the field onlyIn which is described below.

onlyIn property

The OnlyIn field is an optional field that indicates to which channels the dialog will be added. If it is not present, it means that the dialog will be added to all the channels of the environment. Configure it, if required, including an array of channels names.

contextFilters

A contextFilter allows to configure the behavior of a dialog depending on the fulfilment of specific conditions. You can define contextFilters in the dialog-config.json file for a specific intent.

Currently, the conditions that can be established correspond to the user’s subscription type (for example, prepaid or postpaid) and the type of contract (monomsisdn or multimsisdn). Depending on the fulfilment of the established condition (true or false), the behavior of the dialog is different.

For including contextFilters, edit the fields included in the ContextFilter model.

An example is shown below with authorization at library level, only a dialog, without contextFilters, that is returned without suggestions and that applies to all channels.

  {
 "name": "handover",
  "authorization": {
    "purposes": "customer-self-service",
    "scopes": "subscribed-products-user-read"
  },
  "dialogs": [
    {
      "id": "handover",
      "suggestions": false,
      "triggerConditions": [
        {
          "intent": "intent.common.handover"
        }
      ]
    }
  ]
}

The following example includes authorization at library level, only a dialog, without contextFilters, that is returned without suggestions and that applies only to Novum and Movistar Home.

 {
 "name": "handover",
  "authorization": {
    "purposes": "customer-self-service",
    "scopes": "subscribed-products-user-read"
  },
  "dialogs": [
    {
      "id": "handover",
      "suggestions": false,
      "triggerConditions": [
        {
          "intent": "intent.common.handover"
        }
      ],
     "onlyIn": ["novum-mytelco"]
    }
  ]
}

The third example includes contextFilters:

  "dialogs": [
             {
               "intent": "intent.billing.check",
               "contextFilters": [
                  {
                      "name": "subscrition_type_prepaid_invoice",
                      "type": "subscrition_type_filter",
                      "conditions": "/authData/subscriptionType eq 'prepaid'",
                      "true": {
                          "name": "subscription_type_prepaid_invoice_true",
                          "breakDialogExecution": true,
                          "breakFilterEval": false,
                          "resource": "bill:bill.check.prepaid",
                          "suggestions": true
                    }

NOTE: All intents of the same dialog must be defined together for each channel. Like:

  {
    "name": "mocks",
    "dialogs": [
        {
            "id": "mocksv3-dialog",
            "channelDataVersion": "v3",
            "triggerConditions": [
                {
                    "intent": "intent.tv.display"
                }
            ],
            "onlyIn": [
                "set-top-box"
            ]
        },
        {
            "id": "mocksv3-dialog",
            "channelDataVersion": "v3",
            "triggerConditions": [
                {
                    "intent": "intent.tv.search"
                },
                {
                    "intent": "intent.tv.display"
                }
            ],
            "onlyIn": [
                "movistar-plus"
            ]
        }
    ]
}

.env configuration files

When developing a use case, you must include in this file the values for the library-specific configuration variables required for the use case. These variables must be formatted as follows: [library_name]_[variable_name].

There can be multiple .env files corresponding to different libraries, environments, etc. All of them are automatically uploaded into a .env.libraries file during the make-up process.

A simple example of .env variables is shown below:

MYLIBRARY_VERSION=1.2.3
MYLIBRARY_ENDPOINT=https://my-library.test/v1

resources/ folder

The resource folder is optional and, if existing, is placed on the directory: [repository_name]/resources/ or [repository_name]/[library name]/resources/

It includes different folders with images or any other binary files (such as JSON files) required by the use case. Resources in this directory can be organized in different sub-folders: a default folder and locale folders for different culture codes.

📌Practical tip Check the resources/ folder in our global library: https://github.com/Telefonica/aura-bot-libraries/tree/master/packages/bill/resources

Declare in this folder the graphic resources of your use case, if existing. Inside each folder /images, if required, resources may be organized in sub-folders depending on the image resolution.

If existing, the files in the resources/ folder are uploaded to Azure container pointed by the AURA_STATIC_RESOURCE_ENDPOINT and the AURA_STATIC_RESOURCE_SAS_TOKEN environment variables, during the during the make-up process.

package.json file

The package.json is a mandatory file and is placed on the directory: [repository_name]/package.json or [repository_name]/[library name]/package.json

This file contains a plugin block, with the name of the service this plugin provides.

📌Practical tip Check the package.json file in our global library: https://github.com/Telefonica/aura-bot-libraries/blob/master/packages/bill/package.json

For including your use case, follow the structure shown below changing “newlibrary” with the name of your library:

"plugin": {
    "provides": [
        "newlibrary"
    ]
},

The package.json can contain different dependencies. Useful ones for libraries are:

@telefonica/aura-bot-utilities/lib/aura-bot-common: common library shared among aura-bot Platform and the corresponding library for global use cases.
@telefonica/aura-bot-utilities/lib/aura-bot-library-util: library with specific utilities for libraries, such as resource loading, currencies, etc.
@telefonica/aura-logging: recommended for Aura logs tracking.
botbuilder-dialogs: dialogs classes.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Build an Aura Bot dialog

This section includes different processes for building an Aura bot dialog when developing a local use case, both general guidelines and specific ones for concrete scenarios

Introduction

Dialogs are software components that model conversations with the final users by interchanging messages with them. Currently, aura-bot supports the Microsoft Bot Framework SDK v4 for JavaScript as the internal bot engine.

When developing a local use case, that can be both an experience built from scratch or inspired in a global use case, the OB developers must build a new local dialog that includes the logic of the use case or modify an existing one.

The dialog will interact with the customer using a conversational interface, this is, interchanging messages back and forth and, if required, the dialog will summon Kernel or third-party APIs in order to fetch data to fulfil the user’s request.

Before getting started, we recommend you to read some useful Microsoft documentation:
📄 Send and receive text message
📄 Dialogs library

Scenarios for building a dialog

Bot developers can find different scenarios when building a dialog over aura-bot:

Build an Aura Bot library that will contain the dialog, in case it does not exist.
General guidelines for building a dialog: most common scenario for building a dialog over aura-bot
Build a dialog that use async APIs, that is, APIs that do not provide the information back immediately, but with a certain standby time as they must perform a specific task derived from the user’s request.
Configure bypass mode to force sending any input message to aura-bot directly to a external service and vice versa.
Build an operation, which are a type of intents that can be used inside a dialog’s conversational flow.
Migrate a dialog to channelData v3, including the steps for making your use case compatible with channelData v3.
Migrate use cases to Bot Framework 4.19, which is the version used by Aura’s upcoming architecture based on Microsoft skills protocol.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Manage locales for canonical phrases of intents

The aim of this document is to describe how to manage locales to include canonical phrases in intents

Introduction

Intents must have a canonical phrase to be able to disambiguate among them.

For this purpose, it is required to include canonical phrases for CLU intents in POEditor, within a section named “intent” and upload them to aura-bot deployment.

Two scenarios can arise here, distinguishing between global use cases and local ones.

Global use cases

a. Generate the locales in POEditor:

Access the POEditor global project.
Look for the specific resource of the global use case intent, that will have the format: intent:[intent_name].
Edit the text of the specific resource for the global intent including the canonical phrase for this intent.

b. Upload the locales to aura-bot deployment

The “intent” section of the global POEditor project is imported into the bot deployment by the global library:
telefonica/aura-bot-library-disambiguation
If the intent is handled by a global dialog, it must be added in the locale-changes file to be deployed after every local deployment. It must also be notified to the Global Team to add it to the global POEditor, so it can be included in the succeeding aura-bot release.

Local use cases

For local use cases (intents handled by a local dialog), OBs should include resources for the all the intents’ canonical phrases. Aura Global recommends to use local POEditor, although this is not mandatory. The main request for those local resources is to be included in the library in a format compatible with the bot, as explained below.

a. Generate the locales in POEditor:

Access the POEditor local project
Create the specific resource with the mandatory format: intent:[intent_name].
For example, intent:intent.billing.check
Edit the text of the resource with the canonical phrase for this intent

b. Upload the locales to aura-bot deployment

To deploy these resources in the environment, it is required to upload them only from a library. Therefore, the ideal process would be either to use a library that is always deployed in the environment or to create an ad-hoc library to manage common processes and load into this library the section “intent” of the local POEditor project.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

channelData mapping

channelData mapping in Aura response

Introduction

Currently, Aura supports dialogs able to provide responses in v1, v2 and v3 channelData versions. These responses are mapped to be handled by the bot output middlewares as v3, but after that, dialogs are mapped again to the original response version to be returned to the client.

However, incoming middlewares are able to work with different request channelData versions v1, v2 and v3, indistinctly.

Request

The request is currently not transformed and is accessed using channelData utils from the aura-bot-common library.

These utils make transparent the access to all channelData properties needed in v1 or v3.

Response

The response returned by the dialog is normalized in the outgoingchannelDataNormalizer middleware, the first outgoing middleware executed after the dialog.

This normalization is done if the channelData version returned is lower than the current version.

The middleware calls ChannelDataResponseMapper.getResponseChannelData with:

The normalized version (currently, v3) as first parameter.
The channelData in the old version as second parameter.

This mapper function will return a normalized version of the channelData.

After all the middlewares are executed, in the adapter, the response should be transformed to the version returned by dialog again.

To do this, ChannelDataResponseMapper.getResponseChannelData is called again with:

The version originally returned by the dialog as first parameter.
The channelData as second parameter.
The original channelData returned by the dialog as third parameter. This third parameter is needed because in the conversion from old versions to the normalized version certain fields may disappear, so we need to merge the normalized channelData (maybe modified by the outgoing middlewares) with the original returned by the dialog.

Channels using a BotService adapter

Channels such as Facebook that use a BotService Adapter will always use a channelData without version, which internally is translated to v1.

This means that the request will have to be mapped for good. The major implication is that channelData version v3 must take into account the fields needed by these adapters, so the communication and the user’s experience are kept the same.

Currently, aura-bot is only validated to be accessed through the Facebook Messenger adapter. In this case, the protocol allows the exchange of HeroCards, but the way they are sent to the channel is a bit different than in Direct Line channels: they are sent as attachments of the channelData instead of attachments of the activity.

So, in order to allow Aura use cases to send buttons or a complete HeroCard to a user, the attachments field of the channelData must be kept during the version mapping.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot components

Description and role of the main Aura Bot components

aura-bot components can be categorized into three main groups for documentary purposes:

Aura Bot Platform components Components aura-bot has, as a BotFramework bot:

Aura Bot functional modules
Components that have been built over aura-bot to provide it with specific functionalities.

Aura Bot databases Databases used by aura-bot:

Aura Bot ActivityHandler

This is properly the core of the bot, i.e., the message dispatcher. aura-bot just extends the ActivityHandler provided by BotFramework to handle activities properly.

It overwrites the following events, that are executed just after all incoming middlewares finish:

onTurn: to update the states of the turn properly: conversationState, userState, userAuthState.
onMessage: to run the main dialog, just after states have been updated.
onDialog: it is executed after the whole main dialog ends and updates the states of the turn.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot conversational flow

Description of users’ authentication process in Aura Bot. Discover the different types of users and how they can authenticate in Aura.

Aura conversational process

Once the user’s authentication is validated, aura-bot starts the message processing.

Firstly, all incoming message middlewares are executed, in the order established in the bot set-up.
Then, recognizers come into play in order to recognize the user’s intention.
Depending on the type of input message, the process is different. For instance, aura-bot is able to recognize the user’s intent itself if the message is an auraCommand or requires summoning Aura Cognitive Services for this purpose.
Recognizers are executed sequentially and, after one of them recognizes an intention, the rest are not executed.
Once the intent and entities are identified, the next step is to route the message to the dialog in charge of that intent for the current channel. This step is done by the main dialog. This special and core dialog is responsible for:
- Getting the dialog that handles the recognized intent for the current channel. If it does not exist, an error is returned to the channel.
- Validating if the user’s context matches with the context filters configured in the selected dialog. If that is the case, then the context filter dialog is executed.
- Validating the authorization settings of the dialog to be executed with the AuraUser authentication model. In the case of Kernel authentication, it checks that the scopes and purposes of the user contain the mandatory ones to execute the dialog.
  This validation improves aura-bot performance, avoiding external requests to Kernel that will return a permissions error. If the user is anonymous, this step is not executed.
The specific dialog selected is started during one of the steps of the main dialog, and thus the execution is now managed directly by that specific dialog.
The dialog must get the information needed to provide a proper response to the user through Aura NLP, Complex Logic API or Kernel Telco APIs in order to generate the expected answer.
The response is now ready to be provided to the user and will start its way through the outgoing middlewares.
After that, the execution flow continues to the next step of the MainDialog, that is checking whether or not the dialog must include suggestions. To do so, it will check that the proper dialog settings are stored in the context. If suggestions are needed, the suggestions API will be called, the resulting activity will be prepared following the UX Guidelines.
In the end, a complete response consisting of several ordered activities will be provided to the channel, that will read them from Direct Line and the result will be rendered to the user.

Conversational process flowchart

The following flowchart schematically shows the components involved in the process.

Check here the complete Aura Bot conversational process flowchart.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

HTML5 custom tags

Custom tags generated to send commands to Aura

Introduction

Discover the different types of custom tags supported by Aura.

Find here general information regarding custom elements.

Aura action tags

The function of this set of tags is to encapsulate all the interactions within the HTML that is sent in the attachment. Any iteration that occurs within the HTML code must generate an event. In this way, the channel only has to manage the events that occur from these tags.

Capabilities:

Action tags define the type of event triggered:
- External as auracommand
- Internal as internal channel capability
- etc.
Action tags define the trigger to activate the action by voice.
Action tags define the targets of HTML elements that is associated to this action by an event.

Aura action: <aura-action>

This tag contains a collection of sub-tags in which the targets, triggers and events necessary to perform this action will be determined.

Property	Description
id	Optional identifier
name	Custom name of the action

Example:

<aura-action name="selectSeat">

</aura-action>

Aura action trigger: <aura-action-trigger> (Not implemented yet)

This tag is used to identify an action based on a voice message from the user.

Initially, are only two types:

Regex
Proximity

The recognition of the intention of this voice message may be associated with entities.

Property	Description
id	Optional identifier.
type	Recognizer type: `Regex`: A regular expression engine is executed to determine if the value of reg expression matches with the message of voice. This expression may contain groups to identify entities. `Proximity`: This type uses a proximity phrase comparison algorithm. Based on a minimum resemblance value (min-threshold), it will determine if the event will be triggered. You can include entities in the `entity` field.
value	Text to compare. If the type is `Regex`, this text must be a regular expression.
entity	It represents one o more entities to send to the event if the trigger is activated.
entity-field	In the case of a regular expression, it represents an entity calculated on the basis of the regular expression.

Examples:

    <aura-action-trigger type="regex" value="/select seat ([1-500])/" entity-field="$1">  </aura-action-trigger>
    <aura-action-trigger type="proximity" min-threshold="0.99" value="select seat 1C" entity="32">  </aura-action-trigger>

Aura action target: <aura-action-target>

It defines the targets of HTML elements that are associated to this action by an HTML event.

Property	Description
id	Optional identifier.
target	Pattern to determine the identifiers of the tags from the elements that compose the HTML. The format of the pattern is a querySelector syntax.
event	HTML event to which the action should be associated. For example: `click`
evalue	JSON Object to validate. The JSON object has the properties `field` and `value`. The evaluation returns `true` if the field contains the value. Example: `{"field":"checked", "value":true}`
mode	Modality of target element: `submit`, `single` or `multiple`. submit: this value indicates that the composition of the aura-event will be done after the event is launched. single: this value indicates that you only need to evaluate one element independently. multiple: this value indicates that the final composition depends on a set of elements.
entity-field	It represents a property in the target element to be used as entity.
voice-field	It represents a property in the target element to be used for dialogContext models. This value can contain multiple string fields separated by pipes (`\`, `
canon-field	It represents a property in the target element to be used as canon.
entity-type	It represents the type property of the entity model
entity-default	Used to set a entity by default when the command is build.
canon-default	Used to set a canon by default when the command is built.
voice-default	Used as an alternative for voice-field.

Aura action event: <aura-action-event>

It contains the event that will be generated if the action is activated. This event is associated with a data model that contains the information related to the event.

Property	Description
id	Optional identifier. Optional
type	Type of event generated if the action is launched. Values: `auraCommand`.
intent	Intent of the command.
command-type	Type of auraCommand. Values: `intent`, `operation` or `text`.
event-hook	Event to hook the result of the event. It is used to add an event listener to capture the event and result of an aura-action-event. Example: `aura-la-event`. Example of capture: `document.body.addEventListener("aura-la-event", customFunction, true)`.

Examples

To capture the events:

<script>
  /** To capture the event
  /* 1.- Add the listener
  **/
  document.body.addEventListener("seatSelected", customFunction, true);
  /* 2.- create the function to execute */
  function customFunction(e) {
    console.log(e.detail);
}
</script>

Single Button

<input type="button" id="b-1" data-seat="1A" value="Seat 1A" />
<input type="button" id="b-2" data-seat="1B" value="Seat 1B" />
<input type="button" id="b-3" data-seat="1C" value="Seat 1C" />
<input type="button" id="b-4" data-seat="1E" value="Seat 1E" />
<input type="button" id="b-5" data-seat="1F" value="Seat 1F" />
<!--Aura custom tags-->
<aura-action id="selectSingleButton">
   <aura-action-target target="[id^=b-]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Result if button with id=b-1 was clicked:

{
    "auraCommand": {
        "type": "operation",
        "value": {
            "intent": "operation.select.seat",
            "entities": [
                {
                    "entity": "1A",
                    "type": "seat",
                    "canon": "Seat 1A"
                }
            ]
        }
    }
}

Multiple button

<input type="button" id="bm-1" data-seat="1A" value="Seat 1A" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-2" data-seat="1B" value="Seat 1B" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-3" data-seat="1C" value="Seat 1C" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-4" data-seat="1D" value="Seat 1D" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-5" data-seat="1E" value="Seat 1E" class="unselected" onclick="switchStyle(this)" /> <br /> <br />
<input type="button" id="sbm" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectMultipleButton">
   <aura-action-target target="[id^=bm-]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='multiple'> </aura-action-target>
   <aura-action-target target="[id^=sbm]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Radio Button

<input type="radio" name="rbseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
<input type="radio" name="rbseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
<input type="radio" name="rbseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
<input type="radio" name="rbseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
<input type="radio" name="rbseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> <br />
<input type="button" id="srbseat" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectSimpleRadio">
   <aura-action-target target="[name^=rbseat]"  entity-field="value" canon-field="data-seat" entity-type="seat" mode='single'  evalue='{"field":"checked", "value":true}'> </aura-action-target>
   <aura-action-target target="[id^=srbseat]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Checkbox Button

<input type="checkbox" name="chkseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
<input type="checkbox" name="chkseat"  data-seat="1B" value="Seat 1B" />Seat 1B <br />
<input type="checkbox" name="chkseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
<input type="checkbox" name="chkseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
<input type="checkbox" name="chkseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> <br />
<input type="button" id="schkseat" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectByCheckboxMultiple">
   <aura-action-target target="[name^=chkseat]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='multiple'> </aura-action-target>
   <aura-action-target target="[id^=schkseat]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Result if the first and the last checkboxes were checked:


{
    "auraCommand": {
        "type": "operation",
        "value": {
            "intent": "operation.select.seat",
            "entities": [
                {
                    "entity": "1A",
                    "type": "seat",
                    "canon": "Seat 1A"
                },
                {
                    "entity": "1E",
                    "type": "seat",
                    "canon": "Seat 1E"
                }
            ]
        }
    }
}

Select Single

<select name="selectOpt">
   <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
   <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
   <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
   <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
   <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
</select>
<!--Aura tags-->
<aura-action id="selectSingleOption">
   <aura-action-target target="[id^=op-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat" mode='single' > </aura-action-target>
   <aura-action-target target="[name^=selectOpt]" event="change" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Select Multiple

<select name="selectOpt">
   <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
   <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
   <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
   <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
   <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
</select>
 <input type="button" id="smop" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectMultipleOption">
   <aura-action-target target="[id^=mop-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat" mode='multiple' > </aura-action-target>
   <aura-action-target target="[id^=smop]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Input Text

<input type="text" id="textSelect" />
<input type="button" id="textType" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectText">
   <aura-action-target target="[id^=textSelect]" entity-field="value" canon-field="value" evalue="" entity-type="seat" mode='single'> </aura-action-target>
   <aura-action-target target="[id^=textType]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

All In One

<body>
   <section>
      <input type="button" id="bm-1" data-seat="1A" value="Seat 1A" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-2" data-seat="1B" value="Seat 1B" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-3" data-seat="1C" value="Seat 1C" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-4" data-seat="1D" value="Seat 1D" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-5" data-seat="1E" value="Seat 1E" class="unselected" onclick="switchStyle(this)" />     
   </section>
   <section>
      <input type="radio" name="rbseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
      <input type="radio" name="rbseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
      <input type="radio" name="rbseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
      <input type="radio" name="rbseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
      <input type="radio" name="rbseat" data-seat="1E" value="Seat 1E" />Seat 1E <br />
   </section>
   <section>
      <input type="checkbox" name="chkseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
      <input type="checkbox" name="chkseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
      <input type="checkbox" name="chkseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
      <input type="checkbox" name="chkseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
      <input type="checkbox" name="chkseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> 
   </section>
   <section>
      <select name="selectOpt">
         <option value=""></option>
         <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
         <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
         <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
         <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
         <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
      </select>
   </section>
   <section>
      <select name="mselectOpt" multiple>
         <option id="mop-1" label="Seat 1A" value="1A">Seat 1A</option>
         <option id="mop-2" label="Seat 1B" value="1B">Seat 1B</option>
         <option id="mop-3" label="Seat 1C" value="1C">Seat 1C</option>
         <option id="mop-4" label="Seat 1D" value="1D">Seat 1D</option>
         <option id="mop-5" label="Seat 1E" value="1E">Seat 1E</option>
      </select>
      <br />
   </section>
   <section>
      <input type="text" id="textSelect" /> 
      <input type="button" id="textType" data-seat="send" value="Submit" />
   </section>
   <!--Aura tags-->
   <aura-action id="selectSeat">
      <aura-action-target target="[id^=bm-]" event="click" entity-field="data-seat" canon-field="value" entity-type="seat2" mode='multiple'> </aura-action-target>
      <aura-action-target target="[name^=rbseat]" entity-field="value" canon-field="data-seat" entity-type="seat3" mode='single' evalue='{"field":"checked", "value":true}'> </aura-action-target>
      <aura-action-target target="[name^=chkseat]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat4" mode='multiple'> </aura-action-target>
      <aura-action-target target="[id^=op-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat5" mode='single'> </aura-action-target>
      <aura-action-target target="[id^=mop-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat6" mode='multiple'> </aura-action-target>
      <aura-action-target target="[id^=textSelect]" entity-field="value" evalue="" canon-field="value" entity-type="seat7" mode='single'> </aura-action-target>
      <aura-action-target target="[id^=textType]" event="click"  mode='submit'> </aura-action-target>
      <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
   </aura-action>
</body>

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Template for Aura Bot dialogs testing

Template for testing an Aura Bot dialog

Template


import 'mocha';
import { TestAdapter, ConversationState, MemoryStorage, UserState } from 'botbuilder';
import { DialogTurnStatus, DialogSet } from 'botbuilder-dialogs';
import { AddBillDialog } from '../dialogs/collections/bill/add-bill';
import { AuraDataAccesor } from '../models';

describe('Dialog Test', function () {
    this.timeout(5000);
    /**
     * The dialog template test.
     */
    it('Bill dialog Test', (done) => {
        /**
         * Set the common data of Aura-Bot
         */
        const testData = setCommonData();
        /**
         * Uset TestAdapter to launch the bot framework
         */
        const adapter = new TestAdapter(async (turnContext) => {
            const dc = await dialogs.createContext(turnContext);
            const results = await dc.continueDialog();
            if (results.status === DialogTurnStatus.empty) {
                await dc.beginDialog('addBill');
            }
            await testData.conversationState.saveChanges(turnContext);
        });
        /**
         * Create the dialog set and add dialogs to test
         */
        const dialogs = new DialogSet(testData.auraDataAccesor.dialogState);
        dialogs.add(new AddBillDialog(testData.auraDataAccesor));
        /**
         * Make a flow with sends and assert responses
         */
        adapter.send('Hello')
            .assertReply('Dime algo bonito')
            .send('Algo bonito')
            .assertReply('Gracias por el piropo')
            .assertReply('Please enter your name. (1) Yes or (2) No')
            .send('claro')
            .assertReply('end Yes')
            .then(() => done())
            .catch((err) => done(err)); // <- send error to done
    });
});

/**
 * Common Data uses by the Aura Bot.
 */
function setCommonData() {
    const memoryStorage = new MemoryStorage();
    const conversationState = new ConversationState(memoryStorage);
    const auraDataAccesor: AuraDataAccesor = {
        conversationData: conversationState.createProperty('conversationData'),
        userData: new UserState(memoryStorage).createProperty('userData'),
        dialogState: conversationState.createProperty('DialogState')
    };
    return {
        auraDataAccesor,
        conversationState
    };

}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

External API clients

Description of external API clients used by Aura

Introduction

External API clients are associated with services external to Aura.

They are located inside the Github repository @telefonica/aura-clients, which is a Github private repository shared with Telefonica’s LCDO.

Kernel API clients

Aura contains different Kernel API clients for interacting with Telefónica Kernel products, which are described in the following sections.

You can access to the corresponding swaggers, per environment and country, here.

Find more information in the Github repository for the kernel-directsql-api-client: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/kernel-directsql-api-client/

Access Sessions client

Implementation of the Kernel Access Sessions API.

It provides a SingleAccessSessionApi class with all the models and methods implemented to handle Access Sessions API.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-bot-access-sessions-client/

Aura Bot Events client

Implementation of the Kernel Aura Bot Events API.

It provides an API class to handle AuraBotEvent, with all the models and methods implemented to be able to handle this API.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-bot-events-client/

Invoicing client

Implementation of the Kernel Invoicing API v2.

It provides a central class called InvoicingClient that makes it the very simple to interact with Telefónica Kernel Invoicing Service, passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/invoicing-client/

Mobile Balance client

Implementation of Kernel Mobile Balance API

It provides a couple of classes called BalanceClient and TopUpClient that makes it very simple to interact with Telefónica Kernel Mobile Balance Service, passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/mobile-balance-client

Mobile Quota client

Implementation of Kernel Mobile Quota API

It provides a central class called MobileQuotaClient that makes it the very simple to interact with Telefónica Kernel Mobile Quota Service, passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/mobile-quota-client

Smart Wifi client

Implementation of Kernel Smart Wifi API

It provides a central class called SmartWifiClient which makes it very simple to interact with Telefónica Kernel Smart Wifi Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/smart-wifi-client/

Subscribed Products client

Implementation of Kernel Subscribed Products API

It provides a central class called SubscribedProductsClient which makes it very simple to interact with Telefónica Kernel Subscribed Products Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/subscribed-products-client/

User Profile client

Implementation of the Kernel User Profile API

It provides a UserApi class with all models and methods needed to handle user profile requests.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/user-profile-client/

WhatsApp API client

Implementation of the Kernel WhatsApp API

It provides a WhatsApp API class with all models and methods needed to handle WhatsApp requests.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/whatsapp-api-client/

Genesys API client

The common call center solution in Telefonica OBs is a platform called Genesys.

The current client is an implementation of the Genesys API version 8.5.2, that is compatible with the call center platform of all the OBs. It is required in order to provide the internal handover to agent solution in Aura.

As Genesys API is not defined with OpenAPI, we have gathered all the methods and objects needed to handle Genesys requests and provide the API definition by our own.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/genesys-api-client/

Aura AI Service API client

Implementation of the aura-ai-services

It provides FeedbackApi, GenerativeApi, NlpaasApi classes with all the models and methods implemented to handle requests to aura-ai-services.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-aiservices/

Agents API client

Implementation of the agents-api

It provides DefaultApi class with all the models and methods implemented to handle requests to agents-api.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-aiservices/

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Install full Aura Bot

Guidelines for the installation and configuration of full Aura Bot

Introduction to full Aura Bot

This document details the steps to locally deploy a fully functional working aura-bot instance. By fully functional working instance, we mean a bot interacting with the Aura Cognitive services as well as with the Kernel APIs deployed as part of the desired environment the local aura-bot instance should interact with. 

Install Aura Bot

ℹ️ This is a general process suitable for every developer and environment.

The general process for the installation of an aura-bot instance is explained below.

Access to the main aura-bot repository:
https://github.com/Telefonica/aura-bot-platform
Clone the repository for the intended release branch, i.e., for Killers release:
git clone https://github.com/Telefonica/aura-bot-platform.git --branch release/killers
Get into the local repository root directory:
$ cd aura-bot-platform
Log in NPM to be able to download the private NPM package dependencies (request the token from the Aura Platform Team (APE) to properly log in). You can login with user/password or using the token:

User/password -> npm login
Token -> Add the token to the environment variables on your machine. Follow the guidelines for mac/linux.

Now configure your bot as explained in the section configure Aura Bot.
If required, install the existing local use cases (packaged as .tgz files)
There are two options:

a. Add the library .tgz file to the file plugin-config.json (placed in the aura-bot-platform Github repository).
Note that manual addition of libraries to plugin-config.json file requires manual installation too:
npm install <library>
b. Use the automatic script:
npm run import-libraries
This process will install any .tgz in aura-bot-platform/local_modules folder.
The previous command will add the library in package.json and plugin-config.json files and will install them into the project.
If a further configuration of the library is required (for example, disabling some dialogs), this must be done manually by editing plugin-config.json available at the root of the aura-bot-platform folder.

Practical example for working with full Aura Bot

The current section includes a practical example of the process for a specific environment (for example, applied to MacOS, Visual Studio, access to the kubernetes cluster, etc.). Therefore, the steps explained below may slightly differ from the general guidelines, but provide a useful practical approach for developers.

Dependencies

The following tools and artifacts are needed:

NodeJS version 14 You can download it here and install it via package manager.
ngrok
The executable binary can be downloaded for several systems in ngrok. Alternatively, ngrok can be installed via the NPM package, once NodeJS is installed, with the following command:
```
    npm install -g ngrok
```
Personal Kubernetes configuration file
Your local DevOps or Development Team will provide you with it. In this case, this file looks like this (the certificate and key data have been modified for security reasons):

    apiVersion: v1

    clusters:

        cluster:

            certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUV5RENDQXJDZ0F3S

            server: https://aura-auradev-1-14-6.westeurope.cloudapp.azure.com

            name: aura-auradev-1-14-6

    contexts:

        context:

            cluster: aura-auradev-1-14-6

            user: german.torodelvalle-1573743046

            name: aura-auradev-1-14-6

        current-context: aura-auradev-1-14-6

            kind: Config

            preferences: {}

    users:

        name: user-1573743046

        user:

            client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVHRENDQWdDZ0F3SUJB

            client-key-data: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdTR4

A bot service deployed in the Microsoft Azure portal (https://portal.azure.com) enabling the Direct Line channel to be able to interact with the bot from any client using Direct Line.
Visual Studio Code (https://code.visualstudio.com) to be able to debug the running instance of the Aura Bot locally.

Procedure for working with full Aura Bot

To install a working fully operational local instance of aura-bot, follow the steps below:

Local deployment of the aura-bot instance for your Aura Platform release. Check the example below for Jimi Hendrix release (each line corresponds to a command to be executed):
```
    git clone https://github.com/Telefonica/aura-bot-platform.git --branch release/jimihendrix

    cd aura-bot-platform

    npm install
```
Kubernetes configuration: Consider including the next environment variable export in your local terminal starting up configuration file to avoid running the following command each time. Obviously, a correct path to the personal Kubernetes configuration file mentioned as a dependency in the previous dependencies section should be used in the following command.
```
    export KUBECONFIG=~/kubernetes-config.yaml
```
Get the list of available Kubernetes namespaces:
```
    kubectl get ns
```
Get the configuration for the Kubernetes namespace of interest (contact your local DevOps team to figure it out). In our case, since we are deploying a local release of the aura-bot instance, the aura-ap-next should be used as the namespace (the configuration will be stored in a file named aura-bot.ap-next.env):
```
    (kubectl -n aura-ap-next get cm aura-bot -o json | jq -r ".data|to_entries|map(\"\(.key)=\(.value|tostring)\")|.[]" ; kubectl -n aura-ap-next get secret aura-bot -o json | jq -r ".data|to_entries|map(\"\(.key)=\(.value|tostring|@base64d)\")|.[]" ) > aura-bot.ap-next.env
```

Work with Visual Studio Code:

Open the previous aura-bot-platform directory (see step 1) in Visual Studio Code.
Open the internal Visual Studio Code terminal (CONTROL + ` in Windows).
Place the aura-bot.ap-next.env file (see step 4) in the .vscode/.env/ subfolder inside the aura-bot folder. Create the needed directories if not already created.

Include the following launch configuration in the .vscode/launch.json file inside the aura-bot-platform repository (create the needed directories if not already created) to be able to start the aura-bot instance from inside Visual Studio Code. Please, set the AURA_MICROSOFT_APP_ID as well as the AURA_MICROSOFT_APP_PASSWORD configuration variables to the appropriate values obtained when creating the bot service in the Microsoft Azure portal (see the dependency number 4 included in the previous dependencies section):

{

    // Use IntelliSense to learn about possible attributes.

    // Hover to view descriptions of existing attributes.

    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387

    "version": "0.2.0",

    "configurations": [

        {

            "type": "node",

            "request": "launch",

            "name": "aura-bot.ap-next.env",

            "program": "${workspaceFolder}/lib/index.js",

            "console": "integratedTerminal",

            "outFiles": [

                "${workspaceFolder}/lib/**/*.js"

            ],

            "env": {

                "CONFIG_FILE": ".vscode/.env/aura-bot.ap-next.env",

                "AURA_MICROSOFT_APP_ID": "8d72c407-XXXX-4b50-a076-76XXXX5437e4",

                "AURA_MICROSOFT_APP_PASSWORD": "password",

                "AURA_LOGGING_FORMAT": "dev",

                "AURA_LOGGING_LEVEL": "DEBUG"

            }

        }

    ]

}

In the aura-bot.ap-next.env file: Set the values of the configuration variables named AURA_DEFAULT_LOCALE and AURA_DEFAULT_TIME_ZONE to the desired values according to the appropriate language and time zone. For example, for Spain these values are:
```
AURA_DEFAULT_LOCALE=es-es

AURA_DEFAULT_TIME_ZONE=Europe/Madrid
```
Provide access to the Aura Mongo databases:
- Substitute the Mongo connection URI configuration variable (named AURA_MONGODB_URI) located in the .vscode/.env/aura-bot.ap-next.env configuration file to the next value:
```
    AURA_MONGODB_URI=mongodb://localhost:27017
```
- Port forwards the local URI to the real one running the following command in an internal Visual Studio Code terminal using the following command:
```
    kubectl port-forward mongodb-0 -n aura-system 27017:27017
```
This makes your bot use the Mongo database in your development environment, if you are not using Atlas.
Provide access to the Aura Cognitive Services:
- Substitute the Aura Cognitive URI configuration variable (named AURA_COGNITIVE_ENDPOINT) located in the .vscode/.env/aura-bot.ap-next.env configuration file to the next value:
```
    AURA_COGNITIVE_ENDPOINT=http://localhost:7000/auracognitive/v3
```
- Port forwards the local URI to the real one running the following command in an internal Visual Studio Code terminal using the following command:
```
    kubectl -n aura-ap-next port-forward deployment/api-gw 7000:80
```
Provide external access to the locally deployed release of the aura-bot instance:
- Start ngrok in an internal Visual Studio Code terminal using the following command:
```
    ngrok http 8080
```
- Set the new HTTPS URL provided by ngrok in the configuration of the bot service available in the Microsoft Azure portal (see the dependency number 4 included in the dependencies section). The messaging connection endpoint should have a value similar to: https://55a1d84f.ngrok.io/api/messages
The locally deployed release of the aura-bot instance is ready to be started. Click on the “Play” icon in Visual Studio Code to run the launch configuration named aura-bot.ap-next.env.

Interact with the locally deployed Aura release of the aura-bot instance:

11.1. Get a DirectLine token running the following command (instead of the included one, use the secret for the Direct Line channel of the bot service available in the Microsoft Azure portal (see the dependency number 4 included in the dependencies section):

curl --location --request POST 'https://directline.botframework.com/v3/directline/tokens/generate' \

--header 'Authorization: Bearer 55FhfjL8soI.bm-NhUy68mwCfPar4zIjTYHGd5cEGmKWt5zXqmA9rxI' \

-d ''

A response such as the following one is received:

    {

    "conversationId": "AUR2oOohW9Z64MtvuQyoFO-a",

    "token": "ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJBT08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd01234ZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJuYmYiOiAxNTg4NzYyMjQwLA0KICAiZXhwIjogMTU4ODc2NTg0MCwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3XXXXLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.pps98q5aYO2T4S7XwdIBudCzZB1T31HlwJ51tbEMcGGJrcHRI-hXnZskjHlcXIzBJiABeYiZSncqyWsNRWSmoVQ3iIYTrBiJM6y1EYn2qDJO4JYjZI5IZeFnp3GieB3eMP-HsW1DixK2p_C2DwxZy5pDc3nveclejI7SeUpl6m4frzNDPfqv7UoEW6aMthnT64JWhzncfF3y3_X-6J5v5RhTPW0OJEXpEuZ94AkhwHLfjLKzyewMwk0NzyAwmnCSZ0p6XyJjx9lA1FByHMRP0OLwcrfE8l_N_eXwUZuSY10gqRl5Tmm-D9p869mooA_0DuJYZUhgH_0D_4yg8PFjtg",

    "expires_in": 3600

    }

11.2. Start the conversation using the token obtained in the previous step (11.1).

curl --location --request POST 'https://directline.botframework.com/v3/directline/conversations' \

--header 'Authorization: Bearer ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJBT08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd01234ZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJuYmYiOiAxNTg4NzYyMjQwLA0KICAiZXhwIjogMTU4ODc2NTg0MCwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3XXXXLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.pps98q5aYO2T4S7XwdIBudCzZB1T31HlwJ51tbEMcGGJrcHRI-hXnZskjHlcXIzBJiABeYiZSncqyWsNRWSmoVQ3iIYTrBiJM6y1EYn2qDJO4JYjZI5IZeFnp3GieB3eMP-HsW1DixK2p_C2DwxZy5pDc3nveclejI7SeUpl6m4frzNDPfqv7UoEW6aMthnT64JWhzncfF3y3_X-6J5v5RhTPW0OJEXpEuZ94AkhwHLfjLKzyewMwk0NzyAwmnCSZ0p6XyJjx9lA1FByHMRP0OLwcrfE8l_N_eXwUZuSY10gqRl5Tmm-D9p869mooA_0DuJYZUhgH_0D_4yg8PFjtg' \

--data-raw ''

A response such as the following one is received:

{

  "conversationId": "AUR2oOohW9Z64MtvuQyoFO-a",

  "token": "ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJBT08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd0b3JvZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJu1234OiAxNTg4NzYyMjY5LA0KICAiZXhwIjogMTU4ODc2NTg2OSwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.Ft_r71JQ-Qq39nXqzO2u3SEHYMjGY8vMb4_OJL89Uw9NXXXXcvYmM62iu6YG8DcFCy2PFj2hmOev35f06zNXsgbHAthPxTPTIboPO8DyXYFQe8yYbhBKXBt2AIoI4SOO16e_OKaEETh-R2sXe6rfSp3PTgKddzFyLkXCl77e2Tz3TI7Zwe-NIyfmXKhJwd-XzTl7lxJAunSDSDS1i2rwzz8yAjBwJl5wFFhGXnOxPph1bHi_Ag-gU-XIMk_vhTTMLvkCORhBGWZJCNSGXxs5XBUYOZf2oZJA_UWtHqNolNO3K5mF6-cHg188YbAax78-gq0lB2XQCKCamZTmD9TRCg",

  "expires_in": 3600,

  "streamUrl": "wss://directline.botframework.com/v3/directline/conversations/AUR2oOohW9Z64MtvuQyoFO-a/stream?watermark=-&t=ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI61234T08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd0b3JvZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJuYmYiOiAxNTg4NzYyMjY5LA0KICAiZXhwIjogMTU4ODc2MjMyOSwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.igWA6xJmWwYoTeOV_A5cY_1_spptYgG2xqhJFGBc6PR0l62W-XXXXohqwZqfs7-z-VfyRrWKmD6x2xCw17DRGua6P7qE5Sk9XeV5DcD4XE_f80jGsr86CxFxL_F23iAYWOnpRtYNXJ3yCn69GXHBHvp0sAefLno7JqaoeHZlstyEm72o1v_WqFVd1RHW9zzbbEzQrIhmixUoQbEacuIIMAc6Wtesi3bb8iPOVtFIN_nEovceIieeQggMn0YesYDjiQ600zUX6p4FnU8MPtWpwV6XCSspC3iTuuUSjnpMMbekXYqJHItdgPTE4dPFkqQI_mhPEU0Ravn4vWNQLMd0rg",

  "referenceGrammarId": "95090c7e-6475-5a58-ba7a-35e45f903d38"

}

11.3. Send a message to the bot using the conversation obtained in the previous step and any of the tokens obtained in step 11.1 or 11.2 (you should use a valid user Aura id set in the from.id property, request it from your local QA or DevOps team):

    curl --location --request POST 'https://directline.botframework.com/v3/directline/conversations/AUR2oOohW9Z64MtvuQyoFO-a/activities' \

    --header 'Content-Type: application/json' \--header 'Authorization: Bearer ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJBT08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd01234ZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJuYmYiOiAxNTg4NzYyMjQwLA0KICAiZXhwIjogMTU4ODc2NTg0MCwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3XXXXLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.pps98q5aYO2T4S7XwdIBudCzZB1T31HlwJ51tbEMcGGJrcHRI-hXnZskjHlcXIzBJiABeYiZSncqyWsNRWSmoVQ3iIYTrBiJM6y1EYn2qDJO4JYjZI5IZeFnp3GieB3eMP-HsW1DixK2p_C2DwxZy5pDc3nveclejI7SeUpl6m4frzNDPfqv7UoEW6aMthnT64JWhzncfF3y3_X-6J5v5RhTPW0OJEXpEuZ94AkhwHLfjLKzyewMwk0NzyAwmnCSZ0p6XyJjx9lA1FByHMRP0OLwcrfE8l_N_eXwUZuSY10gqRl5Tmm-D9p869mooA_0DuJYZUhgH_0D_4yg8PFjtg
    ' \

    --data-raw ' {

        "type": "message",

        "from": {

            "id": "d1626d20-4e16-46ac-ba3c-c140fa3742a1"

        },

        "text": "Hola"

    }'

A response such as the following one is received:

        {
            "id": "AUR2oOohW9Z64MtvuQyoFO-a|0000001"
        }

To get the message sent by the aura-bot instance, run the following command to get the activities sent in the conversation (use the same conversation started in step 11.2 and any of the tokens obtained in step 11.1.

    curl --location --request GET 'https://directline.botframework.com/v3/directline/conversations/AUR2oOohW9Z64MtvuQyoFO-a/activities' \

    --header 'Authorization: Bearer ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJBT08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd01234ZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJuYmYiOiAxNTg4NzYyMjQwLA0KICAiZXhwIjogMTU4ODc2NTg0MCwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3XXXXLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.pps98q5aYO2T4S7XwdIBudCzZB1T31HlwJ51tbEMcGGJrcHRI-hXnZskjHlcXIzBJiABeYiZSncqyWsNRWSmoVQ3iIYTrBiJM6y1EYn2qDJO4JYjZI5IZeFnp3GieB3eMP-HsW1DixK2p_C2DwxZy5pDc3nveclejI7SeUpl6m4frzNDPfqv7UoEW6aMthnT64JWhzncfF3y3_X-6J5v5RhTPW0OJEXpEuZ94AkhwHLfjLKzyewMwk0NzyAwmnCSZ0p6XyJjx9lA1FByHMRP0OLwcrfE8l_N_eXwUZuSY10gqRl5Tmm-D9p869mooA_0DuJYZUhgH_0D_4yg8PFjtg
    '

A response such as the following one is received:

{

  "activities": [

    {

      "type": "message",

      "id": "AUR2oOohW9Z64MtvuQyoFO-a|0000000",

      "timestamp": "2020-05-06T11:14:43.8618783Z",

      "serviceUrl": "https://directline.botframework.com/",

      "channelId": "directline",

      "from": {

        "id": "d1626d20-4e16-46ac-ba3c-c140fa3742a1"

      },

      "conversation": {

        "id": "DvpneVrCrDG9DVIL7pQr5N-a"

      },

      "text": "Hola"

    },

    {

      "type": "message",

      "id": "AUR2oOohW9Z64MtvuQyoFO-a|0000001",

      "timestamp": "2020-05-06T11:14:49.2303326Z",

      "localTimestamp": "2020-05-06T11:14:45.764+00:00",

      "channelId": "directline",

      "from": {

        "id": "aura-bot-gtorodelvalle",

        "name": "aura-bot-gtorodelvalle"

      },

      "conversation": {

        "id": "AUR2oOohW9Z64MtvuQyoFO-a"

      },

      "text": "Hola, buenas",

      "inputHint": "acceptingInput",

      "channelData": {

        "correlator": "6a3ccc2a-c80e-441f-83ff-945691fd3407"

      },

      "replyToId": "DvpneVrCrDG9DVIL7pQr5N-a|0000000"

    }

  ],

  "watermark": "1"

}

ℹ️ Instead of using HTTP requests, another possibility is to use the Web Sockets URL obtained in step 11.2 (see the streamUrl property obtained in the response) using a Web Sockets client such as the Smart Web Sockets extension for Google Chrome.

Notice the Aura Cognitive services recognized the “Hola” text message sent to the bot as a greeting and it responded with a greeting message (“Hola, buenas”).

You could set a breakpoint in any part of the code (for example, in the greetings dialog) to debug it.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot middlewares

Description of the different Aura Bot middlewares, components in charge of the messages flow

Introduction to Aura Bot middlewares

Middlewares in aura-bot are software components in charge of the messages flow. In fact, they are just classes executed between the bot adapter and aura-bot logic.

Middlewares are defined by Microsoft BotFramework, thus Aura just adds as many middlewares as needed in order to make the bot handle messages appropriately.

Find here further information about middlewares in BotFramework.

There are two types of middlewares defined in aura-bot:

Middlewares that are always executed following a specific order established by the bot.
Middlewares that are optional and are activated by configuration, through the environment variable AURA_ACTIVE_MIDDLEWARES.

The following figure schematically shows the aura-bot middlewares flow for messages, indicating their category and the orderly execution of all of them.

Classification criteria	Categories
When they are executed	- INPUT (turquoise): if they are an input to aura-bot, in order to summon a dialog. - OUTPUT (orange): they are an output from aura-bot, leading to the output message generation. - INPUT-OUTPUT: (half turquoise/half orange), if they have methods to be run before executing the dialog and methods to be executed after it.
Mandatory / optional	- M: mandatory - O: optional
Execution mode: flow stops when middleware fails	- False: Execution flow stops when middleware fails - True: execution continues when middleware fails

To configure the optional middlewares, they should be added to the environment variable AURA_ACTIVE_MIDDLEWARES that should contain the name/s of the needed optional middlewares. It should contain a comma separated list with all or a set of the following names:

batch-outgoing-message-middleware
speak-processor-middleware

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Test Aura Bot

Check the performance of Aura Bot components

Introduction

The current documents contain different tests that can be executed over aura-bot components with several purposes:

Test a developed aura-bot dialog: Debug with mocha and Typescript
Template for testing an aura-bot dialog
Template for testing an aura-bot middleware
Tests for the comparation of joi and ajv libraries
Guidelines for the migration of unittest from Jasmine to Jest

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Guidelines for building a dialog that uses async APIs

Orderly steps for building an Aura Bot dialog that require to call asynchronous APIs

Introduction to asynchronous APIs

Asynchronous APIs are defined as APIs that do not provide the information back immediately, but with a certain standby time as they must perform a specific task derived from the user’s request. When the execution of this task is finished, these APIs invoke a callback and pass to the dialog the result of the task accomplishment.

The call to an asynchronous API must be included in the use case dialog and the payload from the API will be sent to aura-bridge, which is in charge of delivering it to the dialog that invoked this API.

This functionality can be useful, for example, in use cases that need to call to self-diagnostics APIs.

ℹ️ Current requisites:

This functionality only applies to Kernel APIs.
The correct operation implies that the dialog is in bypass mode.

An example of the usefulness of asynchronous APIs is shown below:

The user asks Aura: “Test my optical fiber connection” aura-bot recognizes this request and triggers a specific dialog. The dialog, that must be configured in bypass mode, calls an asynchronous API. The API takes T seconds in answering as Aura has to perform certain verification tests.
After that time, the API sends a callback to the dialog with a text that include the result of the verification tests and offers different solutions for the user to choose.
The user selects one of the options and the intended answer is provided to her.

How to call asynchronous APIs in a dialog

Follow these guidelines in order to make your dialog call an asynchronous API.

1. Check purposes and scopes

Firstly, you should add in the channel configuration (aura-configuration-api) all the necessary purposes and scopes in order to invoke the APIs.

⚠️ It must be done for all the intended channels* that will use the dialog.

2. Call asynchronous APIs in the dialog

For including asynchronous APIs in the dialog, it must work in bypass mode. This bypass mode must be started when the first call to the asynchronous API is made.

    const callbackId = stepContext.context.activity.id;
    const bypass: Bypass<BypassModelData> = await Bypass.initialize(
            stepContext.context,
            this.timeout,
            { callbackId },
            'asyncCallback',
            BypassState.Init,
            getLiteral(stepContext?.context)('factotum:bypass.close.words'));
        const message = this.message4pCreate;
        message.diagnosis_callback_url = getAsyncCallbackUrl(
                stepContext.context, this.configuration, callbackId);
        const response = await this.sendMessageTo4p(stepContext, this.url4p, message, corr);
        // Update bypassmode (if connection is ok)
        bypass.state = BypassState.Bypass;
        bypass.data.tecnicalProblemId = response?.body?.id;
        await bypass.updateBypass(stepContext?.context, false);

This API has a parameter to send the callback where the response is received, in this case aura-bridge. To build this URL, there is a getAsyncCallbackUrl(@telefonica/aura-bot-common) method, belonging to the bridge-utils utility. This will return the callback URL based on the context, the configuration and an identifier that will be sent in the answer.

message.diagnosis_callback_url = getAsyncCallbackUrl (
                 stepContext.context, this.configuration, callbackId);

In each execution of the dialog, this must be finished (as bypass mode requires closing the dialog in each execution), so that it is reactivated by aura-bot when it finds the bypass mode.

Communication flow

The following diagram shows the request flow of a message to a dialog invoking an asynchronous API:

sequenceDiagram
    actor User
    participant Whatsapp
    participant 4P
    participant Bridge
    participant Bot
    participant Dialog
    User ->> Whatsapp: message
    Whatsapp ->> 4P: message
    4P ->> Bridge: message + apiKey + channelId
    Bridge ->> 4P: response 200
    Bridge ->> Bot: message + channelId
    Bot ->> Dialog: message
    Dialog ->> 4P: request async + callback bridge
    4P ->> Dialog: response 200
    Note right of 4P: when 4p finishes the request sends the response to the indicated callback (bridge)
    4P ->> Bridge: response request async
    Bridge ->> 4P: response 200
    Bridge ->> Bot: response request async
    Note right of Bridge: the response is sent as payload
    Bot ->> Bridge: response 200
    Bot ->> Dialog: response request async

Example of a dialog calling an asynchronous API

This is a dialog’s example that makes calls to an asynchronous API.

Firstly, the dialog checks in which bypass state is:

    const corr = ContextUtils.getCorrelator (stepContext.context);
    try {
        const bypass = await Bypass.loadBypass (stepContext.context);
        switch (bypass.state) {
            case BypassState.Off:
            case BypassState.Init: {
                await this.onInit (stepContext, corr);
                break;
            }
            case BypassState.Bypass: {
                await this.onByPass (stepContext, corr);
                break;
            }
            case BypassState.Closed: {
                await this.onClosed (stepContext, corr);
                break;
            }
        }
    } catch (err) {
        await stepContext.context.sendActivity ('Error async event 4p');
        this.logger.error ({error: 'Error async event 4p', stck: err, corr});
    }
    return await stepContext.endDialog ();

If bypass mode is not started, the asynchronous API call will be sent and the bypass mode will be initialized.

    private async onInit (stepContext: WaterfallStepContext, corr: string) {
        try {
            const callbackId = stepContext.context.activity.id;
            const bypass: Bypass <BypassModelData> = await Bypass.initialize (
                stepContext.context,
                this.timeout,
                {callbackId},
                'asyncCallback',
                BypassState.Init,
                getLiteral (stepContext? .context) ('factotum: bypass.close.words'));
            const message = this.message4pCreate;
            message.diagnosis_callback_url = getAsyncCallbackUrl (
                stepContext.context, this.configuration, callbackId);
            const response = await this.sendMessageTo4p (stepContext, this.url4p, message, corr);
            // Update bypassmode (if connection is ok)
            bypass.state = BypassState.Bypass;
            bypass.data.tecnicalProblemId = response? .body? .id;
            await bypass.updateBypass (stepContext? .context, false);
            this.logger.info ({msg: `Bypass initializated`, corr});
        } catch (err) {
            await Bypass.closeBypass (stepContext.context);
            await stepContext.context.sendActivity ('Error call async api 4p');
            this.logger.error ({msg: 'Error call async api 4p', error: err.message, stck: err, corr});
        }
    }

If aura-bot is in bypass mode, the dialog could receive users’ messages. In the example, messages are ignored, but at this point the dialog can receive the response of the asynchronous API. If the sent identifier matches, the content will be sent to the user, thus ending the bypass mode. In the bypass.data element, information can be stored in order to be used between different bypass cycles.

   private async onByPass (stepContext: WaterfallStepContext, corr: string) {
        const payload = ChannelDataUtils.getPayloadAsyncCallback(stepContext.context);
        const bypass: Bypass <BypassModelData> = await Bypass.loadBypass (stepContext.context);
        if (payload && bypass.data.callbackId === payload.callbackId) {
            const payloadText = JSON.stringify (payload);
            this.logger.debug ({msg: `Send activity message $ {payloadText}`, corr});
            await stepContext.context.sendActivity (payloadText);
            await this.cancelTecnicalProblem (stepContext, corr);
        } else {
            this.logger.debug ({msg: `Ignore $ {stepContext? .context? .activity? .text}`, corr});
        }
    }

If the bypass has ended, the bypass time has expired or the user has used one of the closing terms, the dialog must close the bypass mode and perform the appropriate operations. In the following example, a message is sent to the user.

    private async onClosed (stepContext: WaterfallStepContext, corr: string) {
        await Bypass.closeBypass (stepContext.context);
        await stepContext.context.sendActivity ('Bypass closed');
    }

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot channelData

How Aura Bot manages the channelData property used by Aura to define the Aura request-response semantic model

The current section details the management by aura-bot skill of the channelData property used by Aura to define the Aura Request – Response Semantic Model.

The Aura semantic application model defines a set of properties that can be used as secondary elements of the Microsoft Azure Bot Service and Bot Framework Activities property included in the application activities.

channelData is an open field in the activity, i.e., the message exchanged during a communication between a channel and a bot built on top of Microsoft Bot Framework, that is devoted to define the specific format of the request needed by the specific bot to provide a proper response to the channel and, thus, to the user.

The current section will describe the specific channelData aspects related to aura-bot, such as:

How to handle the different channelData versions.
channelData mapping in Aura response.
channelData validations in requests and responses.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

channelData validations

channelData validations done both in the request and the response, according to a certain configuration

Validations in request channelData

Request channelData will be validated if its version is greater than or equal to AURA_CHANNELDATA_VALIDATION_MIN_VERSION, that is always v3 (prior versions will never validate and will get all the channelData “as they are”).

That means, that any version from v3 onwards will be validated (even non existing versions, such as 99, will try to be validated).

Versions from v3 onwards will only use the major as a string (e.g., 3), but also semver is understood (e.g., 3.0.0), but note that minor and patch will be ignored (e.g., 3.2.1 === 3.0.0) when looking for a validator.

Logic location

The validation is done in the channeldata-validator-middleware, that must be one of the first middlewares, to ensure that no other logic is fetching data from channelData before validating it.

Errors

There are two types of errors on request validation:

Validation error: the request channelData does not comply the schema for that version. The error is stored in requestValidationErrors property within the thrown error.
Missing validator error: the specified version does not have a matching validator, so channelData is invalid.

Validations in response channelData

Response channelData will be validated if AURA_CHANNELDATA_RESPONSE_VALIDATION environment variable is set to true.

In that case, all outgoing activities will have their channelData validated, even the error messages, before sending to the user.

The validation must be done after the channelData is transformed into the final version (that could be or not the “internal” version).

Logic location

The response validation is done in Aura Groot, in AuraCloudAdapter class.

Errors

There are two types of errors on response validation:

Validation error: the response channelData does not comply the schema for that version and the error is stored in responseValidationErrors property within the thrown error.
Missing validator error: the specified version does not have a matching validator, so the channelData is invalid.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Bot configuration

Description of Aura Bot configuration basics, nomenclature, environment variables and libraries configuration

Introduction

The current section includes:

Configuration basics: process and priorities, nomenclature, validation of the configuration, etc.
Aura channels configuration
Updated list of Aura Bot environment variables
Aura Bot libraries configuration and variables

Configuration basics

Process and priorities

Aura components environment configuration will be loaded merging the variables defined in the environment of the host running the server and those defined in a configuration file, that will be passed to the server as an environment variable named CONFIG_FILE.

Variable values defined in the host environment will take precedence to those defined in the CONFIG_FILE.

Finally, variables collected by the make-up process of the external libraries .env.libraries will be loaded with less priority (as if they had been defined in the environment or in the CONFIG_FILE, they will have more priority).

Afterwards, all variables are joined together and, in case the same variable key is used twice, the priority will be as follows (the higher in the list, the more priority):

Vars from the environment
Vars from the file pointed by CONFIG_FILE
Vars from .env.libraries (in aura-bot root, autogenerated file)

Nomenclature

Environment variables names should start with AURA_ in main Aura components, to avoid problems with the overlapping of system variables.
Environment variables used in aura-bot libraries should start with the name of the library (BILL_), to isolate variable names and avoid overwriting between different libraries.

Note:
Review carefully with the DevOps Team variable names that are set automatically by kubernetes, such as [APP_NAME]_PORT that has the docker host of the k8s cluster. In the case of aura-bot pods, it will be: AURA_BOT_PORT. So, this variable must not be used internally.

Configuration validation

aura-bot counts on a @hapi/joi validation schema that will contain the variables used by it.

During the start-up process, if the validation of global configuration fails, the full list of variables to fix will be shown and the bot will not start. See libraries configuration for further information.

Once the configuration is loaded and the instance created, it will count on the property environmentConfiguration, that contains all the variables set in the system. The names of the variables will be the same than the environment variables, just the type will be set during the schema validation.

For a complete list of environment variables in the system, check aura-bot environment variables.

Passing configuration to our internal libraries

aura-bot internal modules such as the server, middlewares and all of our internal libraries (aura-kpis, aura-logging, aura-locale-manager, etc.) must be prepared to get the configuration when creating an instance.

They should provide a constructor or an init method, with a configuration argument, to receive the environment configuration, for example:

export class SingletonModule {

    /** Private constructor to avoid unwanted instances */
    private constructor() { }

    readonly id: string = 'SingletonModule';

    public static init(configuration: Configuration): SingletonModule {
         if (!SingletonModule.instance) {
            // Do initializing stuff
            return SingletonModule.instance;
        } else {
            throw new Error('An instance of SingletonModule already exists');
        }
    }

    /** Module internal instance */
    private static instance: SingletonModule;
}

Aura Channels configuration

The list of channels available in the environment includes the channel name, id, basic channel configuration, response type, enabled purposes in Kernel, etc. This setting is configured in aura-configuration-api server.

In principle, this setting should not be modified by the OB developers, as it is automatically modified during the make-up phase. However, it is recommended recommended that local developers use their own aura-configuration API server and can make changes for local testing purposes.

You can find detailed information regarding the channel configuration file in Channel Model section.

AuraChannelsConfiguration is a singleton class that contains utils to obtain information about the channels. This module is initialized at server start-up like other singleton modules. To use it, you should use the instance already created:

const configuration = {
    AURA_CHANNELS_CONFIGURATION_API_ENDPOINT: 'http://...' // Mandatory.
};

AuraChannelsConfiguration.init(configuration);

The variable AURA_CHANNELS_CONFIGURATION_API_ENDPOINT contains the URL to access aura-configuration-api service. AuraChannelsConfiguration uses the following methods:

getChannelByName
Get channel configuration value by name of channel.

AuraChannelsConfiguration.instance.getChannelByName('channelName');

getChannelByPrefix
Get channel configuration value by prefix of channel.

 AuraChannelsConfiguration.instance.getChannelByPrefix('channelPrefix');

getChannelById
Get channel configuration value by id of channel.

AuraChannelsConfiguration.instance.getChannelById('channelId');`

getChannels
Get all channels configuration.

AuraChannelsConfiguration.instance.getChannels();

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Create/update an API client

Guidelines for the generation or the update of an API client in Aura

Introduction

There are two main ways to create or update a new API client, both based on a swagger OpenAPI schema:

Create a new client based on a swagger
Update an already available client by re-creating it based on the next version of the published swagger

API clients are generated automatically from the swagger file delivered by the API constructor, usually Telefónica Kernel. Aura uses a custom code generator based on the OpenAPI initiative in order to generate TypeScript clients, which is compatible with JavaScript. Two different types of clients live together in the current Aura release:

Clients generated directly from the swagger with the original code generator described on the swagger documentation.
Clients generated directly from the swagger based on the custom code generator. ℹ️ Recommended way.

A copy of the swagger generator tools is available in the repository in the folder called tools, to be used directly from the scripts of the client. In the current version, we are using aura-code-generator/packages/aura-client-generator/tools/openapi/openapi-generator-cli-6.2.1.jar as the custom code generator.

Procedures for generating or updating clients

There are three different processes, depending on the type of client and purpose:

Create a new external client for a brand-new API
Create a new internal client for a brand-new API
Update a client to a breaking change version

Moreover, if implementing a minor change version, check how the original client was created and follow the same procedure. Otherwise, there can be uncontrolled breaking changes.

Previous to the creation of a client, it is required to install the library: @telefonica/aura-develop-utilities

Create a new external client

We have integrated Hygen as a way to boost the process of creating new API clients.

To create a new API client template, please follow the next steps:

In your project install the client generator: $ @telefonica/aura-client-generator
Create a new branch with a descriptive name: $ git branch -b feat/new-api-client
Execute the following commands to create or update API:
- $ aura-client-generator, $ aucg or $ aura-cg: Generate new API with base files, model files and API files.
- $ aucg-update: Generate only API files.
- $ aucg-model: Generate only model files.
Send answers for aucg.
- Hygen: Answer the questions requested by the Hygen for the generation of the new client. Hygen will ask you for the name of the new API, the location of the swagger, the location where you want to generate the client (by default, it is generated in the root directory with the name of client), the version, the enumeration, the projectType and the tag to be set.
- Flags options: Add flags options with the answers.
  - $ -V, --version: output the version number
  - $ --clientName: Which is the name of the new API (ex.: Admin, User Authentication, etc.)?
  - $ --swaggerFile: Path of the swagger
  - $ --clientDirectory: In which directory do you want to generate the client (default: “client”)
  - $ --versionNumber: Client version
  - $ --tagName: Tag used in the publishConfig configuration (default: “”)
  - $ --enumeration: Enumeration format (choices: “Unchange”, “Unify”, “Particularize”, default: “Unchange”)
  - $ --projectType: Destination project type (choices: “client”, “server”, default: “client”)
  - $ -h, --help: display help for command

Enumeration question

It is a list of options from which you can choose the specific way the models are generated.

Unchange: No modification is applied to names, enums or interfaces themselves. (If the swagger has several schemas with the same name, they will step on each other).
Unify: This option unifies in a single enum or interface the schemas that may have the same name. (Recommended option).
Particularize: This option separates all enums that have the same name by assigning the name of the enum + the name of the schema it belongs to.

projectType question

It is a list from which you can choose the type of client: external client (client) or internal client (server). This question is asked since the aura-code-generator is used to generate these two types of clients and certain elements change in the generation of each type.

client: make reference to the external client.
server: make reference to the internal client.

Note that when Hygen asks for the location for the new client, the format of this folder name must be a dash-separated name similar to name-of-your-api or ./package/name-of-your-api only in external clients.

In the background, the aura-client-generator command carries out the following steps:

Create a new package for the new API client at the indicated address directory.
Create the .gitignore, .npmignore, .npmrc, package.json, README.md and tsconfig.json files in the new API client package directory.
Create a new src/ folder in the new API client package directory.
Create the index.ts, models.ts files and a folder called api inside this API folder.
The provided Swagger API specification file is copied to the swagger directory of the new API client package directory.

At this stage, developers are ready to start working on the new API client from the newly created API client template:

Write a description of the new client and a minimal usage example in the README file.
Commit your changes and push them to Github.
Make a Pull Request to merge your changes in master/main branch.
After approved, merge the PR into master/main branch.
Then, the new version of the client is published in the private npm registry and available to be used.

Once the creation of the new client is finished, follow the guidelines to contribute your changes according to Contributing code to the repository section.

Create a new internal client

In order to create an internal client, execute the following command:
$ npm run create-client

This will execute the process that will generate a new client, internal clients do not execute hygen as in external clients since all the information they need is passed to them through the flags that are explained below.

The complete command executed is the following:
$ npx aucg --clientName \"server name\" --swaggerFile \"swagger path\" --projectType \"server\"

Where:

npx aucg: command that executes the aucg
--swaggerFile: Location of the server swagger.
--projectType: Type of project, among the ones defined in enumeration projectType. In this case, it is server because it is an internal client. (Remember that this same generator is also used for external clients selecting the projectType client).

Steps to upload changes:

Write a description of the new client and a minimal usage example in the README file.
Commit your changes and push them to Github.
Make a Pull Request to merge your changes in master/main branch.
After approved, merge the PR into master/main branch.
Then, the new version of the client is published in the private npm registry and available to be used.

Once the creation of the new client is finished, follow the guidelines to contribute your changes according to Contributing code to the repository section.

Update a client

ℹ️ This procedure is valid both for external and internal clients

Due to the superagent HTTP library migration of all clients, a new procedure to update those clients has been implemented.

In addition, this new implementation depends on templates, which can be found here. If there are changes in the template that need to be reflected in a client, before continuing with this procedure, you should create a PR with those changes in templates and merge them into master/main branch.

The procedure to update a client with an updated template is as follows:

Create a new branch for the new code:
git checkout -b feat-or-fix-or-chore-depending-on-the-update/the-name-of-your-branch
If needed, add a tag or, if it has already been added, increase the numeric version in the package.json version:
"version": "2.1.0-superagent.x",
Execute the following command to update the client APIs:
npm run swagger-generate-client
Execute the following command to update the client models:
npm run swagger-generate-model
Commit your changes and push them to Github.
Make a Pull Request to merge your changes in master.
After approved, merge the PR into master.
Then, the new version of the client is published in the private npm registry and available to be used.

Authentication methods

All clients are generated using a common template for OpenAPI generator, so they have similar structure: all of them have a generic constructor to set a basePath endpoint: constructor(basePath?: string);

If no basePath is defined, which is not recommended, the default basePath defined on swagger file is used.

The current client generator supports several authentication methods based on swagger security definitions. The available authentication methods are described in the following sections.

Basic authentication

This authentication method is based on user and password.

Credentials can be set by different forms:

Using constructor. Credentials can be set on constructor using this method:

constructor(basePathOrUsername: string, password?: string, basePath?: string)

Using setters. Credentials can be set using username and password setters:

clientInstance.username = 'myuser'; clientInstance.password = 'mypassword';

Bearer authentication

This authentication method is based on a bearer token standard. It injects an Authorization header on HTTP request.

It can be set using the setter:
accessToken: clientInstance.accessToken = 'token'

The token can contain a bearer prefix or not. If no bearer prefix is included, the setter method adds it automatically.

Oauth authentication

This authentication method is based on oauth authentication standard. It is similar to bearer authentication method, so an authorization header is injected on HTTP request.

It can be set using the setter:
accessToken: clientInstance.accessToken = 'token'

The token can contain a Bearer prefix or not. If no Bearer prefix is included, the setter method adds it automatically.

Apikey authentication

This authentication method is based on APIKey authentication standard. It injects a generic header with key and value.

It can be set by using setApiKey method with the key and value parameters:
clientInstance.setApiKey(key: string, value:string);

None

If no security schema is defined in the API definition file or the security methods do not follow any OpenAPI standards, a generic accessToken setter is provided. This setter works as bearer and it injects an authorization header on HTTP request.

It can be set using the setter:
accessToken: clientInstance.accessToken = 'token'

The token can contain a bearer prefix or not. If no bearer prefix is included, the setter method adds it automatically.

Contributing code to the repository

To contribute your code to the repository, follow the next steps:

Once the code is satisfactory, stash changes into your branch.
Push your branch to the remote repository (this step runs the unit tests of all the packages and does not let the process continue until of all them have passed):
```
git push origin feat-or-fix-or-chore-depending-on-the-update/name-of-your-branch
```
From Github, send a new Pull Request from the branch with your code to master.
Ask for revision from any of the main contributors of the project.
Once the code has been reviewed and accepted, merge your code into master.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Dialog context recognizer middleware

Description of dialog-context-recognizer-middleware, that manages the recognition process when there are different options in the response

Introduction

dialog-context-recognizer-middleware uses a model to facilitate the recognition when Aura response is composed of several options, which have either been generated automatically when a Prompt Choice or a list of CardActions has been processed or generated manually.

This model is defined in dialogContext model.

The source code of this recognizer is included in Aura Bot Platform recognizers - Github repository.

The behavior of this recognizer is channel-specific. The dialogContext configuration for each channel follows the model defined in the channel model sub-property.

This recognizer first checks if a cache exists with the dialogContext generated by the last message sent to the user. If it does not exist, then it checks the dialogContext information saved in aura-bot cache, in greater detail in property auraData.conversationData.dialogContext.

This differs with past versions where this information was obtained from channelData property in the activity, which now is defined in the processFromClient property.

The recognition is performed by proximity between the user’s phrase and the dialogContext values to be evaluated.

If Aura has sent several dialogContext messages, the last message will be the one containing a single dialogContext with all the previous ones merged.

If the dialogContext value exists in the cache, it is deleted once fetched. If another recognizer beats the dialog-context-recognizer-middleware, this process is performed inside the finalize-recognizers-middleware.

Environment variables

Three aura-bot environment variables come into play in the process:

AURA_DIALOG_CONTEXT_THRESHOLD: minimum threshold to validate the recognition (by default: 0.8).
AURA_DIALOG_CONTEXT_THRESHOLD_RELATION_UTTERANCE: Microsoft uses in its algorithm a fixed value of 0.5. If the value is not set, then the value will be calculated based on the words of the user’s phrase divided by the words of the phrase to be compared. (by default: not set).
AURA_DIALOG_CONTEXT_ORDINAL_CARDINAL_THRESHOLD: if the client phrase contains a number or the dialogContext values are enumerated by cardinals or/and ordinals, this threshold will be used instead of AURA_DIALOG_CONTEXT_THRESHOLD. This is done to prevent numbers within the phrase from being confused with the position of the items in the options list.(by default: 0.95).

The dialogContext can be generated automatically based on Prompt Choices or CardActions. This is configurable per channel, but developers could add the dialogContext object to the channelData with the expected actions.

Example

An example is shown below: a user asks for a recommendation in Movistar +. If these recommendations are included in a dialogContext, it gives the user the possibility to precisely select one of the options using voice:

dialogContext stored for an Aura response:

{
  "dialogContext": [
    {
      "text": "I want to see the movie for all mankind|1|one|the first|first",
      "value": {
        "name": "I want to see the movie for all mankind",
        "text": "See for all mankindo",
        "type": "suggestion",
        "intent": "intent.tv.search",
        "entities": [
          {
            "type": "ent.audiovisual_film_title",
            "entity": "for all mankind",
            "canon": "for all mankind",
            "label": "",
            "score": 1
          },
          {
            "type": "ent.audiovisual_genre",
            "entity": "film",
            "canon": "films",
            "label": "CN",
            "score": 1
          }
        ]
      }
    },
     {
      "text": "I want to see the movie 30 for 30|two|second|the second|",
      "value": {
        "name": "I want to see the movie 30 for 30",
        "text": "See 30 for 30",
        "type": "suggestion",
        "intent": "intent.tv.search",
        "entities": [
          {
            "type": "ent.audiovisual_film_title",
            "entity": "30 for 30",
            "canon": "30 for 30",
            "label": "",
            "score": 1
          },
          {
            "type": "ent.audiovisual_genre",
            "entity": "film",
            "canon": "films",
            "label": "CN",
            "score": 1
          }
        ]
      }
    },
      {
      "text": "I want to see the movie rgb|3|three|the third|third",
      "value": {
        "name": "I want to see the movie rgb",
        "text": "See for all mankindo",
        "type": "suggestion",
        "intent": "intent.tv.search",
        "entities": [
          {
            "type": "ent.audiovisual_film_title",
            "entity": "rgb",
            "canon": "rgb",
            "label": "",
            "score": 1
          },
          {
            "type": "ent.audiovisual_genre",
            "entity": "film",
            "canon": "films",
            "label": "CN",
            "score": 1
          }
        ]
      }
    },
    .....
  ]
}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

dialogContext model

Description of the dialogContext model, for the management of different existing options in the response

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

Property	Type	Description
text	String	Text or texts (separated by ‘\|’) with the options to be matched.
value	Object	Object of `IntentResult` or other with the action to carry out if the option is validated.

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.

Property	Type	Description
originalFindChoicesOptions	Object	Original prompt findChoiceOptions. Used if the dialogContext recognizer needs to change it, the prompt would be restored to the original state.
originalStored	Boolean	It indicates whether the dialogContext recognizer had to overwrite the original prompt values. Default: `false`.
enabled	Boolean	It indicates whether the generation of ordinal and cardinal lists for prompt options is active. Default: `Inherited from the channel configuration`.
listType	DefaultListType	Type of list to enumerate the prompt options. Default: `OrdinalCardinal`.

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.

Property	Type	Description
enabled	Boolean	It indicates whether the generation of ordinal and cardinal lists for CardAction options is active. Default: `Inherited from the channel configuration`.
listType	DefaultListType	Type of the list to enumerate the CardAction buttons. Default: `OrdinalCardinal`.
synonyms	String[]	Array of strings with synonyms of the title.

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