Processes

• 1: Users authentication
• 1.1: Authentication flow
• 1.2: Users types
• 1.3: Login redirections
• 1.4: Terms & Conditions
• 2: Conversational flow
• 3: channelData management
• 3.1: Handling channelData versions
• 3.2: channelData mapping
• 3.3: channelData validations

1 - Users authentication

Users authentication

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.

1.1 - Authentication flow

Aura authentication flow

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:

1. Validate that the Direct Line token is a valid one, generated by the bot instance running behind aura-bot.

2. 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":[

   ]
}

1.2 - Users types

Aura users types

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.

1.3 - Login redirections

Login redirections

Global authentication dialogs

There are 2 different dialogs to authenticate the user according to the channel:

• account-linking dialog for channels using integrated authentication, for example, Aura Webclient.
• whatsapp-otp-login dialog for SMS-OTP authentication in WhatsApp channel.

Login redirection process

To redirect to login dialogs, we need a contextFilter with the redirectToIntent field set with the intent of the authentication dialog that we want to redirect.

This is done in the channel model:
triggerCondition model > conditionValidation model

For example, if we want to redirect to authentication in a channel, we need to add a configuration in the dialog as shown below:

{
  "name": "bill",
  "dialogs": [
    {
      "id": "balance-check",
      "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
              }
            }
          ]
        }
      ]
    }
  ]
}

In WhatsApp channel, the contextFilter will be the same but changing the redirectToIntent to the intent for WhatsApp authentication (intent.authentication.login):

{
  "triggerConditions": [
    {
      "intent": "intent.factotum-test.whatsapp-auth",
      "contextFilters": [
        {
          "name": "Anonymous redirect to linking",
          "type": "type",
          "conditions": "/type eq 'anonymous'",
          "true": {
            "name": "Anonymous redirect to linking",
            "breakDialogExecution": true,
            "breakFilterEval": true,
            "redirectToIntent": "intent.authentication.login",
            "suggestions": false
          }
        }
      ]
    }
  ]
}

1.4 - Terms & Conditions

Terms and Conditions

Terms and conditions flow

When a user message arrives, the first step in authentication is to check if it is in cache. In case that it is not found, Terms & Conditions API is checked and if the user does not exist or has a pending status, it is redirected to T&C dialog.

Obviously, all the users with accepted status continue with the normal flow. In the Terms and Conditions dialog a record with status pending is stored in the T&C API if does not exist yet and the terms and conditions prompt is shown. If the user accepts, the status accepted is set in T&C API.

Anonymous and authenticated users have different T&C, so if both are configured, users should accept T&C twice: after the first message as anonymous and after the authentication.

Terms and conditions settings

Terms and Conditions settings

In Aura channel model, T&C are set in the termsAndConditionsconfiguration model. It is added to channels who need to enable this feature.

There are two fields with different configurations inside: authenticated and anonymous. Each of these settings will be used according to the type of user. It defines the version and service used in T&C API.

{
  "channel_id": "f7fd1021-41cd-588a-a461-387cc24be223",
  "name": "whatsapp",
  "termsAndConditions": {
    "authenticated": {
      "version": "1",
      "service": "whatsappAuth"
    },
    "anonymous": {
      "version": "1",
      "service": "whatsappAnonymous"
    }
  }
}

2 - Conversational flow

Aura Bot conversational flow

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.

3 - channelData management

Aura Bot channelData

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.

3.1 - Handling channelData versions

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

3.2 - channelData mapping

channelData mapping

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.

3.3 - channelData validations

channelData validations

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.