Aura –

Docs:

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

Build an Aura Bot dialog

This section includes different processes for building an Aura bot dialog when developing a local use case, both general guidelines and specific ones for concrete scenarios

Introduction

Dialogs are software components that model conversations with the final users by interchanging messages with them. Currently, aura-bot supports the Microsoft Bot Framework SDK v4 for JavaScript as the internal bot engine.

When developing a local use case, that can be both an experience built from scratch or inspired in a global use case, the OB developers must build a new local dialog that includes the logic of the use case or modify an existing one.

The dialog will interact with the customer using a conversational interface, this is, interchanging messages back and forth and, if required, the dialog will summon Kernel or third-party APIs in order to fetch data to fulfil the user’s request.

Before getting started, we recommend you to read some useful Microsoft documentation:
📄 Send and receive text message
📄 Dialogs library

Scenarios for building a dialog

Bot developers can find different scenarios when building a dialog over aura-bot:

Build an Aura Bot library that will contain the dialog, in case it does not exist.
General guidelines for building a dialog: most common scenario for building a dialog over aura-bot
Build a dialog that use async APIs, that is, APIs that do not provide the information back immediately, but with a certain standby time as they must perform a specific task derived from the user’s request.
Configure bypass mode to force sending any input message to aura-bot directly to a external service and vice versa.
Build an operation, which are a type of intents that can be used inside a dialog’s conversational flow.
Migrate a dialog to channelData v3, including the steps for making your use case compatible with channelData v3.
Migrate use cases to Bot Framework 4.19, which is the version used by Aura’s upcoming architecture based on Microsoft skills protocol.

Docs:

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

Test an Aura Bot dialog

Guidelines for the design and execution of unit tests for the validation of an Aura Bot dialog

Introduction

When developing a use case, and once the use case dialog is built, it is required to test the dialog in order to verify its proper performance in terms of the conversational flow between the user and aura-bot . This step is mandatory for the OB developers in order to merge their Pull Requests.

This task comprises three main steps:

Generate the unit tests and place them on the use case library.
Execute the unit tests through the Test Adapter that simulates sending messages from the user to the bot.
Validate the dialog with the unit tests within an iterative process: if results are not satisfactory, the required modifications must be done in the dialog .ts file.

Generate the unit tests files

Within the use case library, it is recommended that the unit tests files are placed in the folder src/ folder.
They should be named with the same name as the correponding dialog, which must be also included in this folder:
Dialog: <dialog-name>.ts ➡ Test file: <dialog-name>.spec.ts
Moreover, if auxiliary files are required for the tests, they can be optionally placed in a folder named /test.

📌 For a proper understanding of the unit tests for dialogs, it is recommended that developers check the source code of the Aura dialog greetings from the library common and its associated unit tests, as an example. The code of these unit tests can be also used as a template for designing your own tests.

Execute the Aura Bot dialogs unit tests

For the execution of the unit tests, read the guidelines How to debug with mocha and Typescript.

Docs:

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

Package a developed use case

Guidelines for a use case packaging, previous to its deployment

Instructions for packaging a use case

Once a use case is developed, and previous to its deployment, the use case must be packaged.

The use case’s library should be packed as a .tgz file executing the following command from the library root folder: $ npm pack

The outcome of the command is a .tgz file with the deployable code of the library.

Although the library was not published in npm registry, it is recommendable to update the package.json version field with every change, to be able to track the specific version being deployed in all the environments.

This package is the one that will be installed and tested in the minibot or delivered to the Local Operation Team to be deployed.

Docs:

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

Test a developed use case locally

Once the use case is developed, and prior to its deployment, it is required to test it in local environment. Learn how to do it in this document

Test a developed use case

There are two different options to test your brand-new use case:

Using Aura Minibot locally, the recommended method.
Through full bot local deployment.

Test a use case using Aura minibot

It is highly recommended to use Aura minibot for testing the use case in your local environment.

For this purpose, read the Aura minibot guidelines to know firstly how to install and run Aura minibot.

If you have already installed Aura minibot, go directly to section Develop a new use case to know how to import the use case library, after its packaging as a .tgz file.

Test a use case through full Aura Bot

Firstly, to work with full aura-bot, read the guidelines for the installation and configuration of full Aura Bot.

Now, test your use case following these instructions:

Deploy the library to be tested. There are two options:
- 1. Add the library .tgz file to the file plugin-config.json (placed in the aura-bot-platform Github repository).
    Note that manual addition of libraries to plugin-config.json file requires manual installation too:
    npm install <library>
- 1. Use the automatic script:
    npm run import-libraries
    This process will install any .tgz in aura-bot-platform/local_modules folder.
    The previous command will add the library in package.json and plugin-config.json files and will install them into the project.
    If a further configuration of the library is required (for example, disabling some dialogs), this must be done manually by editing plugin-config.json available at the root of the aura-bot-platform folder.

In the simplest case, plugin-config.json is an array of strings, each of them containing the name of the npm package of a library. It is the way used by aura-bot to configure the plugins that are going to be deployed in the runtime of each instance and is the format defined by the library used internally by aura-bot architect. However, every element from this array can also be an object containing more information.

Note that the following two examples are totally equivalent:

[
    "@telefonica/aura-bot-bill-library",
    "@telefonica/aura-bot-common-library"
]

and

[
    {
        "packagePath": "@telefonica/aura-bot-bill-library"
    },
    {
        "packagePath": "@telefonica/aura-bot-common-library"
    }
]

When a package name is included in the plugin-config.json file, it is loaded when running the bot, and all the dialogs specified in the use case library file index.ts are loaded.

If for any reason, it is required to exclude one or more dialogs from the library, in order to not be loaded, they can be specified with the exclude property of the library, for example:

 [
    "@telefonica/aura-bot-bill-library",
    "@telefonica/aura-bot-common-library",
    {
        "packagePath": "@telefonica/aura-bot-other-library",
        "exclude": [
            "./first-dialog"
        ]
    }
]

In the previous example, all the dialogs from aura-bot-bill-library and aura-bot-common-library are loaded, as well as all the dialogs from aura-bot-other-library. However, the dialog ./first-dialog is excluded (relative path, as specified within the index.ts file).

Max response times due to graceful shutdown policy (Recommendation)

Due to the infrastructure configuration, we recommend that the response time for the developed use cases should be less than the time configured in the AURA_SHUTDOWN_GRACEFUL_TTL aura-bot environment variable. If the message takes longer than the configured time, it could be lost due to aura-bot’s graceful shutdown policy, resulting in the user not receiving a response.

Docs:

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

Deploy a developed use case

Guidelines for the deployment of a new use case in Aura, in order to make it available for Aura users and the recommended checks to be done before deployment

Check points before use case deployment

Once the use case is developed and tested, and before its deployment, it is required to make certain verifications to assure its proper performance in the intended channel.

Check that the intended channel is enabled

aura-configuration-api must include an entry for each one of the desired channels the Aura users are going to use to interact with the aura-bot instance.

For example, if the Novum application is the intended channel, an entry such as the following one should be included in aura-configuration-api:

[
  {
    "name": "novum-mytelco",
    "prefix": "nov",
    "channel_id": "45494a5b-835a-4fff-a813-b3d2be529dbe"
    …
  }
…
]

At this stage, developers should validate with the local DevOps team that the channel name, prefix and identifier are the right ones. This channel identifier should be unique for the specific channel in Aura.

In case other channels are supported, additional entries such as the one provided in the example should be included.

Check that the required scopes and purposes are included

aura-configuration-api must include the Kernel scopes and the purposes granted for the user which are needed to cover all the enabled use cases (dialogs).

These scopes and purposes should include:

The ones needed to get the user’s access token
The ones needed to inject user’s information into the messages reaching the aura-bot instance
The ones needed for the functionality implemented by each enabled use case.

The information regarding which scopes and purposes are needed can be located in the Kernel documentation website](https://developers.baikalplatform.com/) and, more concretely, in the specific sections for each Kernel installation made in every available environment for each specific country.

For example, in case of the Kernel User Profile API, for the production environment in Spain, the scopes and purposes information can be located at the Authentication section in User Profile (3.5.1). Notice the sections highlighted in bold on the previous URL to infer the specific URL to use for each concrete country and environment.

It is important to note that if the scope information is omitted, the requested access token is issued for all the scopes declared when the client application was created in the Kernel infrastructure.

An example of the scopes and purposes to be included into the concrete channel configuration to be able to invoke the previous APIs is the following one:

"name": "novum-mytelco",
    "prefix": "nov",
    "channel_id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
    "fpa_auth_scopes": "device-catalog:devices-read device-stock:stock-read",
    "fpa_auth_purposes": "customer-self-service detect-abnormal-usage device-recommendations-v3 sim-upgrade-suggestion aura-read-insight-events identify-customer bolt-on-suggestion",
......
}

Two examples, for the Kernel User Profile API and the Subscribed Products API, are shown below, where scopes and purposes are found:

The following snippet shows how to indicate the scopes and purposes needed by an Aura user to execute all the dialogs within a library (if authorization setting is set at library level) or one of the dialogs (if set at dialog level), which are included in the dialog configuration (dialog-config.json. These scopes and purposes are validated before making the correspondent API request to Kernel, to handle permissions errors beforehand and avoiding making a request that will fail in the end.

{ "id": "details-services",
      "suggestions": true,
      "authorization": {
        "purposes": "customer-self-service",
        "scopes": "subscribed-products-user-read"
      },
}

Deploy a developed use case

Once your developed use case is successfully tested in your local environment, provide the library’s .tgz file to your Local DevOps Team, which is responsible for the use case deployment.

This process will include the publication of the use case library and aura-bot make-up and running.