Aura Groot

• 1: Environment variables
• 2: Middlewares
• 2.1: Channeldata validator middleware
• 2.2: User middleware
• 3: Recognizers
• 3.1: Domain recognizer
• 3.2: Intent result recognizer
• 4: Operational flows
• 5: Databases

sequenceDiagram
title: BEFORE-DIRE-STRAITS

    actor Channel
    participant AuraGroot #ebdff7
    participant AuraBot #ebdff7

    Channel ->> AuraGroot: request message1
    AuraGroot ->> AuraGroot: create targetSkill in groot-channel
    AuraGroot ->> AuraGroot: save conversationReference in groot-channel
    AuraGroot ->> AuraBot: request message1
    AuraBot -->> AuraGroot: response message1
    AuraGroot ->> AuraGroot: load conversationReference in groot-channel
    AuraGroot -->> Channel: response message1
    AuraBot -->> AuraGroot: response endOfConversation
    AuraGroot ->> AuraGroot: load conversationReference in groot-channel
    AuraGroot ->> AuraGroot: delete targetSkill

    Channel ->> AuraGroot: request message2
    AuraGroot ->> AuraGroot: create targetSkill in groot-channel
    AuraGroot ->> AuraGroot: save conversationReference in groot-channel
    AuraGroot ->> AuraBot: request message2
    AuraBot -->> AuraGroot: response message2
    AuraGroot ->> AuraGroot: load conversationReference in groot-channel
    AuraGroot -->> Channel: response message2
    AuraBot -->> AuraGroot: response endOfConversation
    AuraGroot ->> AuraGroot: load conversationReference in groot-channel
    AuraGroot ->> AuraGroot: delete targetSkill

1 - Environment variables

Aura Groot environment variables

2 - Middlewares

Aura Groot middlewares

Introduction

The current document describes the different middlewares that are part of aura-groot

init-middleware

This middleware is in charge of setting the initial context values (userData accessor, conversationData accessor, correlator) for the rest of the middlewares/handlers.

user-middleware

In this middleware, the user is checked and stored in context for the following middlewares/handlers.

Find detailed information in user-middleware documentation.

channeldata-validator-middleware

This middleware validates input channelData activities and throws an error if something is wrong.

Find more information in channeldata-validator-middleware documentation.

2.1 - Channeldata validator middleware

Channeldata validator middleware

Introduction

The source code of this middleware is included in this Github repository.

This middleware will check if the channelData of the incoming request is valid or not. This validation is made:

• If the environment variable AURA_CHANNELDATA_VALIDATION is set to true.
• If the incoming channelData version is greater or equal than AURA_CHANNELDATA_VALIDATION_MIN_VERSION.
• If a validator for this version exists. Validators are loaded using schemas stored in aura-models package.

If the validation is ok or is not executed because one or more of the previous conditions are not satisfied, aura-groot continues the normal flow, executing the rest of middlewares.

If the validation fails, the error message core:core.model-validation.request.error will be returned to the user and no more middlewares will be executed.

2.2 - User middleware

User middleware

Introduction

user-middleware is the middleware in charge of validating auraId and channel.

This is needed in aura-groot because routing is currently done by channel, so if the request does not include channelId (mandatory only in channelData v3), the user must be checked in aura-authentication-api to obtain the channel of this user.

This middleware throws an error if there is not activity.from.id or if some error is returned by aura-authentication-api (except 404, because anonymous users should continue the flow).

This middleware also handles a basic user’s cache to avoid unnecessary calls to aura-authentication-api with every user’s request. This cache is implemented using bot UserState.

3 - Recognizers

Aura Groot recognizers

Introduction

The current documents describe the different recognizers that are part of aura-groot.

They are listed below:

• domain-recognizer
  This recognizer is in charge of identifying the domain of the user’s input.

• intent-result-recognizer
  This recognizer is in charge of registering of intent result.

3.1 - Domain recognizer

Domain recognizer

Introduction

domain-recognizer is the aura-groot recognizer in charge of identifying the domain in the user’s input request.

This is possible thanks to the mapping of the list of channels and skills that is done at server start-up. A skill can have several associated channels, but a channel can only have one associated skill.

Example:

GOOD
channel1 => skill1
channel2 => skill1
channel3 => skill2

BAD
channel1 => skill1
channel2 => skill2
channel2 => skill1 -> This is not possible

When a user writes through a channel:

• The domain to which the channel belongs is identified
• The skill associated with that domain is executed
• The domain is registered in KPIs

If the recognition of the domain fails, the user will be returned the error message root:skill.not.found.

3.2 - Intent result recognizer

Intent result recognizer

Introduction

intent-result-recognizer is the recognizer in charge of the registration of the intent result.

This recognizer is executed after the execution of the middlewares and before sending a message to user. It is also in charge of registering the result of the intent in KPIs.

It receives information from the skill in the following way:

activity: {
    channelData: {
        payload: {
            skill: {
                intentResult: {
                    name: string,
                    entities: [
                        entity: string,
                        type: string
                    ]
                }
            }
        }
    }
}

4 - Operational flows

Aura Groot operational flows

Introduction

The current document includes the main operational flows in the aura-groot component.

Blocked skill

This flow describes the control of the messages received by aura-groot from the skill and the sending of the error message to the user in case the skill does not respond.

sequenceDiagram
title: BLOCKED-SKILL

    actor Channel
    participant AuraGroot #ebdff7
    participant AuraBot #ebdff7

    Channel ->> AuraGroot: request message1
    AuraGroot ->> AuraGroot: create skillConversation1, begin timeout in targetSkill
    AuraGroot ->> AuraBot: request message1
    AuraBot -->> AuraGroot: response message1
    AuraGroot ->> AuraGroot: delete timeout, update targetSkill
    AuraGroot -->> Channel: response message1
    AuraBot -->> AuraGroot: response endOfConversation
    AuraGroot ->> AuraGroot: delete targetSkill

    Channel ->> AuraGroot: request message2
    AuraGroot ->> AuraGroot: create skillConversation2, begin timeout in targetSkill
    AuraGroot ->> AuraBot: request message2
    Channel -->> AuraGroot: request message3
    AuraGroot ->> AuraGroot: control timeout (active targetSkill)

    alt timeout targetSkill < TIMEOUT
        AuraGroot ->> AuraBot: request message3
        AuraBot -->> AuraGroot: response message2
        AuraGroot ->> AuraGroot: delete timeout, update targetSkill
        AuraGroot -->> Channel: response message2

        AuraBot -->> AuraGroot: response message3
        AuraGroot ->> AuraGroot: delete timeout, update targetSkill
        AuraGroot -->> Channel: response message3
        AuraBot -->> AuraGroot: response endOfConversation message2
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraBot -->> AuraGroot: response endOfConversation message3
        AuraGroot ->> AuraGroot: discard endOfConversation in conversation2
    end

    alt timeout targetSkill > TIMEOUT
        AuraGroot -->> Channel: Error
        AuraGroot ->> AuraGroot: begin timeout, in targetSkill
        AuraGroot ->> AuraBot: request message3
        AuraBot -->> AuraGroot: response message2
        AuraGroot ->> AuraGroot: delete timeout, update targetSkill
        AuraGroot -->> Channel: response message2
        AuraBot -->> AuraGroot: response endOfConversation message2
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraBot -->> AuraGroot: response message3
        AuraGroot ->> AuraGroot: discard delete timeout in targetSkill
        AuraGroot -->> Channel: response message3
        AuraBot -->> AuraGroot: response endOfConversation message3
        AuraGroot ->> AuraGroot: discard endOfConversation in targetSkill
    end

Use case with asynchronous calls

This diagram describes the flow of a user’s request that is resolved through a dialog with asynchronous calls.

Further information regarding how asynchronous APIs are handled by Aura can be found in the Guidelines for building a dialog that uses async APIs.

sequenceDiagram
title: MESSAGE_ASYNC_USECASE
    actor User
    User ->> WA: User request
    WA ->> 4P: User request
    4P ->> AuraBridge: User request
    AuraBridge ->> 4P: 200 OK
    AuraBridge ->> AuraGroot: User request
    AuraGroot ->> AuraBridge: 200 OK
    AuraGroot ->> AuraGroot: create skillConversation1, begin timeout in targetSkill
    AuraGroot ->> AuraSkill: User request
    AuraSkill ->> AuraGroot: 200 OK
    AuraSkill ->> AuraSkill: basic whatsapp flow
    AuraSkill ->> LocalDialog: message
    LocalDialog ->> 4P: request async + callback bridge
    4P ->> LocalDialog: 200 OK
    Note right of 4P: when 4p finishes the request sends the response to the indicated callback (AuraBridge)
    4P ->> AuraBridge: response request async
    AuraBridge ->> 4P: 200 OK
    AuraBridge ->> AuraGroot: response request async
    AuraGroot ->> AuraBridge: 200 OK
    Note right of AuraBridge: the response is sent as payload
    AuraGroot ->> AuraGroot: control timeout
    alt targetSkill.timeout < TIMEOUT
        AuraGroot ->> AuraSkill: response request async
        AuraSkill ->> AuraGroot: 200 OK
        AuraSkill ->> LocalDialog: response request async
        LocalDialog ->> LocalDialog: process response
        LocalDialog ->> AuraSkill: response processing
        AuraSkill ->> AuraGroot: async response processed
        AuraSkill ->> AuraGroot: response endOfConversation
        AuraGroot ->> AuraSkill: 200 OK
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraGroot ->> AuraGroot: delete skillConversation1
        AuraGroot ->> AuraBridge: async response processed
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: async response processed
        4P ->> AuraBridge: 200 OK
        4P ->> WA: async response processed
        WA ->> User: async response processed
    else
        AuraGroot ->> AuraBridge: error
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: async error
        4P ->> AuraBridge: 200 OK
        4P ->> WA: error
        WA ->> User: error
        AuraGroot -> AuraSkill: request async endOfConversation
        AuraGroot -> AuraGroot: delete skillConversation1
        AuraGroot -> AuraGroot: create skillConversation2, begin timeout in targetSkill
        AuraGroot ->> AuraSkill: response request async
        AuraSkill ->> AuraGroot: 200 OK
        AuraSkill ->> AuraSkill: Not recognize
        AuraSkill ->> AuraGroot: none
        AuraSkill ->> AuraGroot: response endOfConversation
        AuraGroot ->> AuraSkill: 200 OK
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraGroot ->> AuraGroot: delete skillConversation2
        AuraGroot ->> AuraBridge: none
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: none
        4P ->> AuraBridge: 200 OK
        4P ->> WA: none
        WA ->> User: none
    end

Use case with files sending by the user

This diagram describes the flow of a use case that includes sending a file by the user (WhatsApp channel).

Further information regarding how to receive a file from the user can be found in:

• file-manager recognizer.
• How to configure a use case to receive a file from the user.

sequenceDiagram
title: MESSAGE_FILE_USECASE
    User ->> WA: Phrase to init UC file dialog
    WA ->> 4P: Phrase to init UC file dialog
    4P ->> AuraBridge:Phrase to init UC file dialog
    AuraBridge ->> 4P: 200 OK
    AuraBridge ->> AuraGroot: Phrase to init UC file dialog
    AuraGroot ->> AuraBridge: 200 OK
    AuraGroot ->> AuraGroot: create skillConversation1, begin timeout in targetSkill
    AuraGroot ->> AuraSkill: Phrase to init UC file dialog
    AuraSkill ->> AuraGroot: 200 OK
    AuraSkill ->> AuraSkill: Basic whatsapp flow for authenticated user
    AuraSkill ->> FileDialog: Start UC file dialog
    FileDialog ->> AuraSkill: Send me a file
    AuraSkill ->> AuraGroot:  Send me a file
    AuraGroot ->> AuraSkill: 200 OK
    AuraGroot ->> AuraGroot: delete timeout in targetSkill
    AuraGroot ->> AuraBridge: Send me a file
    AuraBridge ->> AuraGroot: 200 OK
    AuraBridge ->> 4P: Send me a file
    4P ->> AuraBridge: 200 OK
    4P ->> WA: Send a file
    WA ->> User: Send a file
    User ->> WA: Send the attachment
    WA ->> 4P: Send the attachment
    4P ->> AuraBridge: Send the attachment
    AuraBridge ->> 4P: 200 OK
    AuraBridge ->> AuraGroot: Send the attachment
    AuraGroot ->> AuraBridge: 200 OK
    AuraGroot ->> AuraSkill: Send the attachment
    AuraSkill ->> AuraGroot: 200 OK
    AuraSkill ->> FileApi: Validate / process the attachment
    FileApi ->> AuraBot: 200 OK
    FileApi ->> AuraBridge: Attachment processed, validated and ready (async-callback)
    AuraBridge ->> FileApi: 200 OK
    AuraBridge ->> AuraGroot: Send attachment processed
    AuraGroot ->> AuraBridge: 200 OK
    AuraGroot ->> AuraGroot: control timeout
    Note right of AuraSkill: we could control that it is a system message, but the case would be the same if a message from the user arrives before the asynchronous response
    alt targetSkill.timeout < TIMEOUT
        AuraGroot ->> AuraSkill: Send attachment processed
        AuraSkill ->> AuraGroot: 200 OK
        AuraGroot ->> FileDialog: Send attachment processed
        FileDialog ->> FileDialog: process attachment
        FileDialog ->> AuraSkill: response processed attachment
        AuraSkill ->> AuraGroot: response processed attachment
        AuraSkill ->> AuraGroot: response endOfConversation
        AuraGroot ->> AuraSkill: 200 OK
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraGroot ->> AuraGroot: delete skillConversation1
        AuraGroot ->> AuraBridge: response processed attachment
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: response processed attachment
        4P ->> AuraBridge: 200 OK
        4P ->> WA: response processed attachment
        WA ->> User: response processed attachment
    else
        AuraGroot ->> AuraBridge: error
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: async error
        4P ->> AuraBridge: 200 OK
        4P ->> WA: error
        WA ->> User: error
        AuraGroot -> AuraSkill: request endOfConversation
        AuraGroot -> AuraGroot: delete skillConversation1
        AuraGroot -> AuraGroot: create skillConversation2, begin timeout in targetSkill
        AuraGroot ->> AuraSkill: response processed attachment
        AuraSkill ->> AuraGroot: 200 OK
        AuraSkill ->> AuraSkill: UnexpectedFile
        AuraSkill ->> AuraGroot: UnexpectedFile
        AuraSkill ->> AuraGroot: response endOfConversation
        AuraGroot ->> AuraSkill: 200 OK
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraGroot ->> AuraGroot: delete skillConversation2
        AuraGroot ->> AuraBridge: UnexpectedFile
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: UnexpectedFile
        4P ->> AuraBridge: 200 OK
        4P ->> WA: UnexpectedFile
        WA ->> User: UnexpectedFile
    end

Handover use case

This diagram describes the flow of the handover use case.

Further information regarding about handover use case handover-genesys dialog.

sequenceDiagram

title: handover
actor Channel
participant Bridge #ebdff7
participant AuraGroot #ebdff7
participant AuraBot #ebdff7
participant Genesys #ebdff7

Channel ->> AuraGroot: request message1
AuraGroot ->> AuraGroot: create skillConversation1, begin timeout in targetSkill
AuraGroot ->> AuraBot: request message1
AuraBot -->> AuraGroot: response message1
AuraGroot ->> AuraGroot: delete timeout in targetSkill
AuraGroot -->> Channel: response message1
AuraBot -->> AuraGroot: response endOfConversation
AuraGroot ->> AuraGroot: delete targetSkill
AuraBot ->> Genesys: request chat "init"
Genesys ->> AuraBot: response chat "init"
AuraBot ->> Genesys: message history
Genesys ->> AuraBot: response message history
Genesys -->> Bridge: pushNotification: starter messages with genesys

Bridge ->> AuraGroot: request message2
AuraGroot ->> AuraGroot: create skillConversation2, begin timeout in targetSkill
AuraGroot ->> AuraBot: request message2
AuraBot -->> AuraGroot: response message2
AuraGroot ->> AuraGroot: delete timeout in targetSkill
AuraGroot -->> Bridge: response message2
Bridge -->> Channel: response message2
AuraBot -->> AuraGroot: response endOfConversation
AuraGroot ->> AuraGroot: delete targetSkill

5 - Databases

Aura Groot databases

Introduction

Currently, aura-groot 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 storage are stored in the mongodb-storage.ts file within aura-bot-common repository.

MongoDbStorage

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

The following aura-groot environment variables are used to initialize this class:

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

    const storage = await MongoDbStorage.create(
            this.configuration.AURA_MONGODB_BOT_DATABASE,
            this.configuration.AURA_MONGODB_BOT_COLLECTION_CONTEXT,
            () => ConfigurationManager.instance.get('AURA_MONGODB_BOT_COLLECTION_CONTEXT_INDEX_TTL')
        );

Aura Groot cache module

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

• MetricCache: used for remote and local data. Is a TwoLevelsCache.

How to use cache module

This cache stores the timestamp when a request from the channel arrives at the aura-groot and is retrieved after the skill’s response to calculate the duration in the KPI GrootMessageEntity.

Variables for AuraGrootCache

The following aura-groot environment variables are used to initialize this class:

Example of data storage:

{
    "_id" : "64d0e9608a473f63c8bda87b",
    "correlator" : "6eea808b-30f8-4358-9859-cd42892a962b",
    "data" : [
        2339137,
        419794024
    ],
    "lastAccess" : "2023-08-07T12:53:52.370Z"
}

Redis + MongoDB

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

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

Variables