Aura –

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

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

Aura Bot dialogs

Description of Aura Bot dialogs, components in charge of the conversational flow with the users, its role in the bot and the different types of dialogs in Aura

Introduction

Dialogs are aura-bot components in charge of the use cases’ logic for establishing a conversational flow with the user and, if required, summoning Kernel or third-party APIs in order to fetch specific data and provide an appropriate response back to the user.

aura-bot dialogs are integrated into a library, which is a node.js package with a particular structure that can contain one or several dialogs plus i18n strings, environment variables, configuration files and graphical resources. Libraries are deployed in the bot as plugins.

Currently, aura-bot supports the Microsoft Bot Framework SDK v4 for JavaScript as the internal bot engine. For the dialogs development over aura-bot, developers are kindly requested to read the Microsoft documentation Send and receive text message.

Types of Aura Bot dialogs

aura-bot contains different types of dialogs:

Main dialog: dialog in charge of routing from the recognized intent to its specific dialog. Find detailed information here.
Core dialogs: the current core dialogs are described here.
Dialogs from global libraries that include the logic of Aura global use cases.

Local dialogs: Moreover, in the case of local experiences, which are developed by the OBs from scratch or inspired in global use cases, it is required to build a new local dialog with the logic of the use case. Learn how to build an Aura bot dialog.

Docs:

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

Aura Bot ADapter

Description of aura-bot-adapter component, that extends the CloudAdapter class, the new implementation offered by Microsoft Bot Framework, which implements the Bot Framework Protocol and substitutes the deprecated BotFrameworkAdapter

Introduction

CloudAdapter is the new implementation offered by Microsoft Bot Framework, which implements the Bot Framework Protocol and substitutes the deprecated BotFrameworkAdapter class (deprecated since version 4.16.0).

The aura-bot component aura-bot-adapter now extends the CloudAdapter class and applies new methods to facilitate deployments on cloud’s environments.

aura-bot-adapter has the following roles:

It overwrites the sendActivities method of its parent to provide the feature of having all the activities returned in a turn in a single queue, so they can be handled properly by the batch-outgoing-message-middleware.

Implementation

The main changes that have been implemented during CloudAdapter modification are explained in the following sections:

Initialization

In CloudAdapter, there are differences on how to initialize the adapter. Configuration authentication variables are divided into ConfigurationServiceClientCredentialFactory and ConfigurationBotFrameworkAuthenticationOptions.

BotFrameworkAdapter (deprecated)

const adapter = new AuraBotAdapter({
        appId: this.configuration.AURA_MICROSOFT_APP_ID,
        appPassword: this.configuration.AURA_MICROSOFT_APP_PASSWORD,
        channelService: this.configuration.AURA_MICROSOFT_CHANNEL_SERVICE,
        openIdMetadata: this.configuration.AURA_MICROSOFT_OPEN_ID_METADATA,
        authConfig
    });

CloudAdapter

const credentialsFactory: ConfigurationServiceClientCredentialFactory = new ConfigurationServiceClientCredentialFactory({
    MicrosoftAppId: this.configuration.AURA_MICROSOFT_APP_ID,
    MicrosoftAppPassword: this.configuration.AURA_MICROSOFT_APP_PASSWORD
});
const botFrameworkAuthConfig: ConfigurationBotFrameworkAuthenticationOptions = {
    ChannelService: this.configuration.AURA_MICROSOFT_CHANNEL_SERVICE,
    BotOpenIdMetadata: this.configuration.AURA_MICROSOFT_OPEN_ID_METADATA
};
const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(botFrameworkAuthConfig, credentialsFactory, authConfig);
const adapter = new CloudAdapter(botFrameworkAuthentication);

processActivity vs process

The CloudAdapter class introduces a new method which processes the incoming request and applies a logic afterwards. In aura-bot platform, this logic is focused on forwarding incoming petitions to the ActivityHandler.

BotFrameworkAdapter (deprecated)

await adapter.processActivity(req, res, async (context: TurnContext) => {});

CloudAdapter

await adapter.process(req, res, async (context: TurnContext) => {});

Docs:

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

Plugin Manager

Description of Aura Bot plugin manager, module in charge of loading all the information from external libraries

Introduction

Plugin Manager is the aura-bot module in charge of loading all the dialogs libraries (from now on, libraries will be referred as plugins) to make them available to answer the users’ requests in a use case.

Plugins interface is the definition object that could be consumed by other modules. We can found dialogs and middlewares from external libraries to be imported in aura-bot.

The interface that handles the Plugin Manager for each aura-bot library is:

export interface Plugins {
    middlewares?: Array<MiddlewareExecution<TurnContext>>;
    dialogs: Dialog[];
}

Loading process

The following information is read during the loading process for each plugin (in case the plugin provides it):

configSchema: it contains joi schema of local libraries variable. Find more information in libraries configuration.
dialogs: dialogs of the library to resolve the use case.
middlewares: future use.

In the same event loop using architect to get each plugin, the first step will be to load the configSchema of the plugin and validate it. If there are no errors, the next step will be to load the dialogs and middlewares defined in the plugin.

If the schema validation process throws any error, the plugin will be stopped by the Plugin Manager and the process will go on loading the rest of the plugins. Errors will be gathered during the whole loading process and will be shown at once at the end.

Configuration delivery to dialogs and middlewares

Plugin Manager is in charge of preparing and delivering configuration of external dialogs and middlewares. By now, in this first approach, all variables will be passed to all loaded modules. In this point all variables can be easily filtered, if needed.

Regarding libraries configuration, each library/plugin may count on a @hapi/joi schema. If a library has one, then it will be validated with process.env, that contains all the environment variables from aura-bot and from every configured library merged during configuration process.

Further information is found in configuration basics.

If the plugin has no schema defined, the Plugin Manager will deliver all global configuration variables directly to the plugin, by constructor argument.

Apart from the variables delivered, it can be found other variables from other plugins and global variables that are not required by the specific plugin.

Docs:

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

Aura Bot routing manager

Description of Aura Bot routing manager, in charge of returning a dialog routing configuration

Introduction

The routing manager is an aura-bot module independent from the bot builder framework. It has the only goal to return a dialog routing configuration, where the main part has to be the address of the dialog matching the incoming recognizer object.

The recognizer object (incoming routing request) and the trigger conditions (configuration of an address) models are co-dependent.

Recognition object example:

{
    "intents": {
        "intent.*": {
            "score": 1
        }
    },
    "entities": [
        {
            "entity": "*",
            "score": 1
        }
    ]
}

Trigger condition example:

[
    {
      "intent": "intent.trigger",
    }
]

Trigger condition and Dialog registration

Dialogs and trigger dependence

The trigger condition and the registered dialog are also co-dependant. We can define several trigger conditions per dialog to be registered. Once the dialog to register is ready, we can start binding all the trigger conditions related to the dialog.

Resulting map of the binding process

The incoming request is bound to a channel and a recognizer intent field and the resulting address to the library (or plugin) and the id provided by the dialog configuration.

Registering a dialog

If a dialog is inserted as a plugin:
- It has to be accessible by a trigger condition if it is located at the plugin configuration.
- It has to be accessible by a trigger condition if it has the property triggerCondition in the dialog class, accessible across all channels.
- It has to be accessible by calling it directly with its id if it has an autoRegister property set to true, no routing will be involved.
Register the dialog with the library and dialog id, forming the address.
- Combination of library and dialog id: library:dialogId
- The extra control of the library is because we do not have control over the dialog naming, so we can be sure that each library can implement the name we want and the system will have an unique address.
Bind all the trigger conditions with the resulting address.
- The trigger conditions will be implemented for this address also by channel.
- The model forming the address accessor will be: channel:intent
- The incoming recognizer result will have to match this model.

Internal intent

When we have an internal intent, it has to be accessible across all the channel. We have to register the trigger condition with no channel distinction.

Trigger condition:

// channel id = telefonica
"triggerConditions":[
    {
        "intent": "intent.internal.wifi"
    }
],
id: "dialogId"

Address map:

// the channel of the incoming petition will be ignored
{"intent.wifi": "libraryId:dialogId"}

Flow examples:

Registration
Routing

Class usage

export interface RouteDialogConfiguration {
    suggestions?: boolean;
    triggers: TriggerCondition[];
    channelDataVersion?: string;
}

/**
* @deprecated This interface should not be used in favor of using RouteConfigurationElementMap interface,
* which improves the efficiency of getting route configuration.
 */
export interface RouteConfiguration {
    [library: string]: RouteConfigurationElement
}

/**
 * Route configuration value of map using to return route Configurations.
 */
export interface RouteConfigurationElement {
    channel: string;
    dialogs: {
        [dialog: string]: RouteDialogConfiguration
    }
}

const router = new RoutingMap();

// public addRoute(
//    routeDialogConfiguration: RouteDialogConfiguration,
//    dialogId: string,
//    channel?: string
// ): any {
router.addRoute(
    {showSuggestion: true, triggers: [{intent: intent.pizza}, {intent: intent.best.pizza}},
    'pizzaCompany:bestPizza',
    'novum')
    );

Obtain a route from a recognition:

//    public getRoute(
//        recognizerResult: { intent: string, entities?: Entity[] },
//        channel?: string
//    ): { id: string, showSuggestions: boolean }
const dialogConfig: {id: 'string', showSuggestion: boolean} = router.getRoute({intent: 'pizza'}, 'novum');

contextFilters

contextFilters are applied in the routing phase.

Context filter conditions will be checked using spleen library. These conditions can be as simple as 1 eq 1 (a context filter with this condition will be always executed) or can be more complex such as /authData/subscriptionType neq 'postpaid' (that will be executed when the subscription type of the user be different than postpaid). In this case, we only can check properties of AuraUserBaseModel.

More examples of context filters are included below:

If the user is anonymous, redirect it to intent intent.account.linking

{
  "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
    }
}

If the user is multimsisdn, send him a message

{
  "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
  }
}

If the user’s subscription type is postpaid, send him a message. In this example, we are checking user.authData.subscriptionType, because our user type is AuraUserBaseModel<FourthPlatformAuth>, so user.authData type is FourthPlatformAuth

{
  "name": "user_type_postpaid_not_allowed",
  "type": "user_type_filter",
  "conditions": "/authData/subscriptionType eq 'postpaid'",
  "true": {
    "name": "user_type_postpaid_not_allowed_action_true",
    "breakDialogExecution": true,
    "breakFilterEval": true,
    "resource": "bill:bill.balance.postpaid",
    "suggestions": true
  }
}

Docs:

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

Aura Bot databases

Description of databases used by Aura Bot

Introduction

Currently, aura-bot uses two databases, described below:

Mongo DB
Redis + MongoDB

MongoDB

In order to reuse the code, and clarify the development, all classes related with MongoDB connections are stored in the mongodb-storage.ts file within aura-bot-platform repository.

Here it can be found generic “connection” class, that is mongodb-connection.ts, that will handle the connection request, pooling them and configuring according the configuration (config is mandatory when initializing).

We can find also several “DAO” files, that will couple with a specific MongoDB database and collection, and will create optionally indexes or any other thing required in a specific domain.

MongoDbConnection

There will be only one instance of MongoDbConnection, creating it in the first call to getInstance (requiring config param) and returning the same instance in subsequent calls (where the config param is not required).

To create the instance properly, the following configuration variables are used:

Var name	Description	Required/Optional
AURA_MONGODB_URI	URI to connect to MongoDB, for example mongodb://localhost:27017/?authSource=admin	Required
AURA_MONGODB_USERNAME	User name to authenticate connection to MongoDB	Required
AURA_MONGODB_PASSWORD	Password to authenticate connection to MongoDB	Required
AURA_MONGODB_POOL_SIZE	MongoDB pool size	Optional (Default: 10)
AURA_MONGODB_SSL	Use SSL or not when connecting to MongoDB	Optional (Default: false)

This singleton module should be loaded the first time automatically by the system, and then could be accessed just by calling getInstance method, like:

const connection = await MongoDbConnection.getInstance();
const db = connection.dbConnect(DATABASE);
const collection = db.collection(COLLECTION);

MongoDbStorage

This DAO class will be used by Bot Builder v4 to store the conversation and user data. An index is created to delete documents older than 24 hours (specified by config var AURA_MONGODB_BOT_COLLECTION_CONTEXT_INDEX_TTL).

Following config variables are used to initialize this class:

Var name	Description	Required/Optional
AURA_MONGODB_BOT_DATABASE	Database name where the documents will be stored	Required
AURA_MONGODB_BOT_COLLECTION_CONTEXT	Collection name where the documents will be stored	Required
AURA_MONGODB_BOT_COLLECTION_CONTEXT_INDEX_TTL	Time (in seconds) that will exist the documents without updates, before being deleted	Optional (Default: 86440)

To create and initialize a MongoDbStorage, a code like following could be used:

const storage = await new MongoDbStorage().init(configuration);

Cache module

The cache module allows the generation of different types of cache:

AuraCacheLocal: only used for local data.
AuraCacheRemote: only used for remote data.
AuraCacheRemoteLocal: used for remote and local data, with priority for remote.
AuraCacheLocalRemote: used for local and remote data, with priority for local.

How to use cache module

It is possible to use any of the caches through the following commands:

// cache local.
const auraCacheLocal = new AuraCacheLocal('nameCacheLocal');
// cache remote.
const auraCacheRemote = new AuraCacheRemote('nameCacheRemote');
// cache local-remote
const auraCacheLocalRemote = new AuraCacheLocalRemote('nameCacheLocalRemote');
// cache remote-local.
const auraCacheRemoteLocal = new AuraCacheRemoteLocal('nameCacheRemoteLocal');

Variables for AuraCacheLocal

Only for local cache (AuraCacheLocal), it is possible to define a series of options:

stdTTL: standard TTL as number in seconds for every generated cache element. By default, 0 (0 = unlimited).
compressedData: data is to be compressed in remote cache. By default, false.
deleteOnExpire: boolean value that indicates whether variables will be deleted automatically when they expire or not. If true, the variable will be deleted. If false, the variable will remain. By default, true. You are encouraged to handle the variable upon the event expired by yourself.

const options = { stdTTL: 100, encryptData: true };
const auraCacheLocal = new AuraCacheLocal('nameCacheLocal', options);

Store a key

The following code sets a key value pair. It is possible to define a TTL (in seconds). It returns true on success.

const auraCacheLocal = new AuraCacheLocal('nameCacheLocal');
auraCacheLocal.set('key', 'value');

const auraCacheRemote = new AuraCacheRemote('nameCacheRemote');
await auraCacheRemote.set('key', 'value', 1800); // -> data expire at 30m.

Retrieve a key

The following code gets a saved value from the cache. It returns undefined if the value is not found or has expired. If the value is found, it returns an object with the corresponding key value pair.

const auraCacheLocal = new AuraCacheLocal('nameCacheLocal');
auraCacheLocal.set('key', 'value');
auraCacheLocal.get('key'); // -> value.

const auraCacheRemote = new AuraCacheRemote('nameCacheRemote');
await auraCacheRemote.set('key', 'value');
await auraCacheRemote.get('key'); // -> value.

For caches such as AuraCacheLocalRemote and AuraCacheRemoteLocal, it is possible to force it to obtain data different from the priority:

// cache local-remote
const auraCacheLocalRemote = new AuraCacheLocalRemote('nameCacheLocalRemote');
await auraCacheLocalRemote.set('key', 'value');
await auraCacheLocalRemote.getRemote('key'); // -> value.
auraCacheRemote.getLocal('key');
// cache remote-local.
const auraCacheRemoteLocal = new AuraCacheRemoteLocal('nameCacheRemoteLocal');
await auraCacheRemoteLocal.set('key', 'value');
auraCacheRemoteLocal.getLocal('key'); // -> value.
await auraCacheRemoteLocal.getRemote('key'); // -> value.

Delete a key

The following code deletes a key. It returns the number of deleted entries. A delete will never fail.

const auraCacheLocal = new AuraCacheLocal('nameCacheLocal');
auraCacheLocal.set('key', 'value');
auraCacheLocal.get('key'); // -> value.
auraCacheLocal.del('key'); // -> 1.
auraCacheLocal.get('key'); // -> undefined.

const auraCacheRemote = new AuraCacheRemote('auraCacheRemote');
await auraCacheRemote.set('key', 'value');
await auraCacheRemote.get('key'); // -> value.
await auraCacheRemote.del('key'); // -> 1.
await auraCacheRemote.get('key'); // -> undefined.

Flush all data

The following code deletes all data from a store.

const auraCacheLocal = new AuraCacheLocal('nameCacheLocal');
auraCacheLocal.set('key', 'value');
auraCacheLocal.get('key'); // -> value.
auraCacheLocal.flush(); // -> true.
auraCacheLocal.get('key'); // -> undefined.

const auraCacheRemote = new AuraCacheRemote('auraCacheRemote');
await auraCacheRemote.set('key', 'value');
await auraCacheRemote.get('key'); // -> value.
await auraCacheRemote.flush(); // -> true.
await auraCacheRemote.get('key'); // -> undefined.

Redis + MongoDB

If the configuration variable AURA_BOT_CONTEXT_DATABASE is set to REDIS-MONGODB, aura-bot uses a two-level cache to store the context through Aura Redis Mongo Synchronizer.

The following environment variables must be set for the two databases.

Variables

Var name	Description	Required/Optional
AURA_MONGODB_BOT_COLLECTION_CONTEXT	Name of the collection where the context is stored. By default: `aura-context`.	Required
AURA_MONGODB_BOT_DATABASE	Name of the database where the bot collections are stored. By default: `aura-bot`	Required
AURA_MONGODB_PASSWORD	Password of the MongoDB. Required	Required
AURA_MONGODB_POOL_SIZE	Pool size of the MongoDB. By default: `60`.	Required
AURA_MONGODB_SSL	Boolean value indicating if MongoDB connection uses SSL or not. By default: `true`.	Required
AURA_MONGODB_URI	URI of the MongoDB	Required
AURA_MONGODB_USERNAME	Username of the MongoDB	Required
AURA_REDIS_CONFIGURATION_PREFIX	Prefix for Redis configuration keys. By default: `aura-config:`	Required
AURA_REDIS_CONTEXT_CACHE_PREFIX	Prefix for Redis context cache keys. By default: `context:`	Required
AURA_REDIS_CONTEXT_CACHE_SHADOW_KEY_PREFIX	Prefix for Redis shadow key cache keys. By default: `shadow-key:`	Required
AURA_REDIS_CONTEXT_CACHE_ACTIVE_CONTEXT_PREFIX	Prefix for Redis active context cache keys. By default: `active-context:`	Required
AURA_REDIS_CONTEXT_CACHE_SHARD_COUNT	Number of shards to generate lists for storing unprocessed context.	Required
AURA_REDIS_CONTEXT_CACHE_TTL	Time in seconds to store a context in cache. By default: `60`.	Required
AURA_REDIS_MODE	Mode of Redis distribution (`Cluster`, `Sentinel` or `Single`). By default: `Single`.	Required
AURA_REDIS_PREFIX	Prefix that will be used by all redis keys when using redis-connector. This allow mixing in a single redis service messages coming from different environments in the same Azure subscription.	Required
AURA_REDIS_SENTINEL_INSTANCE_NAME	Name of the Redis instance. Use in sentinel mode.	Optional
AURA_REDIS_HOSTS	A string with list of nodes (host:port) separate by comma. For example: “localhost:port,localhost2:port2”. Default: ‘127.0.0.0:6379’	Required
AURA_REDIS_DATABASE	Database number for `Single` or `Sentinel` mode. By default: `0`.
AURA_REDIS_PASSWORD	A string with the password of Redis.	Required
AURA_REDIS_MAX_RECONNECT_RETRIES	Number of retries to connect to Redis. By default: `25`.	Required
AURA_REDIS_MAX_RECONNECT_INTERVAL	Time in milliseconds to wait before reconnecting to Redis. By default: `5000`.	Required
AURA_REDIS_USE_CONNECTION_POOL	Used connection pool for Redis connections. Default: `true`.	Required
AURA_REDIS_CONNECTION_POOL_MIN	Minimum number of connections in the pool. Default: `2`.	Required
AURA_REDIS_CONNECTION_POOL_MAX	Maximum number of connections in the pool. Default: `100`.	Required