Aura –

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

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

Aura Bot processes

Description of the main functionalities carried by Aura Bot and the different processes that can be executed for its management

The main functionalities in charge of aura-bot as Aura’s neuronal network are listed below:

Aura users’ sign up:
Different ways of registering users in Aura, depending on the channel. Find detailed information in channel authentication.
Aura authentication validation process Aura supports different types of users, each of them with access to specific services and use cases: authenticated users and anonymous users. The authentication process carried out by aura-bot is fully explained in Users authentication.
Aura conversational process aura-bot is in charge of managing the conversational flow with the user, from receiving her request and understand it to fetch the required data to compose the most appropriate response and provide it back to the user. Find detailed information in Aura conversational flow.

Apart from these core tasks in Aura’s performance, there are other processes that can be executed over aura-bot in order to customize it or access to different components.

channelData management

Docs:

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

Aura Bot object, data types and models

Description of the different types of data and models supported by Aura Bot

aura-bot supports several data models, compatible with different languages or structures in order to execute the conversational flow.

The current document includes the description of the different models supported by Aura Bot platform, currently:

auraCommand model
The use of auraCommands, that is, pre-defined options that the user can select from Aura’s interface, is managed by the auraCommand model.

dialogContext model
Aura supports the dialogContext model, a structure that facilitates the recognition of CardActions and prompts without the need of training.

Aura API Key
Aura counts on API Keys to connect to available API endpoints. They are based on an encrypted APIKey data model, which is included in aura-validate-apikey utility.

Docs:

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

Aura Bot formats

Description of the different response message formats supported by Aura Bot

By default, aura-bot uses Directline protocol to send the responses to the channels.

But it contains different response formats depending on the channel, to be able to deliver the responses in the most appropriate way for each channel.

The current available formats for Aura responses are:

For information regarding which channelData version is returned in Aura response, check the document Version in responses