Aura – locales

Docs:

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

Aura response error messages

Sometimes, Aura could return some errors due to authentication or other APIs errors. This document describes the most common errors and how clients should handle them.

Unauthenticated error

In some channels that require authentication, Aura could return an unauthenticated error if the auraId is invalid. In this cases, the client should authenticate the user again and create a new auraId.

ChannelData v3 example:

        {
            "type": "message",
            "id": "4VJyNMnfcQLHuvOAbXMLAK-fr|0000005",
            "timestamp": "2024-06-27T14:01:24.9377437Z",
            "channelId": "directline",
            "from": {
                "id": "aura-bot-x",
                "name": "aura-bot-x"
            },
            "conversation": {
                "id": "4VJyNMnfcQLHuvOAbXMLAK-fr"
            },
            "text": "Desculpe, não consegui verificar suas informações. Por favor, reinicie o aplicativo e tente novamente.",
            "inputHint": "acceptingInput",
            "channelData": {
                "correlator": "5b25cd4a-aa57-420d-9fb3-8db437df01cf",
                "version": "3",
                "status": {
                    "code": "ERROR.USER.UNAUTHENTICATED",
                    "message": "Invalid aura user",
                    "params": {
                        "auraId": "asdf"
                    }
                }
            },
            "replyToId": "4VJyNMnfcQLHuvOAbXMLAK-fr|0000004"
        }

ChannelData v1 example:

        {
            "type": "message",
            "id": "4VJyNMnfcQLHuvOAbXMLAK-fr|0000003",
            "timestamp": "2024-06-27T14:01:07.7998256Z",
            "channelId": "directline",
            "from": {
                "id": "aura-bot-x",
                "name": "aura-bot-x"
            },
            "conversation": {
                "id": "4VJyNMnfcQLHuvOAbXMLAK-fr"
            },
            "text": "Desculpe, não consegui verificar suas informações. Por favor, reinicie o aplicativo e tente novamente.",
            "speak": "Desculpe, não consegui verificar suas informações. Por favor, reinicie o aplicativo e tente novamente.",
            "inputHint": "acceptingInput",
            "channelData": {
                "hasMoreMessages": false,
                "correlator": "593a44ac-3974-472b-a7e4-610b3c760679",
                "Error": {
                    "code": "UNAUTHENTICATED",
                    "data": "invalidAuraId",
                    "message": "Invalid auraId"
                }
            },
            "replyToId": "4VJyNMnfcQLHuvOAbXMLAK-fr|0000002"
        }

Too many requests error

In some cases, certain APIs could return an error 429 due to quota limits or other reasons. In these scenarios, the client should wait the returned value of the parameter retryAfter and try again after this time.

ChannelData v3 example:

        {
            "type": "message",
            "id": "H2JRTbQW25d6Jyccs7PfEb-fr|0000007",
            "timestamp": "2024-06-27T14:08:26.8101993Z",
            "channelId": "directline",
            "from": {
                "id": "aura-bot-x",
                "name": "aura-bot-x"
            },
            "conversation": {
                "id": "H2JRTbQW25d6Jyccs7PfEb-fr"
            },
            "text": "Lo sentimos, ha ocurrido un error inesperado.",
            "inputHint": "acceptingInput",
            "channelData": {
                "correlator": "9df5cb1b-966c-4db4-9df8-e269c682a58b",
                "version": "3",
                "status": {
                    "code": "ERROR.API.TOO_MANY_REQUESTS",
                    "message": "Too many requests",
                    "params": {
                        "retryAfter": "10"
                    }
                }
            },
            "replyToId": "H2JRTbQW25d6Jyccs7PfEb-fr|0000006"
        }

ChannelData v1 example:

        {
            "type": "message",
            "id": "H2JRTbQW25d6Jyccs7PfEb-fr|0000009",
            "timestamp": "2024-06-27T14:08:45.5260908Z",
            "channelId": "directline",
            "from": {
                "id": "aura-bot-x",
                "name": "aura-bot-x"
            },
            "conversation": {
                "id": "H2JRTbQW25d6Jyccs7PfEb-fr"
            },
            "text": "Lo sentimos, ha ocurrido un error inesperado.",
            "speak": "Lo sentimos, ha ocurrido un error inesperado.",
            "inputHint": "acceptingInput",
            "channelData": {
                "hasMoreMessages": false,
                "correlator": "cd06e100-7783-46e8-8051-ee99e8b72f43",
                "Error": {
                    "code": "TOO_MANY_REQUESTS",
                    "data": {
                        "retryAfter": "10"
                    },
                    "message": "Too many requests"
                }
            },
            "replyToId": "H2JRTbQW25d6Jyccs7PfEb-fr|0000008"
        }

Docs:

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

Guidelines for building Aura response texts

When developing a use case, discover how to generate the texts included in each element of the response that Aura provides to its users. Texts are generated with POEditor and imported into Aura Bot.

Process at a glance

Enter
POEditor

. Log in POEditor
. Access your local POEditor project or create one

Generate
resources

. If required, generate a new resource, element associated with an specific text, for importing it into the bot

Edit
texts

. Search the specific text by library or resource name
. Edit the text with the message to be shown to the user

Import
locale files

. Install aura-locale-importer tool
. Upload locales to Aura Bot through this tool

Hot
swapping

. Make modifications available in between two releases through a hot swapping process

Introduction

When a new use case is developed, it is necessary to design Aura response for each step of the use case conversational flow. The answer, depending on the channel, can include text, cards, graphic resources, deeplinks, suggestions and actions.

The current section focuses on the text included in each element of the use case response.

Basic concepts

Get familiar with these basic concepts when designing your Aura response:

POEditor For the generation of the text included in each response element, Aura relies on POEditor.

POEditor offers a centralized localization tool to handle the different messages that the bot shows to the customer and to adapt them to a specific language.

POEditor project Global project (for global use cases) or local project (for local use cases) to work in.
Term Prototypical phrase of the resource to be able to locate it easily. It is composed of a reference (resource), a context and n texts (translations).
Reference (resource) It is the resource ID. Mandatory field for the subsequent importation of the term into the locales. A resource is an aura-bot element for the generation of the required text in every component of Aura response. aura-bot resources are organized in libraries of dialogs. Each resource is associated to a copy. References must not contain spaces, they should be written all together or use kebab-case in the resource name.
Translations Texts containing the translations of each language where the resource is to be used. They correspond to the texts that Aura shows to the user in a specific field of Aura response in the selected channel containing the answer to the user’s request.

Depending on the use case type, different projects and tasks must be carried out:

	Global use cases	Local use cases
POEditor project	Aura POEditor global project (Owned by Global Team)	Aura POEditor local project (Owned by LCDO Team)
Scope	- Edition of texts (copies)	- Edition of texts (copies) - Generation of resources (references)
Reference documentation	User Guide for Global Use Cases	Guidelines for the generation of resources in POEditor Guidelines for the edition of texts in POEditor

Content managers should edit texts in POEditor both for global and local use cases. Meanwhile, the generation of new resources is only required in local use cases.

Once texts or resources are modified, they are automatically imported to aura-bot during the make-up process into the settings/locale folder of the use case library.

Enter POEditor

In order to use POEditor, a license is required. Therefore, the first step is the registration of a POEditor account, if not existing, in the POEditor website.

Once registered, access your local POEditor project.

Generation of resources in POEditor

A resource is an aura-bot element needed for the generation of the required text in every component of Aura response and its subsequent importation into Aura locales.

In this particular case, for local use cases, OBs are able to generate their own resources.

Resources naming conventions

The general format for Aura resources (references in POEditor) is composed of the mandatory name of the library followed by different prefixes:

➡️[library]:[ENVIRONMENT].[CHANNEL].[SUBSCRIPTION_TYPE].[resourcename]⬅️

. Bold: mandatory fields . Italics: optional fields

[library]: mandatory field. Name of aura-bot library where the resource is contained. The library name must be the same as the name of the library that is being exported and must be configured in the locale-update script of the package.json file where the library is declared.
[ENVIRONMENT]:name of the environment. This is an optional field for the aura-bot resource that can be used in case it is required to show the user a different text in different environments. If this field is not existing, the same resource is used for every environment. The field must include the prefix of the environment (in uppercase): PRE or PRO. DEV show the same texts than PRO.
[CHANNEL]:name of the channel. This is an optional field for the aura-bot resource that can be used in case it is required to show the user a different text in different channels. This field must include the prefix of the channel (in uppercase): NOV, MH, MP,STB, STBH. If this field is not existing, the same resource is used for every channel.
[subscriptionType]: optional field. Different texts can be defined for each user’s subscriptionType, particularly: POSTPAID, PREPAID, CONTROL. They must be included in uppercase. If this field is not existing, the same resource is used for every subscription type.
[resourcename]: Name of the intended resource. It can include as many parts as needed to describe the resource. It can be expressed in a single word with lowercase (resourcename) or using kebab-case (resource-name). For example: services:services.usage.summary.

The following table shows some examples of bot resources and their associated copies in Aura:

Aura domain	Resource name (reference)	Description	Example of copy
Bundle	services:services.find.oneservices	Text associated to this resource is shown for every environment, channel and subscription type.	You´ve got %1$s contracted
Bundle	services:PRE.POSTPAID.services.usage.summary	Text associated to this resource is shown to users with subscription type postpaid in PRE environment	Let’s take a look. You’ve got %1$0.2f %2$s of data left, from your %4$0.2f %5$s allowance on %3$s, until %6$s.
Billing	bill:bill.check.genericCardText	Text associated to this resource is shown for every environment, channel and subscription type.	Let’s take a look. You’ve got one bill. It´s 2f%1$s.%2$0
Billing	bill:billing.topup.voucherincomplete	Text associated to this resource is shown for users in every environment and for every subscription type.	Top-up is not done

For each resource, there are certain pre-defined constraints (for example, the maximum number of characters) and determined variables which are common to every defined resource. The following table shows an example of these concepts.

Resource	Variables	Copy (response text)
services:services.usage.summary	%1$0.2f = Real Number, available data %2$s = Text, measuring unit for data %3$s = Text, name of bonus or plan %4$0.2f = Number, total data of bonus or plan %5$s = Text, date	Let’s take a look. You’ve got 5.5 GB of data left, from your 20 GB allowance on Custom plan, until 07-05-2019.

Precedence of prefixes

Resources are managed using a resolution matrix based on “from general to specific”. This means we will always have a generic resource in order to provide an answer to the user and, once we got it, Aura looks for a specific one if exists.

The order in the format reference is important to make the resolution matrix works properly. In this framework, the precedence of the prefixes is (from higher to lower):

SubscriptionType
Channel
Environment

The order in which the different combinations of prefixes must be checked for strings depends on the specificity (the number of matched prefixes) and the previously defined precedence order. For example, given:

library = “services”
subscriptionType = “POSTPAID”
channel = “TEST”
Environment = “PRE”
key = “title” The order of checking for matching terms must be the following (choosing the first existing translation):

services:PRE.TEST.POSTPAID.title
services:TEST.POSTPAID.title
services:PRE.POSTPAID.title
services:PRE.TEST.title
services:POSTPAID.title
services:TEST.title
services:PRE.title
services:title

Generation of a new resource in POEditor

⚠️ Remember that, for adding a new resource in the POEditor project, you need admin grants.

Follow the next steps:

Access the main page of POEditor and enter the username and password to access to the Local projects and choose the project to work on.

Select your POEditor local project and access the “Terms” option. You can see all the existing resources or search by library or name. Note that you should access “Terms” at project level (aura-bot in the example below), not for a specific language.

Click on the “Add Term” button. In this field, the new resource must be added.

Add the resource name, following the resources naming conventions.
Optionally, you can add a context in the “context” field for the categorization of the resource. It is useful for further searching purposes to include the name of the library here.

Save the resource, so it is created and added to the project.
Now, use the buttons in the right to fill in other fields:
- “Reference”: it can be added by clicking on the gear icon placed on the right hand side of the term. It should be the same as the name of the resource. It is important to fill in the “Reference”, as Aura uses it to import the resource into aura-bot.
- “Translations”: text for each different language.
- “Comments”

In order to check and modify references, please click the “R button” to the right of each term.
In order to check or edit all translations, please click the “T box”.

Resources for context filters and errors

There are special resources corresponding to errors or context filters that can be shared between libraries. The recommended way to add these resources is to duplicate them in every library that uses them.

For example, if we want a new error message to be sent when an API fails in two libraries (my-lib-1 & my-lib-2), we will add 2 resources:

my-lib-1:errors.api-error
my-lib-2:errors.api-error

In the case of context-filters, the format of the references will be, for example:

my-lib-1:context-filters.annonymous.not.allowed
my-lib-2:context-filters.annonymous.not.allowed

There is another way to add these resources:

Sharing the same resource BY adding it to a general [library] like:
- “ob-errors” (ob-errors:api-error) or
- “ob-context-filters” (context-filters:annonymous.not.allowed)
Importing it in every use case library that uses it. However, this last method has certain problems, because you need to add the new [library] to the aura-locale-importer command with the flag –b like this:
```
aura-locale-importer -u -j Aura-Bot -b my-lib-1,ob-errors -d ./settings/locale -m library -f
```
And it must be updated every time it changes in all libraries that use it to avoid conflicts during the make-up process.

Edition of texts in POEditor

At this stage, you have to edit the text (copy) of the existing resources associated with the use case under development or to translate the text to one specific language. For this purpose, follow the instructions below:

Enter your local POEditor project and then click in the desired language. All the resources and its associated texts are shown.
To find the text to be edited, there is a search box in the top-right corner of the POEditor interface. It is possible to search by key or part of a key of the resource (spanish translation of the term), or full or partial reference (key used in aura-bot for that term).
In case it is required to edit, for example, all strings concerning to account linking, search “account.linking”, which is the leading part of those strings. Each text can be edited just by clicking on the translation and modifying the text afterwards.
To find a term in a specific library, use the pattern “library_name”:

The edited texts are uploaded to aura-bot when deploying the corresponding Aura release.

Random alternative texts

aura-bot is able to show several alternative options of the same resource randomly. This behavior is provided as a platform feature and it only depends on the way the locales are defined in POEditor. The main idea is to add as many terms as alternative texts needed, keeping the same reference, as can be seen in the following picture.

When the locales are read from POEditor API to be handled by aura-bot, an array of alternatives for the given reference are stored in the locale files of the use case:

"common:common.greetings.main":[
    "Hello"
    "Hello, I am here for helping your"
],

Then, when building the response, aura-bot will return one of the options randomly.

Sorted texts

aura-bot is able to export sorted options of the same resource. If you want to guarantee the order in which the resources will be exported you have to define the resources in POEditor with numerical names(terms) starting at 0 and the same reference. For example

    core:login.loa2.cancel.keywords.0
    core:login.loa2.cancel.keywords.1

It will be exported as:

"core:login.loa2.cancel.keywords":[
    "close" (core:login.loa2.cancel.keywords.0)
    "cancel" (core:login.loa2.cancel.keywords.1)
],

This way ensure that the terms will be exported in order to the corresponding file.

Import locale files

We recommend using [aura-locale-importer() tool, a utility developed by Aura Global Team that allows locale files importation from POEditor.

Install aura-locale-importer tool:

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.
  
  ℹ️ developers should request the token for the installation of the aura-locale-importer tool from the APE Team.

Go to your use case library repository and enter the package.json file. This file contains the scripts of the project.

Go to the field locale-update and add the following command:

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., en-gb. If this field is empty, the system imports 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>: all the libraries to be uploaded by aura-bot. For example: context-filter, core, errors, suggestions, etc.
-d <local-directory>: local directory where result files are uploaded.
-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.
- For local use cases, the local responsible of the POEditor website must, at this stage, provide you with the API token:

- Once you have the token, you can follow two different processes: - Define it in the environment variable $POEDITOR_TOKEN in the host running the process. In this case, this command should not be included here. - Add it in the current command within -t <token>

An example for a local use case in Germany is shown below:

This command generates the locale files for the “bill” library that fulfil the conditions established in the parameters above:
$ aura-locale-importer -u -l de-de -j Aura-Bot-De -b bill -d ./locale -m library -f –t f9023005c8792e57d3593511b69c300e
This command lists the content of the locale folder in the aura-bot project: $ ls .locale
The output can be one of these: de-de.json en-gb.json es-es.json pt-br.json

Once the texts and resources are imported following the process above, when a new version of the library is generated, they are automatically integrated during the make-up process.

Management of locales for intents’ canonical phrases

The management of canonical phrases for CLU intents has been implemented in POEditor, as intents must have a canonical phrase to be able to disambiguate with them.

To do this, follow the guidelines in Manage locales for canonical phrases of intents.

Hot swapping process for the update of POEditor texts

It is possible for aura-bot to load new text locale files through a hot swapping process without service outage in order to have the updated texts available in the period between one release and the consecutive one.

For this purpose, the aura-configuration-updater allows making these modifications by providing the updated locales to your local DevOps Team.

In case developers have the need of making modifications to locales belonging to aura-bridge or aura-configuration-api because of the requirements of their use cases, they can follow the process specified in the document locales-managing.

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

Manage locales for canonical phrases of intents

The aim of this document is to describe how to manage locales to include canonical phrases in intents

Introduction

Intents must have a canonical phrase to be able to disambiguate among them.

For this purpose, it is required to include canonical phrases for CLU intents in POEditor, within a section named “intent” and upload them to aura-bot deployment.

Two scenarios can arise here, distinguishing between global use cases and local ones.

Global use cases

a. Generate the locales in POEditor:

Access the POEditor global project.
Look for the specific resource of the global use case intent, that will have the format: intent:[intent_name].
Edit the text of the specific resource for the global intent including the canonical phrase for this intent.

b. Upload the locales to aura-bot deployment

The “intent” section of the global POEditor project is imported into the bot deployment by the global library:
telefonica/aura-bot-library-disambiguation
If the intent is handled by a global dialog, it must be added in the locale-changes file to be deployed after every local deployment. It must also be notified to the Global Team to add it to the global POEditor, so it can be included in the succeeding aura-bot release.

Local use cases

For local use cases (intents handled by a local dialog), OBs should include resources for the all the intents’ canonical phrases. Aura Global recommends to use local POEditor, although this is not mandatory. The main request for those local resources is to be included in the library in a format compatible with the bot, as explained below.

a. Generate the locales in POEditor:

Access the POEditor local project
Create the specific resource with the mandatory format: intent:[intent_name].
For example, intent:intent.billing.check
Edit the text of the resource with the canonical phrase for this intent

b. Upload the locales to aura-bot deployment

To deploy these resources in the environment, it is required to upload them only from a library. Therefore, the ideal process would be either to use a library that is always deployed in the environment or to create an ad-hoc library to manage common processes and load into this library the section “intent” of the local POEditor project.

Docs:

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

Build Aura response

When developing a use case, a crucial step is to design the response that Aura provides to its users.

Learn how to generate it using the most appropriate texts and elements.

Introduction

Aura must be able to deal with messages from different partners in several languages and, moreover, from different communication channels.

Considering a user request to Aura through a specific communication channel, Aura must provide the appropriate answer to his/her utterance through a precise message expressed in the user’s language and in natural language.

The response to the user can be provided through three different interfaces, depending on the communication channel:

Custom interface: Interface with screen, voice and text interaction. This is the main Aura interface.
Voice interface: Interface for devices without screen, where the interaction is only done through voice.
Chat interface: Message interface where the text is the main interaction mode, based on a conversational model with bubbles and historic data.

Depending on the channel and its rendering capabilities, the response can include different elements: text, cards, graphic resources, deeplinks, suggestions and actions.

The following documents include the guidelines for the generation of three key elements in Aura response:

Texts: how to generate or update Aura response texts in POEditor.
Cards: different types of cards that can be included in Aura response as visual elements.
Graphic resources: static or dynamic graphic resources that can be included in the response to the user.

Docs:

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

Managing locales in RTM

How locales files and POEditor project are managed in RTM.

How to manage locales

To avoid updating the locales with the base project in the main branches in the RTM INIT process, there is a job store-locales, that is responsible for storing the locales of each component/library in the branch-locales collection with the following structure:

{
   "branch": "main/fake",
   "authentication-api": {
        "de-de": "{\n \"authentication:authenticator-error.description\": [\n \"Bei der Authentifizierung ist ein Fehler aufgetreten. Bitte versuche es später noch einmal\"\n ],\n ....",
        "es-cr": "{\n \"authentication:A1004.authenticator-error.description\": [\n \"Parece que has olvidado tu usuario o contraseña de acceso a Mi Movistar.\"\n ] ....}"
   },
    "aura-bot-platform": {
        "es-cr": "{\n \"context-filter:multimsisdn-users-not-allowed.onboarding\": [\n \"Pulsa el micrófono y di lo que quieras. Consulta la ayuda para saber qué cosas puedes preguntarme.\"\n ],\n \"context-filter:user-info-not-accessible\": [\n \"Sorry\"\n ],\n \"core:bypass.close.words\": [\n \"cancelar\",\n \"cerrar\",\n \"salir\",\n \"desconectar\"\n ],\n \"core:empty.response\": [\n \"Ok, estarei aqui sempre que você precisar.\"\n ] }\n",
        "de-de": "{\n \"context-filter:multimsisdn-users-intent-not-allowed.text\": [\n \"Entschuldigung, auf diese Daten kann ich aufgrund deines Vertrages nicht zugreifen. Zukünftig kann ich das sicherlich, aber bis dahin kann ich dir mit Fragen rund um o2 Services weiterhelfen. Wenn du mehr Informationen über deinen Vertrag erhalten möchtest, gehe einfach in deinen [Mein o2 Bereich](www.o2online.de/meino2).\"\n ],\n \"context-filter:user-info-not-accessible\": [\n \"Sorry\"\n ],\n \"core:bypass.close.words\": [\n \"cancelar\",\n \"cerrar\",\n \"salir\",\n \"desconectar\"\n ],\n \"core:empty.response\": [\n \"Ok, estarei aqui sempre que você precisar.\"\n ] }\n"
     }
}

During the development of the main branch, if it is necessary to update the locales of any component, it will be done using the locale-update script, which will have been updated by the following locale-importer command in the creation phase of the branches of each component/library:

aura-locale-importer -u -s Db -pkg <package_name> -m library -b core -d ./locale -f -mb <main-branch-name>
The environment variables SECRET_TOKEN and BRANCH_CONFIG_APIKEY are required for its execution.

This command will do a merge between the local files stored in DB for that component/library and the resources created/updated in the POEditor project main-branch-name generating the new locales files.

In the execution of the prepare-to-merge of the bot, an update-locales step has been added, which updates the locales of each component/library by merging the content of the base project in POEditor (Aura-Bot) with the POEditor project of the main branch.

Endpoints locales

For the management of the locales in BD, the following endpoints have been created in aura-release-train-branches: - /branches/{branch}/locales - /branches/{branch}/locales/{package}

Docs:

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

Manage locales in Aura

The aim of this document is both general and specific processes to describe how locales are handled by Aura Bot services

Introduction

Locales in Aura refer to specific content for an OB and a language, in which any special variant preference that an OB wants to see in its user interface is included.

Localization is an important aspect of internationalization and localization (i18n) for the adaptation of internationalized software for a specific region or language by translating text and adding locale-specific components.

The current section includes key documents to manage locales in Aura:

Docs:

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

aura-locale-manager utility

aura-locale-manager utility allows Aura Bot to manage text resources

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)