Aura – aura-root

Docs:

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

Direct Line flowcharts

Request a new accessToken from Direct Line to access Aura

These steps must be executed before starting the user conversation with Aura. The token to access Direct Line must be requested to Aura because one of the admin secrets of the bot Direct Line configuration is used to generate the tokens.

@startuml
    title: Request a DirectLine accessToken for AuraGroot
    participant Channel #bdf492
    participant DirectLine #FFCC99
    participant DirectLineWebsocket #FFCC99
    participant AuthenticationApi #FFFF99

    Channel -> AuthenticationApi: POST /aura-services/v1/token/wss
    AuthenticationApi -> DirectLine: POST /token
    DirectLine -> AuthenticationApi: 201 Created {token}
    AuthenticationApi -> Channel: 201 Created {token}
    Channel -> DirectLine: Open WebSocket
    Channel -> DirectLine: Start sending user requests
    Channel -> DirectLineWebSocket: Start getting Aura responses
@enduml

New Direct Line message from anonymous users

An anonymous user is the one that has never been authenticated via Kernel and her authentication session has not been stored in aura-authentication-api.

Find more information in the document Channels authentication: anonymous users

@startuml

title: Basic flow for DirectLine anonymous users


    actor User
    participant Channel #bdf492
    participant DirectLine #FFCC99
    participant DirectLineWebsocket #FFCC99
    participant AuthenticationApi #FFFF99
    participant AuraGroot #76bbe7
    participant AuraBot #41a0f9 

    Channel -> DirectLineWebsocket: Open WebSocket
    User -> Channel: Send [message]
    Note over Channel,DirectLine: The previously created token of DirectLine must be sent in the Authorization header as Bearer token.
    Channel -> DirectLine: Send {activity[message]}
    DirectLine -> AuraGroot: Send {activity[message]}
    AuraGroot -> DirectLine: 200 OK
    note right of AuraGroot: KPI entities are stored during Middlewares execution in local memory.\nEvery 2 minutes and before closing a POD, they are written in Azure Storage.
    AuraGroot -> AuraGroot: Middlewares
    AuraGroot -> AuraGroot: Recognizers (GetSkillByChannel)
    AuraGroot -> AuraBot: Send {activity[message]}
    Note over AuraGroot,AuraBot: There are two different conversations: one between the channel and AuraGroot and another one between AuraGroot and the skill.
    AuraBot -> AuraGroot: 200 OK
    AuraBot -> AuthenticationApi: GET AuraId
    AuthenticationApi -> AuraBot: 404 Not found (Anonymous)
    AuraBot -> AuraBot: Middlewares
    note right of AuraBot: KPI entities are stored during Middlewares execution in local memory.\nEvery 2 minutes and before closing a POD, they are written in Azure Storage.
    AuraBot -> AuraBot: Recognizers
    AuraBot -> AuraBot: Main Dialog
    AuraBot -> AuraBot: Execute Specific functional Dialog
    AuraBot -> AuraGroot: Send {responseActivity}
    AuraGroot -> AuraBot: 200 OK
    AuraGroot -> DirectLine: Send {responseActivity}
    DirectLine -> AuraGroot: 200 OK
    Channel -> DirectLineWebsocket: Read {responseActivity}
    Channel -> User: Show {responseActivity}
@enduml

New Direct Line message from authenticated users

Find information regarding users’ authentication in the document Channels authentication: authenticated users.

@startuml

title: Basic flow for DirectLine authenticated users

    actor User
    participant Channel #bdf492
    participant DirectLine #FFCC99
    participant DirectLineWebsocket #FFCC99
    participant AuthenticationApi #FFFF99
    participant AuraGroot #76bbe7
    participant AuraBot #41a0f9 
    participant KernelAuthServer #99FFFF
    participant KernelUserProfileApi #99FFFF
    
    Channel -> DirectLineWebsocket: Open WebSocket
    User -> Channel: Send [message]
    Note over Channel,DirectLine: The previously created token of DirectLine must be sent in the Authorization header as Bearer token.
    Channel -> DirectLine: Send {activity[message]}
    DirectLine -> AuraGroot: Send {activity[message]}
    AuraGroot -> DirectLine: 200 OK
    Note right of AuraGroot: KPI entities are stored during Middlewares execution in local memory.\nEvery 2 minutes and before closing a POD, they are written in Azure Storage.
    AuraGroot -> AuraGroot: Middlewares
    AuraGroot -> AuraGroot: Recognizers (GetSkillByChannel)
    AuraGroot -> AuraBot: Send {activity[message]}
    Note over AuraGroot,AuraBot: There are two different conversations: one between the channel\nand AuraGroot and another one between AuraGroot and the skill.
    AuraBot -> AuraGroot: 200 OK
    opt user is not in cache
        AuraBot -> AuthenticationApi: GET AuraId
        AuthenticationApi -> AuraBot: 200 OK {userData}
        AuraBot -> KernelAuthServer: POST /token
        Note over AuraBot,KernelAuthServer: Here, a 3legged accessToken is requested
        KernelAuthServer -> AuraBot: {token}
        AuraBot -> KernelAuthServer: getIntrospect(token)
        opt channel allows UserProfile
            AuraBot -> KernelUserProfileApi: getUserProfile(userId)
            KernelUserProfileApi -> AuraBot: UserProfile
        end
        AuraBot -> AuraBot: store user in cache: userData, userProfile, valid scopes and purposes
    end
    AuraBot -> AuraBot: Middlewares
    Note right of AuraBot: KPI entities are stored during Middlewares execution in local memory.\nEvery 2 minutes and before closing a POD, they are written in Azure Storage.
    AuraBot -> AuraBot: Recognizers
    AuraBot -> AuraBot: Main Dialog
    AuraBot -> AuraBot: ValidateAuthenticationForDialog
    AuraBot -> AuraBot: Execute Specific functional Dialog
    AuraBot -> AuraGroot: Send {responseActivity}
    AuraGroot -> AuraBot: 200 OK
    AuraGroot -> DirectLine: Send {responseActivity}
    DirectLine -> AuraGroot: 200 OK
    Channel -> DirectLineWebsocket: Read {responseActivity}
    Channel -> User: Show {responseActivity}
@enduml

Docs:

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

Aura Groot metrics

List of metrics available in Aura Groot

http_request_duration_seconds

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

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-groot until its HTTP response is returned, indicating to the client that Aura is processing the request to obtain a proper answer for the Direct Line or aura-bridge.

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

outgoing_request_duration_seconds

This metric is intended to store the processing time related to all the outgoing HTTP requests made by aura-groot.

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

outgoing_message_duration_seconds

This metric is intended to store the processing time of Direct Line or aura-bridge requests arriving to aura-groot.

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

As aura-goot 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-groot 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 (Direct Line or aura-bridge).
channel: channel of the request.

incoming_message_duration_seconds

This metric is intended to store the processing time of Direct Line, aura-bridge or skills requests arriving to aura-groot.

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

As aura-goot 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 channel or skill is sent back to the client callback. This metric measures the duration from when the request arrives at aura-groot until it is processed to send to the channel/bridge or skill.

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 (Direct Line, aura-bridge or skill name). If origin is missing, the content of path label will be added.
channel: channel of the request.

aura_component_version

This metric is intended to store the number of aura-groot 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.

aura_server_unhandled_error

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

It is stored as a Counter in Prometheus.

Labels:

error: exception message that forced the unhandled error.

skill_access_error

This metric is intended to store the number of times a skill has been misconfigured in aura-groot.

It is stored as a Counter in Prometheus.

Labels:

skill: skill name.
code: noRespond or noFound
channel: channel of the request.

skill_request_status

This metric is intended to store the number of times we have obtained a response status per skill in aura-groot.

It is stored as a Counter in Prometheus.

Labels:

skill: skill name.
code: status code of the request.
channel: channel of the request.

skill_response_error

This metric is intended to store the number of times a skill has been blocked in aura-groot.

It is stored as a Counter in Prometheus.

Labels:

skill: skill name
code: blocked
channel: channel of the request.

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

Guidelines for the connection of a skill to Aura Root

Detailed process for the connection of a skill to Aura Root

Introduction

The process for the connection of a skill to Aura Root is common for the three types of skills defined before.

⚠️ It is only important to take into account that, for third-party bots, constructors must previously develop a third-party adapter to communicate the bot with Aura Root (that is, to make it compatible with Microsoft Bot Framework protocol). After doing that, the connection of the bot with Aura Root follows the same common steps as for other types of skills.

Prerequisites

The following previous tasks are required for the further connection of a skill with Aura Root:

We have a skill already developed and published
There is a channel routed by Aura Root to this skill

1. Register a skill in Aura

In order to activate a skill in Aura, make a POST request to the skills module of aura-configuration-api through the corresponding swagger.

https://<environment>.auracognitive.com/aura-services/v2/configuration/skills

The fields in the request are shown below:

id: Unique identifier of the skill. It can be generated with UUID Generator Tool by OB operator.
name: name of the skill by OB operator.
channels: array of strings including the name of the channel(s) associated with the skill.
appId: Microsoft appId
skillEndpoint: endpoint where the skill is published
external: Boolean value indicating if the skill is deployed in the same environment as aura-groot or not.
- If true, the skill is deployed in a different environment.
- If false or this parameter is not existing, then the skill is deployed in the same environment.

ℹ️ NOTE: Both the id and the name of the skill must be assigned by the OB operator, and they must ensure that they are unique in order to avoid collisions.

Check the following example of a request body:

{
    "id": "544bf5c0-9f31-45e3-9f08-89230315e520",
    "name": "skill-name",
    "channels": [
        "channel-name"
    ],
    "appId": "ms-azure-app-id",
    "skillEndpoint": "http://url-to-skill-bot/api/messages",
    "external": true //Only present if the skill is not in the same environment of Aura Groot
}

2. Make changes available in Aura Groot

In order to update Aura Groot configuration with the modifications carried out, at this stage it is required to restart this component. Depending on the enviroment, there are two possible scenarios.

2.1. Connect to skill in a local environment

In these cases, it only will be neccessary to restart aura-groot component in local enviroment to connect to new skill. The instance can be started using the following command for running aura-groot in local environment: npm start

2.2. Connect to skill in a production environment

In Aura production environments, it will not be necessary to restart the component to update the skills configuration. This connection is done automatically through the config-watcher.

The config-watcher runs periodically (every 5 minutes) and, when it detects that the configuration has been modified in aura-configuration-api, it will automatically restart the pods.

Alternative: Use the /refresh endpoint

⚠️ Use this manual process only if you cannot wait for the automatic execution of the config-watcher

In order to connect the skill in production environment in a manual way (only in the above-mentioned scenario), the /refresh endpoint of aura-groot allows the update of the new configuration without restarting the component.

Two different scenarios can arise here:

Update all configuration parameters

Make a port-forward to both aura-groot pods (one request per pod)

kubectl port-forward aura-groot-#### -n <namespace> 8080:8080

The request to the endpoint with post-forward is shown below:

curl --location --request POST 'localhost:8080/refresh'

Update ONLY skills/channels information

If we only want to update skills and/or channels information, send the parameters in the message body:

    curl --location --request POST 'localhost:8080/refresh' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "changes": ["skills", "channels"] // use "skills" and/or "channels" or neither of them
    }'

Docs:

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

Introduction to Aura Root

The current document includes an overview of Aura Root and general information regarding this Aura Virtual Assistant functional component.

Moreover, it includes links to low-level technical documentation for highly-skilled technicians.

Introduction

Aura Root constitutes the core functional block of Aura Virtual Assistant and is responsible for connecting channels with skills (bots).

It carries out the following key tasks:

Receives requests from the channels.
If required, it adapts the incoming request from a channel that Aura is able to understand through an adapter.
Makes the decision about what is the best skill (bot) to answer the user’s request and routes this petition to the corresponding domain bot in a routing component. Currently, routing is only done by channels or channels groups.
Is able to enrich both the request and the answer with additional information coming from Aura context and different models in a enrichment module. (In the current version, no enrichment is available).
Can have multiple skills connected, and one of them could be the current aura-bot functioning as a skill.
Generates entities files with relevant information regarding each interaction, that will be afterwards uploaded to Kernel.

Aura Root functional components

From a functional point of view, Aura Root includes the following features:

Routing

The user’s request is routed to a specific skill (domain bot) able to best respond to this query.

Currently, routing is done only by channels or group of channels (no configuration options are available).

Channel adapter

If the channel does not support a language that Aura understands (Microsoft Direct Line protocol), an adapter is required to establish the communication.

Enrichment

Enrichment adds additional data to enrich both request and response through context information, algorithms, analytical models, insights, etc.

This feature will be available in further releases.

Aura Root technical components

As explained before, Aura Root is a functional representation in order to make the new architecture more understandable for readers.

The technical component that manages the functionalities above defined is aura-groot.

Docs:

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

Guidelines for the connection of a skill to Aura Minigroot

Detailed process for the connection of a skill to Aura Minigroot

Introduction

After the development of a skill, it can be tested easily using a tool created by Aura Global Team: Aura Minigroot.

⚠️ Aura Minigroot works together with the already existing Aura minibot, in fact constituting a unique tool. Both will be provided as docker images and must be installed jointly.

The following sections show the detailed guidelines for the connection of a skill to Aura Minigroot.

Prerequisites

The following previous tasks are required for the further connection of a skill with Aura Minigroot:

There is a skill already developed and running (in this example the skill will be running in localhost)
Aura minibot is already configured and running. You can follow the steps in Aura Minibot user guide.

1. Configure your new skill

To allow aura-groot to redirect activities to a new skill, configure it in:
/mock-configuration/mocks/mock-files/skills-configuration-mock.json.

In this example, we are going to redirect the channel novum-mytelco (you can use a new channel if you want, but you will have to add it to channels-configuration-mock.json):

To do this, the following steps were taken:

Delete the channel novum-mytelco from the first skill (Aura minibot) channels list and add it to our new skill called aura-bot-ext.
Configure the Microsoft appId of our skill, a new skill id (random uuid) and the skillEndpoint.
To access localhost from a docker container, we use host.docker.internal instead localhost.

NOTE: If you use linux, maybe you should also add extra_hosts: "host.docker.internal:host-gateway" to aura-groot in your docker-compose file.

2. User mock configuration

To access this skill, we are going to use anonymous users.

As Aura Minigroot also mocks anonymous users, we need to update the mock data to redirect the mocked anonymous user to our skill setting his channel to 45494a5b-835a-4fff-a813-b3d2be529dbe (the channelId of novum-mytelco):

With this change, all the users not mocked in authentication-mock.json will be redirected to our new skill.

3. Restart the mini-groot

After these changes, you have to restart your Aura Minigroot container to refresh the configurations.

When the container restarts, you should have your new skill working with Aura Minigroot.

Docs:

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

Aura Bot Common library

Aura Bot common is a core library that contains utilities for the integration of different components with Aura

Introduction

Aura Bot common is a helper library published in NPM that includes useful utilities to handle conversations both in aura-bot and in the dialogs.

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

The Aura Bot common library holds models and utility code shared between aura-bot and the libraries. It contains two different types of methods: external and internal, which are described in the following sections.

Aura utils: generic tools to manage dialogs and prompts.
Bridge utils: tools for aura-bridge management.
Aura channelData utils: utilities for managing aura-bot channelData.
Aura context utils: utilities with methods for managing the BotFramework TurnContext.

Docs:

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

Aura request-response semantic model

This section describes the Aura request-response semantic model, which makes it possible for external software components, application and services to speak a language Aura can understand using the Direct Line API

Aura Virtual Assistant component

Introduction

The Direct Line API provides the connectivity between any external software component, service, channel or application and Aura skills.

Anyhow, having a connection means is typically not enough, as a proper understanding and semantics are needed between the communicating parties regarding the data being intercommunicated. In order to improve the communication of Aura with services or channels being integrated into the Microsoft Azure Bot Service and Bot Framework, two concepts come into play:

Activities
Fixed JSON format. This fixed JSON format includes a JSON property called channelData, which channel developers and integrators can use to encode channel-specific data in JSON format and its corresponding semantics.

In this framework, we introduce the so-called Aura Request - Response Semantic Model. This semantic model makes it possible for external software components, application and services to speak a language Aura can understand using the DirectLine API.

Currently, this semantic model is used both for the communication of channels with aura-groot and for the communication of aura-groot with skills in two Aura communication protocols:

Within the Aura Request - Response Semantic Model, two key properties will be fully described throughout these documents:

The general-purpose channel-specific channelData property is the one used by Aura to define the model. When a message is sent from a channel, part of that message is specific to the channel/service and it allows aura-groot and skills to communicate correctly with it.
The payload property can be used by an external component to facilitate the sharing of information between the channels, aura-groot and the skills in order add extra information associated with the channel and, consequently, enrich the request.

Versioning

Aura supports different versions of the Aura Request - Response Semantic Model.

channelData v1

In older Aura Platform releases, the default version was version 1, so some channels did not send the version of the channelData and aura-bot handled their requests as version 1.0.0.

There is an exception: in release Aerosmith, aura-bot included Living Apps handling as a platform feature.

➡️ Access to channelData v1 documentation

channelData v2

Afterwards, version 2 was created to extend the channelData property with new fields, such as actions and status, that with the regular communications with the channels are not needed or, in the case of the actions, are solved by other ad-hoc means.

In Greenday (6.0.1) release, Aura included a WhatsApp connector, the so-named aura-bridge and also channelData version 2 was used to access and to use the extra features of actions and status.

In these Aura Platform releases until Iron Maiden, aura-bot included a lazy definition of the channelData model, so, in fact, it handled almost a different version per channel.

➡️ Access to channelData v2 documentation

channelData v3

From Iron Maiden (7.2.0) onwards, we introduce the so-called channelData normalized version (version 3), an enriched version of channelData with new fields that provide a complete schema definition. This will enforce all channels to use the very same schema to access aura-groot.

➡️ Access to channelData v3 documentation