Categories:
Aura Bot make-up process
The current section describes the make-up processes that take place within Aura Bot
Introduction
The make-up process in aura-bot runs by using the following command:
npm run makeup
All the processes that are executed during the aura-bot make-up are detailed in the following sections.
Environments variables for Aura Bot make-up
Mandatory variables
| Name |
|---|
| AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT |
| AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY |
| AURA_DEFAULT_LOCALE |
| AURA_STATIC_RESOURCE_ENDPOINT |
| AURA_STATIC_RESOURCE_SAS_TOKEN |
| AURA_VERSION |
Optional variables
These optional variables, together with their default values, are shown below. However, it can use some other optional variables, which can be checked out in the aura-bot make-up script in Github.
| Name | Default value |
|---|---|
| AURA_MAKEUP_FILES_ORIGIN | blob |
| AURA_MAKEUP_FILES_DESTINATION | blob |
| AURA_AUTHORIZATION_HEADER | |
| AURA_RESOURCES_PREFIX | ’libraries' |
| AURA_SERVICE_ENVIRONMENT | |
| AURA_MAKEUP_MODE | ‘full’ |
| AURA_CHANNELS_CONFIGURATION_API_ENDPOINT | |
| AURA_CONFIGURATION_CONTAINER | ‘aura-configuration’ |
| AURA_CHANNELS_CONFIGURATION_API_ENDPOINT | |
| AURA_CHANNELS_CONFIGURATION_BLOB | ‘bot-response.json’ |
| AURA_DIALOG_CONFIG_FILENAME | ‘merged-dialog-config.json’ |
| AURA_LOCAL_RESOURCES_PATH | ’local-resources' |
| AURA_LOCAL_RESOURCES_PORT | 3000 |
Load External Libraries
In this process, which is fully automated, the instance will be made-up, joining general configuration and i18n with library-specific ones.
The external libraries loaded by aura-bot are the different dialogs assigned to the use cases. This list of libraries is listed in the plugin-config.json file.
plugin-config.json
[
"@telefonica/aura-bot-common-library",
"@telefonica/aura-bot-disambiguation-library",
"@telefonica/aura-bot-generic-library",
{
"exclude": [
"./handover-genesys/handover-bypass-dialog",
"./handover-genesys/handover-status-dialog"
],
"packagePath": "@telefonica/aura-bot-handover-library"
},
"@telefonica/aura-bot-miscellaneous-library",
"@telefonica/aura-bot-none-library",
"@telefonica/aura-bot-onboarding-library",
"@telefonica/aura-bot-tv-library",
{
"exclude": [
"./wifi-check-connectivity-dialog",
"./wifi-connect-to-guest-dialog",
"./wifi-enable-disable-guest-dialog"
],
"packagePath": "@telefonica/aura-bot-wifi-library"
},
"@telefonica/aura-bot-la-amazon",
"@telefonica/aura-bot-la-iberia",
"@telefonica/mi-movistar-beta",
"@telefonica/generic-faq"
]
The make-up process is in charge of loading all these libraries and unifying the different resources they contain. Each environment contains the libraries associated with the required use cases.
Manage MongoDB Indexes
The indexes configuration file is in /settings/makeup/aura-bot-mongodb-indexes.json.
aura-bot-mongodb-indexes.json (partial)
{
"databases": {
"aura-bot": {
"aura-version-control": {
"version": 1,
"removeIndex": [],
"removeAllData": "",
"indexes": [
{
"version": 1,
"name": "idx_name",
"keys": {
"name": 1
},
"unique": true
}
]
},
"aura-caches": {
"version": 1,
"removeIndex": [],
"removeAllData": "",
"indexes": [
{
"version": 1,
"name": "idx_item_caches",
"keys": {
"item": 1
},
"unique": true
},
{
"version": 1,
"name": "idx_ttl_caches",
"keys": {
"lastAccess": 1
},
"expireAfterSeconds": 3600
}
]
},
"aura-context": {
"version": 1,
"removeIndex": [],
"removeAllData": "",
"indexes": [
{
"version": 1,
"name": "idx_aura_last_access",
"keys": {
"lastAccess": 1
},
"expireAfterSeconds": 3600
}
]
},
"aura-external-kpi":
.....
Once the make-up is executed, this file will be uploaded to the assigned repository [AURA-STORAGE]/aura-configuration/[AURA_VERSION]/aura-bot-mongodb-indexes.json. If this remote file exists, it has priority over the local file.
This configuration is assigned in the make-up process by means of the following model:
const options: MakeupMongoIndexManagerOptions = {
mongodbConfiguration: {
AURA_MONGODB_URI: configuration.AURA_MONGODB_URI,
AURA_MONGODB_DB_NAME: configuration.AURA_MONGODB_BOT_DATABASE,
AURA_MONGODB_USERNAME: configuration.AURA_MONGODB_USERNAME,
AURA_MONGODB_PASSWORD: configuration.AURA_MONGODB_PASSWORD,
AURA_MONGODB_POOL_SIZE: configuration.AURA_MONGODB_POOL_SIZE,
AURA_MONGODB_SSL: configuration.AURA_MONGODB_SSL
},
fileConfiguration: {
containerName: 'aura-configuration',
localPath: 'settings/makeup',
remotePath: '',
files: [{ name: 'aura-bot-mongodb-indexes.json', mimeType: 'application/json' }]
},
replaceLocalWithRemote: true,
storageCredentials: {
storageKey: configuration.AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY,
storageName: configuration.AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT
},
uploadFromLocalToRemote: true,
auraVersion: configuration.AURA_VERSION,
ignoreDownloadErrors: true,
ignoreUploadErrors: true,
dataBaseSuffix: configuration.AURA_ENVIRONMENT_NAME
}
Prepare Locale Resources
Each library may contain a settings/locale folder, with one or more i18n locale files (settings/locale/<lang>.json).
These locale files will be merged by language (in case of conflict, the latest loaded library overrides the previous one), and then merged with global locale files in aura-bot/locale/<lang>.json, taking precedence the global version in case of conflict.
All keys are sorted in resulting JSON files, to increase the readability.
For these local files to be merged, it is required to expose them in the locale property when registering the plugin. This will be done within the file index.ts, as shown in the following example:
import * as libraryUtil from '@telefonica/aura-bot-utilities/lib/aura-bot-library-util';
(...)
const settingsPath = path.resolve(__dirname, '..', 'settings');
register(null, {
my_library: {
locale: libraryUtil.readLocaleFolder(path.resolve(settingsPath, 'locale')),
(...)
}
});
The language resources in aura-bot are located in /locale/:
de-de.json
en-gb.json
es-es.json
pt-br.json
When starting aura-bot, these files are loaded remotely from [AURA-STORAGE]/static-resources/[AURA_VERSION]/locale/.
In the make-up process, the language resources of each loaded external library are merged into one file per language and then uploaded to Azure Storage using uploadFile method.
File example:
{
"common:common.error.main": [
"Aura no está disponible en estos momentos. Por favor, inténtalo un poco más tarde"
],
"common:common.goodbyes.main": [
"¡Hasta la vista!",
"¡Hasta pronto! Espero haber podido ayudarte"
],
"common:common.greetings.main": [
"Hola, buenas",
"Hola, estoy aquí para ayudarte"
]
}
Note that all the keys should start with the name of the library followed by a colon (":"). In the bot, this library name will be appended automatically, so only the last part of the key must be used in the dialogs.
Set Environment Variables
Each library may contain .env files within the folder settings or settings/{DEV|PRE|PRO} (some vars could have a specific value per environment).
If the AURA_SERVICE_ENVIRONMENT environment variable is set, the settings/.env file will be merged with settings/<AURA_SERVICE_ENVIRONMENT>/.env (taking precedence the env-specific values in case of conflict).
Every file is optional. After that, the resulting .env file from each library will be merged together and written down in aura-bot/.env.libraries. Note that this file has the lowest precedence when loading environmental variables in aura-bot.
Multiline values are escaped in order to allow the dotenv library to successfully read the values, even though it is recommended not using them.
For these .env files to be merged, it is required to expose them in the env property when registering the plugin. This will be done within the file index.ts, as shown in the following example:
import * as libraryUtil from '@telefonica/aura-bot-utilities/lib/aura-bot-library-util';
(...)
const settingsPath = path.resolve(__dirname, '..', 'settings');
register(null, {
my_library: {
env: libraryUtil.readEnv(settingsPath),
(...)
}
});
All the environment variables of each external library are merged together with the aura-bot environment variables and assigned as environment variables to the container or containers that will be in charge of raising their corresponding Pods in Kubernetes.
File example:
MYLIBRARY_VERSION=1.2.3
MYLIBRARY_ENDPOINT=https://my-library.test/v1
Note that to avoid conflicts, the env vars specific for a library should start with the library name in uppercase followed by an underscore ("_").
Prepare Remote Channel Config
Each library may contain dialog-config.json files or dialog-config.<AURA_BOT_DEFAULT_LOCALE>.json files.
The AURA_DEFAULT_LOCALE environment variable is required while AURA_SERVICE_ENVIRONMENT is optional. If AURA_SERVICE_ENVIRONMENT is set, these 4 files will be fetched and configuration is merged (the highest in the list means more priority in case of conflict):
- (1) settings/<AURA_SERVICE_ENVIRONMENT>/dialog-config.<AURA_BOT_DEFAULT_LOCALE>.json
- (2) settings/<AURA_SERVICE_ENVIRONMENT>/dialog-config.json
- (3) settings/dialog-config.<AURA_DEFAULT_LOCALE>.json
- (4) settings/dialog-config.json
In case AURA_SERVICE_ENVIRONMENT is not set, only #3 and #4 files are fetched and merged.
After that, the resulting dialog config from each library will be merged together. Then, the config is added to every channel in the config file pointed out by AURA_CHANNEL_CONFIGURATION_ENDPOINT (except the dialogs containing an only_in string array property, that are not added to channels not present in that property) replacing dialog_libraries from each channel. Then the resulting file is uploaded to Azure, replacing the previous one.
For these files to be merged, it is required to expose them in the config property when registering the plugin. This will be done within the file index.ts, as shown in the following example:
import * as libraryUtil from '@telefonica/aura-bot-library-util';
(...)
const settingsPath = path.resolve(__dirname, '..', 'settings');
register(null, {
my_library: {
config: libraryUtil.readDialogConfig(settingsPath),
(...)
}
});
Use onlyIn property
In some cases, the dialog configuration can differ among channels for the same country. In these cases, the onlyIn property must be used in the dialog-config.<AURA_DEFAULT_LOCALE>.json file:
{
"name": "tv",
"authorization": {
"purposes": "customer-self-service",
"scopes": "subscribed-products-user-read"
},
"dialogs": [
{
"id": "tv-carousel-info",
"suggestions": false,
"triggerConditions": [
{
"intent": "intent.carousel.info"
},
{
"intent": "intent.tv.details"
}
],
"onlyIn": [
"movistar-plus"
]
}
]
}
This configuration file is built by merge each channel configuration from each external library and uploaded to [AURA-STORAGE]/aura-configuration/bot-response.json using uploadStringAsBlob and/or (according to AURA_MAKEUP_FILES_DESTINATION) uploading channel information in aura-configuration-api.
bot-response.json (partial)
[
{
"channel_id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
"fpa_auth_purposes": "customer-self-service detect-abnormal-usage device-recommendations-v3 sim-upgrade-suggestion aura-read-insight-events identify-customer bolt-on-suggestion",
"fpa_auth_scopes": "device-catalog:devices-read device-stock:stock-read",
"name": "novum-mytelco",
"nlp": {
"enabled": true,
"enabled": true
}
},
"prefix": "nov",
"dialogLibraries": [
{
"name": "generic",
"dialogs": [
{
"id": "get-generic",
"triggerConditions": [
{
"intent": "intent.greetings"
}
]
}
]
},
{
"name": "bill",
"dialogs": [
{
"id": "balance-check",
"suggestions": true,
"authorization": {
"purposes": "customer-self-service",
"scopes": "mobile-balance-read"
},
"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
}
},
{
"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
}
},
...
Process Resources
Each library may contain a resources folder with images or any other binary files. If present, those files are uploaded to Azure container pointed by AURA_SERVICE_ENVIRONMENT env var, within libraries/<library> virtual path.
This uploading process could last longer than the other make-up steps, so the process could throw errors after showing that the make-up process is finished (with pending uploading processes).
The following snippet shows how to use those files within the dialogs (it will take AURA_STATIC_RESOURCE_ENDPOINT and AURA_STATIC_RESOURCE_SAS_TOKEN env vars from the environment):
import * as libraryUtil from '@telefonica/aura-bot-library-util';
(...)
const wholeUrl = getResourcePath('my_library', 'icon.png');
If we need to retrieve an image with specific device resolution as coming in the imageSettings resolution field of activity channelData, we should use getImageUrl method as follows:
import { getImageUrl } from '@telefonica/aura-bot-library-util';
[...]
const wholeUrlWithResolution = getImageUrl(stepContext.context, 'my_library', 'icon.png', configuration);
In libraries, the resources path must be exposed in the resources property when registering the plugin. This will be done within the file index.ts, as shown in the following example:
register(null, {
my_library: {
resources: path.resolve(__dirname, '..', 'resources'),
(...)
}
});
In the aura-bot make-up process the resources of each external library are uploaded to Azure Storage so that they can be later consumed by them. Remote path: [AURA-STORAGE]/static-resources/libraries/[LIBRARY_NAME].