Develop features

• 1: Aura common utilities
• 1.1: Aura Bot utilities
• 1.1.1: aura-bot-kpis
• 1.1.2: aura-bot-library-util
• 1.1.3: aura-minibot-service
• 1.1.4: aura-movistar-libraries
• 1.1.5: Aura Bot Common library
• 1.1.5.1: Aura utils
• 1.1.5.2: Bridge utils
• 1.1.5.3: Aura channelData utils
• 1.1.5.4: Conversational context utils
• 1.1.5.5: Ai service
• 1.2: Aura utilities
• 1.2.1: aura-channel-data-handler
• 1.2.2: aura-server-common
• 1.2.2.1: dapr-pubsub-service plugin
• 1.2.2.2: API definition
• 1.2.2.2.1: Dapr PubSub API
• 1.2.3: aura-configuration
• 1.2.4: aura-crypto-adapter
• 1.2.5: aura-locale-manager
• 1.2.6: aura-models
• 1.2.7: aura-mongo-handler
• 1.2.8: aura-orchestrator
• 1.2.9: aura-storage-file-manager
• 1.2.10: aura-validate-apikey
• 1.2.11: aura-file-validator
• 1.2.12: aura-redis-handler
• 1.3: Aura develop utilities
• 1.4: Aura Clients
• 1.5: aura-http-monkey-patcher
• 1.6: aura-json-schema-generator
• 1.7: aura-kpis
• 1.8: aura-behavior-manager
• 1.9: aura-logging
• 2: Develop a bridge plugin
• 3: Develop filters for Engine filter API
• 4: Contributing to Aura
• 4.1: Access to Github repositories
• 4.2: Contributing with code
• 4.3: Migrate a git folder
• 4.4: Manage Jira
• 4.5: Source Folder Layout
• 5: Upgrade Aura Bot
• 6: Release Train Manager
• 6.1: Github as Orchestrator
• 6.2: Branch Configuration
• 6.2.1: Main branch stages
• 6.3: Managing locales
• 6.4: API definition

1 - Aura common utilities

Aura common utilities

Introduction

aura-common-utilities is a multipackage repository with all the libraries provided by Aura team to make development easier.

aura-common-utilities repository is organized into four packages:

• aura-bot-utilities, used for handling different tasks over aura-bot.
• aura-utilities, used by other Aura components.
• aura-develop-utilities, that include utilities used for different development purposes.
• aura-clients referred to tools that make easier to call APIs.

Additionally, there are certain utilities that have not been migrated to these packages yet and are documented outside the packages sections.

1.1 - Aura Bot utilities

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.

1.1.1 - aura-bot-kpis

aura-bot-kpis utility

Introduction

The aura-bot-kpis utility contains the necessary utilities to manage KPI entities in aura-bot and aura-groot.

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

These guidelines will allow you to get a copy of the project running on your local machine for development and testing purposes.

Run tests

This project uses Jest for BBDD testing.

Unit tests

$ npm run test

Style tests

These tests perform the validation coding rules defined in Aura using the eslint tool.

You can validate the code using:

$ npm run lint

Coverage tests

You can run the coverage tests using:

$ npm run test

The threshold established to validate the coverage is as follows:

• lines: 90%
• functions: 90%
• statements: 90%
• branches: 70%

Versioning

We use [SemVer] (http://semver.org/) for versioning.

More information regarding latest versions:

$ npm show @telefonica/aura-bot-kpis

1.1.2 - aura-bot-library-util

aura-bot-library-util utility

Introduction

aura-bot-library-util utility is an NPM library with utility functions provided by the Aura Bot Global Team to make it easier the development of dialogs in aura-bot.

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

This library only contains utilities used in the dialogs, not needed by the bot itself.

To use it, just define the dependency with @telefonica/aura-bot-library-util in your package.json file. It is published as a private library in NPM, so request a valid NPM token to access it.

The utility files included in aura-bot-library-util utility are described in the following sections.

CurrencyUtils

aura-bot-library-util/currency-util.ts

getLocalizedCurrency

It returns money amounts formatted with country specific settings.

    const amount: string = getLocalizedCurrency('es-es', 460.56, 'EUR');

    /* 460.56 € */

    const amount: string = getLocalizedCurrency('es-uy', 460.56, 'UYU');

    /* $ 461 */

Datautils

aura-bot-library-util/data-unit-util.ts

getDataAndUnit

It returns converted internet data amount and unit from bytes quantity, following the country specific settings.

    const [dataQt, dataUnit] = getDataAndUnit(context, config, 1536)
    const [dataQt, dataUnit] = getDataAndUnit(context, config, 1536, true)

    /*
     * Result depending on AURA_DEFAULT_LOCALE env var
     * pt-br - ['1,5', 'GB']
     * en-gb - ['1.50', 'GB']
    */

LocaleUtils

aura-bot-library-util/locale-util.ts

getLiteral

This intermediate method generates a getText function ready to receive resources keys and sequential params.

    /* If we need to convert only one text in function scope, we can use it as one line function */

    const text: string = getLiteral(context, 'services')('services.find.moreinfo', param1, param2);
    const text: string = getLiteral(context)('services:services.find.moreinfo', param1, param2);

    /* When we need to convert several texts in function scope for the same library,
    we can preassign result function to variable and proceed all along dialog step */

    const getServicesText: Function = getLiteral(context, 'services');

    const text: string = getServicesText('services.find.moreinfo', param1, param2);

    /* if we need to convert several texts in function scope for several libraries */

    const getText: Function = getLiteral(context);

    const text: string = getText('services:services.find.moreinfo', param1, param2);
    const errorText: string = getText('errors:error.notFound');

getTextByKeys

Factory function used mainly in graphs to retrieve converted text objects, avoiding redundancy.

    const getGraphText: Function = getTextByKeys(context, 'graphics');

    const texts: any = getGraphTexts(['of', 'remaining'], { unit: 'data.gb' })

    /* Output
        {
            of: 'graphics:of', // converted text,
            remaining: 'graphics:remaining', // converted text,
            unit: graphics:data.gb, // converted text
        }
    */

withLocale

It encapsulates all data we need to call LocaleManager instance getText method.

For instance, getLiteral function passes an inline arrow function to simply receive the params that the result function was invoked with:

    /**
     * handy method to retrieve text.
     *
     * @param  {TurnContext} context The dialog step context.
     * @param  {string} libraryName? Library name.
     */
    export function getLiteral(context: TurnContext, libraryName?: string) {
        return withLocale(
            context,
            ({ getText, library }: any, literal: string, ...args: any[]) => getText(`${library ? library + ':' : ''}${literal}`, args),
            libraryName
        );
    }

This way, we can compose any method that fits our dialog text composition specific needs. A trivial working code sample could be:

    const _getText: Function = withLocale(stepContext.context, intermediateFunc)

    function intermediateFunc({ getText }, obj: any, params: string[], isError?: boolean) {
        const finalTextKey: string = isError ? obj.error : obj.text;
        return getText(finalTextKey, params);
    }

    const obj = {
        text: 'services:services.some.text',
        error: 'errors:error.message.error'
    }

    const text: string = _getText(obj, ['first', 'second']);
    const errorText: string = _getText(obj, [], true);

getErrorMessage

It composes a full error message with fallback text when required.

    export interface StatusCodeMessagesMap {
        default: string;
        code400?: string;
        code404?: string;
    }
    try {
        //Do stuff
    } catch (error) {
        const messageMap: StatusCodeMessageMap = {
            default: 'services:services.custom.error',
            code400: 'services:services.error.badRequest',
            code404: 'services:services.error.notFound'
        }

        const errorMessage: string = getErrorMessage(stepContext.context, error.code, messageMap)
    }

sendLoggerErrorAndActivity

It sends full logged error message activity.

    try {
        /* [...] */
    }  catch (error ) {

        const messageMap: StatusCodeMessageMap = {
            default: 'services:services.custom.error',
            code400: 'services:services.error.badRequest',
            code404: 'services:services.error.notFound'
        }


        sendLoggerErrorAndActivity(
            context,
            this.logger,
            messageMap,
            ServicesFindDialog.id,
            error
        )
    }

LibraryUtil

aura-bot-library-util/library-util.ts

excludeDialogs

It excludes dialogs provided in an array.

excludeDialogs(dialogNames: string[], options: any);

readLocaleFolder

Ir returns an object with locale name as key and file content as value.

readLocaleFolder(localePath: string);

readEnv

It returns an object with env variables from current environment.

readEnv(configuration: any, envPath: string);

readDialogConfig

It returns an object with dialog config from current environment.

readDialogConfig(configuration: any, configPath: string);

replaceToDialogByIntent

Given an intent, it replaces the current dialog by the intent that matches with it. This method triggers the main dialog and keeps the context-filter functionality in the replaced one.

await replaceToDialogByIntent(stepContext: WaterfallStepContext, intent: string);

generateSasUrl

It generates and returns the URL of the blob resource, applying expiration.

await generateSasUrl(fileName: string, remoteContainerPath: string,
    configuration: Configuration, corr?: string, expiration?: number);

uploadFileUrl

It uploads a file to Azure Storage from an URL.

await uploadFileUrl(sourceUrlFile: string, remoteFilePath: string,
    configuration: Configuration, corr?: string, containerName?: string) ;

ResourcesUtils

aura-bot-library-util/resources-util.ts

getImageUrl

It intercalates supported resolution folder path into image path, following channel image resolution settings.

    // Current supported resolutions.
    enum SupportedResolutions {
        HDPI = 'hdpi',
        XHDPI = 'xhdpi',
        XXHDPI = 'xxhdpi',
        XXXHDPI = 'xxxhdpi'
    }

    // Taking channelData imageSettings resolution == xxxhdpi

    getImageUrl(context, 'services', 'images/default/imageName.png', configuration);

    // https://<storageUrl>/libraries/services/images/xxxhdpi/imageName.png?<params>

getResourcePath

It gets the whole resource path uploaded to blob-storage, that is accessible, to be included in cards.

const uri: string = DialogUtils.getResourcePath('generic', resource, this.configuration);

1.1.3 - aura-minibot-service

aura-minibot-service utility

Introduction

The aura-minibot-service utility contains the common elements needed by aura-bot and aura-groot to generate their mini versions: scripts, mock classes and templates, etc.

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

These guidelines will allow you to get a copy of the project running on your local machine for development and testing purposes.

Run tests

This project uses Jest for BBDD testing.

Unit tests

$ npm run test

Style tests

These tests perform the validation coding rules defined in Aura using the eslint tool.

You can validate the code using:

$ npm run lint

Coverage tests

You can run the coverage tests using:

$ npm run test

The threshold established to validate the coverage is as follows:

• lines: 90%
• functions: 90%
• statements: 90%
• branches: 70%

Versioning

We use [SemVer] (http://semver.org/) for versioning.

More information regarding latest versions:

$ npm show @telefonica/aura-minibot-service

1.1.4 - aura-movistar-libraries

aura-movistar-libraries utility

Introduction

aura-movistar-libraries utility is an NPM library that contains utility functions provided by Aura Global Team to be used with dialogs in Movistar channels:

• Movistar Home
• Movistar Plus
• Set-top-box (STB)

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

To use it, just define the dependency with @telefonica/aura-movistar-libraries-utilities in your package.json. It is published as a private library in npm, so request a valid NPM token to access it.

models/intent-models

It contains all the necessary classes and interfaces for Movistar use cases. Some of these classes and interfaces are: MovistarPlusResolution, MovistarStatus, SuggestionAction, etc.

utils/movistar-payload-utils

It contains the functions executed to fill the payload of the message depending on the settings/payloadType in the intent configuration.

The principal functions are: getPayloadDefault, getPayloadCommunications, getPayloadTV and getPayloadWifi.

utils/movistar-resolution-utils

It contains the function to make a query to the Movistar plus resolution API. This query returns a MovistarPlusResolution object that contains suggestions, actions, sound, payload, etc.

Object example returned by getMovistarPlusResolution with intent intent.common.greetings in the STB channel:

{
      "intent":"intent.common.greetings",
      "entities":[

      ],
      "resources":[
         {
            "type":"title",
            "name":"tv.notUnderstand",
            "params":{

            }
         }
      ],
      "status":"ok",
      "payload":{
         "type":"",
         "data":{

         },
         "data_additional":{

         },
         "action":"NONE",
         "status":{
            "code":"470",
            "message":"Intent not Supported Error - General Code",
            "info":{ 

            }
         }
      },
      "user_action":{

      },
      "suggestions":[
         {
            "intent":"intent.tv.display",
            "entities":[
               {
                  "entity":"Canal Cocina",
                  "type":"ent.audiovisual_channel",
                  "score":1,
                  "canon":"Canal Cocina",
                  "label":""
               }
            ],
            "resources":[
               {
                  "type":"title",
                  "name":"tv.switchToChannel.suggestion.title",
                  "params":{
                     "channels":"Canal Cocina"
                  }
               },
               {
                  "type":"button",
                  "name":"tv.switchToChannel.suggestion.button",
                  "params":{
                     "channels":"Canal Cocina"
                  }
               }
            ]
         }
        /// More suggestions were returned but are ommited in this example object
      ],
      "sound":"none"
   }

utils/movistar-utils

A compendium of utilities which formats activity’s channelData to be compatible with Movistar channels.

The principal function of this file is getMovistarMessage. It returns a properly formed channelData message for the Movistar channels, depending on the input parameters and the settings field in the configuration of the intent. All other functions are auxiliary of this principal.

Example of object returned by getMovistarMessage with input params:

Input params

• Context: Context of the dialog
• Text: null
• MovistarConfig:

{
   "type":"common",
   "action":"COMMON.GREETINGS",
   "locales":{
      "success":[
         "common:common.greetings.main"
      ],
      "error":[
         "common:common.error.main"
      ]
   },
   "needTvResolution":true
}

• MovistarPlusResolution: Same as show in previous example

Output message

{
   "text":"Hola, buenas",
   "channelData":{
      "intent":{
         "id":"intent.common.greetings",
         "name":"intent.common.greetings",
         "entities":[

         ]
      },
      "content":{
         "text":"Hola, buenas",
         "speak":"Hola, buenas",
         "sound":"positive",
         "actions":[

         ]
      },
      "dialogContext":[
         {
            "text":"Quiero ver Canal Cocina",
            "value":{
               "intent":"intent.tv.display",
               "entities":[
                  {
                     "entity":"Canal Cocina",
                     "type":"ent.audiovisual_channel",
                     "score":1,
                     "canon":"Canal Cocina",
                     "label":""
                  }
               ]
            }
         }
         /// More suggestions were returned but are ommited in this example object
      ],
      "customData":{
         "type":"common",
         "action":"COMMON.GREETINGS",
         "data":{

         },
         "data_additional":{

         },
         "status":{
            "code":"200",
            "message":"Success - General Code",
            "info":{

            }
         }
      },
      "fullScreen":false,
      "version":"1.0.0"
   },
   "inputHint":"acceptingInput",
   "attachments":[
      {
         "contentType":"application/vnd.microsoft.card.hero",
         "content":{
            "buttons":[
               {
                  "type":"postBack",
                  "title":"Quiero ver Canal Cocina",
                  "value":{
                     "name":"Quiero ver Canal Cocina",
                     "text":"Ver Canal Cocina",
                     "type":"suggestion",
                     "intent":"intent.tv.display",
                     "entities":[
                        {
                           "entity":"Canal Cocina",
                           "type":"ent.audiovisual_channel",
                           "score":1,
                           "canon":"Canal Cocina",
                           "label":""
                        }
                     ],
                     "inputIntent":"intent.common.greetings",
                     "inputEntities":[

                     ]
                  }
               }
               /// More suggestions were returned but are ommited in this example object
            ]
         },
         "name":"SUGGESTIONS"
      }
   ]
}

suggestionType

Formerly, there was a differentiation between channels based on their prefix. This implementation was quite strict and to parameterize this behavior a new configuration variable has been developed.

SuggestionType must be configured for channels Movistar-Plus, Set-on-Box and Set-on-Box-Haac and its value can be either actions or attachments describing where suggestions must be placed in activity’s channelData.

• ‘actions’: Movistar-Plus
• ‘attachment’: Set-on-Box, Set-on-Box-Haac

1.1.5 - Aura Bot Common library

Aura Bot Common library

Introduction

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

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

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

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

1.1.5.1 - Aura utils

Aura utils

Introduction

Aura utils utility allows managing Aura dialogs and prompts.

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

It contains different methods, described in the following sections.

DialogUtils

Generic tools for any dialog.

setDataActiveDialog

It saves data between steps of a waterfall. Only valid in the same dialog.

DialogUtils.setDataActiveDialog(stepContext, KEY_DESCRIPTION, description);

getDataActiveDialog

It gets data between the steps of a Waterfall through an identifier.

const description = DialogUtils.getDataActiveDialog(stepContext, KEY_DESCRIPTION);

getResourcePath

It gets the whole resource path uploaded to blob-storage to be included in cards.

const uriGenericRaw= DialogUtils.getResourcePath('generic', `${this.configuration.GENERIC_RESOURCES_BASE_PATH}/config/${this.configuration.GENERIC_RAW_NAME}`, this.configuration)

If we need a full URL image path including device resolution, getImageUrl method from @telefonica/aura-bot-library-util should be used instead.

isDeeplink

It returns true if the passed URL is a deeplink, and false otherwise.

const isDeepLink = DialogUtils.isDeeplink('http://movistar.es/campain/ahora.html')

PromptUtils

getRetriesValidator

It gets a validator function that will be called each time the user responds to the prompt. In this function, it controls the number of retries to show the prompt.

If attempt is allowed, it is the recognizer that will let an attempt (when there are not results) or the dialog the will manage the result found.

If the retries exceed to maxRetries parameter, the control will be returned to dialog, managing results or not.

If an attempt is shown, the configured retryPrompt (or the same prompt as default) will be shown.

// Create a ChoicePrompt without retries
const myPrompt = new ChoicePrompt(ID_PROMPT,PromptUtils.getRetriesControl(0));

getRetriesValidatorAndOverwriteRecognizerResult

This validator function is similar to getRetriesValidator but also overwrites the recognizer result obtained by the prompt recognizer with a previous stored value.

This recognizer result value can be set with the function ContextUtils.setPromptRecognizedResult. By default, the result is: prompt-check-recognizer-middleware.

// Create a ChoicePrompt with 3 retries and use of ordinals control overwriting promptRecognizedResult with the value of aura-bot.
const myPrompt = new ChoicePrompt(ID_PROMPT,PromptUtils.getRetriesValidatorAndOverwriteRecognizerResult(3));

getAbsolutePath

It returns an absolute normalized file path.

const path: string = getAbsolutePath('/test/demo_path.txt');

1.1.5.2 - Bridge utils

Bridge utils

Introduction

Bridge utils utility includes methods for managing aura-bridge.

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

It contains different methods, described in the following sections.

getAsyncCallbackUrl

This method is used for use cases that use asynchronous APIs and have to send a callback URL. It builds the URL with the parameters expected by the end point of aura-bridge, which will be the one that receives the event.

This returns the URL to send as callback parameter.

    function getAsyncCallbackUrl(context: TurnContext,
        configuration: Configuration, callbackId?: string, apiKeyHeader: boolean = false): string

Example of use:

const callbackUrl = getAsyncCallbackUrl(stepContext.context, this.configuration, callbackId);

getAsyncCallbackUrlDataEncrypt

This method builds the URL with the parameters expected by the endpoint for async-callbacks in aura-bridge.

   function getAsyncCallbackUrlDataEncrypt(auraId: string, channelId: string, conversationId: string, corr: string, configuration: Configuration, version: string, messageId: string, callbackId?: string, apiKeyHeader: boolean = false): string

Example of use:

const callbackUrl = getAsyncCallbackUrlDataEncript( auraId, channelId, conversationId, corr, configuration, version, messageId, callbackId, true);

1.1.5.3 - Aura channelData utils

Aura channelData utils

Introduction

channelData utils utility allows managing Aura channelData.

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

It contains different methods, described in the following sections.

getAuraModality

It returns the modality associated to a context. Otherwise, it returns an error if the channel could not be retrieved and injected into the message.

Types of AuraModality:

export enum AuraModality {
    text = 'text',
    voice = 'voice',
    form = 'form'
}

Example of use:

const modality = ChannelDataUtils.getAuraModality(context);

getFullAura

It returns fullAura object from auraMode.

Example of use:

const fullAura = ChannelDataUtils.getFullAura(context);

getAppContext

It gets AppContext from client and returns an structure with certain information about the client such as: device, application, location, channel, etc.

Example of use:

const appContext = ChannelDataUtils.getAppContext(context);

getCustomContent

It returns a boolean if it is a custom content.

Example of use:

const isCustomContent: boolean = ChannelDataUtils.getCustomContent(context);

getAuraId

It gets Aura id from the activiy.

Example of use:

const auraId: string = ChannelDataUtils.getAuraId(context);

getAuraCommandIntent

It gets the auraCommand intent.

Example of use:

const auraCommandIntent: string = ChannelDataUtils.getAuraCommandIntent(context);

getChannelConfiguration

It gets the complete channel configuration from id or name.

Example of use:

const channel: ChannelConfiguration = ChannelDataUtils.getChannelConfiguration(channelsConfiguration, channelId, channelName);

getChannelId

It gets the channel Id.

Example of use:

const channelId: string = ChannelDataUtils.getChannelId(context);

getChannelName

It gets the channel name.

Example of use:

const channelName: string = ChannelDataUtils.getChannelName(context);

getChannelPrefix

It gets the channel prefix.

Example of use:

const channelPrefix: string = ChannelDataUtils.getChannelPrefix(context);

getDeviceId

It gets the device Id.

Example of use:

const deviceId: string = ChannelDataUtils.getDeviceId(context);

getAccountNumber

It gets the account number from userContext.

Example of use:

const accountNumber: string = ChannelDataUtils.getAccountNumber(context);

getRequestVersion

It returns the channelData version. If it is not found, AURA_CHANNELDATA_DEFAULT_VERSION will be returned.

Example of use:

const version: string = ChannelDataUtils.getRequestVersion(context);

setAppContext

It sets AppContext in channelData. In certain scenarios, it will be necessary to overwrite it to keep the track of changes that have occurred (e.g., in the applied contextFilters).

Example of use:

ChannelDataUtils.setAppContext(context, appContext);

getActions

It gets actions from channelData. If exists, target will only extract actions for this target.

Example of use:

const actions = ChannelDataUtils.getActions(context);

getStatusFromMessage

It gets status to message activity.channelData.status.

Example of use:

const status: AuraResponseStatus = ChannelDataUtils.getStatusFromMessage(activity): ;

getPayloadEvent

It gets the payload event.

Example of use:

const payload: ChannelDataPayload.PayloadEvent = ChannelDataUtils.getPayloadEvent(context);

getPayloadAsyncCallback

It gets the payload asyncCallback.

Example of use:

const payload = ChannelDataUtils.getPayloadAsyncCallback(context);

getPayloadBridgeUser

It gets the bridge user.

Example of use:

const payload: ChannelDataPayload.PayloadEvent = ChannelDataUtils.getPayloadBridgeUser(context);

Methods to be used only by Aura Bot

setAuraCommad

It sets an auraCommand, adding to the channelData attribute the auraCommand object with the type and value attributes.

Example of use:

ChannelDataUtils.setAuraCommad(this.context, new AuraCommand(AuraCommandType.TYPE, commandValue))

setResponseVersion

It sets the channelData version.

Example of use:

const currentResponseVersion: string = ChannelDataUtils.setResponseVersion(activity, ConfigurationManager.instance.environmentConfiguration);

checkRequestVersion

It determines whether the version is major than AURA_RESPONSE_VERSION or not.

Example of use:

const check: boolean = ChannelDataUtils.checkRequestVersion(context, ConfigurationManager.instance.environmentConfiguration);

setStatusToMessage

It sets status to message activity.channelData.status.

Example of use:

ChannelDataUtils.setStatusToMessage(activity, status): ;

1.1.5.4 - Conversational context utils

Conversational context utils

Introduction

Conversational context utils utility allows managing BotFramework TurnContext.

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

It contains different methods, described in the following sections.

getAuraUser

It gets the AuraUser with the minimum BaseModel attributes and, optionally, more specific attributes of the authenticator.

Minimum BaseModel attributes:

export interface AuraUserBaseModel<T> {
    auraId: string;
    auraIdGlobal: string;
    type: AuraUserType;
    userId: string;
    authData: T;
    channel: ChannelConfiguration;
    timestamp: number;
    deviceId?: string;
    accountNumber?: string;
    phoneNumber?: string;
    authorizationId?: string;
    redirectIntent?: string;
    originalAddress?: MessageUserInfo;
    sessionId?: string;
    idTokenHint?: string;
}

Example of use:

const auraUser = ContextUtils.getAuraUser(context);

getAuraPersistentData

It gets persistent data including information about: conversationData, userData and dialogData.

export interface AuraPersistentData {
    conversationData: any;
    userData: any;
    dialogData: any;
}

Example of use:

const persistentData = await ContextUtils.getAuraPersistentData(stepContext.context);
if (persistentData.conversationData.orderPizza) {
    orderPizza = persistentData.conversationData.orderPizza;
}
...

getCorrelator

It gets the correlator (identifier to track the request).

const corr: string = ContextUtils.getCorrelator(stepContext.context);
this.logger.info({ msg: 'App GenericFaq Closed', corr });

getRecognitionResult

It gets the result of the recognition process.

⚠️ In some cases, the recognition process has been altered to avoid the execution of other recognizers and the result might not be as expected.

export interface RecognizerResult {
    /**
     * Utterance sent to recognizer
     */
    readonly text: string;
    /**
     * If original text is changed by things like spelling, the altered version.
     */
    readonly alteredText?: string;
    /**
     * Intents recognized for the utterance.
     *
     * @remarks
     * A map of intent names to an object with score is returned.
     */
    readonly intents: {
        [name: string]: {
            score: number;
        };
    };
    /**
     * (Optional) entities recognized.
     */
    readonly entities?: any;
    /**
     * (Optional) other properties
     */
    [propName: string]: any;
}

Example of use:

const recognitionResult: RecognizerResult = ContextUtils.getRecognitionResult(stepContext.context);
const entities = recognitionResult.entities;

getTopIntentResult

Among all the recognized intents, it gets the topIntent with the highest score and the utm information.

⚠️ In some cases, the recognition process has been altered to avoid the execution of other recognizers and the result might not be as expected.

export interface AuraIntentResult extends RecognizerResult {
    topIntent: Intent;
    utm: Utm;
}

Example of use:

const auraIntentResult: AuraIntentResult = ContextUtils.getAuraIntentResult(stepContext.context);
const utmInfo: Utm = auraIntentResult.utm;

getTopIntent

Among all the recognized intents, it gets the topIntent with the highest score directly.

⚠️ In some cases, the recognition process has been altered to avoid the execution of other recognizers and the result might not be as expected.

export interface Intent {
    intent: string;
    entities?: IEntity[];
    score?: number;
    type?: IntentType;
}

Example of use:

const auraIntentResult: Intent = ContextUtils.getTopIntent(stepContext.context);

getTopIntentValue

Among all the recognized intents, it gets the topIntent value in string format. For example: intent.balance.check.

⚠️ In some cases, the recognition process has been altered to avoid the execution of other recognizers and the result might not be as expected.

Example of use:

const intent : string = ContextUtils.getTopIntentValue(stepContext.context);

getUserChannel

It gets the user’s channel.

export interface ChannelConfigurationPartial {
    auraBotCacheTTL?: number;
    id: string;
    brand?: string;
    dialogLibraries?: DialogLibraryConfiguration[];
    name?: string;
    nlp?: NlpConfig;
    actions?: ChannelActions;
    prefix?: string;
    requestOptions?: RequestOptionsModel;
    responseOptions?: ResponseOptions;
    security?: Security;
    whatsapp?: WhatsAppModel;
    type?: BridgeType;
    metadata?: DocumentMetadata;
}
export interface ChannelConfiguration extends ChannelConfigurationPartial {
    brand: string;
    name: string;
    prefix: string;
    nlp: NlpConfig;
}

Example of use:

const userChannel: ChannelConfiguration = ContextUtils.getUserChannel(stepContext.context);

getPromptRecognizedResult

It gets the recognizerResult from turnState to retrieve the value in the validator function.

This function is currently used in getRetriesValidatorAndOverwriteRecognizerResult function, used for overwrite the default recognizerResult with the result got in the prompt recognizer.

Example of use:

const userChannel: PromptRecognizerResult<any> = ContextUtils.getPromptRecognizedResult(context);

setPromptRecognizedResult

It saves the recognizerResult in the turnState to retrieve the value later in the validator function.

This function is currently used in the prompt recognizer where a custom recognizeChoices is performed (including number and ordinal recognition).

Example of use:

const result: PromptRecognizerResult<FoundChoice> = { succeeded: false };
if (matched.length > 0) {
	result.succeeded = true;
    result.value = matched[0].resolution;
}
// Save personalized recognizer result
ContextUtils.setPromptRecognizedResult(context, result);

existError

It checks if an error exist and returns a boolean. (Mainly, it is designed for middlewares)

Example of use:

 if (!ContextUtils.existError(context)) {
 ...
 }

setError

It sets an error without warning the user at that time, allowing the execution of remaining middlewares. (Mainly designed for middlewares)

Example of use:

try {
} catch (error) {
	await ContextUtils.setError(context, error);
}

setErrorAndSendActivity

It sets an error and immediately sends a message to the user. (Mainly designed for dialogs).

Example of use:

try {
} catch (error) {
	await ContextUtils.setErrorAndSendActivity(context, error);
}

setHistoryConversation

It stores in Conversation Data the request and response messages. This method is deprecated.

Example of use:

await ContextUtils.setHistoryConversation(
     context,
     activity,
     ConfigurationManager.instance.environmentConfiguration.AURA_MAX_HISTORY_CHAT_ITERATIONS
);

addToHistoryConversation

It stores in Conversation Data the request and response messages.

⚠️ This method is deprecated.

Example of use:

this.addToHistoryConversation(context, activity, maxHistorySize, false);

getHistoryConversation

It returns the history conversation stored in Conversation Data.

Example of use:

const history = await ContextUtils.getHistoryConversation(context, true,
        (item: DialogChatHistory) =>
            `(${getLocalFormattedIsoTime(item.date)})` +
            `[${(item.type === 'request') ? User : AURA}]:${item.message}`
    )

Result:

2021-3-15 15:55:02 User:  Que ponen en la cuatro
2021-3-15 15:55:04 AURA:  Ok, estarei aqui sempre que você precisar.
2021-3-15 15:55:08 User:  Hola?
2021-3-15 15:55:09 AURA:  Ok, estarei aqui sempre que você precisar.
2021-3-15 15:55:15 User:  Bye
2021-3-15 15:55:16 AURA:  Ok, estarei aqui sempre que você precisar.

setConversationState

It stores the conversation state in turnState.

Example of use:

ContextUtils.setConversationState(context, this.conversationState);

saveConversationState

It saves the cached state object if it has been changed. If the force flag is passed in the cached state, the object will be saved regardless of whether it has been changed or not. If no object has been cached, an empty object will be created and then saved.

Example of use:

await ContextUtils.saveConversationState(context, true);

loadConversationState

It reads and caches the backing state object for a turn. Subsequent readings will return the cached object, unless the force flag is passed, in which the state object to be re-read will be forced.

Example of use:

await ContextUtils.loadConversationState(context, loadFromRemote);

getInternalSuggestions

It gets Aura suggestions.

Example of use:

const internalSuggestions: InternalSuggestions = ContextUtils.getInternalSuggestions(stepContext.context);

setInternalSuggestions

It sets Aura suggestions.

Example of use:

getUserAuthPersistentData

It gets the user’s authentication state for login/logout.

export interface IUserAuthState {
    refreshCache?: boolean; // Deprecated in Vortex release
    accountRemovalTimestamp?: number;
}

Example of use:

const userAuthState = await ContextUtils.getUserAuthPersistentData(stepContext.context);

getCorrelatorFromChannelData

It gets the correlator from channelData, if exists there, or creates a new one.

Example of use:

const correlator = ContextUtils.getCorrelatorFromChannelData(context);

setStatus

It sets status to the response channelData object.

Example of use:

ContextUtils.setStatus(context, new AuraResponseStatus(AURA_STATUS.ERROR.OTHER.GENERAL));

getError

It gets the error from context.

Example of use:

const error = ContextUtils.getError(context);

getRecognizer

It gets the recognizer.

Example of use:

const error = ContextUtils.getRecognizer(context);

setRecognizer

It sets the recognizer.

Example of use:

const error = ContextUtils.getSecognizer(context, recognizer);

1.1.5.5 - Ai service

AI Service

Introduction

AI ​​Service allows you to manage calls to external AI services through generative APIs. The service is responsible for abstracting the details of the API calls and providing a simple interface for recognizing intents using different recognizers.

Creating an instance of the service

To create an instance of the service, you need to provide a AiRecognizerServiceConfiguration object with the following parameters:

Example of use:

import { AuraBotCommon } from '@telefonica/aura-bot-utilities';

const aiService = new AuraBotCommon.AiRecognizerService({
    AURA_AUTHORIZATION_HEADER: process.env.AURA_AUTHORIZATION_HEADER!,
    AURA_GATEWAY_API_ENDPOINT: process.env.AURA_GATEWAY_API_ENDPOINT!,
    AURA_GATEWAY_API_ISSUER_URL: process.env.AURA_GATEWAY_API_ISSUER_URL!
});

Recognizing intents. The recognize method

The recognize method allows you to recognize intents from a TurnContext using a specific intent configuration. The method takes the following parameters:

Example of use:

const intentConfiguration = AiRecognizerService.getConfigurationByRecognizer(
    context, AiRecognizerService.TRIAGE_RECOGNIZER
);

const intent = await aiService.recognize(context, intentConfiguration);

This method uses the generative API to send the message and receive the response. It also manages the session ID by storing it in the TurnContext for future requests.

Recognizing intents using triage. The recognizeUsingTriage method

The recognizeUsingTriage method allows you to recognize intents from a TurnContext using the triage recognizer. The method takes the following parameter:

Example of use:

const intent = await aiService.recognizeUsingTriage(context);

Getting configurations

The AI Service provides two static methods to retrieve intent configurations from the TurnContext:

• getConfigurationByRecognizer: Retrieves the configuration for a specific recognizer by its name.
• getConfigurationByDialog: Retrieves the configuration for a specific dialog by its intent name.

1.2 - Aura utilities

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

1.2.1 - aura-channel-data-handler

aura-channel-data-handler utility

Introduction

The aura-channel-data-handler utility contains the necessary utilities to manage the content of []channelData](/docs/components/request-response-model/) for the input/output response to aura-bot.

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

These guidelines will allow you to get a copy of the project running on your local machine for development and testing purposes.

Run tests

This project uses Mocha for BBDD testing.

Unit tests

$ npm run test

Style tests

These tests perform the validation coding rules defined in Aura using the eslint tool.

You can validate the code using:

$ npm run lint

Coverage tests

You can run the coverage tests using:

$ npm run test

The threshold established to validate the coverage is as follows:

• lines: 90%
• functions: 90%
• statements: 90%
• branches: 70%

Use aura-channel-data-handler utility

Transform channelData from an old version to the latest version (normalized)

The mapper will try to obtain the correct mapper based on the version indicated in version field. If the request does not contain a version, it will try to map using version 1.0.0:

import { ChannelData, ChannelDataRequestMapper } from '@telefonica/telefonica/aura-channel-data-handler';
...
const channelData: ChannelData = ChannelDataRequestMapper.getNormalized(context.activity.channelData);

Continuing with the previous example, the channelData obtained from the normalization can also be used as a helper to perform predefined operations:

// You can get the original request (example v1)
...
import { ChannelDataRequestHelper } from '@telefonica/telefonica/aura-channel-data-handler';
...

const helper: ChannelDataRequestHelper = channelData as unknown as ChannelDataRequestHelper;
const channelDataOriginal = helper.getOriginalRequest();

Versioning

We use [SemVer] (http://semver.org/) for versioning.

More information regarding latest versions:

$ npm show @telefonica/aura-channel-data-handler

1.2.2 - aura-server-common

aura-server-common utility

Introduction

The aura-server-common utility is a library for sharing code between Aura server applications.

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

For this component, SemVer is used for versioning.

Tests running

This project uses tslint to validate the coding style.

Unit tests

To execute the tests, use the following command:

$ npm run test

Coding style tests

These tests perform the validation coding rules defined in Aura using the tslint tool.

You can validate the code using:

$ npm run lint

Developer notes

The folder structure used for development is:

.
├── __test__            // Folder for test in jest
└── src                 // Shared code between APIs and modules.
    ├── handlers        // Expressjs handlers folder
    ├── middlewares     // Expressjs middlewares folder
    ├── models          // Models
    ├── modules         // Modules to be loaded by orchestrator
    ├── routes          // Expressjs routes folder
    └── utils           // Common utilities

Handlers

• validate-auth-apiKey: To get or create the correlator and validate the APIKey of the request.
• validate-google-auth: To validate the Google x-goog-signature of the request.

Middlewares

• error-handler: Global error handler.
• incoming-request: To register metrics for incoming requests.
• set-correlator: To get the correlator from several places.
• set-not-cache: To set Cache-Control and ETag headers to prevent caching.
• validate-apiKey: To get or create the correlator and validate the APIKey of the request.
• validate-token: To validate the token.

Modules

• async-hooks-blocking: To manage async hooks and capture stack traces.
• configuration-manager: To manage config and load environment variables.
• oas-manager: To register security handlers, for example openAPIBackend.
• plugin-manager: To manage plugins to add different services.
• prometheus-manager: To manage Prometheus metrics.

Routes

• generic: To manage generic routes such us: healthz, favicon and shutdown.
• metrics: To manage metrics routes.

Utils

• aura-error-factory: Collection of functions to manage conversion errors.
• oas-utils: Collection of functions to manage token, validation failures and error responses.
• time-utils: Collection of functions to manage time.
• token-validations: Collection of functions to validate tokens.

Plugins

• dapr-pubsub-service: plugin which allows the interaction with the Dapr PubSub Service

1.2.2.1 - dapr-pubsub-service plugin

dapr-pubsub-service plugin

Introduction

The dapr-pubsub-service allows the interaction with the Dapr PubSub Service.

Consumes components (IOC)

Provides components (IOC)

1.2.2.2 - API definition

API definition for Aura Server Common

APIs index

• Dapr PubSub API

1.2.2.2.1 - Dapr PubSub API

Dapr PubSub API

1.2.3 - aura-configuration

aura-configuration utility

Introduction

aura-configuration utility is a library designed to load Aura configuration (channels, etc.) and use models (classes and interfaces) related to channels.

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

Aura current channels configuration

AuraCurrentChannelsConfiguration is a singleton class that contains some utils to obtain information about the channels. This module is initialized at server start-up like other singleton modules. To use it, you should use the instance already created:

const configuration = {
    AURA_CHANNELS_CONFIGURATION_API_ENDPOINT: 'http://...', // Mandatory.
    AURA_AUTHORIZATION_HEADER: 'APIKEY xxx' // Mandatory.
};

AuraCurrentChannelsConfiguration.init(configuration);

Configuration

getChannelByName

Get channel configuration value by name of channel.

AuraCurrentChannelsConfiguration.instance.getChannelByName('channelName');

getChannelsBySecurityChannelId

Get channel configuration value by security.channelId.

AuraCurrentChannelsConfiguration.instance.getChannelsBySecurityChannelId('channelSecurityId');

getChannelByPrefix

Get channel configuration value by prefix of channel.

AuraCurrentChannelsConfiguration.instance.getChannelByPrefix('channelPrefix');

getChannelById

Get channel configuration value by id of channel.

AuraCurrentChannelsConfiguration.instance.getChannelById('channelId');

getChannels

Get all channels configuration.

AuraCurrentChannelsConfiguration.instance.getChannels();

Aura Channels Configuration - Deprecated

⚠️ AuraChannelsConfiguration is deprecated. Use AuraCurrentChannelsConfiguration in new modules instead.

AuraChannelsConfiguration is a singleton class that contains some utils to obtain information about the channels.

This module is initialized at server startup like other singleton modules. To use it, you should use the instance already created:

const configuration = {
    AURA_CHANNELS_CONFIGURATION_API_ENDPOINT: 'http://...', // Mandatory.
    AURA_AUTHORIZATION_HEADER: 'APIKEY xxx' // Mandatory.
};

AuraChannelsConfiguration.init(configuration);

Configuration

getChannelByName

Get channel configuration value by name of channel.

AuraChannelsConfiguration.instance.getChannelByName('channelName');

getChannelByPrefix

Get channel configuration value by prefix of channel.

AuraChannelsConfiguration.instance.getChannelByPrefix('channelPrefix');

getChannelById

Get channel configuration value by id of channel.

AuraChannelsConfiguration.instance.getChannelById('channelId');

getChannels

Get all channels configuration.

AuraChannelsConfiguration.instance.getChannels();

filterChannelsWithProperty

Filter all channels has a property with name element value.

AuraChannelsConfiguration.instance.filterChannelsWithProperty('element');

filterChannelsByType

Filter all channels with property type equal to param.

AuraChannelsConfiguration.instance.filterChannelsByType('type');

Configuration

Aura Skill Configuration

AuraSkillConfiguration is a singleton class that contains some utils to obtain information about the skills. This module is initialized at server start-up like other singleton modules. To use it, you should use the instance already created:

const configuration = {
    AURA_CHANNELS_CONFIGURATION_API_ENDPOINT: 'http://...', // Mandatory.
    AURA_AUTHORIZATION_HEADER: 'APIKEY xxx' // Mandatory.
};

AuraSkillConfiguration.init(configuration);

Configuration

getSkillByName

Get skill configuration value by name of skill.

AuraSkillConfiguration.instance.getSkillByName('skillName');

getSkillById

Get skill configuration value by id of skill.

AuraSkillConfiguration.instance.getSkillById('skillId');

getSkills

Get all skills configuration.

AuraSkillConfiguration.instance.getSkills();

loadSkills

Load all skills configuration. By default, only active skills are returned.

AuraSkillConfiguration.instance.loadSkills(correlator);

To get all skills:

AuraSkillConfiguration.instance.loadSkills(correlator, false);

addSkill

Add new skill configuration.

AuraSkillConfiguration.instance.addSkill(newSkill, correlator);

deleteSkill

Delete skill configuration with id skillId.

AuraSkillConfiguration.instance.deleteSkill('skillId', correlator);

Aura Application Configuration

AuraApplicationConfiguration is a singleton class that contains some utils to obtain information about the applications. This module is initialized at server start-up like other singleton modules. To use it, you should use the instance already created:

const configuration = {
    AURA_CHANNELS_CONFIGURATION_API_ENDPOINT: 'http://...', // Mandatory.
    AURA_AUTHORIZATION_HEADER: 'APIKEY xxx' // Mandatory.
};

AuraApplicationConfiguration.init(configuration);

Configuration

getApplicationByName

Get application configuration value by name of application.

AuraApplicationConfiguration.instance.getApplicationByName('name');

getApplicationById

Get application configuration value by id of application.

AuraApplicationConfiguration.instance.getApplicationById('id');

getApplications

Get all applications configuration.

AuraApplicationConfiguration.instance.getapplications();

loadApplications

Load all applications configuration. By default, only active applications are returned.

AuraApplicationConfiguration.instance.loadApplications(correlator);

To get all applications(disabled too):

AuraApplicationConfiguration.instance.loadApplications(correlator, false);

Models

Channel

Set of interfaces and enums necessary to work with the channel configuration.

Import example:

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

Common

Import example:

import {
} from '@telefonica/aura-configuration';

1.2.4 - aura-crypto-adapter

aura-crypto-adapter utility

Introduction

aura-crypto-adapter is a utility that provides methods for encrypting and decrypting data using a specified encryption algorithm and managing vectors associated with the encryption process. It also includes a method for generating checksums using different algorithms.

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

Configuration

The following variables are required for the configuration of aura-crypto-adapter. They belong to aura-bot environment variables.

• AURA_ENCRYPTION_KEY - Mandatory
• AURA_ENCRYPTION_IV_LENGTH - Mandatory
• AURA_ENCRYPTION_ALGORITHM - Mandatory

Basic usage

• Import the CryptoAdapter class:

  import { CryptoAdapter } from '@telefonica/aura-crypto-adapter';
  

• Create an instance of cryptoAdapter by providing the required configuration variables.

  const cryptoAdapter = new CryptoAdapter(configuration);
  

• To encrypt information, call the encrypt method of the cryptoAdapter instance, passing the information and an optional key (if it is needed to use a different one than the given on configuration).

  const encryptedToken = cryptoAdapter.encrypt(information);
  

• To decrypt information, use the decrypt method of the cryptoAdapter instance, again providing an optional key.

  const decryptedInformation = cryptoAdapter.decrypt(encryptedToken);
  

• Checksum Verification: If you need to verify the integrity of the data, you can use the checksum method of the CryptoAdapter class. Store or transmit the checksumValue along with the encrypted data. When decrypting, calculate the checksum again and compare it with the stored value to ensure data integrity.

  const checksumValue = CryptoAdapter.checksum(data);
  

Run tests

You can validate run jest testing tools with the script:

$ npm run test

Linter

You can validate the code using the eslint tool with the script:

$ npm run lint

Versioning

We use SemVer for versioning.

For all available versions, look at the tags in this repository.

1.2.5 - aura-locale-manager

aura-locale-manager utility

Introduction

aura-locale-manager is a utility that allows aura-bot to manage text resources, that means, to use custom i18n per environment and channel.

This library provides two functionalities:

• LocaleManager class to handle i18n texts resolution.
• LocaleRemoteLoader class that runs before LocaleManager starts in order to get a fresh version of the locale files from the configured Azure Storage blob container. If an error occurs when uploading the remote files, the former set of locale files will be used.

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

Configuration

The following variables are required for the configuration of aura-locale-manager. They belong to aura-bot environment variables.

• AURA_DEFAULT_LOCALE - Mandatory
• AURA_SERVICE_ENVIRONMENT - Mandatory
• AURA_LOCALE_REMOTE_CONTAINER - Mandatory
• AURA_VERSION - Mandatory
• AURA_LOCALE_REMOTE_CONTAINER_PREFIX - Mandatory
• AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT - Mandatory
• AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY - Mandatory
• AURA_LOCALE_REMOTE_BACKUP - Optional
• AURA_LOCALE_FORCE_IMPORT – Optional

Create an instance

ℹ️ This step is not required when developing a use case, as the locale manager instance is provided by aura-bot. Take it only for descriptive purposes.

A new instance can be created by calling getInstance() method, passing config object as parameter (mandatory in the first call). Subsequent calls to getInstance will return the same instance (singleton).

When creating the instance, the folder specified in the config var AURA_LOCALE_FOLDER is read and looks for JSON files. All those files are loaded once, during the start-up stage. The environment can be specified in AURA_SERVICE_ENVIRONMENT config variable.

Use of aura-locale-manager utility

After getting the instance, translations can be got by using getText method (using the default locale specified in AURA_DEFAULT_LOCALE) or by using getTextByLocale (specifying the desired locale).

getText

const localizer = await LocaleManager.getInstance();
const myMessage = localizer.getText('common:greeting', auraUser, correlator);

getTextByLocale

const localizer = await LocaleManager.getInstance();
const myMessage = localizer.getTextByLocale(this.configuration.AURA_DEFAULT_LOCALE, 'common:greeting', auraUser, correlator);

getTextByLocaleAndPrefixes

This method gathers the translation for the given term key, locale and user’s configuration. It allows getting the texts without a full AuraUser instance.

const localizer = await LocaleManager.getInstance();
const myMessage = localizer.getTextByLocaleAndPrefixes('es-es ', 'common:greeting', channelPrefix, userSubscriptionType, correlator);

loadRemoteLocales

⚠️ This method is only used during aura-bot start-up to get the fresh version of the locales stored in Azure Storage. Do not use it within a dialog.

It allows loading remote resources:

const localeRemote = await LocaleRemoteLoader.getInstance();
localeRemote.loadRemoteLocales();

getAllText

This method returns an array with all the translations for the given term key, locale and user’s context.

const cancelKey = LocaleManager.instance.getAllText('core:login.loa2.cancel.keywords', userData, corr)

1.2.6 - aura-models

aura-models utility

Introduction

aura-models utility is a library to store the common interfaces used in Aura projects.

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

Run tests

Style tests

These tests perform the validation coding rules defined in Aura using the eslint tool.

You can validate the code using:

$ npm run lint

Models summary

src
├── channel-data
│   └── payload.ts
├── genesys
│   └── userdata.ts

Versioning

We use [SemVer] (http://semver.org/) for versioning.

For all available versions, look at the [tags in this repository] (https://github.com/Telefonica/aura-mocks-server/tags).

1.2.7 - aura-mongo-handler

aura-mongo-handler utility

Introduction

aura-mongo-handler utility is the connector and cache for MongoDB.

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

Steps to Create a Two Level Cache

• First, initialize the MongoDB Connector
• Instantiate a new TwoLevelCache Object

Initialize MongoDB Connector

To initialize the Singleton of MongoDB connector, you need these variables in your configuration object:

• AURA_MONGODB_URI

• AURA_MONGODB_POOL_SIZE

• AURA_MONGODB_SSL

• AURA_MONGODB_USERNAME

• AURA_MONGODB_PASSWORD

• BRIDGE_MESSAGE_CACHE_TTL -> Time in miliseconds

• BRIDGE_MONGODB_DATABASE_CACHE -> Database name in MongoDB for Cache

• BRIDGE_MONGODB_COLLECTION_DL_CACHE -> Collection name in MongoDB for Cache

• BRIDGE_MONGODB_INDEX_DL_CACHE -> Index field name in MongoDB Collection

To initialize, use the following command:

  Connector.init(configuration);

Instantiate a new TwoLevelCache Object

To instantiate a TwoLevelCache object, the following elements are needed:

• A Mongo DataBase Name
• A collection name
• The property in the model to be saved in the cache to use as index in MongoDB. This index must be created by deploy scripts.

Constructor:

(name: string, localTTlMiliseconds: number, databaseName: string, collectionName: string, indexId?: string)

• name: Name inside the logs generated by this instance.
• localTTlMiliseconds: Local cache lifetime in in miliseconds.
• databaseName: Name of the database in MongoDB.
• collectionName: Name of the collection in MongoDB database.

const tlCache = new TwoLevelsCache<CustomModel>('LogName',30000, 'collectionName', 'DataBaseName', 'customId'); 

If you need more than one cache and use an instance for each of them, you can do this:

export class AppCaches {
    public static auraBotCache: TwoLevelsCache<AuraBotModel>;
    public static userDataCache:TwoLevelsCache<UserModel>;

    public static init(configuration: any) {
        AppCaches.auraBotCache = new TwoLevelsCache('AuraBotCache', 30000, 'AuraCacheDB','AuraCacheCollection', 'auraId');
        AppCaches.userDataCache = new TwoLevelsCache('AuraUserCache', 30000, 'UserCacheDB','UserCacheCollection''userId');
        return this;
    }
}

1.2.8 - aura-orchestrator

aura-orchestrator utility

Introduction

aura-orchestrator utility contains the orchestrator used in aura-bot and aura-bridge based on the strategy design pattern. It is based on @telefonica/event-bus dependency.

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

Start Orchestrator module

The orchestrator handles an array of classes (with certain required elements), that aura-bot may receive configuration if necessary. Modules are then initialized asynchronously. For example:

const orderedModules = [ModuleA, ModuleB, ModuleC]; 

// Instantiate the Service App. 
const appOrchestrator = new Orchestrator(); 

// Add configuration, that will be required by almost all other modules 
appOrchestrator.setConfigurationManager(Configuration); 

// Add the dependent modules in order. 
appOrchestrator.addModules(sortedModules); 

// Initiate the App. 
await appOrchestrator.init(); 

Creation of singleton modules

In order to develop a new singleton module that will be used by aura-bot both itself and during the plugins execution, developers should keep in mind the following issues:

• All modules added to the orchestrator need and publish a static variable called instance, that will hold the singleton instance of that module.

• Modules must have a public and static method init, that could be async or not, and that will create the singleton instance (and setting it to the instance variable). This method should only be called once by module or must throw an exception. It is only called by the orchestrator.

An example implementation is shown below:

export class Class1 {

    public static instance: Class1;

    private constructor() { 
        // Stuff here... 
    }

    public static async init(config: Configuration): Promise<Class1 > { 
        if (!Class1 .instance) {
            Class1 .instance = new Class1 ();

            // More stuff here

            return Class1 .instance;
        } else {
            throw new Error('An instance of Class1  already exists');
        }
    }
}

1.2.9 - aura-storage-file-manager

aura-storage-file-manager utility

Introduction

aura-storage-file-manager is an utility to manage local and remote resources. At the moment, remote files are arranged using Azure Storage.

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

StorageCredentials

Initialization example:

const config = {
    storageName: 'storageName',
    storageKey: 'storageKey',
    AURA_KPIS_STORE_CONTAINER: 'aura-kpis',
};
this.storageFileManager = new StorageFileManager({ storageName: 'storageName', storageKey: 'storageKey' }, 'correlator');

Models

FileConfiguration

FileToDownload

DownloadFileModel

Methods

downloadFiles

This method downloads one or more files.

Example:

 const fileConfiguration = {
            containerName: 'aura-configuration',
            localPath: 'settings/makeup',
            remotePath: '',
            files: [{ name: 'aura-bot-mongodb-indexes.json'}]
        };
 const storageFileManager = new StorageFileManager({storageName: 'storageName', storageKey: 'secret'} );
 const filesDownloaded:DownloadFileModel[] = await storageFileManager.downloadFiles(fileConfiguration, false, true);

Example download all files:

 const fileConfiguration = {
            containerName: 'aura-configuration',
            localPath: 'settings',
            remotePath: 'settings',
            files: [{ name: '*'}]
        };
 const storageFileManager = new StorageFileManager({storageName: 'storageName', storageKey: 'secret'} );
 const filesDownloaded:DownloadFileModel[] = await storageFileManager.downloadFiles(fileConfiguration, false, true);

uploadStringAsBlob

This method gets the string passed as parameter and modifies blob’s content with it.