Aura –

Docs:

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

Aura Bot utilities

Description of aura-bot-utilities

Introduction

aura-bot-utilities is a package belonging to aura-common-utilities that includes utilities for handling different tasks over aura-bot.

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

How to install aura-bot-utilities package

$ git clone https://github.com/Telefonica/aura-common-utilities.git

$ cd aura-common-utilities/packages/aura-bot-utilities

How to import an utility from this package

To import an utility from the aura-bot-utilities package, execute the following command:

import { ... } from '@telefonica/aura-bot-utilities/lib/[*utility-name*]';

For example:

import { generateAttachment, getReference, getTextFromResolution } from '@telefonica/aura-bot-utilities/lib/aura-bot-library-util';

Available utilities

List of utilities in the aura-bot-utilities package:

aura-bot-common utility includes useful utilities to handle conversations both in aura-bot and in the dialogs.
aura-bot-kpis utility simplifies how KPI entities are handled in aura-bot and aura-groot.
aura-bot-library-util utility for developing aura-bot libraries and dialogs.
aura-minibot-service utility simplifies how aura-minibot and aura-minigroot are generated.
aura-movistar-libraries utility that contains utilities to be used in dialogs for Movistar channels.

Docs:

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

Aura utilities

Description of aura-utilities

Introduction

aura-utilities is a package belonging to aura-common-utilities that includes utilities used by other Aura components.

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

How to install aura-utilities package

$ git clone https://github.com/Telefonica/aura-common-utilities.git

$ cd aura-common-utilities/packages/aura-utilities

How to import an utility from this package

To import an utility from the aura-utilities package, execute the following command:

import { ... } from '@telefonica/aura-utilities/lib/[*utility-name*]';

For example:

import { ... } from '@telefonica/aura-utilities/lib/aura-channel-data-handler';

Available utilities

List of utilities in the aura-utilities package:

aura-channel-data-handler utility that allows managing channelData content
aura-configuration utility for loading configuration and models related to channels
aura-crypto-adapter utility for encrypting and decrypting user tokens
file-validator utility, used by aura-file-manager to validate files.
aura-locale-manager utility for the management of text resources
aura-models utility that stores common interfaces in Aura projects
aura-mongo-handler utility, a tool for handling MongoDB database
aura-orchestrator utility for the management of text resources by aura-bot
aura-redis-handler utility, in charge of connecting and using Redis. request-utils
aura-server-common utility allows code sharing between Aura server applications
aura-storage-file-manager utility in charge of uploading or downloading remote files
aura-validate-apikey utility for the validation of APIKeys in incoming requests
aura-makeup-index-manager utility

Docs:

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

Aura develop utilities

Description of aura-develop-utilities

Introduction

aura-develop-utilities is a package belonging to aura-common-utilities that includes utilities used for different development purposes.

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

How to install aura-develop-utilities package

$ git clone https://github.com/Telefonica/aura-common-utilities.git

$ cd aura-common-utilities/packages/aura-develop-utilities

Available utilities

List of utilities in the aura-develop-utilities package:

aura-client-generator utility: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-develop-utilities/src/aura-client-generator/

Docs:

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

Aura Clients

Description of aura-clients

Introduction

aura-clients is a package belonging to aura-common-utilities that includes tools that make easier to call APIs.

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

How to install aura-clients package

$ git clone https://github.com/Telefonica/aura-clients.git

$ cd aura-common-utilities/packages/aura-clients

How to import an utility from this package

To import an utility from the aura-clients package, execute the following command:

import { ... } from '@telefonica/aura-clients/lib/[*client-name*]';

For example:

import { ChannelConfiguration } from '@telefonica/aura-clients/lib/aura-configuration-api-client';

Available aura-clients

Find the current aura-clients, both internal or external ones in Aura API clients.

Docs:

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

aura-http-monkey-patcher utility

aura-http-monkey-patcher utility is in charge of HTTP monkey patching

Introduction

aura-http-monkey-patcher utility is designed as a common place to do activities in HTTP monkey patching.

It is placed in the Github repository:
aura-bot-libraries/packages/aura-http-monkey-patcher/.

Use of aura-http-monkey-patcher utility

When loading the modules in the app orchestrator (or any other method), the methods startMetricsTimer and kpiApiRequest could be overriden. (both are optional).

        // Initiate the App.
        await appOrchestrator.init();
        // Sets required methods in HttpMonkeyPatcher
        HttpMonkeyPatcher.instance.startMetricsTimer = startPrometheusTimer;
        HttpMonkeyPatcher.instance.kpiApiRequest = KpiHandler.instance.apiRequest.bind(KpiHandler.instance);

Docs:

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

aura-json-schema-generator utility

aura-json-schema-generator utility is a tool to generate Typescript classes

Introduction

aura-json-schema-generator utility is a tool to generate Typescript classes from JSON schema file(s). It provides a command that generates Typescript interface files from one or more schema files.

It is placed in the Github repository:
aura-bot-libraries/packages/aura-json-schema-generator/.

The input file(s) is mandatory. The output directory is optional (./types by default). In it, a directory is created for every schema including the schema version, and inside that directory, another one is created with the schema name that will contain the typescript interfaces.

Installation

Although it is possible to install the package locally, it is recommended to install it globally, in order to allow the execution of the generator binary anywhere.

$ npm install -g @telefonica/aura-json-schema-generator

Once installed globally, a new command aura-json-schema-generator will be available in the PATH, so we can generate Typescript interface files from one or more schema files.

Run aura-json-schema-generator utility

aura-json-schema-generator

Two other names for this command are available: aura-jsg and aujsg

Arguments

There are two arguments that can be passed in the command line when running:

The first argument (mandatory) is the path of a JSON Schema file or a directory that contains JSON Schema files.
The second argument (optional) is the path where the Typescript files will be created. types is the default value. This information can be found when running the command without arguments:

$ aura-json-schema-generator

ERROR Argument missing. Use: aura-json-schema-generator <input file or dir> [<output dir>]

This command will create the Typescript interfaces from a JSON Schema file named simple.json in the default output directory types within current directory:

$ aura-json-schema-generator ./simple.schema.json

DEBUG Reading json schema ./simple.schema.json
INFO  Output path will be './types'
INFO  Writing ./types/1.0.0/simple/simple.d.ts

This command will create all the Typescript interfaces from channelData schemas in the directory resources/channel-data/3.0.0 in a specified output directory src/channel-data/:

$ aura-json-schema-generator resources/channel-data/3.0.0/ src/channel-data/

DEBUG Reading json schema ./resources/channel-data/3.0.0/request/channeldata-3.0.0-request.schema.json
DEBUG Reading json schema ./resources/channel-data/3.0.0/response/channeldata-3.0.0-response.schema.json
INFO  Output path will be './src/channel-data'
INFO  Writing ./src/channel-data/3.0.0/request/request-channel-data.d.ts
INFO  Writing ./src/channel-data/3.0.0/response/response-channel-data.d.ts

The following example shows the execution of the aura-json-schema-generator in the happening of an error in any of the provided schemas. As can be seen, an error is shown indicating both the file that contains the error and thus cannot be processed and the specific error or errors in the schema.

In this case, the error is in the file request/channeldata-3.0.0-request-wrong.schema.json and the problems are that neither ApplicationWrong nor AuraCommandWrong cannot be found, so the schema for this file cannot be generated. The rest of the files in the folder resources/channel-data/3.0.0/ will be processed and their schemas will be generated correctly.

$ aura-json-schema-generator resources/channel-data/3.0.0/ src/channel-data/

DEBUG Reading json schema ./resources/channel-data/3.0.0/request/channeldata-3.0.0-request-wrong.schema.json
ERROR Object ApplicationWrong not found
ERROR Object AuraCommandWrong not found
ERROR Error reading file ./channel-data/3.0.0/request/channeldata-3.0.0-request-wrong.schema.json
DEBUG Reading json schema ./channel-data/3.0.0/response/channeldata-3.0.0-response.schema.json
INFO  Output path will be './src/channel-data'
INFO  Writing ./src/channel-data/3.0.0/response/response-channel-data.d.ts

aura-types-from-swagger-generator

Two other names for this command are available: aura-tfsg and autfsg

Arguments

There are three arguments that can be passed in the command line when running:

The first argument (mandatory) is the path of a JSON/YAML Schema file or a directory that contain JSON/YAML Schema files.
The second argument (optional) is the path where the Typescript files will be created. types is the default value.
The third argument (optional) is an array of strings with options:
- –unique-file: Create all the models data in a single file by swagger.
- –unify-enumerated: Unify the generated enums.
- –particularize-enumerated: Particularize the generated enums.

This command will create the typescript interfaces, enums and types from a Swagger file named swagger.json in the default output directory types within current directory:

$ aura-types-from-swagger-generator ./swagger.json

Using swagger with this info:

{
   "openapi": "3.0.0",
   "info": {
      "title": "Aura Bridge",
      "description": "Set of endpoints that support the aura bridge",
      "version": "1.1.0"
   },
   ...
}

The result has the following structure:

types
└── 1.1.0
    └── aura-bridge.ts

aura-markdown-from-json-schema-generator

The execution of the following command will create the markdown documentation from a JSON schema file:

$ aura-markdown-from-json-schema-generator aura-models/resources/channel-data/payload.schema.json payload-types.md

For example, using a JSON schema with this info:

{
   ...
   "Payload": {
         "description": "Channel data payload information",
         "title": "Payload",
         "type": "object",
         "additionalProperties": false,
         "properties": {
            "bridge": {
               "$ref": "#/definitions/channel-data/Bridge",
               "description": "Information sent from the bridge",
               "title": "bridge"
            },
            "handover": {
               "$ref": "#/definitions/channel-data/Handover",
               "description": "Information sent from Handover",
               "title": "handover"
            },
            "event": {
               "$ref": "#/definitions/channel-data/PayloadEvent",
               "description": "Information sent as an event",
               "title": "event"
            }
         },
         "required": [
            "bridge"
         ]
   },
   ...
}

The outcome of the execution of the previous command will generate:

The input JSON schema (in the example, aura-models/resources/channel-data/payload.schema.json)
A markdown output file, in the example: payload-types.md:

### Payload

Channel data payload information

| Property        | Type         | Description                                        |
| --------------- | ------------ | -------------------------------------------------- |
| **bridge**      | Bridge       | Information sent from the bridge                   |
| *handover*      | Handover     | Information sent from Handover                     |
| *event*         | PayloadEvent | Information sent as an event                       |

Components

Enums

Particularize Enumerated

For this flow, enums are generated as follows:

Enums are generated from the properties of models that have the isEnumerated and enums flags.
Enums are generated from types, checking if it is a type with an array, a type with different types, etc.
The enums that are not being used are filtered out to avoid generating them.

oneOf

oneOf is a property used to indicate that a component can have one of the types it receives as options. For example:

   Component1:
      properties:
         property1:
            type: array
            items:
               oneOf:
                  - $ref: '#/components/schemas/Item1'
                  - $ref: '#/components/schemas/Item2'
                  - $ref: '#/components/schemas/Item3'

If the items within oneOf do not have the title field filled, by default it will be name + Type + incr_counter:

   {
      "paths": {},
      "components": {
         "schemas": {
               "Component_Property_1": {
                  "type": "string",
                  "enum": [
                     "none",
                     "auto"
                  ]
               },
               "Component_Property_2": {
                  "type": "object",
                  "properties": {
                     "name": {
                           "type": "string"
                     }
                  },
                  "required": [
                     "name"
                  ]
               },
               "Component_1": {
                  "oneOf": [
                     {
                           "type": "string",
                           "enum": [
                              "none",
                              "auto"
                           ]
                     },
                     {
                           "$ref": "#/components/schemas/Component_Property_1"
                     },
                     {
                           "type": "object",
                           "properties": {
                              "name": {
                                 "type": "string"
                              }
                           },
                           "required": [
                              "name"
                           ]
                     },
                     {
                           "type": "string",
                           "enum": [
                              "none",
                              "auto"
                           ]
                     },
                     {
                           "type": "object",
                           "properties": {
                              "name": {
                                 "type": "string"
                              }
                           },
                           "required": [
                              "name"
                           ]
                     },
                     {
                           "$ref": "#/components/schemas/Component_Property_2"
                     }
                  ]
               }
         }
      }
   }

The result would be as follows:

   /**
    * Enum for Component_Property_1
    *
    * @enum {string}
    */
   export enum ComponentProperty1 {
      None = 'none',
      Auto = 'auto'
   }

   /**
    * Enum for Component_1
    *
    * @enum {string}
    */
   export enum Component_1Enum {
      None = 'none',
      Auto = 'auto'
   }

   /**
    * Enum for Component_1
    *
    * @enum {string}
    */
   export enum Component_1Enum1 {
      None = 'none',
      Auto = 'auto'
   }

   /**
    * Type for Component1
    */
   export type Component1 = Component_1Enum | ComponentProperty1 | Component1Type | Component_1Enum1 | Component1Type1 | ComponentProperty2;

   /**
    * @interface ComponentProperty2
    */
   export interface ComponentProperty2 {

      name: string;
   }

   /**
    * @interface Component1Type
    */
   export interface Component1Type {

      name: string;
   }

   /**
    * @interface Component1Type1
    */
   export interface Component1Type1 {

      name: string;
   }

Docs:

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

aura-kpis utility

aura-kpis utility allows the generation of KPIs entity files

Introduction

aura-kpis utility is a library used by all Aura apps to generate KPIs entity files equally in all of them.

It is placed in the Github repository:
aura-bot-libraries/packages/aura-kpis/.

It has two working modes:

file: Entity files will be stored locally on the current server instance. For development purposes.
blob: Entity files will be stored remotely on an Azure Blob Container with aura-storage-file-manager uploadLogs.

Configuration

These configuration variables MUST be set in the server using the library.

KPIs environment variables:
- AURA_VERSION: mandatory, Aura release.
- AURA_DEFAULT_LOCALE: mandatory, string with the default locale to be used in the server. It uses two letter codes both for country and culture, for example: es-es, en-gb.
- AURA_DEFAULT_TIME_ZONE: mandatory, timezone where the service is running.
- AURA_KPI_TO_DSV_CACHE_TTL: optional, number of milliseconds to cache existing requests to calculate their duration. By default, 1800.
- AURA_KPI_TO_DSV_DELIMITER: optional, string with the delimiter to be used in KPIs entities files. By default, |.
- AURA_KPI_TO_DSV_EXTENSION: optional, string with the extension to be used in KPIs entities files. By default, txt.
- AURA_KPI_FILE_PREFIX: mandatory, string with the prefix used in the KPIs entities files of this service. Usually its format is component/prefix. For CSV files it is used as is, so files are stored in Azure Storage in that path, meaning a virtual folder named component and that the files will start by prefix. But for Avro files, the value of the variable is split into 2 by / and only the prefix part is used to name the files, that are store together with files generated by all components in the same virtual folder.
- AURA_KPI_STORE_MODE: optional, string to indicate what is the destination of the KPIs entities files. By default, blob.
  - If file, they will be stored locally on the instance, in the folder shown in KPI_TO_DSV_LOCAL_FILES_DIRECTORY. For development purposes.
  - If blob, they will be stored remotely on the Azure blob container shown in KPIS_STORE_CONTAINER. Mandatory in environments running on k8s.
- AURA_KPI_TO_DSV_LOCAL_FILES_DIRECTORY: optional, string with the local directory to store KPIs entities files. By default, ./kpis-dsv. It MUST be the same than the one configured in KPIS_UPLOADER module. Only needed if AURA_KPI_STORE_MODE==file.
- AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY: optional, string with the Azure Storage Access Key to be able to write files in KPIS_STORE_CONTAINER. Only needed if AURA_KPI_STORE_MODE==blob.
- AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT: optional, string with the Azure Storage Account name to be able to write files in KPIS_STORE_CONTAINER. Only needed if AURA_KPI_STORE_MODE==blob.
- AURA_KPIS_STORE_CONTAINER: optional, string with the name of the Azure Blob container to store KPIs entities files. By default, aura-kpis. It MUST be the same than the one configured in KPIS_UPLOADER module. Only needed if AURA_KPI_STORE_MODE==blob.
- AURA_KPIS_BLOB_STORE_INTERVAL: optional, number with the time interval in milliseconds to upload asynchronously logs to the KPIS_STORE_CONTAINER. By default, 60000. Only needed if AURA_KPI_STORE_MODE==blob.
- AURA_SOURCE_PATH_AVRO_ADAPTERS: optional, string containing the adapters to transform data, '/schemas/aura-csv-adapter.json' for CSV transform and '/schemas/aura-avro-adapter.json' to transform in CSV and AVRO. By default: '/schemas/aura-csv-adapter.json'.

Use aura-kpis utility

aura-kpis utility needs to add a dedicated events emitter that handles KPI events.

Initialize the specific KPI writer, based on your service configuration:

// Start Kpis Writer
const kpisWriterFactory: KPIWriterFactory = KPIWriterFactory.getInstance();
const kpisWriter: KPIEntityWriter = await kpisWriterFactory.createKpiWriter();

Use the classes and utilities provided by the library:

import { KPIEventBody, KPIEmittersEvents, KPIActionEmitter } from '@telefonica/aura-kpis';
const kpisLogger = new KPIActionEmitter('MyModule');

Fill the corresponding event with the data available in every moment. Update this data on each step, before emitting the event.

let kpisEvent: KPIEventBody = {
    request: {
        correlator: correlator,
        requestId: requestId
    },
    user: {
        auraId: auraId,
        channelId: channelId
    },
    channel: {
        channelId: channelId
    }
};

If the name of the environment variables of your service do not match with the library names, the configuration can be also be passed as an object of type KPIWriterConfiguration.
Depending on the value of AURA_KPI_STORE_MODE a different set of properties is validated.
In those meaningful steps, emit the corresponding event. The basic approach is to emit one event (KPIEmittersEvents.REQUEST_STARTED) when the request lands on the server and another when the response is returned (for instance, KPIEmittersEvents.KPIS_USER_REQUEST_FINISHED, in the case of a user request):

kpisLogger.emit(KPIEmittersEvents.KPIS_USER_REQUEST_FINISHED, kpisEvent);

Events

API entity filling: this case just needs a couple of events to handle incoming and outgoing steps.
- KPIS_API_REQUEST_STARTED: event that shows that a new request to one external API is started. It adds to a cache a time mark, so the duration of the request can be calculated.
- KPIS_API_REQUEST_FINISHED: last event of a new request to one external API has finished, emitted when the response is returned.
MESSAGE entity filling: this case just needs a couple of events to handle incoming and outgoing steps.
- KPIS_MESSAGE_REQUEST_STARTED: event that shows that a new message goes in aura-bot. It adds a time mark to a cache, so the duration of the request can be calculated.
- KPIS_MESSAGE_REQUEST_FINISHED: event to write the KPI of the given message being handled by aura-bot. It is emitted when a new message comes in and when its response is returned.
EXTENDED_MESSAGE entity filling: this case just needs a couple of events to handle incoming and outgoing steps.
- KPIS_EXTENDED_MESSAGE_REQUEST_STARTED: event that shows that a new message enters aura-bot. It adds a time mark to a cache, so the duration of the request can be calculated. It is an extended logic made from MESSAGE entity.
- KPIS_EXTENDED_MESSAGE_REQUEST_FINISHED: event to write the KPI of the given message being handled by aura-bot. It is emitted when a new message comes in and when its response is returned. It is an extended logic made from MESSAGE entity.
NOTIFICATION entity filling: this case just needs a couple of events to handle incoming and outgoing steps.
- KPIS_NOTIFICATION_REQUEST_STARTED: event that shows that a new notification request has arrived. It adds a time mark to a cache, so the duration of the request can be calculated.
- KPIS_NOTIFICATION_REQUEST_FINISHED: last event of a notification request, emitted when the response is returned in the corresponding controller.
RECOGNIZER entity filling: this case just needs a couple of events to handle incoming and outgoing steps.
- KPIS_RECOGNIZER_REQUEST_STARTED: event that shows that a new recognizer request is started. It adds a time mark to a cache, so the duration of the request can be calculated.
- KPIS_RECOGNIZER_REQUEST_FINISHED: last event of a recognizer request, emitted when the response is returned.
SUGGESTION entity filling: this case just needs a couple of events to handle incoming and outgoing steps.
- KPIS_SUGGESTION_REQUEST_STARTED: event that shows that a suggestion is shown to the user or clicked by her. It adds a time mark to a cache, so the duration of the request can be calculated.
- KPIS_SUGGESTION_REQUEST_FINISHED: last event of a suggestion shown to the user or clicked by her, emitted when the response is returned.
USER entity filling: This case needs partial events to assure that no value of the USER entity is missed, both in successful and error cases.
- KPIS_REQUEST_STARTED: event that shows that a new request has arrived. It adds to a cache a time mark, so the duration of the request can be calculated.
- KPIS_USER_REQUEST_FINISHED: last event of a user request, emitted when the response is returned in the corresponding controller.
- KPIS_USER_CREATE_DB: partial user event, emitted when requesting the DB.
- KPIS_USER_DELETE_DB: partial user event, emitted when the user is deleted from the DB.
- KPIS_USER_FIND_DB: partial user event, emitted when the user is found in the DB.
- KPIS_USER_CREATE_SERVICE: partial user event, emitted when returning from the user creation service.
- KPIS_USER_LOGIN_SERVICE: partial user event, emitted when returning from the user login service.
- KPIS_USER_DELETE_SERVICE: partial user event, emitted when returning from the user deletion service.
GATEWAY entity filling: this case just needs a couple of events to handle incoming and outgoing steps.
- KPIS_GATEWAY_MESSAGE_REQUEST_STARTED event that shows that a new request enters aura-gateway-api. It adds a time mark to a cache, so the duration of the request can be calculated.
- KPIS_GATEWAY_MESSAGE_REQUEST_FINISHED: event to write the KPI of the given request being handled by aura-gateway-api. It is emitted when its response is returned.
GROOT entity filling: this case just needs a couple of events to handle incoming and outgoing steps.
- KPIS_GROOT_MESSAGE_REQUEST_STARTED: event that shows that a new message enters aura-groot. It adds a time mark to a cache, so the duration of the request can be calculated.
- KPIS_GROOT_MESSAGE_REQUEST_FINISHED: event to write the KPI of the given message being handled by aura-groot. It is emitted when a new message comes in and when its response is returned.

Docs:

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

aura-behavior-manager utility

Guidelines for using aura-behavior-manager utility that allows modifying the behavior of Aura Bot or Aura Bridge in development environments without restarting them

Introduction

The main feature of the aura-behavior-manager is to be able to change the application (aura-bot or aura-bridge) behavior in development environments. All these changes can be made to the fly, without the need to restart the bot/bridge instance.

For this purpose, the aura-behavior-manager makes use of a series of commands linked to each of the previously configured behavior that can be sent to application in a specific format.

⚠️ WARNING

aura-behavior-manager must be exclusively used in development environments.
Do not use in production environments, as it disrupts Aura behavior and can lead to a faulty operation of the system.

As an example, aura-behavior-manager could change the value of an environment variable AURA_TERMS_AND_CONDITIONS_EXPIRATION:

/bot:set:property AURA_TERMS_AND_CONDITIONS_EXPIRATION 10000

Components and class hierarchy

To implement the aura-behavior-manager, you should make use of @telefonica/aura-behavior-manager library. This contains the following components:

BehaviorManager: Base class from which you must extend a specific BehaviorManager (Example: BotBehaviorManager, BridgeBehaviorManager).
BehaviorCommandControl: Responsible for the tasks associated with user commands.
BehaviorStubsHandler: It allows to register/modify/restore the modified methods in the code.
BehaviorCoreCommands: It contains the basic commands of the behavior manager.
RemotelyConfigurable: Utility that allows any class to read configuration from Azure using cron.

@startuml BehaviorManager class diagram
class RemotelyConfigurable {
  storageCredentials
  storageManager
  containerName
  sourceFilePath
  cronExpression
  cronTask
  settings
  status
  lastUpdated
  +start()
  +stop()
  +read()
}

class BehaviorManager {
  name
  commandPattern
  behaviors
  commandControl
  stubsHandler
}

class BehaviorStubsHandler {
  stubs
  +start()
  +restore()
  +getStubs()
}

class BehaviorCommandControl {
  component
  commandPattern
  +isCommand()
  +getCommandList()
  +execute()
}

class BehaviorProperty {
    +setProperty()
    +unsetProperty()
    +getProperty()
    +getDefaultProperty()
    +getBehavior()
}


RemotelyConfigurable <|--down BehaviorManager
BehaviorManager *---right BehaviorCommandControl
BehaviorManager *---right BehaviorStubsHandler
BehaviorManager <|--down BehaviorProperty
BehaviorProperty <|--down BotBehaviorManager
BehaviorProperty <|--down BridgeBehaviorManager

@enduml

How that works?

In order to use the aura-behavior-manager, it must be loaded at the component start (aura-bot/aura-bridge).

Once it has started, it will load the list of behaviors (can be identified as plugins) that will allow certain actions to modify the behavior of the component. Examples of these behaviors can be: Property, Profile, etc. In the section Description of a Behavior, a behavior is described in detail.

When a message is received, the BehaviorCommandControl is responsible for detecting if it is a command. If so, it tries to execute the command associated with the behavior that defines it:


@startuml Behavior manager command control flow
start
#palegreen:message;

if (text message is command?) then (true)
  #cyan:Execute command using "commandControl";
  #cyan:Reply with command response;
  end
endif

#palegreen:Process the message normally;

stop
@enduml

Description of a behavior

A behavior is the minimum unit that allows defining a change in the behavior of the system (aura-bot, aura-bridge).

Every behavior to be incorporated to aura-behavior-manager must implement the following interface:

/**
 * @interface BehaviorComponent
 */
export interface BehaviorComponent {
    getBehavior: () => BehaviorComponentInformation;
}

/**
 * @interface BehaviorComponentInformation
 * Behavior information
 */
export interface BehaviorComponentInformation {
    /**
     * Behavior name.
     */
    name: string;
    /**
     * Behavior description.
     */
    description?: string;
    /**
     * Information with the piece of code used as a substitute for other functionality.
     */
    stub?: BehaviorStubInformation;
    /**
     * Command information associated with this behavior.
     */
    commands: BehaviorCommand[];
}

Therefore, a behavior has the following properties:

name (*): Behavior name.
description: Behavior description.
stub: As it is done in unit tests, it allows defining a code that will replace the original functionality in the code.
commands: List of commands to invoke the different functionalities that the behavior defines.

As an example, we will create a new HelloBehavior, which will respond with a simple ‘Hello’ in the command response:

export class HelloBehavior implements BehaviorComponent {

    /**
     * Get behavior (hello).
     * @returns {BehaviorComponentInformation} Get behavior information
     */
    public getBehavior(): BehaviorComponentInformation {
        return {
            name: 'Hello',
            description: 'Hello example behavior',
            // stub -> We don't need to "stub" any code for this example
            commands: [
                { name: 'get:hello', description: 'Say hello', execute: this.getHello.bind(this) }
            ]
        };
    }

    /**
     * Say hello.
     * @param {CommandControlOptions} options Options
     */
    private async getHello(options: CommandControlOptions) {
        return 'Hello';
    }
}

Now, it would be possible to send to aura-bot:

/bot:get:hello

You can check other examples of behaviors here

Predefined behavior: the core behavior

The aura-bot-behavior library already defines a behavior that includes a series of common commands to be used by aura-bot and aura-bridge:

Name	Description
get:commands	Get command list
get:stubs	Get stub list
set:stubs	Start configured stubs
unset:stubs	Restore stubs
get:status	Get behavior manager status
get:settings	Get full settings
get:remoteSettings	Reload and Get settings from remote (force reload)
get:profiles	Get profile list

As an example, we will show the list of available commands:

/bot:get:commands     # You can also use: /bot get commands

Thus, you should have a response similar to the following:

[
  {
    "name": "get:commands",
    "description": "Get command list"
  },
  {
    "name": "get:stubs",
    "description": "Get stub list"
  },
  {
    "name": "set:stubs",
    "description": "Start stubs"
  },
  {
    "name": "unset:stubs",
    "description": "Restore stubs"
  },
  {
    "name": "get:status",
    "description": "Get behavior manager status"
  },
  {
    "name": "get:settings",
    "description": "Get full settings"
  }
]

Aura Bot Behavior Manager

How to activate Aura Bot Behavior Manager?

In order to activate aura-behavior-manager in aura-bot, two environment variables must be configured with the following values:

AURA_SERVICE_ENVIRONMENT, with the value "DEV" and
DEV_AURA_BEHAVIOR_MANAGER_ACTIVE, with the value true.

With these two variables correctly configured, the BotBehaviorManager module will be added to the Orchestrator module list and a message will be shown in the startup process: ‘Behavior manager loaded’.

Defined behaviors

Below are the different behaviors defined in the Bot and the commands to be able to interact with them.

Those behaviors marked with ‘(*)’ are necessary for the BotBehaviorManager to work properly.

CommandBehavior (*)

It is the necessary behavior to be able to interact with the Bot’s behavior system, so without this behavior it will not be possible to send commands.

Stub:

Name	Stub destination	Description
Command control	beginDialogStep	Modify “beginDialogStep” function to detect and execute commands

Property behavior

It allows you to modify a list of environment variables without the need to restart the system. Currently, only the following list of variables have been enabled to be modified by the Behavior Manager:

AURA_ACCESS_TOKEN_EXPIRATION_MARGIN
AURA_MONGODB_BOT_COLLECTION_CONTEXT_INDEX_TTL

If you need to add new variables, you should use the ConfigurationManager.instance.get method on all sites where you can use that variable.

Stub:

Name	Stub destination	Description
Property	ConfigurationManager.get	Modify `get` function to change the value of a variable

Commands:

Name	Description
set:property	Set property
get:property	Get property
get:properties	Get properties. All properties configured by the user (`conversationId`)
get:defaultProperty	Get default environment property. The value of the current environment variable
get:defaultProperties	Get default environment properties. All current environment variables

Examples:

/bot:set:property AURA_MONGODB_BOT_COLLECTION_CONTEXT_INDEX_TTL 10 # Set property value for conversationId
/bot:get:property AURA_MONGODB_BOT_COLLECTION_CONTEXT_INDEX_TTL # Get property value for conversationId
/bot:get:properties # All properties configured by the user
/bot:get:defaultProperty AURA_MONGODB_BOT_COLLECTION_CONTEXT_INDEX_TTL # The value of the current environment variable
/bot:get:defaultProperties # All current environment variables

Aura Bridge Behavior Manager

How to activate Aura Bridge Behavior Manager ?

In order to activate aura-behavior-manager in aura-bridge, two environment variables must be configured with the following values:

AURA_SERVICE_ENVIRONMENT, with the value "DEV" and
DEV_AURA_BEHAVIOR_MANAGER_ACTIVE, with the value true.

With these two variables correctly configured, the BridgeBehaviorManager module will be added to the Orchestrator module list and a message will be shown in the startup process: ‘Behavior manager loaded’.

Settings

Environment variables that can be configured to adapt the Behavior Manager:

Name	Description
DEV_AURA_BEHAVIOR_COMMAND_PATTERN	Pattern to recognize a behavior command
DEV_AURA_BEHAVIOR_SETTINGS_FILE_MICROSOFT_AZURE_STORAGE	Profile configuration file location for the behavior-manager
DEV_AURA_BEHAVIOR_SETTINGS_FILE_CRON_PATTERN	CRON expression associated with the reload time of the configuration file

Using the default value for DEV_AURA_BEHAVIOR_COMMAND_PATTERN allows you to run commands of the type:

    /bridge:get:property DEV_AURA_BEHAVIOR_COMMAND_PATTERN
    /bridge get property DEV_AURA_BEHAVIOR_COMMAND_PATTERN
    /bridge unset proxies

The aura-behavior-manager allows to use a configuration file to manage profiles (currently disabled). This file is read at start-up and refreshed according to the variable settings DEV_AURA_BEHAVIOR_SETTINGS_FILE_CRON_PATTERN. The configuration file is stored in Azure Blob Storage. The path to this configuration file is built as follows:

AURA_MICROSOFT_AZURE_STORAGE_STATIC_CONTAINER_NAME/AURA_VERSION/DEV_AURA_BEHAVIOR_SETTINGS_FILE_MICROSOFT_AZURE_STORAGE}

An example of default location can be:

static-resources/7.2.0/aura-bridge/aura-bridge-behavior-manager.json

Further information about aura-bridge environment variables section.

Description of a bridge behavior

A behavior allows defining a change in the behavior of the aura-bridge.

In order to allow an aura-bridge plugin to manage BridgeBehaviorManager commands, the interface BehaviorComponentInformation has been extended as follows:

/**
 * @interface BehaviorComponentInformationBridge
 * Bridge behavior component information
 */
export interface BehaviorComponentInformationBridge extends BehaviorComponentInformation {
    pluginControllerStub?: (
        req: Request, res: Response, next: NextFunction,
        behaviorController: BehaviorController,
        original: (req: Request, res: Response, next: NextFunction) => Promise<void>
    ) => Promise<void>;
}

This new pluginControllerStub field defines the decorator function for plugin controllers. The original function (endpoint controller defined in the swagger) will be passed as the last argument (the original parameter).

Enable a plugin to manage behavior commands

Only the Api or Processor (extends API type) plugins can manage Behavior Manager commands.

The only action by a plugin to enable Behavior Manager command controller is to complete the information from the behaviorController field defined in the PluginApi interface:

export interface PluginApi extends Plugin {
    /**
     * If defined, the plugin can manage commands for the behavior manager.
     * This only takes effect in development environments.
     */
    behaviorController?: BehaviorController;
}

export interface BehaviorController {
    /**
     * Get request information.
     *
     * @param {express.Request} req Express request
     * @returns {AuraBridgeRequestInfo} Request information
     */
    getRequestInformation(req: Request): AuraBridgeRequestInfo;
    /**
     * Get text from input message.
     *
     * @param {express.Request} req Express request
     * @returns {string} Text message
     */
    getTextFromMessage(req: Request): string;
    /**
     * Send text message using client.
     *
     * @param {string} message Text message
     * @param {express.Request} req Express request
     * @param {AuraBridgeRequestInfo} requestInfo Request information
     */
    sendTextMessage?(message: string, req: Request, requestInfo: AuraBridgeRequestInfo): Promise<void>;
}

The getRequestInformation and getTextFromMessage functions are required and necessary to be able to recognize and execute commands. The sendTextMessage function is optional and allows the user to receive feedback from the command execution.

Defined behaviors

Below are the different behaviors defined in aura-bridge and the commands to be able to interact with them.

Those behaviors marked with ‘(*)’ are necessary for the BridgeBehaviorManager to work properly.

CommandBehavior (*)

It is the necessary behavior to be able to interact with the aura-bridge behavior system, so without this behavior it will not be possible to send commands.

Plugin controller stub:

Name	Stub destination	Description
Command control	plugin controller	Modify plugin controller to detect and execute commands

This behavior will affect those plugins that define the behaviorController field in the API type plugin definition.

CommonBehavior (*)

It defines commands that are associated with BridgeBehaviorManager itself.

Commands:

Name	Description
get:conversationId	Get conversation id
get:all	Get all configuration associated with the current conversation
unset:all	Unset all cache information associated with the current conversation

PropertyBehavior

It manages information from the aura-bridge environment variables.

Currently, only the following list of variables have been enabled to be modified by the BridgeBehaviorManager:

AURA_BOT_APIKEY
AURA_BOT_ENDPOINT
AURA_BRIDGE_ENDPOINT
AURA_FP_WHATSAPP_ENDPOINT
AURA_BRIDGE_REQUEST_VERSION

If you need to add new variables, you should use the ConfigurationManager.instance.get method on all sites where you can use that variable.

Stub:

Name	Stub destination	Description
Property	ConfigurationManager.get	Modify `get` function to change the value of a variable

Commands:

Name	Description
set:property	Set property
get:property	Get property
get:properties	Get all the properties configured
get:defaultProperty	Get default environment property
unset:property	Unset property (If property name is not present, all will be deleted)
unset:allProperties	Unset all properties

How to redirect requests to your local Aura Bot

Set the property AURA_BOT_ENDPOINT with the next aura-bridge command and all requests in the conversation will be redirected to the local aura-bot. For example, at a local address using ngrok (https://1111-11-11-111-11.ngrok.io):

/bridge set property AURA_BOT_ENDPOINT  "https://1111-11-11-111-11.ngrok.io/api/messages"

To see the answer, you need to modify the service URL of the activity with the aura-bridge enpoint of the environment.

ProxyBehavior

It allows redirecting requests made to aura-bridge to an alternative URL.

This redirection is based on the configuration of two parameters:

urlPath: String to match with the value of req.path in the original request.
endpointDestination: URL base where the petition will be redirected.

Plugin controller stub:

Name	Stub destination	Description
Bridge proxy	plugin controller	Modify plugin controller to perform a redirection of incoming request

This behavior will affect those plugins that define the behaviorController field in the API type plugin definition.

Commands:

Name	Description
set:proxy	Set new proxy. Params
get:proxy	Get proxy. Params [urlPath]
get:proxies	Get all proxies
unset:proxy	Remove proxy. Params
unset:proxies	Remove all proxies

PluginBehavior

It allows you to display information regarding the aura-bridge plugins.

Commands:

Name	Description
get:plugins	Get all loaded bridge plugins
get:stubPlugins	Get plugins with behavior manager active (can manage commands)

Use cases

How to redirect requests from WhatsApp to your local Aura bridge

Set proxy with the following aura-bridge command and all requests from WhatsApp (“whatsapp/messages”) in the conversation will be redirected to the local aura-bridge. For example, at a local address using ngrok (https://1111-11-11-111-11.ngrok.io):

/bridge set proxy "whatsapp/messages" "https://1111-11-11-111-11.ngrok.io"

Docs:

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

aura-logging utility

aura-logging utility is used for controlling login in Aura

Introduction

aura-logging utility is a custom login tool across every Aura apps intended to prevent possible errors in execution time or unspecified login format.

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

The current logging format, including different fields and logging levels to be used across Aura components, is included in the Aura logging common format section.

emit function has been deprecated, please use logging method in future implementations:

jest.spyOn(AuraLog.prototype, 'logging').mockImplementation();

Use aura-logging utility

Basic usage

import { AuraLogger } from '@telefonica/aura-logging';

const logger: AuraLog = new AuraLog('new-component');

logger.debug(msg: 'ok');

Configuration

Set level and format

import { AuraLogger } from '@telefonica/aura-logging';

AuraLogger.setLevel('DEBUG');
AuraLogger.setFormat('json');

Set default fields on each log

import { AuraLogger } from '@telefonica/aura-logging';

AuraLogger.defaultFields({version: '1.2.3', app: 'randomApp'});

Everything else should be managed by the dependency.

aura-logging format

The current section describes the process for writing operational logs by Aura components and the defined fields and levels.

File format: JSON
- If possible, each input in a log file might be a plain JSON object
What should be logged in each level:
- DEBUG LEVEL:
  - in/out of each step in a server
  - Incoming requests in a server
  - DB access
  - Health-check requests
  - Any other thing interesting for the developer
- INFO LEVEL:
  - Outgoing responses in a server
  - Calls to external APIs (see HTTP requests below)
  - Message pushed to queues
  - Bot: NLP resolution
  - Bot: after user authentication, logs user’s data
- WARN LEVEL:
  - A non blocking error or special situation in the current request
- ERROR:
  - Outgoing error responses in a server
  - Error responses from external APIs (see HTTP requests below)
- FATAL:
  - If server is closed

Fields names

Fields marked in bold are mandatory
Fields marked in italics are optional

Common

All logs in the system must count on the following list of fields:

Field	Type	Format	Description
time	string	YYYY-mm-DDTHH:MM:SS.MSSZ	ISO 8601 UTC time
corr	string	UUID	Cross component request identifier
msg	string	List of messages	Description of the operation
lvl	string	Valid log level	One of `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
host	string	string	POD where the container is running
version	string	X.Y.Z	Version of the component writing the log
module	string	string	Class/module identifier within the component writing the log

All logs in the system could count with the following field:

Field	Type	Format	Description
app	string	string	Application name

Specific cases

Outgoing server response (INFO and ERROR)

Field	Type	Format	Description
drt	integer	number	Request duration in milliseconds
status	integer	HTTP status code	Valid HTTP status code
path	string	string	HTTP servers: endpoint path aura-bot: library resolving the request
method	string	HTTP method name	HTTP method called (in case of HTTP servers)

Examples

Successful response

{
    "time": "2019-04-05T11:51:09.325Z",
    "lvl": "INFO",
    "corr": "9c83c5d8-f3b5-4074-b475-28e2f528dd50",
    "userId": "123456677890",
    "auraId": "9c83c5d8-f3b5-4074-b475-28e2f528dd50",
    "auraIdGlobal ": "12344556778900 asdf3455",
    "channelId ": "f110f872-5d99-4839-b950-452847f1e59a",
    "version ": "8.2.1",
    "module ": "aura-users-controller",
    "msg ": "Get user by auraid",
    "drt ": 45,
    "status": 200,
    "path": "/users/123456677890",
    "method": "GET"
}

Error response

{
    "time": "2019-04-05T11:51:09.325Z",
    "lvl": "ERROR",
    "corr": "9c83c5d8-f3b5-4074-b475-28e2f528dd50",
    "userId": "123456677890",
    "auraId": "9c83c5d8-f3b5-4074-b475-28e2f528dd50",
    "auraIdGlobal ": "12344556778900 asdf3455",
    "channelId ": "f110f872-5d99-4839-b950-452847f1e59a",
    "version ": "8.2.1",
    "module ": "aura-users-controller",
    "msg ": "AuraId does not exist",
    "drt ": 45,
    "status": 404,
    "path": "/users/123456677890",
    "method": "GET"
}

Error cases

Field	Type	Format	Description
error	string	error.message	Exact error message returned by the failed request/module
stck	string	stack trace of the error	Only in DEBUG for `expected` errors. In ERROR for `unexpected`

HTTP requests and responses

This type is used both at the request and at the response. At the response it has more fields.

Field	Type	Format	Description
method	string	HTTP method name	Name of the HTTP method
domain	string	FQDN	Domain name called with this request
path	string	`//`	Path called by the request, including params
reqParams	string	csv key:value	Only for DEBUG logs. Array of request params: headers, except: `Authorization`, `x-token-info`, query and body params, except: `jwt`, `code`, `sastoken`
status	string	HTTP status code	Valid HTTP status code. Only response
drt	integer	number	Total duration of the request processing in milliseconds. Only response.
body	string	string / json	Only for DEBUG logs. Complete `response.body`
origin	string	comma separated string	From header `X-Real-IP` or `remoteAddress` field from express request

Examples

Request

 {
     "time": "2019-04-05T11:51:09.325Z",
    "lvl": "INFO",
    "module": "aura-http-monkey-patcher",
    "domain": "localhost",
    "method": "POST",
    "path": "/deployments/deployment_bot_gpt-35-turbo/chat/completions?",
    "corr": "no-correlator",
    "version": "8.5.0",
    "app": "aura-gateway-api",
    "host": "mac-XQM577TDV0"
}

Successful response

{
    "time": "2019-04-05T11:51:09.325Z",
    "lvl": "INFO",
    "corr": "9c83c5d8-f3b5-4074-b475-28e2f528dd50",
    "method": "GET",
    "domain": "api.global-int.baikalplatform.com",
    "path": "/userprofile/v3/users/123456677890",
    "version ": "8.2.1",
    "module ": "subscriptions-service",
    "msg ": "User profile retrieved",
    "origin": "10.0.0.1",
    "drt ": 45,
    "status": 200
}

Error response

{
    "time": "2019-04-05T11:51:09.325Z",
    "lvl": "INFO",
    "corr": "9c83c5d8-f3b5-4074-b475-28e2f528dd50",
    "method": "GET",
    "domain": "api.global-int.baikalplatform.com",
    "path": "/userprofile/v3/users/123456677890",
    "version ": "8.2.1",
    "module ": "subscriptions-service",
    "msg ": "User profile cannot be retrieved",
    "origin": "10.0.0.1",
    "drt ": 45,
    "status": 403,
    "error": "{\"code\":\"PERMISSION_DENIED\",\"message\":\"Client does not have sufficient permission\"}"
}

Aura Bot

In aura-bot, the outgoing response message of the server should include these fields:

Field	Type	Format	Description
conversationId	string	string	Identifier of the conversation in DL
fromId	string	string	Identifier of the user in the channel
replyToId	string	string	Identifier of the message being answered
type	string	string	Type of the activity, in this version only `message`
locale	string	2 letters: lang-country	ISO culture code: `en-gb`, `es-es`, etc.

Aura NLP

In Aura NLP, the outgoing response message of the server should include these fields:

Field	Type	Format	Description
intent	string	intent.{name} or None	Intent resolved by Aura NLP server
domain	string	string	Domain to which the detected intent belongs
accuracy	float	Four decimals number, [0, 1]	Probability of returning the correct intent

Logging levels and usages

Level	Description
DEBUG	Log extra info and steps, for development purposes.
INFO	To follow the request with the most important steps and information
WARN	A non blocking error or special situation in the current request
ERROR	A blocking error in the current request
FATAL	A blocking error that avoids the normal behavior of the server, so it would be stopped.

Correlator policy

The correlator property in the log traces (corr) is mandatory in all levels but DEBUG, even though it is also highly recommended in that level.

We can use a correlator passed by in the original request (from other component), and we will use the same correlator in requests to other components (that allows them) in order to keep a cross-component correlator (the same correlator is used in the all the request-response flow, involving several APIs/servers/components).

If the correlator is not passed by the component creating the request, a new random correlator is generated at the beginning of the flow and is used from then on (even in requests to other components).

The correlator is used to relate all operations done in a request-response flow, that is all things done from the moment when the user starts the request untilaura-bot sends the last response (all operations logged must have the same corr).

There are a couple of exceptions to the last rule, as we are not able to get a correlator in all cases (some of them within a request-response flow, others outside it). Some special values are defined to know in which case the log trace is:

corr	Description
<uuid>	Normal case. The same correlator is used in all the request-response flow (passed in the original request, or random generated at the beginning).
no-correlator	The log trace does not have a correlator because it cannot have one (i.e., by technical limitations, such as HTTP request triggered by an event).
aura-system	The log trace is outside a request-response flow (such as server starting, server stopping, etc.)
null\|undefined	These values are not permitted and are always considered a bug.

⚠️ Note: Do not abuse of the use of no-correlator, when the developer is lazy enough to get the current request-response correlator, and prefers to set no-correlator to avoid the bug detection when null or undefined. no-correlator means that it is impossible to get the correlator.

Standard logs

The log id must be:

The name of the class, if we are writing a class:

// to class AuraBridgeFlow
const logger: AuraLog = new AuraLog('aura-bridge-flow');

The name of the file, if we are writing an utility file:

// to dialog whatsapp-utilities file
const logger: AuraLog = new AuraLog('whatsapp-utilities');

The dialog identifier if we are writing a dialog:

// to dialog DisambiguationDialog
const logger: AuraLog = new AuraLog(DisambiguationDialog.id);

Define the log outside the class to avoid attacks:

const logger: AuraLog = new AuraLog('aura-bridge-flow');

export class AuraBridgeFlow {
    ...
}

In the dialogs, it is convenient to use this standard: [${Dialog.id} dialog]

logger.debug({ msg: `[${DisambiguationDialog.id} dialog] Started`, corr });

You can include an object as a string key to get more information about the case. In this scenario, avoid including very large objects to precent blocking the pods due to logs writing.

logger.info({ msg: 'Try to upload and validate attachments', fromId: from, auraId: auraUser.auraId, corr });