Aura – hot-swapping

Docs:

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

General guidelines for locales management

The aim of this document is to describe how locales are handled by Aura Bot services for the following components: aura-groot, aura-authentication-api, aura-bridge, aura-bridge-outbound.

⚠️ Remember that hot swapping of aura-bot locales must be done through the aura-configuration-updater

Introduction

The objective of the current document is to describe the hot swapping process to update POEditor texts in Aura without service outage, both for global and local use cases. Hereinafter, we will refer it as hot swapping process.

For each type of use cases, the process uses different projects and has a different scope, as shown in the following table.

Global use cases	Local use cases
- Aura POEditor global project (owned by Aura Global Team)	- Aura POEditor local project (owned by L-CDO Team)
- Scope: edition of texts	- Scope: edition of texts and definition of resources

In both cases, the texts correspond to PRE and PRO resources in POEditor.

Follow the orderly guidelines in the succeeding sections:

⚠️ If you have local use cases, you must carry out the process included in this document for update POEditor texts each time a new version of your local use cases is deployed.

Previous steps

Previous steps include the management of POEditor itself for the edition of texts and, depending on the use case type, the generation of resources. These tasks are fully defined in the corresponding documents:

Global Use Cases > Edition of POEditor texts
Local Use Cases > Edition of POEditor texts and generation of resources (references)

Generation of POEditor token

Once the texts have been modified in POEditor, it is necessary to have a Read-only API Token in order to import them into aura-bot.

Global Use Cases: developers should request the read-only API Token to the APE Team.
Local Use Cases: developers should request the read-only API Token to the local responsible of POEditor project.

The reading token is obtained from the POEditor website, where the OB edits the texts.

Figure 1. Add readonly API token

Figure 2. API access

Importing locale files with aura-locale-importer tool

We recommend using aura-locale-importer tool, a utility developed by Aura Global Team that allows to handle the importation and exportation of locale files with POEditor.

Install aura-locale-importer tool:
1.1. Log in NPM to download the private NPM package dependencies. You can log in with user/password or using the token:
- User/password -> npm login
- Token -> Add the token to your environment variables on your machine. Follow the guidelines for mac/linux.
1.2. Install the npm application globally in the host. You can use two equivalent commands for installing the latest available version:
npm install –g @telefonica/aura-locale-importer or
npm i @telefonica/aura-locale-importer -g
Copy in a local directory the file containing the locale resources to be updated (JSON file from aura-bot/locale/ directory). If there is no file, the aura-locale-importer tool will generate one.
Get full locale files to be uploaded:
```
$ aura-locale-importer -u -l <language-country> -j <POEditor project> -b <my-library> -d <local-directory> -m library -f –t <token>
```
Where:
- -l <language-country>: country translation e.g., es-es, de-de, en-gb. If this field is empty, the system will import every translation file.
- -j <POEditor project>: POEditor project to be used:
- For global use cases: aura-bot project (global project)
- For local use cases: name of the OB’s local project
- -b <my-library>: specific libraries to be uploaded in the hot swapping process. For example: fill this parameter with authentication for aura-authentication-api, or fill it with bridge for aura-bridge.
- -d <local-directory>: local directory where result files will be imported.
- -f: this parameter forces the files overwriting.
- -m library: it indicates the way of working. For the current release, it must be library.
- -t <token>: read-only API token to access to POEditor.
Here, developers can follow two different processes:

a. Define it in the environment variable $POEDITOR_TOKEN in the host running the process. In this case, this command should not be included here.

b. Add it in the current command within -t <token>

An example for a local use case in Germany is shown below:
- This command will generate all the locale files that fulfil the conditions established in the parameters above:
```
`$ aura-locale-importer -u -l de-de -j Aura-Bot-De -d ./locale -m library -f –t f9023005c8792e57d3593511b69c300e`
```
- This command lists the content of the locale folder in Aura Bot project. $ ls .locale
The output will be: de-de.json

Locale files uploading

This process requires certain previous steps, as all the resources and texts (from the bot core, global use cases or local use cases) must be merged together during the make-up process.

Access the Azure blob container static-resources in your intended environment, where the JSON file with your resources and texts is. This file will be in the following paths, depending on the component:

For aura-authentication-api:
static-resources/authentication/locale/<aura-version>/<language-country>.json
For aura-bridge:
static-resources/aura-bridge/locale/<aura-version>/<language-country>.json

It is recommended to use Azure Storage Explorer in order to easily access this file.

Figure 3. Updating locale files to Azure

Download this file for its edition.
Add the new content from the imported locale files to the downloaded files or replace the specific content.

For example, you can add a new resource from the imported file (Section 4.3.) to the end of the file downloaded from Azure (Step 1). Or you could replace one of the texts appearing in the downloaded file (Step 1) with one of the new texts shown in the imported file.
Validate the JSON format through the online tool JSONLint.
Upload again the JSON file into the corresponding Azure blob container (depending on the component, the locale file must be in a different container as explained in step 1). Depending on the component, the files should be loaded into a different folder. In case the folder in that path does not exist, please create it manually.

⚠️ It is recommended to make a backup copy before overwriting.
If you want to keep previous versions of the JSON files as a backup during testing, you must remove the JSON extension from the file name to prevent these files from also being imported into Aura. For example:
❌ <language-country>.json.backup
✔️ <language-country>.backup

This assures that only one JSON file is present for each language.

Make modifications available

Check LocaleManager configuration

Check the configuration of the component to be updated, aura-authentication-api or aura-bridge, following LocaleManager configuration, for instance:
$ kubectl –n <aura-ns> edit cm <authentication-api|aura-bridge>

⚠️ Firstly, read the document connecting to Kubernetes to know how to operate with Kubernetes in your environment.

Where:

<aura-ns> is aura namespace, with the following format: aura-<OB>-<environment>
The specific value for <aura-ns> is an output for the installation process and can be found in the path _output_install/*info.json, in the field services_namespace.

This will open a text editor (such as vi) showing the whole config map of the specified pod.

The servers aura-authentication-api and aura-bridge count on a series of environment variables that manage the process. Developers should check several items, shown in the following screenshots for both servers.

You have the right Aura version: variable AURA_VERSION.
Verify the values for the Azure Storage account: variable AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT.

Figure 4. Check LocaleManager configuration

The definition of these variables is shown below:

AURA_VERSION: string with the semantic versioning of Aura to be read from the remote blob container. By default, it takes the version packaged originally in the docker image (7.0.0. in the case of Heroes). It is required to put a correct value, to be sure that the container is loading the correct set of files.
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT: string with the name of the Azure Storage account related to the given aura deployment.

Restart the corresponding pod/pods

For the Kubernetes version 1.15 onwards, the following command must be launched for restarting the corresponding pod/pods.

If developers have modified the locale file for aura-bridge, they will need to restart aura-bridge pods.
The same applies for changes made in aura-authentication-api, its pod should only be restarted in case you modified the locale file in the folder for this component.

kubectl version >= 1.15: 
$ kubectl rollout restart deployment [authentication-api, aura-bridge]

Docs:

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

Hot swapping in Aura

Description of Aura processes that can be executed without service outage

Introduction

The objective of the current documents is to describe the available actions that can be carried out over Aura through hot swapping processes, that is, without interrupting its operation. These actions include the update, insertion or removal of specific components or resources. The modifications resulting from these processes can be available immediately without the need to wait for the deployment of a subsequent Aura Platform release.

Despite the previous definition, performing a specific hot swapping process within a component can impact other components. In such cases, it becomes necessary to either restart the affected component or carry out a particular action to mitigate any potential issues or conflicts.

Available hot swapping processes and associated impact

The following table illustrates the available hot swapping processes against key Aura components, the impact of the process over each of them and the consequent actions that must be executed afterwards.

Each hot swapping process in the table is fully described in the document Hot swapping processes.

|——-|————-|———————-|————|———-|———-|————-|————|————————-|——————|———————|——————|———|————————| | 1. Update locales | Restart | Restart | Restart | aura-configuration-updater

Make-up | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | | 2. Update NLP packages | N/A | N/A | N/A | N/A | Restart | NO¹ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | | 3. Modify TV use cases (User helper) | N/A | N/A | N/A | N/A | N/A | Restart | N/A | N/A | N/A | N/A | N/A | N/A | N/A | | 4. Channels handling | Restart | Restart | Reload | Make-up | Restart | Restart | Restart | NO² | Reload| Restart | Restart | N/A | | 5. Skills handling | N/A | N/A | Reload | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | | 6. Applications handling | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | Reload | N/A | N/A | N/A | N/A | | 7. Add new local dialogs in aura-bot | N/A | N/A | N/A | DeployLocal | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | | 8. Update libraries and dialogs configuration | N/A | N/A | N/A | aura-configuration-updater | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | | 9. Add static resources in a uc | N/A | N/A | N/A | aura-configuration-updater | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | | 10. Review indexes definitions | N/A | N/A | Make-up | Make-up | N/A | N/A | Make-up | Make-up | N/A | N/A | Make-up | Force | Make-up |

Legend

N/A: The change does not apply to the component
NO: The change does not apply to the component, unless a condition is met
Restart: the component will be restarted automatically by the config-watcher. The restart is executed pod by pod, with no impact to final users
Reload: the component is not restarted, but its configuration will be reloaded automatically by the config-watcher.
aura-configuration-updater: The hot swapping process must be executed using aura-configuration-updater.
Make-up: the make-up of the component is executed during the deploy phase: both with deploy-core and deploy-local. Take into account that aura-configuration-updater is included into the deploy_local process
DeployLocal: the component is automatically restarted after the execution of its make-up
Force: a restart of the component must be executed manually

Notes

Assuming it doesn’t involve resolution changes ↩︎
Until associated training is added, if applicable ↩︎

Docs:

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

Guidelines for the design of graphic resources in Aura response

Learn how to design of different types of graphic resources and include them in the response that Aura provides to its users

Introduction

You can design your own graphic resources inside the visual components of Aura response (mainly, in the card), always depending on the rendering capability of the channel.

They are categorized into two main groups:

Static graphic resources: icons, images, diagrams, etc.
Dynamic graphic resources: graphics that include users’ data and change depending on them (for instance, new plot for data usage use case per country). These graphics can fetch data from Kernel or from external services (for instance, images from smartphone models that can be shown to the user).

The following sections define the procedure for including both a static and dynamic graphic resource in Aura response.

Include static resources by library

The static resource must be previously defined in the resources/ folder of the use case library.
In the use case dialog (.ts file), each resource must be declared as shown in the following snippet:
```
import * as libraryUtil from '@telefonica/aura-bot-utilities/lib/aura-bot-library-util';
(...)
const wholeUrl = libraryUtil.getResourcePath(config, 'my_library', 'icon.png');
```
Where:
- config: configuration object that should contain the environment variables AURA_STATIC_RESOURCE_ENDPOINT and AURA_STATIC_RESOURCE_SAS_TOKEN.
- 'my_library': library name
- 'icon.png': name of the image
In order to get a complete URL, including device screen resolution, invoke getImageUrl from the library aura-bot-library-utils.
In the index.ts file of your use case library, the resources path must be exposed in the resources property when registering the plugin, as shown in the following example:
```
register(null, {
    my_library: {
       …
        resources: path.resolve(__dirname, '..', 'resources'),
        (...)
    }
```
Where:
- 'resources': name of the folder where the resources are defined, within the library.
Just after it, the resource must be uploaded to Microsoft Azure Storage Explorer, in the images/ folder of the corresponding library. Doing so, Azure generates an URL for the defined resource.

Hot swapping of static resources

Once a static resource is created through the above defined steps, the OB can follow a hot swapping process for the modification of the resource:

The name of the icon must not be modified: it has to be the same as the name in the code.
Updata de resource file directly in Microsoft Azure Storage Explorer, in the /resources/images/ folder of the corresponding library. Doing so, Azure generates an URL for the defined resource.
However, it must be taken into account that, during the make-up process, the bot overwrites it, so the updating process should be repeated by the OB. For example, this process can be executed when publishing a local use case.
It is not necessary to restart the bot, as the method which is invoked internally already fetches the icon from Azure Storage.

Include a dynamic graphic resource

The inclusion of dynamic graphic resources in Aura involves two main stages:

Data recovery from a Kernel API or from an external API For Kernel APIs, follow the process in the document Create / update an API client.
Generation of dynamic graphic resources: Developers must implement their own dynamic graphic resources generator. After generating the resource, the process of uploading the resource into Azure must be done manually.
If the dynamic resource is integrated into the card of Aura response, follow the instructions in Build Aura response: cards.

Docs:

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

Hot swapping of Aura applications configuration

Guidelines to execute modifications in Aura applications configuration through a hot swapping process

Prerequisites

The URL of aura-configuration-api must have the following format: https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration where:
- {{aura-services-domain}} should be svc-[country]-[environment], for instance svc-es-pre
Recommended:
- kubectl installed in your local host.
- curl installed in your local host.
- jq installed in your local host.

Access Aura Configuration API

Get the APIKey

First, we must get the APIKey, AURA_AUTHORIZATION_HEADER, of aura-configuration-api. For this purpose, follow these steps:

Execute the following command:

# substitute {{aura-environment}} with the environment you're configuring
export AURA_ENVIRONMENT={{aura-environment}}

$ kubectl -n $AURA_ENVIRONMENT get secret aura-configuration-api -o json | jq -r ".data.AURA_AUTHORIZATION_HEADER|@base64d

Copy the value of APIKey.

Update the application configuration

To update the configuration of an application, we must make a patch to the aura-configuration-api indicating the application that we want to modify and the new value:

Execute the next curl to update configuration:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment, svc-[country]-[environment].
# substitute {{applicationId}} with the value of application to change
# substitute {{apikey}} with the value of APIKey get in the previous step
$ curl --location --request PATCH 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/applications/{{applicationId}}' \
--header 'correlator: {{correlator}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}' \
--data-raw '{
    "id": "{{applicationId}}",
     // Send the object to update
    }
}'

Check the change through the following request:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment svc-[country]-[environment].
# substitute {{applicationId}} with the value of application to change
# substitute {{apikey}} with the value of APIKey get in the previous step
# The response will be the application configuration.
$ curl --location --request GET 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/applications/{{applicationId}}' \
--header 'correlator: {{correlator}}' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}'

ℹ️ NOTE: The config-watcher runs periodically (every 5 minutes) and when it detects that the application configuration has been modified, it will restart the pods.

Docs:

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

Hot swapping processes in Aura

Key processes that can be done over Aura without service outage

1. Update of locales: Hot swapping of POEditor texts

If locales belong to aura-bot (Generation or update of locales through POEditor when developing a use case):
Hot swapping is done through the aura-configuration-updater.
If locales belong to aura-groot, aura-authentication-api, aura-bridge, aura-bridge-outbound: Hot swapping is done through the guidelines Manage locales in Aura.

By doing so, the update of locales will be available without the need to wait for the next Aura Platform release.

Be aware of the impact of both processes over certain Aura components: Available hot swapping processes and associated impact - Item 1 in table.

2. Update of NLP packages

When developing a use case over Aura NLP, the understanding model including the trainings and test set files must be deployed.

If OBs are interested in the update of an NLP package through a hot swapping process, the local DevOps Team can execute two different procedures, which are equivalent in terms of outcome and impact on the system. Therefore, OBs have the freedom to choose whichever process they prefer.

Through aurak8s installer: Local NLP deployment
Through the use of Aura Operator: NlpTraining

By doing so, the updated NLP package will be available without the need to wait for the next Aura Platform release.

Be aware of the impact of both processes over certain Aura components: Available hot swapping processes and associated impact - Item 2 in table.

3. Modify TV use cases

Certain modifications in TV use cases (channels mapping, specific experiences, etc.) can be executed through a hot swapping process. They correspond to experiences that are managed by the User_helper component and, specifically, by the M+ Resolution module, that resolves TV use cases calling different APIs.

If OBs are interested in the update of a TV use case through a hot swapping process, the local DevOps Team can execute two different procedures, which are equivalent in terms of outcome and impact on the system. Therefore, OBs have the freedom to choose whichever process they prefer.

Through aurak8s installer: Local ResolutionResources deployment
Through the use of Aura Operator: ResolutionResources

Be aware of the impact of both processes over certain Aura components: Available hot swapping processes and associated impact - Item 3 in table.

4. Channels handling

The execution of changes in the configuration of channels can be done through a hot swapping process using the aura-configuration-api component.

This process is fully described in the document Update channels configuration.

Be aware of the impact of this process over certain Aura components: Available hot swapping processes and associated impact - Item 4 in table.

5. Skills handling

The hot swapping processes that can be executed in the framework of skills management are included in the document Hot swapping processes in Aura distributed architecture and include adding a new skill to aura-root, modifying it or deleting an existing one.

Be aware of the impact of this process over certain Aura components: Available hot swapping processes and associated impact - Item 5 in table.

6. Applications handling

The execution of changes in the configuration of applications, the components in charge of the communitation of a channel, service or skill with aura-gateway-api for the connection with an external service, can be done through a hot swapping process using the aura-configuration-api component. This process is fully described in the document Hot swapping processes in Aura Applications Configurations.

Be aware of the impact of this process over certain Aura components: Available hot swapping processes and associated impact - Item 7 in table.

7. Add new local dialog in aura-bot

The deployment of a new local dialog over a specific Aura Platform release can be done through a hot swapping process, following the guidelines Local modules deployment.

Be aware of the impact of this process over certain Aura components: Available hot swapping processes and associated impact - Item 8 in table.

8. Update of libraries and dialogs configuration

Aura allows making changes in certain aura-bot configuration related to libraries, dialogs and channels through hot swapping processes:

contextFilters of the intents in aura-bot dialogs
Scopes and purposes in aura-bot libraries and dialogs

These processes can be done using the aura-configuration-updater.

Be aware of the impact of this process over certain Aura components: Available hot swapping processes and associated impact - Item 9 in table.

9. Add static resources in a use case

When developing a use cases, aura response can include static resources such as visual components (cards), such as icons, images, diagrams, etc.

If required, the update of these resources can be done through a hot swapping process, following the guidelines included here.

These processes can also be done using the aura-configuration-updater.

Doing that, the updated static resources will be available in the period between one release and the consecutive one.

Be aware of the impact of this process over certain Aura components: Available hot swapping processes and associated impact - Item 10 in table.

10. Review indexes definitions

Due to the continuous evolution of the Aura Platform, it is possible that the indexes definitions of the different components need to be reviewed and updated. This process can be done through a make-up process.

If required, the update of these indexes can be done through a hot swapping process, uploading a new index definition file to Azure Blob Storage, in the container aura-configuration/AURA-VERSION and then executing the make-up process of the corresponding component.

Follow the guidelines Manage MongoDB Indexes to understand how to define a new index file.

Be aware of the impact of this process over certain Aura components: Available hot swapping processes and associated impact - Item 11 in table.

Docs:

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

Hot swapping processes in Aura distributed architecture

Guidelines to execute modifications in Aura distributed architecture through a hot swapping process

Introduction

Constructors can add, delete of modify a skill through a hot swapping process, without affecting other skills, through the aura-configuration-api.

Through this process, aura-groot can be modified to route to a new skill or delete from its routing tables other skills if constructors do not want to send requests to them.

Guidelines

Add a new skill

Deploy a new skill in your own deployment site.
Prepare your channel:
- (Optional) If your skill is serving a new channel, add the channel to the aura-configuration-api.
- (Optional) If your skill is serving an already existing channel that is not handled by any skill, nothing is needed.
- (Optional) If your skill is serving an already existing channel that is handled by another skill, delete the channel from the current skill configuration aura-configuration-api, launching a PATCH request.
Prepare the POST request to the aura-configuration-api in order to add the skill.
Send the request to the aura-configuration-api to add the skill.
After the request is processed, aura-groot automatically loads the new skill and starts routing requests to it.

Delete an existing skill

Prepare the DELETE request to the aura-configuration-api to delete the skill.
Send the request to the aura-configuration-api to delete the skill.
After the request is processed, aura-groot automatically removes the deleted skill and no longer routes requests to it.
(Optional) If your skill is serving a dedicated channel that is no longer needed, remove the channel from the aura-configuration-api.
At this point, the skill can be undeployed from your deployment site.