Aura – Experiences Builder

Docs:

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

Introduction to Aura use cases

Learn what is a use case in Aura and which are the different types of experiences that can be developed

Introduction

Aura is offered as a platform to the business units to integrate it into their customer relationship channels and with a series of capabilities to create locally relevant experiences for the users. These experiences are called use cases.

A use case is a specific experience triggered by a direct request from the users that provides them with the most appropriate response to their requests due to Aura’s capability of understanding natural language, processing it and building personalized responses in real time.

Types of use cases in Aura

Use cases in Aura are divided into two main groups:

Generic questions use cases

Experiences based on frequently asked questions (FAQs), that is, the most common questions that customers can ask Aura in their interactions and that are most likely to remain constant over time. A great percentage of interactions with Aura is based on these questions.

✅ Examples of generic question use cases:

How can I get my IMEI number?
Use data abroad
Activate O2 wifi

Global use cases

Global use cases are already designed and developed by Aura Platform Team. You cannot modify their logic but use them as they are or get inspired for deploying your own experiences:

Video use cases are available.

📃 Learn how to manage global use cases in the Use Global Use Cases section.

Personalized use cases

Custom-made experiences that provide specific answers to each customer based on her data and context.

✅ Examples of personalized use cases:

Show me my last bill
Check my data consumption
Status of my complaint A-330
Check my balance
Which devices are connected to my wifi?

They are classified into two categories:

Use cases managed by the generic-dialog

The generic-dialog allows the creation of personalized experiences easily, only by means of a simple configuration, with no code development. It is available for use cases in TV channels that imply direct actions (Switch off the TV; rewind the movie 10 seconds; etc.)

Interested in these use cases?

📃 Understand what is the generic-dialog and the conditions for its use here.
📃 Learn the detailed guidelines for the generation of a use case through the generic-dialog here.

Local use cases

Custom-made experiences in Aura that can be built by constructors from scratch or inspired in a global use case.

All of them require:

Writing code over aura-bot
Training the system to understand the user’s request through Aura NLP

📃 For creating this custom-made use cases, follow the guidelines in Develop local experiences in Aura.

Docs:

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

Use global use cases

Learn how to make the most of Aura global use cases, experiences already developed by Aura Platform Team at your disposal

Introduction

Aura global use cases are experiences already designed, developed and tested by the Aura Platform Team (i.e., check my bill; list my bundle; data allowance; etc.).

Take into account that global use cases cannot be modified by OBs, they must be used as they are. You only have to perform a mandatory task over them for the edition of texts to be included in the response to your users.

Optionally, you can install the use case in local environment to become aware of how it is designed and build as an inspiration source for the development of other local use cases.

Check the global use cases currently included in Aura Platform:

Experiences in video services related to play TV content, channels tuning, navigation and other use cases for TV-related channels.
Find the available experiences in Aura video use cases.

Interested in making a global use case available in your Aura system?

Firstly, learn how to install it in the install global use cases section.
Once installed, if your goal is using the use case as is, you can personalize the texts that will be shown in the conversational flow with the user following the guidelines in Build Aura response: edit POEditor texts
If you simply want to get inspired and analyze how the global use case has been developed, check the section Analyze a global use case in local environment

Docs:

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

Develop experiences through the generic-dialog

Learn how to develop a use case through Aura bot generic-dialog, only by means of a simple configuration and with no code development.

Related documents
📄 generic-dialog descriptive documentation

Introduction

The generic-dialog allows OBs to implement certain local use cases for Movistar Home, Movistar Plus and Set-top Box (STB) channels in an autonomous, agile and simple way with no code development, only by means of configuration.

First, we highly recommend you to read these documents:

Description of aura-bot generic-dialog:
- generic-dialog v1 -> compatible with channelData v1
- generic-dialog v3 -> compatible with channelData v3
Conditions for a use case in order to be built using the generic-dialog. Check these conditions here.

Use case development flowchart

The following flowchart schematically shows the process for the development of a local use case through the generic-dialog.

This process contains specific stages for the generic-dialog and other stages that are the same as for use cases developed with other uc-specific dialogs.

Guidelines for the development of a use case through the generic-dialog v3

1. Meet the generic library and dialog

The OB willing to develop a local use case managed by the generic-dialog will be provided with a Github repository:
https://github.com/Telefonica/aura-bot-libraries-[OB]/tree/master/packages/generic-[OB]
You should copy the global generic-dialog structure:
https://github.com/Telefonica/aura-bot-libraries/tree/master/packages/generic

When developing a local use case through the generic-dialog, OB developers may only modify the file dialog-config.json placed on the settings folder.

The library can contain specific files per language and OB:
/generic-[OB]/settings/dialog-config.<AURA_DEFAULT_LOCALE>.json
Where AURA_DEFAULT_LOCALE is the culture code to be used by default in the current deployment: en-gb, es-es, pt-br, de-de.

The dialog-config.<AURA_DEFAULT_LOCALE>.json contains all the intents that the generic-dialog can trigger for a specific channel, each of them with their associated configuration.

2. Add and configure the new intent in the dialog-config.json file

Developing a local use case through the generic-dialog only requires to include a new intent and its configuration in the dialog-config.json file placed on the settings folder of the generic-[OB] library.

Follow the instructions below:

Access to your global library and enter the dialog-config.json file:
https://github.com/Telefonica/aura-bot-libraries-[OB]/tree/master/packages/generic-[OB]/settings/dialog-config.<AURA_DEFAULT_LOCALE>.json
Include your use case intent in this file.
To add a new intent only means to include a new configuration managed by the generic-dialog. This extends the configuration of the dialog-config intents to include all the settings. Remember that the intent name must be defined following the format: intent.[DOMAIN].[INTENT].
Add the specific configuration for this intent in the settings field. Fields in the configuration belongs to two specific fields in the channel configuration model:
intentSettings model
IntentSettingsLocales model

Check the properties in these models and their associated fields and values in Channel model.

3. Specific case: intents/entities that require the application of a function on the dialog’s parameters

ℹ️ This scenario only applies to use cases with intents or entities that require the conversion of certain dialog parameters through a function in order to get the correct payload and the expected output in the channel.

A clear example is a use case that requires a certain conversion of entities, for example, move forwards: NLP recognizes a certain entity but it is required to create a function that converts minutes into hours:

See complete examples for Move forwards and Move backwards.

Just in case it is required to apply a function on any dialog parameter, developers have to define the functions block on the dialog-config.json file. This consists on two fields params and algorithm, which are explained the following sections.

"functions": {
                "params": [
                     …
                 ],
                 "algorithm": "…"
}

The utils folder of the generic library contains the generic-test-utils file for the parameterization of functions. This file includes the functionalities to make modifications to any parameter of the dialog if required due to the fact that the function is too complex to be added in the dialog-config.json

New functionalities must be added in an orderly and commented manner with a JSdoc including a description of the functionality and, at least, an enumeration of the parameters it uses.

 Calculate the value in seconds in case the entity type
 does not come in this format (ent.time_length_sec).
 Right now it only calculates from minutes to second.
 
 @function calculateSecondLevels
 @param  {Intent} currentIntent
 @return persistentData.dialogData.actionParams.SEND_KEY.levels set to seconds
 
export function calculateSecondLevels(currentIntent: Intent) {
    currentIntent.entities.map((ent) => {
        if (!isNaN(ent.entity)) {
            persistentData.dialogData.actionParams.SEND_KEY = { levels: ent.type === 'ent.time_length_sec' ? Number(ent.entity) : Number(ent.entity) * 60 };
        }
    });
}

field `params`

The params attribute contains the parameters needed to execute the modification algorithm. The parameters must be already available in the generic-dialog variable functionVar within the generic-dialog.ts file.

Currently, there are three parameters: currentIntent, persistentData and context, explained below.

File generic-dialog.ts

const functionVars = {
    currentIntent: DialogUtils.getDataActiveDialog(stepContext, 'options').intentResult,
    persistentData: await ContextUtils.getAuraPersistentData(stepContext.context),
    context: stepContext.context
};

File dialog-config.json

    "functions": {
        "params": [
            "currentIntent"
        ]

The input parameters for functionVars are described below:

currentIntent: it contains an object of type intentResult with the intent and entities attributes.
- intent contains a string with the name of the intent.
- entities is an array with the values returned by Aura NLP. These values help us evaluate the intent and to be able to interact on the values returned in entities.

{
    "intent": "intent.tv.move_forwards",
    "entities": {
        "entity": "20",
        "type": "tef.time_length_min",
        "score": 1,
        "start_index": 7,
        "end_index": 8,
        "canon": "0"
    }
}

persistentData: it contains the dialog’s data developers want to persist. Data is passed as a parameter to the getMovistarMessage function where data is accessed, if necessary, to display in the payload.
context: it contains the TurnContext. This object is useful for accessing through functionalities most of the data that may be needed in case of parameterization. The utility that includes helper methods to manage Bot Framework TurnContext is context-utils.

const correlator = ContextUtils.getCorrelator(context);
 const { userId, phoneNumber }: AuraUserBaseModel<FourthPlatformUserModel> = ContextUtils.getAuraUser(context);

Field `algorithm`

The algorithm field can be completed in two ways:

Add the script directly in the dialog-config.<AURA_DEFAULT_LOCALE>.json file. In this case, developers have to take into account two limits:

The code must be included in Javascript.
The script must be on one line, so it cannot be too complex.
See the examples for the use case Move forwards.

Add the functionality in the utilities file:
https://github.com/Telefonica/aura-bot-libraries-[OB]/tree/master/packages/generic-[OB]/src/utils/generic-dialog-utils.ts
and referencing the name of the functionality in the dialog-config.json file: The function calculateSecondLevels is declared in the file generic-dialog-utils.ts.

export function calculateSecondLevels(currentIntent: Intent) {
    currentIntent.entities.map((ent) => {
        if (!isNaN(ent.entity)) {
            persistentData.dialogData.actionParams.SEND_KEY = { levels: ent.type === 'ent.time_length_sec' ? Number(ent.entity) : Number(ent.entity) * 60 };
        }
    });
}

The file dialog-config.json must reference this functionality: calculateSecondLevels (See the example for Move backwards.

4. Build response

For local use cases, this step is required to generate both the resources and their associated texts for every dialog across all channels in a local POEditor project and to include the new text resources in the corresponding locale file of the generic-[OB] library.

5. Validate the generic-dialog with unit tests

Bot Framework 4 provides a Test Adapter that allows launching unit tests for the validation of the dialog performance and to check that its performance is adequate in terms of the conversational flow between the user and aura-bot.

The tests of each use case included in the generic-dialog are located in the following path:
https://github.com/Telefonica/aura-bot-libraries-[OB]/tree/master/packages/generic-[OB]/src/tests/ In this folder, tests should be organized by the use case domain, including one folder for each specific library. The library is included in the name of the intent that has this format:
intent.{LIBRAY_NAME}.{INTENT_NAME}

As an example, the figure shows this organization for the global library generic, containing tests for use cases in the domains: communications, domotics, e-commerce, navigation, tv and wifi.

The folder also contains the file generic-test-utils.ts, that includes configurations and functionalities common to all tests. The purpose of this file is to avoid code duplication in each test. It also contains the getDialogIntentConfig functionality needed to retrieve the settings and mock up the getIntentConfig function.

In case it is necessary to modify any attribute of the configuration, it can be modified in the corresponding test by accessing the attribute to modify its configuration but not creating a new configuration.

import { configuration } from '../generic-test-utils';
configuration.AURA_LOCALE_FORCE_IMPORT: true,

6. Package and test the use case locally

Once the previous stages are finished, now you can package the use case’s library as a .tgz file and test it in local environment.

If the local testing is satisfactory, your use case is ready for its deployment.

How channelData v3 is formatted in responses

IntentResult

intentResult contains fixed values obtained from a map intent-intentResult. intentResult also has information about the default actions associated to this intent.

You can find more info in actions v3.

Actions

Actions are formatted mixing all the information from:

Default actions by intent in intentResult
Configuration in the dialog’s settings
Parameters calculated on runtime by dynamic functions configured in settings

All this information is mixed in the above-described order. settings will overwrite default values by intent, and runtime parameters will overwrite parameters in settings.

Default actions by intentResult

Certain intents have associated actions in its intentResult.

For example: Volume up intent will have the SEND_KEY action associated to the VOL- key and the rest of the needed parameters. This action will only be added to the response if the volume up intent have configured the SEND_KEY action. If the action by default is not configured in settings, it will not be sent.

Dialog settings

In the settings field of the dialog’s triggerCondition, you can add inside a new field actions including all the actions and parameters needed for this intent.

Only set the action name and all the default params will be returned, for example:

For intent intent.tv.move_forwards, we will add this configuration:

{
  "actions": [
    {
      "name": "SEND_KEY"
    },
    {
      "name": "MAKE_SOUND"
    }
  ]
}

As intent.tv.move_forwards has the default action SEND_KEY associated in its intentResult, these default values will be returned.

However, intent.tv.move_forwards does not have the action MAKE_SOUND associated, so the value returned will be the default for this action (by default, MAKE_SOUND will return a positive sound).

You can check actions associated to every intentResult in actions v3.

In order to overwrite these default values, you only have to configure them as shown below:

{
  "actions": [
    {
      "name": "SEND_KEY",
      "params": {
        "keyCode": "MOVE_FORWARD",
        "levels": "10"
      }
    },
    {
      "name": "MAKE_SOUND",
      "params": {
        "sound": "negative"
      }
    }
  ]
}

With this configuration, the levels of the SEND_KEY action will be overwritten to 10 (default is 60) and keyCode will be overwritten to MOVE_FORWARD (in this case, it is the same value as default).

In the MAKE_SOUND action, the sound value will be overwritten to negative (default is positive). The rest of the values will be the default ones (for example the target field).

The response will be something like this:

{
  "channelData": {
    "actions": [
      {
        "name": "SEND_KEY",
        "target": "stb",
        "params": {
          "keyCode": "MOVE_FORWARD",
          "levels": "10",
          "deviceId": "Mi-29283"
        }
      },
      {
        "name": "MAKE_SOUND",
        "target": "channel",
        "params": {
          "sound": "negative"
        }
      }
    ]
  }
}

Parameters in runtime

In the generic-dialog, it is possible to add functions to change the behavior of the dialog. If you want to modify params from actions in runtime you need to set it in the following variable:

persistentData.dialogData.actionParams.[ACTION_NAME]

For example, if you want to modify the returned sound according to the recognized entities, configure a function like this:

"functions": {
    "params": [
        "currentIntent",
        "persistentData"
    ],
    "algorithm": "currentIntent.entities.map((ent) => { persistentData.dialogData.actionParams.MAKE_SOUND = { sound: ent.type === 'ent.userHappy' && ent.entity ? 'positive' : 'negative'}})"
}

Values stored in runtime in persistentData.dialogData.actionParams.MAKE_SOUND will overwrite default values and configured values in settings.

Special parameters

deviceId is a special actions parameter that should be set in runtime. All the actions with target = stb will set this value in the action params by default.

Practical examples

TV remote actions

Use case with a direct transformation intent to action.

        {
            "intent": "intent.tv.channel_down",
            "settings": {
                "locales": {
                    "success": [
                        "tv.channelDown"
                    ]
                },
                "actions": [
                    {
                      "name": "SEND_KEY",
                      "params": {
                        "keyCode": "P-",
                        "Levels": "1"
                      }
                    }
                ],
                "needPlayingContent": true
            }
        }

Move forwards

Use case that requires the generation of a conversion function. This function is applied to the dialog’s parameters in order to get the correct payload.

       {
         "intent": "intent.tv.move_forwards",
         "settings": {
           "needPlayingContent": true,
           "locales": {
             "success": [
               "tv:tv.moveForwards"
             ]
           },
           "actions": [
             {
               "name": "SEND_KEY"
             },
             {
               "name": "MAKE_SOUND"
             }
           ],
           "functions": {
             "params": [
               "currentIntent",
               "persistentData"
             ],
             "algorithm": "currentIntent.entities.map((ent) => { if (!isNaN(ent.entity)) { persistentData.dialogData.actionParams.SEND_KEY = { levels: ent.type === 'ent.time_length_sec' ? Number(ent.entity) : Number(ent.entity) * 60}}})"
           }
         }
       }

Move backwards

Use case that requires the generation of a conversion function. This function is applied to the dialog’s parameters in order to get the correct payload.

In this case, the field algorithm references to the function calculateSecondLevels, described in the file: packages\generic\src\utils\generic-dialog-util.

{
          "intent": "intent.tv.move_backwards",
          "settings": {
            "needPlayingContent": true,
            "locales": {
              "success": [
                "tv:tv.moveBackwards"
              ]
            },
            "actions": [
              {
                "name": "SEND_KEY",
                "params": {
                    "keyCode": "MOVE_BACK",
                    "Levels": "60"
                }
              },
              {
                "name": "MAKE_SOUND",
                "params": {
                    "sound": "positive"
                }
              }
            ],
            "functions": {
              "params": [
                "currentIntent"
              ],
              "algorithm": "calculateSecondLevels"
            }
          }
        }

Docs:

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

Develop local experiences in Aura

Casuistry and processes for the development of local personalized use cases in Aura

Introduction

Local use cases in Aura are custom-made experiences that can be built by constructors from scratch or inspired in a global use case.

Key tasks for a local use case development

Depending on your skills, there are three categories of profiles that must work over specific Aura components:

Bot developers

Work over aura-bot
They should build the logic of the conversational flow with the user, make Aura resolve the user’s request and provide back the most appropriate response.
Guidelines: Build the use case logic

NLP experts or linguists

Work over Aura NLP
They are in charge of making Aura understand the user’s request through building and training an understanding model.
Guidelines: Train Aura to understand

Content managers

Their role is the design of the texts that will be included in the conversational flow with the user.
Guidelines: Build Aura response

Optional tasks

Apart from the key tasks listed above, there are certain optional activities that can be done when developing a local experience for its configuration, such as including the developed experience in Suggestions.

Specific scenario: Use case development in WhatsApp channel

When developing a use case in WhatsApp, the general procedure must be followed. However, certain extra steps must be carried out in these channels due to their limitations.

Check them in Use cases development in WhatsApp.

Specific scenario: Use case development in RCS channel

When developing a use case in RCS, the general procedure must be followed. However, certain extra steps must be carried out in these channels due to their limitations.

Check them in Use cases development in RCS.

Docs:

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

Use cases development tools

Creating Aura experiences is easier thanks to the innovative tools and resources our engineers have designed for use case developers.

Discover the available ones and when and how you can use them

Introduction

In both cases, certain tools are release-dependent, so you should select the appropriate one for your Aura Platform release.

The key tools at your disposal are listed below:

▶️ Get started with Aura minibot, in order to work in local environment for testing purposes

▶️ The NLP virtual machine is ready for the configuration of the NLP development environment

▶️ Discover Abacus 1.0.0., a tool for training, testing and certify an NLP model.

▶️ With Aura mocks server you can provide a mock for any service using aura-bot

Docs:

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

Aura API clients

Available API clients in Aura and process for their creation or update

Introduction

aura-bot has connections with several APIs through the use of different modules, which constitutes a practical way to communicate with them.

In this framework, API clients, or just clients, are defined as modules to be used inside the code that contain a set of tools with the purpose of carrying out requests in the simplest way.

API clients are generated automatically from the swagger file delivered by the API constructor, usually Kernel. Aura uses a custom code generator based on the OpenAPI initiative in order to generate TypeScript clients which is compatible with JavaScript.

There are two types of clients, External Clients that are associated with services external to Aura, and Internal Clients, associated with Aura servers.

All Aura API clients can be found in the following Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/

Content in this section

This section contains all the information related to Aura API clients:

Docs:

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

Development troubleshooting

In this section you will find solutions to common problems that we may encounter when developing in Aura

Introduction

The current section includes guidelines for the resolution of the most common problems that can occur when developing over aura-bot and in the Webclient channel.

Apart from the guides included here, specific problem-solving procedures for a component are included in this component documentation.

Aura – Experiences Builder

Docs:

Introduction to Aura use cases

Introduction

Types of use cases in Aura

Generic questions use cases

Global use cases

Personalized use cases

Use cases managed by the generic-dialog

Local use cases

Docs:

Use global use cases

Introduction

Docs:

Develop experiences through the generic-dialog

Introduction

Use case development flowchart

Guidelines for the development of a use case through the generic-dialog v3

1. Meet the generic library and dialog

2. Add and configure the new intent in the dialog-config.json file

3. Specific case: intents/entities that require the application of a function on the dialog’s parameters

field params

Field algorithm

4. Build response

5. Validate the generic-dialog with unit tests

6. Package and test the use case locally

How channelData v3 is formatted in responses

IntentResult

Actions

Default actions by intentResult

Dialog settings

Parameters in runtime

Special parameters

Practical examples

TV remote actions

Move forwards

Move backwards

Docs:

Develop local experiences in Aura

Introduction

Key tasks for a local use case development

Optional tasks

Specific scenario: Use case development in WhatsApp channel

Specific scenario: Use case development in RCS channel

Docs:

Use cases development tools

Introduction

Docs:

Aura API clients

Introduction

Content in this section

Docs:

Development troubleshooting

Introduction

field `params`

Field `algorithm`