Aura – plugin

Docs:

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

agent-dispatcher-api plugin

Technical description of the agent-dispatcher-api plugin

Introduction

agent-dispatcher-api plugin manages and dispatches the requests to the agent API.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
redisConnector	PluginType.Service	Redis connector
sessionService	PluginType.Service	Session service
agentsConfiguration	PluginType.Service	Agents Configuration

Provides components (IOC)

Name	Type	Description
agentDispatcherApi	PluginType.API	Agent dispatcher API

Docs:

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

aura-generative-api plugin

Description of the aura-generative-api plugin

Introduction

The aura-generative-api plugin manages the endpoints for the communication with atria-model-gateway.

Consumes components (IOC)

Name	Type	Description
generativeProcessService	PluginType.Service	Send data to model-gw and process the response
applicationConfiguration	PluginType.Service	Configuration of applications

Provides components (IOC)

Name	Type	Description
generativeApi	PluginType.API	Endpoints for the communication with generative APIs

Docs:

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

Aura bridge global plugins catalog

Current global plugins developed in Aura bridge by the Aura Platform Team

Global plugins repository

Check the Github global plugins repository to see the currently available plugins in aura-bridge.

Aura Platform Team is progressively documenting each plugin within this section. The already documented ones include the corresponding link below.

admin-api plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/admin-api
async-callback-directline-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/async-callback-directline-processor
auraline-conversation-api plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/auraline-conversation-api
- auraline-conversation-api plugin description
auraline-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/auraline-incoming-processor
- auraline-incoming-processor plugin description
auraline-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/auraline-service
aurapush-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/aurapush-incoming-processor
aurapush-sendfeedback-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/aurapush-sendfeedback-service
- aurapush-sendfeedback-service plugin description
directline-auraline-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-auraline-processor
- directline-auraline-processor plugin description
directline-rcs-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-rcs-processor
- directline-rcs-processor plugin description
directline-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-service
- directline-service plugin description
directline-whatsapp-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-whatsapp-processor
directline-whatsapp-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-whatsapp-service
- directline-whatsapp-service plugin description
genesys-directline-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/genesys-directline-processor
- genesys-directline-processor plugin description
rcs-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/rcs-incoming-processor
rcs-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/rcs-service
whatsapp-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/whatsapp-incoming-processor
whatsapp-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/whatsapp-service
- whatsapp-service plugin description

Docs:

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

Input validation video plugin

Docs:

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

Agents Manager API plugins

agents-manager plugins are components that provide different functionalities to agents-manager

Introduction

agents-manager is composed of plugins, which provide functionality to this component. Plugins work independently, the same way as a service in microservices oriented architecture: isolated, self-contained and without affecting other existing functionalities in the system.

From the different types of plugins, only Api plugins are available in agents-manager.

The following plugins are currently available in agents-manager. Certain plugins are used by all or some of the other plugins and others are specific for one capability.

agent-dispatcher-api plugin
This plugin manages request to Agent Dispatcher API.
development-api plugin
This plugin manages configuration in development environments. Only available in development environments.
configuration-service plugin
This plugin manages requests to Agent Configuration.
redis-connector-service plugin
This plugin manages requests to Redis.
session-service plugin
This plugin manages the sessions.
agent-deployment plugin, that provides deployment functionalities for agents within the agents-manager. Plugin currently deactivated.

Discover detailed information regarding the available plugins in the left index.

Plugins management

agents-manager uses the @architect/architect library for the management of plugins, so it is the architect library that is responsible for managing the dependencies injection in each module.

To create the architect application, agents-manager uses the PluginManager module (located in the modules/plugin-manager folder). This module starts as the rest of modules at the agents-manager start-up.

The PluginManager performs the following tasks:

It starts the architect application with the plugins defined in plugin-config.json file, located at the root of the agents-manager component.
It adds the core modules to the IOC context. See the section plugins modules.
It stores the information of each module defined in the plugins.

Apart from the agents-manager core environment variables, each plugin can define its own specific variables. Access the document agents-manager environment variables and find them in the section corresponding to your plugin.

Plugin basic structure

Currently, agents-manager uses @architect/architect library for plugins management.

A basic plugin must define at least:

A package.json file defining the library, like any other JavaScript library, with a plugin section defining which modules it consumes and supplies.
A source code file that defines the modules that it supplies (index.ts for example).

The structure of this basic plugin is as follows:

session-api
├── index.ts
└── package.json

Plugins modules

agents-manager currently adds one module that can be used by the different plugins. To use it, it is only necessary to add the package.json dependencies on plugin.consumes (like any other module/component).

configurationManager: Module with the agents-manager configuration information.
redisConnector: Module with the agents-manager Redis connection.

A plugin can provide one or more plugin modules and each plugin module can be of a different type. Each type of module is intended to add a specific functionality to agents-manager.

Docs:

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

Aura gateway API plugins

aura-gateway-api plugins are components that provide different functionalities to aura-gateway-api

Introduction

aura-gateway-api is composed of plugins, which provide functionality to this component. Plugins work independently, the same way as a service in microservices oriented architecture: isolated, self-contained and without affecting other existing functionalities in the system.

From the different types of plugins, only Api plugins are available in aura-gateway-api.

The following plugins are currently available in aura-gateway-api. From the different ATRIA capabilities that this component can manage, certain plugins are used by all or some of them and others are specific of one capability.

aura-generative-api plugin
This module manages request to external OpenAI APIs.
aura-generative-process-service plugin
This module manages the communication and data processing with external OpenAI APIs.
aura-nlp-resolution plugin
This module manages the request to NLP services.
aura-nlp-resolution-process-services plugin
This module manages the communication and data processing with external NLP services.
aura-development-api plugin
This module manages configuration in development environments. Only available in development environments.
aura-feedback-api plugin
This module manages requests to provide feedback about the generative and RAG services behavior.
aura-agents-api plugin
This module manages the communication with agents.
dapr-pubsub-service plugin This plugin allows the interaction with the Dapr PubSub Service.
aura-operations-api plugin
This module allows you to perform operations on now, currently launching the generateDB

Discover detailed information regarding the available plugins in the left index.

Plugins management

aura-gateway-api uses the @architect/architect library for the management of plugins, so it is the architect library that is responsible for managing the dependencies injection in each module.

To create the architect application, aura-gateway-api uses the PluginManager module (located in the modules/plugin-manager folder). This module starts as the rest of modules at the aura-gateway-api start-up.

The PluginManager performs the following tasks:

It starts the architect application with the plugins defined in plugin-config.json file, located at the root of the aura-gateway-api component.
It adds the core modules to the IOC context. See the section plugins modules.
It stores the information of each module defined in the plugins.

Apart from the aura-gateway-api core environment variables, each plugin can define its own specific variables. Access the document aura-gateway-api environment variables and find them in the section corresponding to your plugin.

Plugin basic structure

Currently, aura-gateway-api uses @architect/architect library for plugins management.

A basic plugin must define at least:

A package.json file defining the library, like any other JavaScript library, with a plugin section defining which modules it consumes and supplies.
A source code file that defines the modules that it supplies (index.ts for example).

The structure of this basic plugin is as follows:

session-api
├── index.ts
└── package.json

Plugins modules

aura-gateway-api currently adds one module that can be used by the different plugins. To use it, it is only necessary to add the package.json dependencies on plugin.consumes (like any other module/component).

configurationManager: Module with the aura-gateway-api configuration information.
redisConnector: Module with the aura-gateway-api Redis connection.

A plugin can provide one or more plugin modules and each plugin module can be of a different type. Each type of module is intended to add a specific functionality to aura-gateway-api.

Docs:

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

Aura bridge plugins

Aura bridge plugins are components that provide different functionalities to the bridge

Introduction

aura-bridge is composed of plugins, which provide functionality to the bridge. Plugins work independently, the same way as a service in a microservices oriented architecture: isolated, self-contained and without affecting other existing functionalities in the system.

The aura-bridge plugins system also allows an OB to generate new plugins and create an “ad hoc” aura-bridge, with the functionalities required and removing those which are not needed for the OB.

ℹ️ The practical process for the generation of plugins is included in develop a plugin and activate in aura-bridge.

Discover in the current documents detailed information regarding aura-bridge plugins:

Types of plugins

There are different types of plugins:

Api. REST services that perform specific tasks not associated with the communication with a channel.
Client. These plugins define clients that can be used to communicate with a channel. These clients are normally used by processor plugins.
Processor. Plugins in charge of communicating with a channel, transforming the message received from a source channel to a destination channel.
Service. Utility plugins to be used by the rest of plugins.

Plugins management

As indicated in the previous section, aura-bridge uses the library@architect/architect for the management of plugins, so it is the architect library that is responsible for managing the dependencies injection in each module.

To create the architect application, aura-bridge uses the PluginManager module (located in the modules/plugin-manager folder). This module starts as the rest of modules at the aura-bridge start-up.

The PluginManager performs the following tasks:

It starts the architect application with the plugins defined in plugin-config.json file, located at the root of the aura-bridge component.
It adds the core modules to the IOC context. See the section modules added by aura-bridge.
It stores the information of each module defined in the plugins.

An example to define aura-bridge-example-service plugin of the previous section is shown below:

/* file: plugin-config.json */
[
    "./lib/plugins/aura-bridge-example-service",
]

Currently, the plugins are in the src/plugins folder of aura-bridge, but in the future these plugins should be independent libraries and could be charged by library name (for example: @telefonica/aura-bridge-example-service).

Apart from the aura-bridge core environment variables, each plugin can define its own specific variables. Access the document Aura bridge environment variables and find them in the section corresponding to your plugin.

Plugin basic structure

Currently, aura-bridge uses @architect/architect library for plugins management.

A basic plugin must define at least:

A package.json file defining the library, like any other JavaScript library, with a plugin section defining which modules it consumes and supplies.
A source code file that defines the modules that it supplies (index.ts for example).

The structure of this basic plugin is as follows:

aura-bridge-example-service
├── index.ts
└── package.json

A couple of examples with the content of each file are included below:

/* file: index.ts */
import { PluginType, registerPlugin } from '@telefonica/aura-bridge-common';
import { v4 as uuidv4 } from 'uuid';
import { Services } from './example-consume-services';

export = registerPlugin([
    {
        type: PluginType.Service,       // Plugin service type
        name: 'exampleService',         // Name of the plugin service
        instance: {                     // [provides] Instance that provides the module
            getUniqueId() {
                return uuidv4();
            }
        },
        services: Services              // [consumes] Needed modules are added here
    }
]);

/* file: package.json */
{
    "name": "@telefonica/aura-bridge-example-service",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [
            "configurationManager"
        ],
        "provides": [
            "exampleService"
        ]
    }
}

The modules specified in the plugin.consumes field define the services that are needed by this plugin. The modules specified in the plugin.provides field define the modules that this plugin offered.

Plugins modules

aura-bridge currently adds three modules that can be used by the different plugins. To use them, it is only necessary to add the package.json dependencies on plugin.consumes (like any other module/component).

configurationManager: Module with the aura-bridge configuration information.
auraBridgeCache: Module to manage the aura-bridge cache.
prometheus: Service for metrics management.

A plugin can provide one or more plugin modules and each plugin module can be of a different type. Each type of module is intended to add a specific functionality to aura-bridge.

The existing types are defined in PluginType, which are described in the following sections.

export enum PluginType {
    Api = 'Api',
    Client = 'Client',
    Processor = 'Processor',
    Service = 'Service'
}

All plugins modules must follow the base Plugin interface:

export interface Plugin {
    /**
     * Plugin module name.
     */
    name: string;
    /**
     * Object where the services that plugin module consume will be injected (IOC).
     */
    services?: unknown;
    /**
     * Plugin module type.
     */
    type?: PluginType;
    /**
     * @hapi/joi schema definition with the variables used by the plugin module.
     */
    configuration?: { [key: string]: any; };
}

API plugin module

Use the aucli tool to generate the scaffolding of an API plugin: aucli bridge generate api

An API plugin module type mainly contains:

At least one source code file that defines the API plugin module and controllers for each of the operations specified in the swagger definition.
A package.json file defining the library, with a plugin section defining which modules it consumes and supplies.
A swagger.yaml file that contains a detailed description of the entire API defined by the plugin.

The basic structure for a API plugin module type is as follows:

aura-bridge-example-api
├── index.ts
├── package.json
└── swagger.yaml

A type API module must implement the PluginApi interface:

export interface PluginApi extends Plugin {
    /**
     * List of controllers (Express) defined by the plugin module.
     */
    controller: { [operationId: string]: PluginApiController | ((req: Request, res: Response) => Promise<void>) };
}

export interface PluginApiController {
    /**
     * Is directline processor?
     */
    isDirectlineProcessor?: boolean;
    /**
     * Channel type.
     */
    channelType?: BridgeType;
    /**
     * Express controller function.
     */
    controller: (req: Request, res: Response) => Promise<void>;
    /**
     * Custom error handler.
     */
    errorHandler?: (err: any, request: express.Request, response: express.Response, next: express.NextFunction) => void;
}

A couple of examples with the content of each file are included below:

/* file: index.ts */
import { PluginType, registerPlugin } from '@telefonica/aura-bridge-common';
import { Services } from './example-api-consume-services';

const controller = {
    hello: (req: Request, res: Response) => {
        res.send({ message: 'Hello from example api!' });
    }
}

export = registerPlugin([
    {
        type: PluginType.Api,           // Plugin module type
        name: 'exampleApi',             // Plugin module name
        controller,                     // Controllers definitions (linked to swagger operationId),
                                        // or it is possible to also use the PluginApiController interface
        services: Services,             // [consumes] Needed modules are added here
    }
]);

/* file: package.json */
{
    "name": "@telefonica/aura-bridge-example-api",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [ ],
        "provides": [
            "exampleApi"
        ]
    }
}

# file: swagger.yaml
openapi: 3.0.0
info:
  title: aura bridge example api
...
paths:
  /example/hello:
   get:
     operationId: hello             # Function name defined in "controller".
     x-router-controller: plugins   # It should always be "plugins".
     responses:
       '200':
         description: OK
         headers: { }

An API module can also define its own error handling and not use the default error handling defined in the bridge core.

Example:

public errorHandler(err: any, request: express.Request, response: express.Response, next: express.NextFunction) {
    const corr = (request as any).correlator;

    let status: number = 200;
    let message: string = 'Accepted request';

    if (err.statusCode === 401) {
        status = err.statusCode;
        message = 'Unauthorized request';
    }

    // An error in swagger validation is simply logged as a warning
    if (err.failedValidation) {
        logger.warning({
            msg: `Bad request on swagger validation. The first error message was: ${err?.validationResult[0]?.message}`,
            stck: err.validationResult, corr,
            step: AuraBridgeStep.Controller
        });
    }

    response.status(status).send({ code: status, message });
}

Client module

Use the aucli tool to generate the scaffolding of a client module: aucli bridge generate client

A client module type mainly contains:

At least one source code file that defines the client module and the client itself.
A package.json file defining the library, with a plugin section defining which modules it consumes and supplies.

The basic structure for a client module type is as follows:

aura-bridge-example-client
├── index.ts
├── package.json

A type client module must implement the PluginClient interface:

export interface PluginClient extends Plugin {
    /**
     * Client instance.
     */
    instance?: any;
    /**
     * Returns a client instance if it must be initiated asynchronously.
     */
    getInstance?: () => any;
}

The instance field or the getInstance method should be used to obtain the client, but not both. If the client does not need to be initiated asynchronously, the client definition in the instance field is the preferred option. If it is necessary to asynchronously start the client, the getInstance method must be used.

A couple of examples with the content of each file are included below:

/* file: index.ts */
import { PluginType, registerPlugin } from '@telefonica/aura-bridge-common';
import { Services } from './example-consume-services';
import { ExampleClient } from './example-client';

export = registerPlugin([
    {
        type: PluginType.Client,
        name: 'ExampleClient',
        instance: new ExampleClient(),
        services: Services
    }
]);

/* file: package.json */
{
    "name": "@telefonica/aura-bridge-example-client",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [
            "configurationManager"
        ],
        "provides": [
            "ExampleClient"
        ]
    }
}

/* file: example-client.ts */
import { AuraBridgeClient, AuraBridgeRequestInfo, SendMessageOptions } from '@telefonica/aura-bridge-common';
import { AuraLogger } from '@telefonica/aura-logging';
import { Services } from './example-consume-services';

const logger: AuraLogger.AuraBusEmitter = new AuraLogger.AuraBusEmitter('ExampleClient');

export class ExampleClient extends AuraBridgeClient {
    public constructor() {
        super('ExampleClient', Services.configurationManager.environmentConfiguration);
    }

    public async sendMessage(message: any, options: SendMessageOptions): Promise<void> {
        const { corr }: Partial<AuraBridgeRequestInfo> = options.requestInfo;
        // TODO: Implement the message sending logic here.
    }
}

A basic client should only extend the AuraBridgeClient class and implement the sendMessage method. The client can define any other method, but the sendMessage method will be used by the processors to send a message to a destination.

If the client uses the OAuth protocol, it is possible to add the OpenID authorization information to the client and automatically update the access token for the communication. To make use of this functionality, it is necessary that the new client extends from AuraBridgeClientOAuthTokens class instead of AuraBridgeClient class:

/* file: example-client.ts */
import { AuraBridgeClientOAuthTokens, AuraBridgeRequestInfo, SendMessageOptions } from '@telefonica/aura-bridge-common';
import { AuraLogger } from '@telefonica/aura-logging';
import { Services } from './example-consume-services';

const logger: AuraLogger.AuraBusEmitter = new AuraLogger.AuraBusEmitter('ExampleClient');

export class ExampleClient extends AuraBridgeClientOAuthTokens {
    public constructor() {
        super(
            'ExampleClient',
            Services.configurationManager.environmentConfiguration,
            [] // TODO: Add list ClientOAuthInformation here
        );
    }

    public async init(): Promise<void> {
        await this.refreshTokens();    // <-- It is responsible for updating the tokens before it expire.
    }

    public async sendMessage(message: any, options: SendMessageOptions): Promise<void> {
        const { corr }: Partial<AuraBridgeRequestInfo> = options.requestInfo;
        // TODO: Implement the message sending logic here.
    }
}

In addition to the refreshTokens method, the AuraBridgeClientOAuthTokens class defines the following methods:

addOpenIdClients: Add new clients to the list to update your tokens.
getTokenByClientId: Get token by client id.
stopRefreshTokens: Stop refresh client tokens.

Processor module

Use the aucli tool to generate the scaffolding of a processor module: aucli bridge generate processor.

As a general rule, a processor is responsible for converting an input message (from a “source” channel) to an output message (that will be sent to a “destination” channel).

Processor flow

To help with the task of generating a processor (in addition to the aucli tool) , the aura-bridge-common library provides the AuraBridgeFlow class that allows to define the converter and the client that will be used to convert and send the incoming message to the destination in a simple and declarative way.

const flow: BridgeFlow = {
    source: {                               // Source from where the request is initiated
        type: BridgeNodeType.Directline
    },
    destination: {                          // Destination where the request will be redirected
        type: BridgeNodeType.TestModel,
        converter: DirectlineToTestModelConverter,
        client: services.testModelClient,
        clientOptions: { queue: { bridgeFlowName: directlineToTestModelFlow.name } }
    },
    onError: {
        // ...
    }
};

In the same way, in case an exception occurs, it is possible to define the list of channels that should be informed.

const flow: BridgeFlow = {
    source: {
        // ...
    },
    destination: {
        // ...
    },
    onError: {                          // How and which channels should be informed on exception
        destinations: [
            {
                type: BridgeNodeType.TestModel,
                converter: ErrorToTestModelApiConverter,
                client: services.testModelClient,
                decode: TestModelDestinationResponseError
            },
            {
                type: BridgeNodeType.Directline,
                converter: ErrorToDirectlineEventConverter,
                client: services.directlineClient,
                decode: directlineDestinationResponseError
            }
        ]
    }
};

Declaring a destination

The destination field must follow the interface BridgeDestination.

export interface BridgeDestination extends BridgeNode {
    /**
     * Client instance that will be used to send the message to the destination
     */
    client: AuraBridgeClient;
    /**
     * Client options. System to send the message used: queue, retries, etc
     */
    clientOptions?: SendMessageClientOptions;
    /**
     * Converter to use
     */
    converter?: AuraBridgeMessageConverter;
    /**
     * Relationship between exception and response error
     */
    decode?: ExceptionResponseError[];
    /**
     * Optional condition for a destination to be executed
     */
    condition?: (error?: Error, lastError?: Error, requestInfo?: AuraBridgeRequestInfo, message?: any) => boolean;
}

The process to send a message using the previous definition is shown below:

If the indicated condition is true, the message will be converted (using converter) and sent (using client with options defined in clientOptions field). If during the process there is an error that throws an exception, all the destinations defined in onError.destinations field will be executed in order in the same way.

The following diagram shows the execution sequence:

flowchart LR
    subgraph source
        A[Message]
    end
    subgraph destination
    direction LR
        A[Message] --> Check{check condition}
        Check -->|True| Converter[Converter]
        Check -->|False| End[end]
        Converter --> |Converted message| Client[Client]
        help[Send message using clientOptions]
    end

When an exception is thrown, all the destinations defined in onError.Destinations are processed, passing both the original message and the exception occurred:

flowchart LR
    subgraph onError information
        Message[Message]
        Exception[Exception message]
    end
    subgraph onError destinations
    direction LR
        Message[Message] --> CheckOnError{check condition}
        Exception --> CheckOnError{check condition}
        CheckOnError -->|True| ConverterOnError[Converter]
        CheckOnError -->|False| EndOnError[Next destination]
        ConverterOnError --> |Converted message| ClientOnError[Client]
        helpOnError[Send message using clientOptions]
    end

Sending a specific message on exception

When an exception occurred during the execution of a flow (BridgeFlow), it is possible to decode the exception in a specific error message for each destination defined in onError.destinations field.

The list that relates the exception with each message is added in the field decode of BridgeDestination. Each of these elements must implement the following interface:

/**
 * @interface ExceptionResponseError
 */
export interface ExceptionResponseError {
    /**
     * Name error from exception
     */
    name?: string;
    /**
     * Message to user key
     */
    messageToUserKey?: string;
    /**
     * Error status from exception
     */
    status?: number;
    /**
     * Error response code
     */
    responseCode?: string;
    /**
     * Response error information
     */
    response: ResponseError;
}

In the following code, the example shows how to send a message with status 500 and message key bridge:error.transform when an error in the converter has occurred:

const exampleResponseError: ExceptionResponseError[] = [
    {
        name: AuraBridgeConverterError.name,
        response: {
            status: StatusCodes.INTERNAL_SERVER_ERROR,
            description: 'Internal bridge error converting input message to output format',
            messageToUserKey: 'bridge:error.transform'
        }
    }
];

Basic structure of the processor module

The processor module type mainly contains:

At least one source code file that defines the processor plugin module and controllers for each of the operations specified in the swagger definition.
A package.json file defining the library, with a plugin section defining which modules it consumes and supplies.
A swagger.yaml file that contains a detailed description of the entire API defined by the plugin.
A source code file that defines the BridgeFlow.
A source code file that defines the AuraBridgeMessageConverter.

The basic structure for a processor plugin module type is as follows:

aura-bridge-example-processor
├── index.ts            # Processor plugin module and controller
├── converter.ts        # Converter (AuraBridgeMessageConverter)
├── flow.ts             # Flow (BridgeFlow)
├── package.json
└── swagger.yaml        # Api definition

A type processor module must implement the PluginProcessor interface:

export interface PluginProcessor extends PluginApi {
    /**
     * List of defined flows.
     */
    flows: BridgeFlow[];
}

In addition to the definition of flows, the same requirements as for an API plugin type are applied.

If the processor plugin must manage the aura-groot response (using DirectLine) for a channel type, it is possible to use the PluginApiController interface to define the controller.

For example:

/* Manage aura-groot response messages for whatsapp channels */
postDirectlineConversationsActivities: {
    isDirectlineProcessor: true,                            // Indicates if it is a directline processor
    channelType: BridgeType.Whatsapp,                      // Channel type
    controller: directlineWhatsappController.controller     // Controller definition
}

In this way, all the messages sent for the WhatsApp type channel to /aura-services/{channelName}/v3/conversations/{conversationId}/activities and /aura-services/{channelName}/v3/conversations/{conversationId}/activities/{messageId} endpoints will be managed by the defined controller.

⚠️ These endpoints do not need to be defined in the plugin swagger, since they are supplied by the aura-bridge core.

A couple of examples with the content of each file are shown below:

/* file: index.ts */
/* description: Using controller function */

import ...

const controller = {
    exampleNotification: async (req: Request, res: Response) => {
        const env = Services.configurationManager.environmentConfiguration;
        res.status(200).send();
        await AuraBridgeFlow.process(exampleToDirectlineFlow(Services), getRequestInformation(req, env), req.body);
    }
};

export = registerPlugin([
    {
        type: PluginType.Processor,         // Plugin module type
        name: 'exampleProcessor',           // Plugin module name
        controller,                         // Controllers definitions (linked to swagger operationId)
        flows: [exampleToDirectlineFlow],   // Flows
        services: Services                  // [consumes] Needed modules are added here
    }
]);

/* file: index.ts */
/* description: Using PluginApiController interface */

import ...

const controller = {
    // This plugin manages all the requests from aura-groot for the testModel channel type destination
    postDirectlineConversationsActivities: {
        isDirectlineProcessor: true,
        channelType: BridgeType.TestModel,
        controller:  async (req: Request, res: Response) => {
            ...
        }
    }
};

export = registerPlugin([
    {
        type: PluginType.Processor,         // Plugin module type
        name: 'directlineTestModelProcessor',    // Plugin module name
        controller,                         // Controllers definitions (linked to swagger operationId)
        flows: [exampleToDirectlineFlow],   // Flows
        services: Services                  // [consumes] Needed modules are added here
    }
]);

/* file: converter.ts */
import ...

export class ExampleConverter extends AuraBridgeMessageConverter {
    public static async message(incomingMessage: ExampleMessage) {
        // Logic of the converter here
    }
}

/* file: flow.ts */
/**
 * Flow: example to directline.
 *
 *
 * [Example] ─────> (bridge) ───(ok)──────> [Directline]
 *
 * @returns {BridgeFlow} flow
 */
export function asyncCallbackToDirectlineFlow(services: any): BridgeFlow {
    const flow: BridgeFlow = {
        source: {
            type: BridgeNodeType.Example
        },
        destination: {
            type: BridgeNodeType.Directline,
            converter: ExampleConverter,
            client: services.directlineClient,
            clientOptions: { retries: {} }
        },
        onError: {
            destinations: [
                ...
            ]
        }
    };

    return flow;
}

/* file: package.json */
{
    "name": "@telefonica/aura-bridge-example-processor",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [ ... ],
        "provides": [
            "exampleProcessor"
        ]
    }
}

# file: swagger.yaml
openapi: 3.0.0
info:
  title: aura bridge example processor
...
paths:
  /example/notification:
   get:
     operationId: exampleNotification       # Function name defined in "controller".
     x-router-controller: plugins           # It should always be "plugins".
     responses:
       '200':
         description: OK
         headers: { }

Service module

Use the aucli tool to generate the scaffolding of a service plugin: aucli bridge generate service

A service plugin module is a set of utilities that can be reused by the rest of plugins and mainly contains:

At least one source code file that defines the service plugin module and the service itself.
A package.json file defining the library, with a plugin section defining that modules consume and supplies.

The basic structure for a service plugin module type is as follows:

aura-bridge-example-service
├── index.ts
└── package.json

A type service module must implement the PluginService interface:

export interface PluginService extends Plugin {
    /**
     * Service instance.
     */
    instance?: any;
    /**
     * Returns a service instance if it must be initiated asynchronously.
     */
    getInstance?: () => any;
}

The instance field or the getInstance method should be used to obtain the service, but not both. If the service does not need to be initiated asynchronously, the service definition in the instance field is the preferred option. If it is necessary to asynchronously start the service, the getInstance method must be used.

A couple of examples with the content of each file are shown below:

/* file: index.ts */
import { PluginType, registerPlugin } from '@telefonica/aura-bridge-common';
...

const exampleService = {
    isActionMessage: (message: ExampleMesageModel) => {
        return !!message?.channelData?.customData?.action;
    }
}

export = registerPlugin([
    {
        type: PluginType.Service,       // Plugin module type
        name: 'exampleService',         // Plugin module name
        instance: exampleService,       // Service instance
        services: Services              // [consumes] Needed modules are added here
    }
]);

/* file: package.json */
{
    "name": "@telefonica/aura-bridge-example-service",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [ ],
        "provides": [
            "exampleService"
        ]
    }
}

Plugins in specific channels

There is a relationship between a channel and the different plugins that give full support to the channel in aura-bridge. This is because plugins can supply: services, incoming messages management, output messages management, etc.

Therefore, to support a channel like WhatsApp, several plugins may be necessary and knowing that relationship allows to enable/disable the support to the complete channel in aura-bridge correctly.

Plugins for WhatsApp channel

Plugin	Dependencies	Core dependencies
whatsapp-incoming-processor	whatsapp-service, directline-service	configurationManager, prometheus
directline-whatsapp-processor	whatsapp-service, directline-service	configurationManager
directline-whatsapp-service	whatsapp-service, directline-service	configurationManager
whatsapp-service		configurationManager, prometheus
directline-service		configurationManager, auraBridgeCache

How to disable the WhatsApp channel

To disable the WhatsApp channel, it is necessary to take into account the following:

The whatsapp-incoming-processor and directline-whatsapp-processor plugins are not dependent on any other plugin, so they can be removed from the plugin-config.json file.
The directline-whatsapp-service, whatsapp-service and directline-service plugins can be used by other plugins and can only be removed if they are not needed.

Plugins for async-callback

Plugin	Dependencies	Core dependencies
async-callback-directline-processor	directline-service	configurationManager, prometheus

How to disable the async-callback functionality

The async-callback-directline-processor plugin is not dependent on any other plugin, so it can be removed from the plugin-config.json file to completely disable the async-callback functionality.

Plugins for Genesys

Plugin	Dependencies	Core dependencies
genesys-directline-processor	directline-service	configurationManager

How to disable the Genesys functionality

The genesys-directline-processor plugin is not dependent on any other plugin, so it can be removed from the plugin-config.json file to completely disable the Genesys functionality.

Docs:

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

Aura mocks server plugins

aura-mocks-server plugins are components that provide different functionalities to this component

Introduction

aura-mocks-server is composed of plugins, which provide functionality to the tool. Plugins work independently, the same way as a service in a microservices oriented architecture: isolated, self-contained and without affecting other existing functionality in the system.

Discover in the current documents detailed information regarding aura-mocks-server plugins:

Descriptive information regarding plugins: types of plugins, plugins management, plugin basic structure, plugins modules
Available plugins in the aura-mocks-server global plugins catalog

Global plugins catalog

The available global plugins of aura-mocks-server are included in the Github global plugins repository.

Aura Platform Team is progressively documenting each plugin within the current documents. Check the already documented ones in the left sidebar index.

Types of plugins

There are different types of plugins:

Api. REST services that perform specific tasks not associated with the communication with a channel.
Client. These plugins define clients that can be used to communicate with a channel. These clients are normally used by processor plugins.
Processor. Plugins in charge of communicating with a channel, transforming the message received from a source channel to a destination channel.
Service. Utility plugins to be used by the rest of plugins.

Plugins management

As indicated in the previous section, aura-mocks-server uses the library@architect/architect for the management of plugins, so it is the architect library that is responsible for managing the dependencies injection in each module.

To create the architect application, aura-mocks-server uses the PluginManager module (located in the modules/plugin-manager folder). This module starts as the rest of modules at the aura-mocks-server start-up.

The PluginManager performs the following tasks:

It starts the architect application with the plugins defined in plugin-config.json file, located at the root of the aura-mocks-server component.
It adds the core modules to the IOC context. See the section modules added by aura-mocks-server.
It stores the information of each module defined in the plugins.

An example to define aura-mocks-server-example-service plugin of the previous section is shown below:

/* file: plugin-config.json */
[
    "./lib/plugins/aura-mocks-server-example-service",
]

Currently, the plugins are in the src/plugins folder of aura-mocks-server, but in the future these plugins should be independent libraries and could be charged by library name (for example: @telefonica/aura-mocks-server-example-service).

Apart from the aura-mocks-server core environment variables, each plugin can define its own specific variables.

Plugin basic structure

Currently, aura-mocks-server uses @architect/architect library for plugins management.

A basic plugin must define at least:

A package.json file defining the library, like any other JavaScript library, with a plugin section defining which modules it consumes and supplies.
A source code file that defines the modules that it supplies (index.ts for example).

The structure of this basic plugin is as follows:

aura-mocks-server-example-service
├── index.ts
└── package.json

A couple of examples with the content of each file are included below:

/* file: index.ts */
import { PluginType, registerPlugin } from '@telefonica/xxxx-server-common';
import { v4 as uuidv4 } from 'uuid';
import { Services } from './example-consume-services';

export = registerPlugin([
    {
        type: PluginType.Service,       // Plugin service type
        name: 'exampleService',         // Name of the plugin service
        instance: {                     // [provides] Instance that provides the module
            getUniqueId() {
                return uuidv4();
            }
        },
        services: Services              // [consumes] Needed modules are added here
    }
]);

/* file: package.json */
{
    "name": "@telefonica/aura-mocks-server-example-service",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [
            "configurationManager"
        ],
        "provides": [
            "exampleService"
        ]
    }
}

Plugins modules

aura-mocks-server currently adds three modules that can be used by the different plugins. To use them, it is only necessary to add the package.json dependencies on plugin.consumes (like any other module/component).

configurationManager: Module with the aura-mocks-server configuration information.
auramocks-serverCache: Module to manage the aura-mocks-server cache.
prometheus: Service for metrics management.

A plugin can provide one or more plugin modules and each plugin module can be of a different type. Each type of module is intended to add a specific functionality to aura-mocks-server.

The existing types are defined in PluginType, which are described in the following sections.

export enum PluginType {
    Api = 'Api',
    Client = 'Client',
    Processor = 'Processor',
    Service = 'Service'
}

Docs:

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

aura-mocks-administration-api plugin

Plugin that returns Aura Mocks Server data.

Description

The aura-mocks-administration-api plugin returns data info from Aura Mocks Server, such as app, cache or plugins.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-administration-api

This is part of aura-mocks-server project.

Administration Endpoints API

Enpoint	Method	Group	description
/administration/heapStatistics	GET	App	Get heap statistics
/administration/heapSnapshot	GET	App	Get heap snapshot
/administration/cache	GET	Cache	Get cache
/administration/cache/stats	GET	Cache	Get cache stats
/administration/plugins	GET	Plugins	Get plugins

GET: /administration/heapStatistics

Return Aura Mocks Server data info.

{
    "aura-mocks-server-1.0.0": {...}
}

GET: /administration/heapSnapshot

Generate and upload snapshot to Azure Storage.

{
    "status": 200
}

GET: /administration/cache

Return cache data info.

{
    "info": {
        "Server": {...},
        "Clients": {...},
        "Memory": {...},
        "Persistence": {...},
        "Stats": {...},
        "Replication": {...},
        "CPU": {...},
        "Modules": {...},
        "Errorstats": {...},
        "Cluster": {...},
        "Keyspace": {...}
    }
}

GET: /administration/cache/stats

Return cache stats data.

{
    "stats": {...}
}

GET: /administration/plugins

Return plugins data info.

[
    {
        "name": "redisStorageService",
        "pkg": "@telefonica/aura-redis-service",
        "version": "1.0.0",
        "package": "aura-mocks-redis-service",
        "consumes": [
            "configurationManager"
        ],
        "provides": [
            "redisStorageService"
        ]
    }
]

Docs:

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

Agent Deployment Plugin

The agent-deployment plugin is a component that provides deployment functionalities for agents within the agents-manager.

Introduction

The agent-deployment plugin is designed to manage the deployment of agents in a flexible and scalable manner. It allows multiple agents to be deployed within a single microservice, and the same agent can be deployed with different configurations across different microservices or within the same microservice.

Plugin Management

The agent-deployment plugin uses the @architect/architect library for managing dependencies and plugin lifecycle. The PluginManager module, located in the modules/plugin-manager folder, is responsible for initializing the plugin at the start-up of the agents-manager.

The PluginManager performs the following tasks:

Initializes the architect application with the plugins defined in the plugin-config.json file, located at the root of the agents-manager component.
Adds core modules to the IOC context. See the section plugin modules.
Stores information about each module defined in the plugins.

Plugin Basic Structure

A basic plugin must define at least:

A package.json file defining the library, with a plugin section specifying which modules it consumes and supplies.
A source code file that defines the modules it supplies (index.ts for example).

The structure of this basic plugin is as follows:

agent-deployment-plugin
├── index.ts
└── package.json

Example `index.ts`

import { PluginType, registerPlugin } from '@telefonica/agents-manager-common';
import { Services } from './deployment-consume-services';

export = registerPlugin([
    {
        type: PluginType.Service,
        name: 'agentDeploymentService',
        instance: {
            deployAgent(agentConfig) {
                // Implementation for deploying an agent
            }
        },
        services: Services
    }
]);

Example `package.json`

{
    "name": "@telefonica/agent-deployment-plugin",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [
            "configurationManager"
        ],
        "provides": [
            "agentDeploymentService"
        ]
    }
}

Plugin Modules

The agent-deployment plugin can utilize the following modules provided by the agents-manager:

configurationManager: Module with the agents-manager configuration information.
redisConnector: Module with the agents-manager Redis connection.

A plugin can provide one or more plugin modules, and each plugin module can be of a different type. Each type of module is intended to add specific functionality to the agents-manager.

Docs:

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

aura-mocks-async-callback-api plugin

Plugin that mocks asynchronous notification message

Description

The aura-mocks-async-callback-api plugin simulates aura-bridge asynchronous notification message for asynchronous API requests, both internal, such as file-manager or external, such as technical-problems-api in Kernel. It also adds several useful endpoints for the QA team and performance testing.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-async-callback-api

This is part of aura-mocks-server project.

Endpoints API

Enpoint	Method	Group	description
/async-callback/notifications	GET	Async Callback	Get notifications
/async-callback/notifications	DELETE	Async Callback	Delete notifications
/async-callback/notifications	POST	Async Callback	Send notification

GET: /async-callback/notifications

Get message by messageCorrelator. The query param messageCorrelator is mandatory.

DELETE: /async-callback/notifications

Delete message by messageCorrelator. The query param messageCorrelator is mandatory.

POST: /async-callback/notifications

Add new asynchronous notification message

{
    "payload": {...},
    "creation_date": "2019-08-08T15:19:48.259Z",
    "user_id": "9a47b037-825f-4ae7-bf55-6290efd5d036"
}

Docs:

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

aura-generative-process-service plugin

Description of the aura-generative-process-service plugin

Introduction

The aura-generative-process-service plugin manages the communication with atria-model-gateway to allow applications to communicate with LLMs.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
applicationConfiguration	PluginType.Service	Configuration of applications

Provides components (IOC)

Name	Type	Description
generativeProcessService	PluginType.Service	Send data to model-gw and process the response

Docs:

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

aura-mocks-auraline-api plugin

Plugin that mocks Auraline.

Description

The aura-mocks-auraline-api plugin simulates aura-bridge for aura-bot Auraline callbacks and adds several useful endpoints for the QA Team and performance testing.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-auraline-api

This is part of aura-mocks-server project.

Endpoints API

Enpoint	Method	Group	description
/auraline/v1/activities	GET	Auraline	Get activities
/auraline/v1/activities	DELETE	Auraline	Delete activities
/auraline/v1/conversations/:conversationId/activities/:activityId	POST	Auraline	Add activities
/auraline/v1/conversations/:conversationId/activities	DELETE	Auraline	Delete activities

GET: /auraline/v1/activities

Return activities by conversationId.

Query params:

Name	Type	Description	Mandatory
conversationId	string	Conversation id	True
retries	integer	Number of retries	False
timeBetweenRetries	integer	ms between retries	False

DELETE: /auraline/v1/activities

Delete activities by conversationId.

Query params:

Name	Type	Description	Mandatory
conversationId	string	Conversation id	True

POST: /auraline/v1/conversations/:conversationId/activities/:activityId

Push new Auraline activity for conversationId

DELETE: /auraline/v1/conversations/:conversationId/activities

Delete Auraline activities by conversationId

Docs:

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

auraline-conversation-api plugin

Technical description of auraline-conversation-api plugin

Introduction

auraline-conversation-api plugin allows you to generate conversation identifiers together with an associated token to be able to communicate through the new Auraline service. This service works similarly to Microsoft Direct Line.

It is mandatory to load this plugin if any channel wants to communicate with aura-bot through Auraline.

Based on official Direct Line API 3.0

Open a new conversation

Before establishing a communication between a client and aura-bot through the Auraline channel, it is necessary to obtain a conversation ID and a token associated to it. This token will be used as APIKey to send messages to the user together with the conversation ID created.

HTTP
POST https://bridge-url.com/aura-services/v1/auraline/conversations
Authorization: APIKEY [Secret]

Conversation Response Model (Create or Update Token)

Property	Type	Description
conversationId	string	The identification of conversation created or updated (refresh token).
token	string	Token generated for conversation. It is temporary and can be refreshed. Use with “APIKEY” string in the Authorization HTTP header.
expires_in	number	Time in seconds for the duration of the token. If you want to refresh it, it must be done before this time has elapsed. It will be set based on the value of AURALINE_CONVERSATION_EXPIRATION_TIME

The following snippets provide an example of the start conversation request and response.

Request

HTTP
POST https://bridge-url.com/aura-services/v1/auraline/conversations
Authorization: APIKEY iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

Response

HTTP/1.1 201 Created
[other headers]
BODY
{
  "conversationId": "X7CZj0LdjAPGfiCpg4Fv",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800,
}

Refresh a Conversation Token

A conversation token can be refreshed an unlimited number of times, as long as it has not expired, as an expired token cannot be refreshed.

To refresh a conversation token, issue this request:

HTTP
POST https://bridge-url.com/aura-services/v1/auraline/conversations/{conversationid}/refresh
Authorization: APIKEY [TOKEN_TO_BE_REFRESHED]

The following snippets provide an example of the Refresh Token request and response.

Request

HTTP
POST https://bridge-url.com/aura-services/v1/auraline/conversations/X7CZj0LdjAPGfiCpg4Fv/refresh
Authorization: APIKEY RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

Response

If the request is successful, the response contains:
- A new token that is valid for the same conversation as the previous token.
- An expires_in value that indicates the number of seconds until the new token expires.
For the new token to remain useful, you must refresh the token before it expires:
```
HTTP
HTTP/1.1 200 OK
[other headers]
BODY
{
  "conversationId": "X7CZj0LdjAPGfiCpg4Fv",
  "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}
```

Docs:

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

auraline-incoming-processor plugin

Technical description of auraline-incoming-processor plugin

Introduction

This plugin receives requests and transforms them to Auraline format to send them to aura-groot.

The specific environment variables for this plugin are located at auraline-incoming-processor plugin configuration.

Consumes components (IOC)

Name	Type	Description
auralineClient	PluginType.Service	Auraline client
configurationManager	PluginType.Service	Configuration manager
directlineClient	PluginType.Service	DirectLine client
directlineService	PluginType.Service	Services and utilities for Directline channel

Provides components (IOC)

Name	Type	Description
auraline-directline-processor	PluginType.Processor	Manage requests
auraline-status-processor	PluginType.Processor	Manage status

Controller

This plugin sets the endpoints it supports.

Operation id	Path	Description
postAuralineMessages	/aura-services/v1/auraline/conversations/{conversationId}/activities	Manage the messages sent
postAuralineStatus	/aura-services/v1/auraline/conversations/{conversationId}/activities/{activityId}/status	Manage the status

auraline-directline-processor flow definition

To process a message, the auraline-directline-processor uses AuraBridgeFlow with the following definition:

    const flow: BridgeFlow = {
        name: 'auralineToDirectlineFlow',
        source: {
            type: BridgeNodeType.Auraline
        },
        destination: {
            type: BridgeNodeType.Directline,
            converter: AuralineToDirectlineConverter,
            client: services.directlineClient,
            clientOptions: { retries: {} }
        },
        onError: {
            destinations: [
                {
                    type: BridgeNodeType.Auraline,
                    converter: AuralineToAuralineApiConverter,
                    client: services.auralineClient,
                    decode: auralineDirectlineResponseError
                },
                {
                    type: BridgeNodeType.Directline,
                    converter: AuralineToDirectlineEventConverter,
                    client: services.directlineClient
                }
            ]
        }
    };

According to the flow definition, AuraBridgeFlow tries to process, convert and send (using retries) the message to aura-groot using the DirectLine client.

If some type of error occurs during this process, an event message will be sent to aura-groot and client with the error information.

flowchart LR
    subgraph Flow
        direction LR
        B(Controller) --> C(Converter)
    end
    A(Client) -->|message| Flow
    Flow -->|ok| D(Bot Directline)
    Flow -->|error| E(Bot Directline Event)
    Flow -->|error| F(Client message)

auraline-directline-processor message conversion

The plugin uses two converters to transform messages to DirectLine format: AuralineToDirectlineConverter and AuralineToDirectlineEventConverter.

AuralineToDirectlineConverter

Main converter, in charge of transforming messages to DirectLine format messages using the directline-message-factory-v3 service of directline-service plugin.

AuralineToDirectlineEventConverter

It makes the conversion to a DirectLine event message if an error in the process has occurred.

Auraline status controller

This controller handles Auraline status requests and validate the APIKey fields. After that, it returns the status and if there is not an error, it passes the message to Auraline status processor.

Auraline status processor

This processor handles the status, deletes the message in queues and log errors if received.

Docs:

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

Aura Push send feedback service

Description of Aura Push send feedback service

Description

aurapush-sendfeedback-service plugin contains the services and utilities to send information to the aura-push service.

To send this information an event consumer is used: aurapush-sendfeedback-consumer. This consumer listens for the following events:

whatsapp.ackMessageReceived: Event emitted when a new ack message is received.
core.flow.error.directlineToWhatsappFlow: Event emitted when an error occurs during sending a message from Direct Line to WhatsApp.

sequenceDiagram  
    alt whatsapp.ackMessageReceived
        AuraPushFeedbackConsumer->>+onAckMessageReceived: ACK
    end
    alt core.flow.error.directlineToWhatsappFlow
        AuraPushFeedbackConsumer->>+onCoreErrorDirectlineToWhatsappFlow: Core flow error
    end
        onAckMessageReceived->>+auraPushFeedbackClient: ACK and path
        onCoreErrorDirectlineToWhatsappFlow->>+auraPushFeedbackClient: Core flow error and path
        auraPushFeedbackClient->>+Aura Push: Message

⚠️ For Brazil OB, the aurapush-sendfeedback-service plugin requires a specific configuration in the installer aurak8s.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
eventService	PluginType.Service	Bridge event management service

Provides components (IOC)

Name	Type	Description
auraPushSendFeedbackService	PluginType.Service	Services and utilities for AuraPush send message feedback
auraPushFeedbackClient	PluginType.Service	Aura push feedback client

Docs:

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

aura-mocks-bot-api plugin

Plugin that mocks aura-bot

Description

The aura-mocks-bot-api plugin simulates Directline requests for aura-groot with several useful endpoints for the QA team and performance testing.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-bot-api

This is part of aura-mocks-server project.

Endpoints API

Enpoint	Method	Group	description
/api/messages	POST	bot	Send messages: send messages. Optional param `reply=true` to send response with Directline format to aura-bridge
/api/messages	GET	bot	Get messages
/api/messages	DELETE	bot	Delete messages

GET: /api/messages

Get message by to. The query param to is mandatory.

DELETE: /api/messages

Delete message by to. The query param to is mandatory.

POST: /api/messages

Add new aura-bot message.

{
    "type": "message",
    "id": "IiKY7bzb1Pd5VdtN4FZKmB-a|0000000",
    "timestamp": "2021-01-28T16:02:49.6587305Z",
    "serviceUrl": "https://directline.botframework.com/",
    "channelId": "directline",
    "from": {
    "id": "ca9961f9-c6f0-3acd-5c72-ce2719f43ec9"
    },
    "conversation": {
    "id": "IiKY7bzb1Pd5VdtN4FZKmB-a"
    },
    "textFormat": "plain",
    "locale": "es-ES",
    "channelData": {
    "auraCommand": {
        "type": "suggestion",
        "value": {
        "intent": "intent.common.greetings"
        }
    }
}

Docs:

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

aura-mocks-data-store-api plugin

Plugin that mocks data-store

Description

The aura-mocks-data-store-api plugin simulates an API to manage documents in a generic way with several useful endpoints for the QA team and performance testing.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-data-store-api

This is part of aura-mocks-server project.

Endpoints API

Defines an API to manage documents in a generic way.

Enpoint	Method	Group	description
/data-store/sorted/:collection	POST	Data Store	Save document
/data-store/sorted/:collection	GET	Data Store	Find documents
/data-store/sorted/:collection/:id	GET	Data Store	Get document in collection by id

GET: /data-store/sorted/:collection

Get message by timestamp. The query param timestamp is mandatory.

DELETE: /data-store/sorted/:collection

Delete message by timestamp. The query param timestamp is mandatory.

POST: /data-store/sorted/:collection

Add new collection document.

Docs:

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

Develop a plugin and activate it in Aura Bridge

Guidelines for the generation of a new plugin and its activation/deactivation in Aura Bridge

Introduction

The process for the generation of a plugin and its activation or deletion in aura-bridge includes the following steps:

Plugin development

Install aura-development-cli (aucli)

To generate a new plugin, use aucli, a set of tools available in the “Command Line Interface” format to help you with development and testing.

How to use aucli?

Access the “help” command:

$ aucli bridge -h

Usage: aucli bridge [options] [command]

tasks associated with 'bridge' commands

Options:
  -h, --help      display help for command

Commands:
  generate        tasks associated with 'generate' commands
  help [command]  display help for command

Execute the following command in the aura-bridge project path:

$ aucli bridge generate plugin

✔ Whats the origin of the process? (ex.: Directline, Whatsapp, ...)? · channel1
✔ Whats the destination of the process? (ex.: Directline, Whatsapp, ...)? · channel2
✔ The name of processor is correct? (y/N) · true

The following files will be generated in aura-bridge:

added: src/plugins/channel1-channel2-processor/channel1-channel2-consume-services.ts
added: src/plugins/channel1-channel2-processor/channel1-channel2-controller.ts
added: src/plugins/channel1-channel2-processor/channel1-to-channel2-converter.ts
added: src/plugins/channel1-channel2-processor/error-to-channel2-api-converter.ts
added: src/plugins/channel1-channel2-processor/channel1-channel2-flow.ts
added: src/plugins/channel1-channel2-processor/index.ts
added: src/plugins/channel1-channel2-processor/package.json
added: src/plugins/channel1-channel2-processor/channel1-channel2-destination-channel2-response-error.ts
added: src/plugins/channel1-channel2-processor/channel1-channel2-utils.ts

Add a new swagger

Add a swagger inside your plugin in the path:
src/plugins/channel1-channel2-processor/swagger.yaml

openapi: 3.0.0
info:
  title: administration api to aura bridge
  description: Set of endpoints related to bridge administration
  version: 1.0.0
tags:
  - name: admin
    description: Bridge administration plugin
servers:
  - url: 'http://localhost:8045'
    description: Local server
  - url: 'https://svc-ap-current.auracognitive.com'
    description: ap-current
paths:
  /aura-services/v1/testing/channel1: # include the path to the new plugin
      get:
        tags:
          - testing-channe1
        description: channel1 testing.
        operationId: getChannel1Messages # controller function name.
        x-router-controller: plugins # in path src/controllers/plugins.ts
        responses:
          '200':
            description: OK
            headers: { }
          '500':
            description: An internal server error has occurred.

Add a new function controller

Add all the controllers in the path: src/controllers/plugins.ts

import Channel1Channel2Message from '../plugins/channel1-channel2-processor/channel1-channel2-controller';

export function getChannel1Messages(req: express.Request, res: express.Response) {
    Channel1Channel2Message.controller(req, res);
}

Plugin activation in Aura bridge

Every plugin to be loaded in aura-bridge must be defined in the plugin-config.json file.

⚠️ If this plugin has dependence with other plugins, they must also be added to the plugins list. If during the aura-bridge boot a plugin has a dependency with another not installed plugin, the bridge will fail in the boot process and will log an error indicating the lost dependency.

Add the plugin to the configuration file plugin-config.json (located at the root of the aura-bridge project):

[
    ...
    "./lib/plugins/channel1-channel2-processor",
    ...
]

Activate a new plugin during development

To activate a new plugin during development, it is only necessary to add the plugin path in the plugin-config.json file:

[
    "./lib/plugins/directline-service",
    "./lib/plugins/directline-whatsapp-processor",
    "./lib/plugins/whatsapp-incoming-processor",
    "./lib/plugins/whatsapp-service",
    // New plugin location here.
]

⚠️ take into account the dependencies with other plugins, as explained in the previous section.

Activate a new plugin for production

To add a new plugin in production, it is necessary to define the list of plugins using the plugin-config.json key in the aura-bridge ConfigMap for deployment in Kubernetes.

Example of aura-bridge ConfigMap using a configuration file:

apiVersion: v1
kind: ConfigMap
metadata:
  name: aura-bridge
  labels:
    app: aura-bridge
    stack: service
  namespace: {{ kubernetes_core_namespace }}
data: 
  plugin-config.json: |
    {{ lookup('file','<FOLDER_PATH>/plugin-config.json',convert_data=False) | indent(4,indentfirst=False) }}

Plugin removal in Aura bridge

To remove a plugin, it is only necessary to delete the plugin path in the plugin-config.json file.

⚠️ In order to eliminate a plugin correctly, it is necessary to verify that no other plugins from those installed depends on the one we want to eliminate.

Docs:

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

development-api plugin

Technical description of the development-api plugin

Introduction

The development-api plugin manages the configuration in development environments. Only available in development environments.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
redisConnector	PluginType.Service	Redis connector

Provides components (IOC)

Name	Type	Description
developmentApi	PluginType.API	Endpoints to change development configuration
behaviorCache	PluginType.Service	Cache to store the configuration changes
behaviorManager	PluginType.Service	Management of changes

Docs:

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

directline-auraline-processor plugin

Technical description of directline-auraline-processor plugin

Introduction

This plugin receives requests from aura-groot and send them to Auraline callback.

Consumes components (IOC)

Name	Type	Description
auralineClient	PluginType.Service	Auraline client
configurationManager	PluginType.Service	Configuration manager
directlineService	PluginType.Service	Services and utilities for Directline channel

Provides components (IOC)

Name	Type	Description
directlineAuralineProcessor	PluginType.Processor	Manage Auraline responses

auraline-directline-processor flow definition

To process a message, the auraline-directline-processor uses AuraBridgeFlow with the following definition:

    const flow: BridgeFlow = {
        name: 'directlineToAuralineFlow',
        source: {
            type: BridgeNodeType.Directline
        },
        destination: {
            type: BridgeNodeType.Auraline,
            converter: DirectlineToAuralineConverter,
            client: services.auralineClient,
            clientOptions: { queue: { bridgeFlowName: directlineToAuralineFlow.name } }
        },
        onError: {
            destinations: [
                {
                    type: BridgeNodeType.Auraline,
                    converter: ErrorToAuralineApiConverter,
                    client: services.auralineClient,
                    decode: AuralineDestinationResponseError
                }
            ]
        }
    };

According to the flow definition, AuraBridgeFlow tries to process, convert and send (using queues) the message to the Auraline callback endpoint defined in the callbackOptions channel configuration property, within the ResponseOptions model.

If some type of error occurs during this process and is marked as recoverable, certain retries will be executed. If after all, the error continues, an error message will be sent to the endpoint.

AuralineToDirectlineConverter

Main converter, in charge of transforming DirectLine activities to Auraline format. The response messages will have the following format:

{
        "activities": [
            {
                "type": "message",
                "serviceUrl": "http://aura-bridge-outbound:8045/aura-services/auraline",
                "channelId": "c71dc728-5fe2-4735-927d-0c419b35ec59",
                "conversation": {
                    "id": "4nc3u4hn"
                },
                "recipient": {
                    "id": "user1"
                },
                "text": "Hi!",
                "inputHint": "acceptingInput",
                "channelData": {
                    "hasMoreMessages": false,
                    "correlator": "53c42d06-3be1-48c4-a6c9-afa6e76d54fc"
                },
                "replyToId": "8vvicc88",
                "id": "8vvicc88|0001"
            }
        ],
        "correlator": "53c42d06-3be1-48c4-a6c9-afa6e76d54fc",
        "timestamp": "2023-11-08T12:24:36.420Z",
        "id": "8vvicc88",
        "to": "user1",
        "conversationId": "4nc3u4hn"
    }

Inside the activities array, all activities will have a unique identifier (messageId|XXXX) that the client should store to later send the ack to Auraline.

Docs:

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

directline-rcs-processor plugin

Technical description of directline-rcs-processor plugin

Introduction

This plugin receives requests from aura-groot and send them to RCS callback.

Consumes components (IOC)

Name	Type	Description
rcsClient	PluginType.Service	RCS client
directlineClient	PluginType.Service	Directline client
configurationManager	PluginType.Service	Configuration manager
directlineService	PluginType.Service	Services and utilities for Directline channel

Provides components (IOC)

Name	Type	Description
directlineRcsProcessor	PluginType.Processor	Manage RCS responses

rcs-directline-processor flow definition

To process a message, the directline-rcs-processor uses AuraBridgeFlow with the following definition:

    const flow: BridgeFlow = {
        name: 'directlineToRcsFlow',
        source: {
            type: BridgeNodeType.Directline
        },
        destination: {
            type: BridgeNodeType.Rcs,
            converter: DirectlineToRcsConverter,
            client: services.rcsClient,
            clientOptions: { queue: { bridgeFlowName: directlineToRcsFlow.name } }
        },
        onError: {
            destinations: [
                {
                    type: BridgeNodeType.Rcs,
                    converter: ErrorToRcsApiConverter,
                    client: services.rcsClient,
                    decode: RcsDestinationResponseError
                },
                {
                    type: BridgeNodeType.Directline,
                    converter: ErrorToDirectlineEventConverter,
                    client: services.directlineClient,
                    decode: RcsDestinationResponseError
                }
            ]
        }
    };

According to the flow definition, AuraBridgeFlow tries to process, convert and send (using queues) the message to the Google RCS messages endpoint. If some type of error occurs during this process and is marked as recoverable, certain retries will be executed. If after all, the error continues, an error message will be sent to RCS and an error event will be sent to aura-groot.

rcsToDirectlineConverter

Main converter, in charge of transforming DirectLine activities to RCS format.

This converter only handles activities with an attachment type application/vnd.telefonica.aura.rcs.message with content in RCS format.

{
  "type": "message",
  "serviceUrl": "http://localhost:8045/aura-services/javiagent",
  "channelId": "f7fd1021-41cd-588a-a461-387cc24be225",
  "from": {},
  "conversation": {
    "id": "d152aee9-1aaa-5b54-95a5-79352eee2e45"
  },
  "recipient": {
    "id": "34659949469",
    "name": "javiagent_xxxxxx_agent@rbm.goog"
  },
  "text": "Text doesn't matter",
  "inputHint": "acceptingInput",
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.rcs.message",
      "content": {
        "contentMessage": {
          "richCard": {
            "carouselCard": {
              "cardWidth": "MEDIUM",
              "cardContents": [
                {
                  "title": "Card #1",
                  "description": "The description for card #1",
                  "suggestions": [
                    {
                      "reply": {
                        "text": "Card #1",
                        "postbackData": "{\\"intent\\": \\"intent.factotum-test.rcs-formats\\",\\"entities\\":[{\\"type\\":\\"type\\",\\"entity\\":\\"postback\\"},{\\"type\\":\\"data\\",\\"entity\\":\\"card 1\\"}]}"
                      }
                    }
                  ],
                  "media": {
                    "height": "MEDIUM",
                    "contentInfo": {
                      "fileUrl": "https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg",
                      "forceRefresh": "false"
                    }
                  }
                },
                {
                  "title": "Card #2",
                  "description": "The description for card #2",
                  "suggestions": [
                    {
                      "reply": {
                        "text": "Card #2",
                        "postbackData": "{\\"intent\\": \\"intent.factotum-test.rcs-formats\\",\\"entities\\":[{\\"type\\":\\"type\\",\\"entity\\":\\"postback\\"},{\\"type\\":\\"data\\",\\"entity\\":\\"card 2\\"}]}"
                      }
                    }
                  ],
                  "media": {
                    "height": "MEDIUM",
                    "contentInfo": {
                      "fileUrl": "https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg",
                      "forceRefresh": "false"
                    }
                  }
                }
              ]
            }
          }
        }
      }
    }
  ],
  "channelData": {
    "correlator": "73b72144-7247-4876-880b-57b63efa323e",
    "version": "3",
    "status": {
      "code": "SUCCESS",
      "message": "Success"
    },
    "payload": {
      "bridge": {
        "channelId": "f7fd1021-41cd-588a-a461-387cc24be225"
      }
    }
  },
  "replyToId": "11879060267953086"
}

If an attachment of this type is not present, a simple message with the value of the activity.text field will be sent to the user.

Docs:

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

directline-service plugin

Technical description of directline-service plugin

Introduction

directline-service plugin contains the services and utilities related to message creation for Microsoft Directline v3. This plugin also contains the Directline client to send messages to aura-root.

The specific environment variables for this plugin are located at directline-service plugin configuration.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
auraBridgeCache	PluginType.Service	Cache for ack messages

Provides components (IOC)

Name	Type	Description
directlineClient	PluginType.Client	Direct Line client
directlineService	PluginType.Service	Services and utilities for Direct Line protocol

directlineClient plugin

The directlineClient class extends from the AuraBridgeClient and allows sending requests to aura-root.

directlineService

The directlineService class provides utilities related to the Directline client.

messageFactory for channelData v1 (DirectlineMessageFactory): Factory to create different types of Directline messages with channelData v1.
messageFactory for channelData v3 (DirectlineMessageFactoryV3): Factory to create different types of Directline messages with channelData v3.

Docs:

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

directline-whatsapp-service plugin

Technical description of directline-whatsapp-service plugin

Introduction

directline-whatsapp-service plugin contains the services and utilities for directline-whatsapp message conversion.

The specific environment variables for this plugin are located at directline-whatsapp-service configuration.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
prometheus	PluginType.Service	Metrics client for prometheus
whatsappService	PluginType.Service	Services and utilities for WhatsApp channel

Provides components (IOC)

Name	Type	Description
directlineWhatsappService	PluginType.Service	Services and utilities for Direct Line - WhatsApp message conversion

whatsappService

The DirectlineWhatsappService class provides the following utilities:

directlineToWhatsappConverter: It converts DirectLine messages (DirectlineMessageModel) to WhatsApp messages (WhatsappMessageResponseModel).
directlineWhatsappUtils: Utilities to help with message conversion: DirectLine to WhatsApp.

Converting Direct Line messages to WhatsApp models

The DirectlineToWhatsappConverter class extends from AuraBridgeMessageConverter and converts DirectLine messages to WhatsApp models.

To make this conversion, the DirectlineToWhatsappConverter differences between the following types of messages depending on the DirectLine message content:

Type	Direct Line message content
`text`	Direct Line messages that do not contain attachments
`list`	Direct Line messages that contain more than one attachment and the `attachmentLayout` field value is `list`.
`carousel`	Direct Line messages that contain more than one attachment and the `attachmentLayout` field value is `carousel`.
`heroCard`	Direct Line message that contains a single attachment and the `contentType` field value is `application/vnd.microsoft.card.hero`.
`file`	Direct Line message that contains a single attachment and the `contentType` field value is `application/vnd.telefonica.aura.file`.
`template`	Direct Line message that contains a single attachment and the `contentType` field value is `application/vnd.telefonica.aura.template`.
`videoCard`	Direct Line message that contains a single attachment and the `contentType` field value is `application/vnd.microsoft.card.video`.
`whatsapp`	Direct Line message that contains a single attachment and the `contentType` field value is `application/vnd.telefonica.aura.whatsapp`.

In the case of list and carousel, in which there is more than one attachment, each attachment in list follows the same procedure to obtain type depending on the value of the contentType field.

⚠️ Currently, the file, template and videoCard types are disabled when they must be generated from list or carousel.

Type `text` conversion

DirectLine messages identified with the text type is transformed to WhatsApp text messages using the WhatsappMessageFactory.createTextMessage.

Find further information about sending WhatsApp text messages.

Type `heroCard` conversion

DirectLine messages identified with the heroCard type is transformed to WhatsApp text messages using the WhatsappMessageFactory.createTextMessage.

These messages will be transformed to WhatsApp list messages, WhatsApp reply buttons or enumerated text lists, following the defined guidelines in WhatsApp list options.

The transformation to a WhatsApp message depends on the type of list obtained:

button type. It will be transformed to WhatsApp interactive button message using the WhatsappMessageFactory.createInteractiveButtonMessage.
list type. It will be transformed to WhatsApp interactive list message using the WhatsappMessageFactory.createInteractiveListMessage.
enumeratedList type. It will be transformed to WhatsApp formatted text message using the WhatsappMessageFactory.createHeroCardMessage.

Type `file` conversion

DirectLine messages identified with the file type is transformed to WhatsApp media messages using the WhatsappMessageFactory.createFileMessage.

The currently supported file types are: image, document, audio and video.

Find here further information about sending WhatsApp media messages.

Type `template` conversion

DirectLine messages identified with the template type is transformed to WhatsApp media messages using the WhatsappMessageFactory.createTemplateMessage.

Find here further information about sending WhatsApp template messages.

Type `videoCard` conversion

DirectLine messages identified with the template type will be transformed to WhatsApp media messages using the WhatsappMessageFactory.createTemplateMessage.

Find here further information about sending WhatsApp template messages.

Type `whatsapp` conversion

Direct Line messages identified as type whatsapp will be sent to WhatsApp without any transformation. This kind of messages is composed of an attachment type application/vnd.telefonica.aura.whatsapp whose content will be sent directly to WhatsApp. Only the field to will be added.

Text conversion to WhatsApp markdown format

All texts obtained using LocaleManager instance are formatted in WhatsApp markdown format. This implies that all resources defined in POEditor to be used in WhatsApp messages must use the markdown standard format.

The getLocaleTextWithParsedMarkdown function from whatsapp-message-utils is responsible for converting the text to WhatsApp markdown format.

For the text sent from the DirectLine message, the DirectlineToWhatsappConverter class converts text to WhatsApp markdown format according to the following:

If the DirectLine message contains information in the channelData.payload.bridge.whatsapp.textConvert field, its value is used to convert to WhatsApp markdown format.
If the request field is not present, the channel configuration is used.
Finally, if it is not possible to obtain conversion information in the previous cases, the text message is converted by default.

By default, aura-bridge converts the text received from DirectLine message to specific WhatsApp markdown format.

The practical processes for modifying this behavior is explained in the following documents:

Docs:

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

aura-mocks-dynamic-settings-service plugin

Description of the aura-mocks-dynamic-settings-service plugin

Description

The aura-mocks-dynamic-settings-service plugin is responsible for loading profile configurations from an Azure account or locally to be used afterwards.

An attempt is made to collect data from the specified Azure Storage account and container. If nothing is found, a default file is collected locally from path src/plugins/aura-mocks-dynamic-settings-service/dynamic-settings-default.json. The active cron performs this check periodically.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-dynamic-settings-service

This is part of aura-mocks-server project.

Variables

name	type	description	mandatory
AURA_MOCKS_DYNAMIC_SETTINGS_SERVICE_CRON	string	Cron expression for dynamic settings loading	no
AURA_MOCKS_DYNAMIC_SETTINGS_SERVICE_RESOURCE_CONTAINER	string	Container where dynamic settings file is stored	no
AURA_MOCKS_DYNAMIC_SETTINGS_SERVICE_RESOURCE_PATH	string	Path to JSON configuration file used by dynamic settings service	no

Example of dynamic settings file

{
    "type": "Local",
    "plugins": [
        {
            "name": "auraMocksGenesysApi",
            "settings": {
                "pushProviders": [
                    {
                        "name": "default",
                        "pushUrl": "https://svc-ap-current.auracognitive.com/aura-services/v1/genesys/messages?apikey=123456",
                        "headers": {
                            "genesys-callback": "http://perf-mock.aura-mocks.svc"
                        }
                    }
                ],
                "profiles": [
                    {
                        "name": "default",
                        "configuration": {
                            "chat": {
                                "updateAliasForEachRequest": true,
                                "autoMessages": [
                                    {
                                        "from": {
                                            "nickname": "system",
                                            "type": "External"
                                        },
                                        "type": "ParticipantJoined",
                                        "timeout": 1
                                    }
                                ]
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Docs:

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

aura-mocks-genesys-api plugin

Plugin that mocks the behavior of Genesys, the call-center service used by Telefónica OBs.

Description

The aura-mocks-genesys-api plugin contains the services used by aura-bot and aura-bridge to work without real Genesys services.

These services are mainly:

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-genesys-api

This is part of aura-mocks-server project.

Genesys API

Chat API Version 2

Genesys documentation: https://docs.genesys.com/Documentation/GMS/latest/API/ChatAPIv2

Currently, the mock for Genesys has the following endpoints implemented:

Enpoint	Method	Group	description
/genesys/2/chat/{serviceName}	POST	Chat	Request Chat
/genesys/2/chat/{serviceName}/{chatId}/send	POST	Chat	Send Message
/genesys/2/chat/{serviceName}/{chatId}/disconnect	POST	Chat	Disconnect
/genesys/2/chat/{serviceName}/{chatId}/pushUrl	POST	Chat	PushUrl

Start a new chat

Steps

Perform a POST request to /Genesys/2/Chat/{ServiceName}
When a new chat is created using the POST request to “/Genesys/2/Chat/{ServiceName}”, the system uses the settings indicated in the profile parameter or uses the default profile configuration if this parameter is not informed (see Profiles mock API
Send messages to chat using the endpoint /genesys/2/chat/{serviceName}/{chatId}/send

You can change at any time the value of Pushurl using the endpoint /genesys/2/chat/{serviceName}/{chatId}/pushUrl

Sessions Mock API

To help in testing tasks, the mocks exposes a series of services associated with the sessions it manages and the profiles that can be used to start a conversation.

Get session information

Sessions are identified by the chatId, so once a chat is created, you can check the session using /genesys/2/mock/sessions/{chatId}.

Endpoins

Enpoint	Method	Group	description
/genesys/2/mock/sessions	GET	Session	Get chat mock sessions
/genesys/2/mock/sessions/{chatId}	GET	Session	Get session by chatId
/genesys/2/mock/sessions/stats	GET	Session	Get session stats
/genesys/2/mock/sessions/keys	GET	Session	Get session keys
/genesys/2/mock/sessions	DELETE	Session	Remove session

Profiles Mock API

The profiles allow you to configure a different execution environment to the default environment, in order to receive answers in another address (Pushurl) and execute automatic actions when starting a new chat.

What are the profiles for?

When a new chat is created using the POST request /genesys/2/chat/{serviceName}, a profile is used to configure mainly two parameters:

pushUrl: It indicates the address where PUSH notifications will be sent.
autoMessages: Messages that will be executed automatically at the beginning of the conversation and using the waiting time indicated for each message.

See default profile settings

An example of configuration for the “default” profile is shown below:

// Post result to "/genesys/2/mock/profiles"
[
    {
        "profile": "default",
        "settings": {
            "chat": {
                "pushUrl": "https://svc-ap-current.auracognitive.com/aura-services/v1/genesys/messages",
                "autoMessages": [
                    {
                        "from": {
                            "nickname": "system",
                            "type": "External"
                        },
                        "type": "ParticipantJoined",
                        "timeout": 1
                    },
                    {
                        "from": {
                            "type": "External"
                        },
                        "type": "Message",
                        "timeout": 1,
                        "text": "You have approximately 15 minutes to be attended"
                    },
                    {
                        "from": {
                            "type": "External"
                        },
                        "type": "Message",
                        "timeout": 1,
                        "text": "Soon one of our agents will attend you personally"
                    },
                    {
                        "from": {
                            "nickname": "agent1",
                            "type": "Agent"
                        },
                        "type": "ParticipantJoined",
                        "timeout": 1
                    },
                    {
                        "from": {
                            "type": "Agent"
                        },
                        "type": "Message",
                        "timeout": 1,
                        "text": "Hello, I am an Agent, how can I help you?"
                    }
                ]
            }
        }
    }
]

In the default configuration, once a new chat is created, the following messages will be executed:

A second after starting the chat, the “system” (external) user will join conversation.
After that, “system” will send a message “You have approximately 15 minutes to be attended” (1 second after the previous message).
“system” will send a message “Soon one of our agents will attend you personally” (1 second after).
“agent1” (Agent) user will join conversation (1 second after).
“agent1” will send a message “Hello, I am an Agent, how can I help you?” (1 second after).

Endpoints

Enpoint	Method	Group	description
/genesys/2/mock/profiles	GET	Profile	Get profiles
/genesys/2/mock/profiles/{profile}	GET	Profile	Get profile by name
/genesys/2/mock/profiles/default	POST	Profile	Set profile by name
/genesys/2/mock/profiles/reset	GET	Profile	Reset profiles
/genesys/2/mock/chat/{serviceName}/{chatId}/send	POST	MockChat	Send message directly to the session, with optional timeout

Chat Mock API

You can send any type of event in chat using the service /genesys/2/mock/chat/{serviceName}/{chatId}/send. The format is similar to “autoMessages” for a profile.

The postman linked to this documentation contains an example of all types of events that can be sent to chat.

Postman

aura-mocks-genesys-api Postman collection

Docs:

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

genesys-directline-processor plugin

Technical description of genesys-directline-processor plugin

Introduction

This plugin receives requests from handover and transforms them to DirectLine format to send them to aura-groot.

The specific environment variables for this plugin are located at genesys-directline-processor plugin configuration.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
directlineClient	PluginType.Service	DirectLine client
directlineService	PluginType.Service	Services and utilities for Directline channel

Provides components (IOC)

Name	Type	Description
genesysProcessor	PluginType.Processor	Manage requests from handover

Controller

This plugin sets the endpoints that support handover.

Operation id	Path	Description
postGenesysMessages	/aura-services/v1/genesys/messages	Manage the messages sent by handover

Flow definition

To process a message from handover, the genesys-directline-processor plugin uses AuraBridgeFlow with the following definition:

    const flow: BridgeFlow = {
        source: {
            type: BridgeNodeType.Genesys
        },
        destination: {
            type: BridgeNodeType.Directline,
            converter: GenesysToDirectlineConverter,
            client: services.directlineClient,
            clientOptions: { retries: {} }
        },
        onError: {
            destinations: [
                {
                    type: BridgeNodeType.Directline,
                    converter: GenesysToDirectlineEventConverter,
                    client: services.directlineClient
                }
            ]
        }
    };

According to the flow definition, AuraBridgeFlow tries to process, convert and send (using retries) the message to aura-groot using the DirectLine client.

If some type of error occurs during this process, an event message will be sent to aura-groot with the error information.

flowchart LR
    subgraph Flow
        direction LR
        B(Controller) --> C(Converter)
    end
    A(Handover) -->|message| Flow
    Flow -->|ok| D(Groot Directline)
    Flow -->|error| E(Groot Directline Event)

Message conversion

The plugin uses two converters to transform messages from Handover to DirectLine format: GenesysToDirectlineConverter and GenesysToDirectlineEventConverter.

GenesysToDirectlineConverter

Main converter, in charge of transforming Handover messages to DirectLine format messages using the messageFactory service of directline-whatsapp-service plugin.

The Handover data information in DirectLine message is added to the channeldata.payload.handover field. The converted message also includes an auraCommand with suggestion type and value defined in the environment variable AURA_GENESYS_AURA_COMMAND_DEFAULT_INTENT (by default: intent.common.handover).

Further information about handover payload in channelData v3

GenesysToDirectlineEventConverter

It makes the conversion to a DirectLine event message if an error in the process has occurred.

Docs:

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

aura-mocks-json-server-api plugin

Module that mocks the behavior of any of the REST APIs called by aura-bot

Description

aura-mocks-json-server-api is a tool using express that allows you to generate REST services with predefined responses from a Javascript file that can be easily modified.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-json-server-api

This is part of aura-mocks-server project.

Create a simple “hello” response

You must create a file to store the information of your new response mocks in data/db/module (for our example, greetings.js):

data
├── db
│   ├── module
│   │   ├── greetings.js

Add to greetings.js the response to the request GET /greetings/hello:

module.exports = {
  "configuration": {
    "name": "greetings",
    "basePath": "/greetings"
  },
  "routes": {
    "/hello": {
      "GET": {
        "examples": {
          "default": {
            "status": 200,
            "body": {
              "response": "Hello from mock"
            }
          }
        }
      }
    }
  }
};

Now, you can make a call to:

    <URL_MOCK_SERVER>/greetings/hello

That should answer with a:

{
    "response": "Hello from mock"
}

Creating a more complex answer

For example, to create a POST service /aura-services/v1/users/:id, where the user is dynamic:

 "routes": {
    "/aura-services/v1/users/:id": {
      "GET": {
        "configuration": {
          "getExampleKey": (req, res) => { return req.params && req.params.id ? req.params.id : 'default'; }
        },
        "examples": {
          "default": {
            "status": 200,
            "body": {
              "auraIdGlobal": "929285cb270001356476db33a4e31ce86402948213097e81717b50e549054cf2",
              "auraId": "fb7926db-0283-41ef-a02f-541946090c92",
              "userId": "85826044177A204DDEBCCEA98CE9439C3C770E03",
              "channelId": "60f0ffda-e58a-4a96-aad9-d42be70b7b42",
              "authorizationId": "",
              "phoneNumber": "",
              "idTokenHint": null
            }
          },
          "fb7926db-0283-41ef-a02f-541946090c92": {
            "status": 200,
            "body": {
              "auraIdGlobal": "929285cb270001356476db33a4e31ce86402948213097e81717b50e549054cf2",
              "auraId": "fb7926db-0283-41ef-a02f-541946090c92",
              "userId": "85826044177A204DDEBCCEA98CE9439C3C770E03",
              "channelId": "60f0ffda-e58a-4a96-aad9-d42be70b7b42",
              "authorizationId": "",
              "phoneNumber": "",
              "idTokenHint": null
            }
          }
        }
      }
    }
  }

How to get requests and responses automatically

The main idea is to obtain and generate all the requests in an automated way from the data sent and received by the aura-bot platform itself. In this way, there is no need to generate by hand each of the services required by the bot.

To obtain these requests, it is possible to use a sniffer and filter by the domains used by the aura-bot platform itself or use the aura-bot platform to record in a file all the requests and responses made (chosen option).

Modifications in Aura Bot Platform (temporary)

To use aura-bot platform as a request/response generator, you can temporarily modify the code as follows:

http-monkey-patcher.ts

line 1

import * as fs from 'fs';

before line 90

const requestResponse = {};

after line 122

parsedOptions.port = args[0].port;

after line 200: request.once ‘finish’

(requestResponse as any).request = {
    type: 'request',
    domain: host,
    port: parsedOptions.port,
    method: parsedOptions.method,
    path: parsedOptions.path,
    corr: this.getCorrelatorFromRequest(request) || CorrelatorUtil.noCorrelator,
    headers: request.getHeaders(),
    body: requestBody
};

after line 250: response.once ’end

(requestResponse as any).response = {
    type: 'response',
    domain: host,
    method: parsedOptions.method,
    status: response.statusCode,
    path: parsedOptions.path,
    body: responseBody,
    drt: duration,
    corr
};

fs.appendFile('/tmp/request-response-data.txt', `${JSON.stringify(requestResponse)}\n\n`, () => { });

To import the data obtained, check the documentation for json-server-import script

aura-mocks-json-server-api plugin scripts

Import requests/response to aura-mocks-server database

script: json-server-import.js

To import the information obtained previously, the script src/scripts/json-server-import.ts is used.

This script allows you to load the request / response information into the mock server database.

npm run jsonserver:import --file=/tmp/hello-greeting.txt

The previous sentence will load the requests, overwriting existing ones.

You can also debug the script code:

npm run jsonserver:import:debug --file=/tmp/hello-greeting.txt

How it works

The script will load in the JSON server database information of each request associated with the example named default. (All loaded requests are loaded as “samples” by default).

Examples are each of the responses that a request can return. You can create examples with a different identifier to default using the getExampleKey function (in configuration object) for that request:

...
  "routes": {
    "/aura-services/v1/users/:id": {
      "GET": {
        "configuration": {
          "getExampleKey": (req, res) => { return req.params && req.params.id ? req.params.id : 'default'; }
        },
...

In the previous configuration, the json-server-import script will get the example identifier using the id parameter obtained from the request URL itself. Thus, the request /aura-services/v1/users/e7c26f93-bf15-419b-8893-2728afad3b6c will create the example:

...
        "examples": {
          "e7c26f93-bf15-419b-8893-2728afad3b6c": {
            "status": 200,
            "body": {
              "auraIdGlobal": "5c7ba5d26fa2945b3b9b29b64d6822edd914dd0d82cf28eae5287dd2a28b7768",
              "auraId": "e7c26f93-bf15-419b-8893-2728afad3b6c",
              "userId": "17c1ee02-0140-11ea-a69e-362b8e000000",
              "channelId": "45494a5b-835a-4fff-a813-b3d2be529dbe",
              "authorizationId": "",
              "phoneNumber": "phone_number",
              "idTokenHint": null
            }
          }
        }
...

Show routes in aura-mocks-server database

script: json-server-routes.js

This script will show the routes stored in the JSON server database and the examples that each route contains.

npm run jsonserver:routes

aura-mocks-json-server-api plugin database

/v3/domain_classifier/default_query

Currently, the mocks service for apigw url /auracognitive/v3/domain_classifier/default_query is ready to respond to the following POST queries:

Intent	Channel	Phrase (spanish)
intent.common.goodbyes	mp	hasta pronto
intent.common.greetings	mp	hola
intent.common.help	mp	ayuda
intent.common.swearwords	mp	joder
intent.common.thankyous	mp	gracias
intent.tv.content_get_info	mp	peliculas de fox
intent.tv.display	mp	quiero ver cuatro
intent.tv.none	mp	aabb
intent.tv.question_time_loc	mp	hora del partido del barcelona
intent.tv.search	mp	busca masterchef
intent.tv.search	mp	busca telediario
intent.tv.search_similar	mp	similar a telediario

/aura-services/v1/users/:id

User (auraId)	Channel Name	channelId
fb7926db-0283-41ef-a02f-541946090c92	mp	60f0ffda-e58a-4a96-aad9-d42be70b7b42

Docs:

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

aura-mocks-openai-api plugin

Description of the aura-mocks-openai-api plugin that mocks some of the services defined in the Azure OpenAI Service, used mainly by the Aura Gateway API service.

Description

The aura-mocks-openai-api plugin contains the services used by aura-gateway-api to work without real OpenAI services.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-openai-api

Currently, the plugin mocks the following services:

Create Completion

This is part of aura-mocks-server project.

aura-mocks-openai-api API

Endpoints description

Currently, the mock for OpenAI has the following endpoints implemented:

Enpoint	Method	Group	description
/openai/deployments/:deployment_id/chat/completions	POST	Chat	Create chat completions

Create chat completions

The endpoint /openai/deployments/:deployment_id/chat/completions is used to create a new chat completion. It is a POST request that receives the following query parameters:

Parameter	Type	Description
api-version	string	version of the API to be used

The response can be modified using the content field of the request body.

Using a specific response

The content field of the request body can be used to return a specific response:

{
    "messages": [
        {
            "role": "user",
            "content": "error_400_content_filter"
        }
    ]
}

Using retries profile

The content field of the request body can be used to return responses based on a profile. The retries profile allows to return different responses for each retry. Example:

{
    "messages": [
        {
            "role": "user",
            "content": "user2|retries:status-500&status-200"
        }
    ]
}

In the example above, the retries profile will return the first response with status 500 and then the second response with status 200.

Defined responses

The following table shows the different mock responses that can be used:

Mock response	Description
error_400_content_filter	Returns a 400 error with content filter error
error_401_incorrect_api_key	Returns a 401 error with incorrect APIKey
error_429_exceeded_quota	Returns a 429 error with exceeded quota
error_429_rate_limit_reached	Returns a 429 error with rate limit reached
error_500_server_error	Returns a 500 error with server error
error_503_engine_overloaded	Returns a 503 error with engine overloaded
missing_response	Returns a 200 response with an empty response body
success_length	Returns a 200 success response
success_stop	Returns a 200 success response with finish_reason stop

The “error_429_exceeded_quota” and “error_429_rate_limit_reached” responses will have the “Retry-After” header set to 5 seconds.

Docs:

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

aura-mocks-plugin-manager-service plugin

Description of the aura-mocks-plugin-manager-service plugin

Description

The aura-mocks-plugin-manager-service plugin is responsible for registering the different plugins of project.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-plugin-manager-service

This is part of aura-mocks-server project.

Docs:

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

aura-mocks-profiles-response-service plugin

Description and guidelines for working with the aura-mocks-profiles-response-service plugin

Introduction

The aura-mocks-profiles-response-service plugin provides the rest of the plugins a specific utility to employ profiles and perform different behaviors, depending on the information received in requests and the configuration by type.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-profiles-response-service

How to use

To use it, you must:

Import services with injected plugins.
Use Dynamic settings plugin to fetch the profile.
Use profileService to fetch the profile settings.

    import { services } from './services';
    const profiles: ProfileSettings[] = services.dynamicSettings?.getSettingsForPlugin('nameOfProfile')?.profiles;
    const profileSettings: ProfileSettings = services.profileService.getProfile(profile, profiles);

Methods

getData

    /**
     * Get data of profile.
     *
     * @param {string} value Message identifier
     * @returns {ProfileData} Profile data
     */
    public getData(value: string): ProfileData {

Example

    const profileData: ProfileData = services.profileService?.getData(profile);

isProfile

    /**
     * Determine whether the service contains a correct profile.
     *
     * @param {string} value Value to test
     * @param {ProfileSettings[]} profiles Profile list
     * @returns {boolean} Is profile?
     */
    public isProfile(value: string, profiles: ProfileSettings[]): boolean {

getProfile

    /**
     * Get profile from value.
     *
     * @param {string} value Value to test
     * @param {ProfileSettings[]} profiles Profile list
     * @returns {ProfileSettings|undefined} Profile settings
     */
    public getProfile(value: string, profiles: ProfileSettings[]): ProfileSettings | undefined {

Example

    services.profileService.getProfile(profile, profiles);

executeProfile

    /**
     * Executes given profile.
     *
     * @param {ProfileSettings} profile Settings of channel.
     * @param {object[]} savedMessages Messages stored in cache.
     * @param {object} message Message sent by the bridge.
     * @param {ResponseMessage} response Default response.
     * @param {ProfileData} profileData Profile data
     * @returns {ResponseResult} Response result.
     */
    public executeProfile(
        profile: ProfileSettings,
        savedMessages: any[],
        message: any,
        response: ResponseMessage,
        profileData: ProfileData
    ): ResponseResult {

Example

    services.profileService.executeProfile(profileSettings, messages, message, {} as any, profileData);

executeProfileRetries

    /**
     * Executes profile retries.
     *
     * @param {ProfileSettings} profile Settings of channel.
     * @param {object[]} savedMessages Messages stored in cache.
     * @param {object} message Message sent by the bridge.
     * @param {ResponseMessage} response Default response.
     * @param {ProfileData} profileData Profile data
     * @returns {ResponseResult} Response result.
     */
    private executeProfileRetries(
        profile: ProfileSettings,
        savedMessages: any[],
        message: any,
        response: ResponseMessage,
        profileData: ProfileData
    ): ResponseResult {

Example

    this.executeProfileRetries(profile, [{text: 'hola'}], 'hola', response, profileData);

executeProfileTokenExpired

    /**
     * Execute `tokenExpired` profile.
     * Emulate the `token expired` response from 4P.
     *
     * @param {any} message Message sent by the bridge.
     * @returns {ResponseResult} Response result.
     */
    private executeProfileTokenExpired(message: any): ResponseResult {

getNamespaceAndProfile

    /**
     * Get namespace and profile from value.
     * Example: '12345|namespace:aura-ap-next|retries:wa-1015&4p-200' => { namespace: 'aura', profile: '12345|retries:wa-1015&4p-200' }
     *
     * @param {string} value Value to test
     * @returns {{ namespace: string, profile: string }} Namespace and profile
     */
    public getNamespaceAndProfile(value: string): { namespace: string, profile: string } {

Example

    const { namespace, profile } = services.profileService.getNamespaceAndProfile(id);

Docs:

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

aura-mocks-redis-service plugin

Module that connect plugins to Redis database

Description

aura-mocks-redis-service plugin is a tool using aura-redis-handler that allows the connection of plugins to Redis database.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-redis-service

This is part of aura-mocks-server project.

Methods

delete

Delete element by key from Redis.

Property	Type	Description
pattern	string	Unique key for Redis
corr	string	Unique correlator

Example:

 await redisService.delete('test-key', 'test-correlator');

get

Get element by key from Redis.

Property	Type	Description
pattern	string	Unique key for Redis
corr	string	Unique correlator

Example:

 await redisService.get('test-key', 'test-correlator');

info

Return info from Redis.

Property	Type	Description
sections	string[]/undefined	Array with sections
corr	string	Unique correlator

Example:

 await redisService.info(['section_1'], 'test-correlator');

lPush

Put an element at the beginning of a Redis list.

Property	Type	Description
pattern	string	Unique key for Redis
value	string	Data to save
corr	string	Unique correlator

Example:

 await redisService.lPush('test-key', 'data', 'test-correlator');

rPush

Put an element at the end of a Redis list.

Property	Type	Description
pattern	string	Unique key for Redis
value	string	Data to save
corr	string	Unique correlator

Example:

 await redisService.rPush('test-key', 'data', 'test-correlator');

lRange

Get elements by key and range from Redis list.

Property	Type	Description
pattern	string	Unique key for Redis
from	number	Start index
to	number	End index
corr	string	Unique correlator

Example:

 await redisService.lRange('test-key', 0, 10, 'test-correlator');

set

Add data by key to Redis.

Property	Type	Description
pattern	string	Unique key for Redis
value	string	Data to save
corr	string	Unique correlator

Example:

 await redisService.set('test-key', 'data', 'test-correlator');

sAdd

Add element to the set of Redis.

Property	Type	Description
pattern	string	Unique key for Redis
value	string	Data to save
corr	string	Unique correlator

Example:

 await redisService.sAdd('test-key', 'data', 'test-correlator');

sInter

Get elements by key Redis.

Property	Type	Description
pattern	string	Unique key for Redis
corr	string	Unique correlator

Example:

 await redisService.sInter('test-key', 'data', 'test-correlator');

sRem

Remove element from the set of Redis.

Property	Type	Description
pattern	string	Unique key for Redis
value	string	Value to search
corr	string	Unique correlator

Example:

 await redisService.sRem('test-key', 'data', 'test-correlator');

zAdd

Add element to the sorted set.

Property	Type	Description
pattern	string	Unique key for Redis
score	number	Index of the element
value	string	Value to add
corr	string	Unique correlator

Example:

 await redisService.zAdd('test-key', 'data', 'test-correlator');

zRevRange

Get elements by key and range.

Property	Type	Description
pattern	string	Unique key for Redis
from	string/number	Start index
to	string/number	End index
corr	string	Unique correlator

Example:

 await redisService.zRevRange('test-key', 0, 10, 'test-correlator');

withLock

Lock Redis key and execute function.

Property	Type	Description
fn	function	Callback
key	string	Key to lock
corr	string	Unique correlator

Example:

 await redisService.withLock(await () => true, 'test-key', 'test-correlator');

Docs:

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

aura-mocks-send-feedback-api plugin

Plugin that mocks feedback sent by *aura-bridge

Description

The aura-mocks-send-feedback-api plugin simulates the server that is responsible for receiving the different requests from the aurapush-sendfeedback-service plugin of *aura-bridge component. These requests may involve the sending of statues, errors o messages.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-send-feedback-api

This is part of aura-mocks-server project.

Endpoints API

Enpoint	Method	Group	description
/feedback/statuses/update	PUT	Send Feedback	Update statuses
/feedback/errors/update	PUT	Send Feedback	Update errors
/feedback/messages/update	PUT	Send Feedback	Update messages
/feedback/messages	DELETE	Send Feedback	Delete cache
/feedback/messages/:messageId	GET	Send Feedback	Get message feedback by MessageId
/feedback/messages	GET	Send Feedback	Get all message feedback

PUT: /feedback/statuses/update

Update statuses by messageId, so messageId is mandatory.

PUT: /feedback/errors/update

Update errors by messageId, so messageId is mandatory.

PUT: /feedback/messages/update

Update messages by messageId, so messageId is mandatory.

DELETE: /feedback/messages/

Delete feedback message by messageId. The query param messageId is mandatory.

GET: /feedback/messages/

Get all messages feedback by MessageId. The query messageId value is mandatory.

GET: /feedback/messages/:messageId

Get message feedback by MessageId. The property in body messageId is mandatory.

Docs:

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

aura-mocks-sms-soap-service plugin

Description of the aura-mocks-sms-soap-service plugin

Description

The aura-mocks-sms-soap-service** plugin is responsible for providing a mock SOAP service with access to a test bot dialog: sms-soap-service-dialog.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-sms-soap-service

This is part of aura-mocks-server project.

Endpoints API

Enpoint	Method	Group	description
/sms	GET	soap	Soap Service with operation: sendSMS

Variables

name	type	description	mandatory
AURA_MOCKS_SOAP_ACTIVE	string	Flag to indicate if SOAP service is active. By default: `false`.	false
AURA_MOCKS_SOAP_SERVER_URI	string	URI for SOAP service used to define wsdl. By default: `http://localhost:3000`.	false

Docs:

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

aura-mocks-storage-file-manager plugin

Description of the aura-mocks-storage-file-manager plugin

Description

The aura-mocks-storage-file-manager plugin is responsible for providing access to the aura-storage-file-manager utility to upload and download files from an Azure Storage account.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-storage-file-manager

This is part of aura-mocks-server project.

Variables

name	type	description	mandatory
AURA_MOCKS_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Azure storage access key	yes
AURA_MOCKS_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Azure storage account	yes
AURA_MOCKS_AZURE_STORAGE_CONTAINER	string	Container where mocks resources are stored. By default: `aura-mocks-server`	no

Docs:

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

aura-mocks-store-activities-api plugin

Plugin that mocks sending activities* of aura-bot*

Description

The aura-mocks-store-activities-api plugin simulates sending activities messages with several useful endpoints for the QA team and performance testing.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-store-activities-api

This is part of aura-mocks-server project.

Endpoints API

Enpoint	Method	Group	description
/activities	GET	bot	Get messages
/v3/conversations/:conversationId/activities/:activityId	POST	bot	Delete messages

GET: /activities

Get message by activityCorrelator. The query param activityCorrelator is mandatory.

POST: /v3/conversations/:conversationId/activities/:activityId

Add activities.

POST: /api/messages

Add new activity message.

    {
        "type": "Receive_Message",
        "activity": {
            "type": "message",
            "id": "DF8d619NDYp3ywW1ew9QFK-fr|0000003",
            "timestamp": "2022-05-23T14:59:52.0129204Z",
            "channelId": "directline",
            "from": {
                "id": "BOT-aura-ap-next",
                "name": "BOT-aura-ap-next"
            },
            "conversation": {
                "id": "DF8d619NDYp3ywW1ew9QFK-fr"
            },
            "attachmentLayout": "list",
            "text": "Fiquei com dúvida. Veja se uma dessas respostas pode ajudar:",
            "speak": "Fiquei com dúvida. Veja se uma dessas respostas pode ajudar:",
            "inputHint": "expectingInput",
            "attachments": [
                {
                    "contentType": "application/vnd.microsoft.card.hero",
                    "content": {
                        "buttons": [
                            {
                                "type": "imBack",
                                "title": "Canonic phrase for intent:intent.bundle.get_name_by_type",
                                "value": "Canonic phrase for intent:intent.bundle.get_name_by_type"
                            },
                            {
                                "type": "imBack",
                                "title": "Canonic phrase for intent:intent.common.greetings",
                                "value": "Canonic phrase for intent:intent.common.greetings"
                            },
                            {
                                "type": "imBack",
                                "title": "¿Cómo puedo acceder a Mi Movistar?",
                                "value": "¿Cómo puedo acceder a Mi Movistar?"
                            }
                        ]
                    }
                }
            ],
            "channelData": {
                "hasMoreMessages": false,
                "correlator": "6ed5ed79-cd88-415e-9135-654417fef9b6"
            },
            "replyToId": "DF8d619NDYp3ywW1ew9QFK-fr|0000002"
        }
    }

Docs:

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

aura-mocks-whatsapp-api plugin

Plugin that mocks WhatsApp.

Description

The aura-mocks-whatsapp-api plugin simulates aura-bridge for aura-bot WhatsApp callbacks and adds several useful endpoints for the QA team and performance testing.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-whatsapp-api

This is part of aura-mocks-server project.

Endpoints API

Enpoint	Method	Group	description
/whatsapp/messages	GET	Whatsapp	Get messages
/whatsapp/messages	POST	Whatsapp	Add new message
/whatsapp/messages	DELETE	Whatsapp	Delete messages
/whatsapp/messages/:id	PUT	Whatsapp	Add new read message
/whatsapp/read-messages	GET	Whatsapp	Get read messages
/whatsapp/read-messages	POST	Whatsapp	Add new read message
/whatsapp/read-messages	DELETE	Whatsapp	Delete readmessages
/whatsapp/no-notification/messages	POST	Whatsapp	Add new message
/whatsapp/no-notification/messages/:id	PUT	Whatsapp	Add new read message
/whatsapp/4p/:error/messages	POST	Whatsapp	Add new message and return error
/whatsapp/4p/:error/messages/:id	PUT	Whatsapp	Add new read message
/whatsapp/:error/messages	POST	Whatsapp	Add new message and return error
/whatsapp/:error/messages/:id	PUT	Whatsapp	Add new read message

GET: /whatsapp/messages

Get messages from WhatsApp. The query param to is mandatory.

POST: /whatsapp/messages

Add new message for WhatsApp.

{
    "to": "34666666660",
    "text": "Testing POST /whatsapp/messages"
}

DELETE: /whatsapp/messages

Delete messages from WhatsApp. The query param to is mandatory.

PUT: /whatsapp/messages/:id

Add new read message for WhatsApp.

{
    "to": "34666666660",
    "text": "Testing PUT /whatsapp/messages/:id"
}

GET: /whatsapp/read-messages

Get read messages from WhatsApp. The query param to is mandatory.

POST: /whatsapp/read-messages

Add new read message for WhatsApp.

{
    "to": "34666666660",
    "text": "Testing POST /whatsapp/read-messages"
}

DELETE: /whatsapp/read-messages

Delete read messages from WhatsApp. The query param to is mandatory.

POST: /whatsapp/no-notification/messages

Add new message for WhatsApp.

{
    "to": "34666666660",
    "text": "Testing POST /whatsapp/no-notification/messages"
}

PUT: /whatsapp/no-notification/messages/:id

Add new read message for WhatsApp.

{
    "to": "34666666660",
    "text": "Testing PUT /whatsapp/no-notification/messages/:id"
}

POST: /whatsapp/4p/:error/messages

Add new message and return status code error.

{
    "to": "34666666660",
    "text": "Testing POST /whatsapp/4p/:error/messages"
}

PUT: /whatsapp/4p/:error/messages/:id

Add new read message for WhatsApp.

{
    "to": "34666666660",
    "text": "Testing PUT /whatsapp/4p/:error/messages/:id"
}

POST: /whatsapp/:error/messages

Add new message and return status code error and error message.

{
    "to": "34666666660",
    "text": "Testing POST /whatsapp/:error/messages"
}

PUT: /whatsapp/:error/messages/:id

Add new read message for WhatsApp.

{
    "to": "34666666660",
    "text": "Testing PUT /whatsapp/:error/messages/:id"
}

Docs:

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

whatsapp-client-service plugin

Technical description of whatsapp-client-service plugin

Introduction

whatsapp-client-service plugin contains the services and utilities related to the WhatsApp channel. This plugin also contains the WhatsApp client to send messages to WhatsApp through Kernel.

The specific environment variables for this plugin are located at whatsapp-client-service plugin configuration.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
prometheus	PluginType.Service	Metrics client for Prometheus

Provides components (IOC)

Name	Type	Description
whatsappClient	PluginType.Client	WhatsApp client

whatsappClient plugin

The WhatsappClient class extends from the AuraBridgeClientOAuthTokens class to obtain the access tokens used in OpenId authentication necessary to perform communications with the Kernel API.

The WhatsappClient allows sending requests to WhatsApp through the Kernel API and is responsible for managing and refreshing all the access tokens of the whatsapp channel type.

Management of multiple Kernel WhatsApp APIs

WhatsappClient is able to handle multiple versions of Kernel WhatsApp APIs. Every channel could have in its configuration a version field with the Kernel WhatsApp API version, and this is the version to be used. By default, if no version is configured, WhatsappClient will use v1. Currently, v1 and v2 are supported.

Configuration by channel

The whatsApp.client field allows the configuration of WhatsappClient options. The interface for this field is defined as follows:

export interface FPClientModel {
    /** Client id */
    id: string;
    /** Client secret */
    secret: string;
    /** Client purposes */
    purposes?: string;
    /** Client scopes */
    scopes?: string;
    /** Client version */
    version?: string;
}

Example:

{
    ...
    "type": "whatsapp",
    "whatsapp": {
        "client": {
            "id": "client-id",              // Client id
            "purposes": "client-purposes",  // Client purposes
            "scopes": "client-scopes",      // Client scopes
            "secret": "client-secret"       // Client secret
            "version": "v1"
        }
    }
}

Error management policy

The WhatsappClient defines its own retry policy when an error occurs.

export const whatsappClientErrorPolicy: IndexedErrorPolicy = {
    // Client code (whatsapp)
    responseCode: {
        429: {
            description: 'The frequency limit was reached',
            recoverable: true
        },
        500: {
            description: 'Generic error-Message failed to send because of an unknown error.Try again later.',
            recoverable: true
        },
        1015: {
            description: 'Customer frequency limit reached.',
            recoverable: true
        },
        1016: {
            description: 'System overloaded.',
            recoverable: true
        },
        1017: {
            description: 'It is not the main master node.',
            recoverable: true
        },
        1018: {
            description: 'It is not a primary main app.',
            recoverable: true
        }
    },
    // Http status (4P)
    status: {
        // 404
        [StatusCodes.NOT_FOUND]: {
            description: ReasonPhrases.NOT_FOUND,
            recoverable: true
        },
        // 408
        [StatusCodes.REQUEST_TIMEOUT]: {
            description: ReasonPhrases.REQUEST_TIMEOUT,
            recoverable: true
        },
        // 409
        [StatusCodes.CONFLICT]: {
            description: ReasonPhrases.CONFLICT,
            recoverable: true
        },
        // 413
        [StatusCodes.REQUEST_TOO_LONG]: {
            description: ReasonPhrases.REQUEST_TOO_LONG,
            recoverable: true
        },
        // 500
        [StatusCodes.INTERNAL_SERVER_ERROR]: {
            description: ReasonPhrases.INTERNAL_SERVER_ERROR,
            recoverable: true
        },
        // 502
        [StatusCodes.BAD_GATEWAY]: {
            description: ReasonPhrases.BAD_GATEWAY,
            recoverable: true
        },
        // 503
        [StatusCodes.SERVICE_UNAVAILABLE]: {
            description: ReasonPhrases.SERVICE_UNAVAILABLE,
            recoverable: true
        },
        // 504
        [StatusCodes.GATEWAY_TIMEOUT]: {
            description: ReasonPhrases.GATEWAY_TIMEOUT,
            recoverable: true
        }
    }
};

The WhatsappClient retry policy differences between two types of errors:

Errors generated by WhatsApp API, associated with the responseCode error field.
Errors generated by Kernel API, associated with the status error field.

Docs:

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

whatsapp-service plugin

Technical description of whatsapp-service plugin

Introduction

whatsapp-service plugin contains the services and utilities related to the WhatsApp channel. This plugin also contains the WhatsApp client to send messages to WhatsApp through Kernel.

The specific environment variables for this plugin are located at whatsapp-service plugin configuration.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
prometheus	PluginType.Service	Metrics client for Prometheus
whatsappClient	PluginType.Client	WhatsApp client

Provides components (IOC)

Name	Type	Description
whatsappService	PluginType.Service	Services and utilities for WhatsApp channel

whatsappService

The WhatsappService class provides utilities related to the WhatsApp client.

messageFactory (WhatsappMessageFactory): Factory to create different types of WhatsApp messages.
interactiveMessageUtils (WhatsappInteractiveMessageUtils): Utilities for interactive message management.
whatsappUtils (WhatsappUtils): Utilities for WhatsApp channel.

Find here further information about WhatsApp API section.

Docs:

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

Agent deployment plugin

Agent Deployment plugin description for aura-configuration-api

Introduction

The agent-deployment plugin defines services associated with the management of agents base in aura-configuration-api server.

All these services are defined in the _agents-deployment namespace (/agents-deployment).

Servers definition

By default, the servers defined in the swagger include the base path (for v2):
/aura-services/v2/configuration.

Therefore, in order to access the services, the base path and service path must be used.

Examples:

aura-services/v2/configuration/agents-deployment
aura-services/v2/configuration/agents-deployment/{agentDeploymentId}

Endpoints

Path	Method	Description
/agents-deployment/	GET	Get all agent deployment information
/agents-deployment/	POST	Add a new agent deployment
/agents-deployment/{agentDeploymentId}	GET	Get agent deployment information using agent deployment id
/agents-deployment/{agentDeploymentId}	PUT	Replace agent deployment information associated to agent deployment id
/agents-deployment/{agentDeploymentId}	PATCH	Update some fields of agent deployment information using agent deployment id
/agents-deployment/{agentDeploymentId}	DELETE	Delete agent deployment information using agent deployment id

You can read the complete documentation of each service in the aura-configuration-api agent deployment swagger file.

Retrieving information from agents base

Retrieving specific fields from agent deployment information

It is possible to get only a specific list of fields for agent deployment information, reducing the amount of data transmitted when necessary, using the includeFields query parameter.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/agents-deployment?includeFields=id,name' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: XXX'

Response example:

[
    {
        "id": "cd2b534c-16c3-4d89-a87e-ec45d3939232",
        "name": "mongo-device-recommender-agent",
    }
]

Excluding fields in agent deployment information

It is also possible to exclude agent deployment information fields using the excludeFields query parameter.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/agents-deployment?excludeFields=metadata,name' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX'

Response example:

[
    {
        "id": "1870fa4a-bcc4-4a7c-88fc-c0194555a076",
        "config": {},
        "secrets": {},
        "image": "auraregistry.azurecr.io/aura/atria-agent-mongo-devices-recommender",
        "tag": "1.0.0"
    }
]

Filtering agent deployment information

It is possible to filter agent deployment information using the filter query parameter.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/agents-deployment?filter=tag:1.0.0' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX'

Database

The complete definition of the data model can be found in agent deployment collection section within the administration module.

Docs:

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

configuration-service plugin

Description of the configuration-service plugin

Introduction

The configuration-service plugin manages the configuration of agents.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager

Provides components (IOC)

Name	Type	Description
agentsConfiguration	PluginType.Service	Agents configuration

Docs:

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

TV content get info plugin

Complex Logic Framework plugin for the TV content get info use case

Introduction

The TV content get info plugin resolves the request from a user getting information about channel.

It includes some key steps described in the following sections.

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data has an error, the resource returned is:
tv:video.model-validation.request.error.

Get content info about a channel

The content get info about a channel is based in the received entities.

The content get info stage follows the steps set below:

Build the `search_query` param

The content get info builds a search_query param using label values of first entity ent.audiovisual_channel to prioritize channels searching. If the label value is null for an entity, then the canon value is used.

Entity used to search is: ent.audiovisual_channel

The entity will be used as follows:

If there are channel entities and other entities, then the search_query parameter is built only using the first channel entity.
- For instance: channel_name: "La 1"
If there are not entities allowed, then a query param to content get info is not built.

With this prioritization, the system builds a search_query param that will be used to call the video query API for searching purposes.

Video query API

After preparing the search_query parameter, we will make a query to Video Contents normalized Kernel API by searching through all the possible fields with the remaining words.

To make this API call, several parameters are needed, which are described below:

user_id: Input data[aura_user][user_id]
administrative_number: Input data[app_context][user][account_number]
access_token: Input data[aura_user][access_token]
scopes: Input data[aura_user][scopes]
purposes: Input data[aura_user][purposes]
device_type: Input data[app_context][device][type]
catalog_types: LIVE.
search_query: String with a custom search query based in the received entities.
show_series: series.
commercialization_types: List made by SVOD.
max_quality: Input data[app_context][device][max_quality]
order: personal
commercial_offer: Input data[app_context][user][profile] if exists. Otherwise, do not use this param.
live_at: UTC current time at which the request is made.
profile: Input data[app_context][user][video_profile_name] if exists. Otherwise, do not use this param.
current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

The fields current_region and profile may not be implemented in certain cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem, we should send these fields only when input data has this value.

Content get info response

When a user requests for getting content information about a channel, the following possible scenarios can occur for the response:

a. No content with channel info is received. The returned resource is tv:video.content-get-info.by-channel.no-results

b. Receive content with channel info. The returned resource is tv:video.content-get-info.by-channel.single-result

c. More than one type of content is received. The returned resource is tv:video.content-get-info.by-channel.multiple-results

d. The request does not contain any ent.audiovisual_channel entity. The returned resource is tv:video.content-get-info.by-channel.no-results

e. Receive an API error. The returned resource is tv:video.api.answer.error

Response

The response follows this response schema.

Where:

intent: input intent.
entities: input entities.
result_intent: This field is always MEDIA.SEARCH.
resources: List of response resources that includes three main parameters:
- type: Type of the response resource.
- name: Name of the response resource. Example: tv:video.content-get-info.by-channel.single-result
- params: This field returns any required parameter in the resource.
payload: Information provided by the Kernel API, when we make the content get info request. If we receive a response, this field includes the following parameters:
- type: The value of this field depends on the type of data included in the field data (info returned by the API):
  - If it is a value: details
  - If it is a list: content_list
- data: It returns the information provided by the Kernel API.
status: Final status request. This field includes the following parameters:
- code: Status code.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.
actions: Actions to follow with the result of request. This plugin could include the following actions:
- MAKE_SOUND: The target for this action is channel and its unique parameter is sound (with negative value assigned). This action is returned when we have the resource tv:video.content-get-info.by-channel.no-results
conditions: Condition for the actions to be applied.

Docs:

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

TV Conversational Search plugin

Complex Logic Framework plugin for the TV Conversational Search use case

Introduction

The TV Conversational Search plugin resolves requests from a user to obtain personalized recommendations for audiovisual content from Telefónica catalogs.

Intent: intent.conversational.search
Main result intents: MEDIA.SEARCH (default), CHANNEL.PLAY (when zapping to a live channel).

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data is invalid, the resource returned is:

tv:video.model-validation.request.error.

Entities used for search

The plugin works with the following entity types:

Entity type	Usage in search	Notes
`ent.audiovisual_query`	Yes	Free text query, multiple values accepted with `\|\|`.

Multiple entities & values:
You can repeat the same entity type multiple times and/or provide several values in a single entity using the \|\| separator.

Building the search query

The plugin constructs two query strings:

search_query → technical query sent to Kernel API:
- Group query and channel entities in parentheses.
- Joins different entity types with AND.
- Query: split on ||, trim each value, and join with OR inside the parentheses (no quotes).
- Example:
```
(mystery OR series)
```
search_query_response → a simplified, user-readable query string included in the payload and telemetry.

If no entities are present, the plugin returns a no results response.

API video query (Handler 4P)

Plugin calls Handler4P.tv_4p_handler.get_user_content_search(...) with the following parameters:

user_id: data[aura_user][user_id]
administrative_number: data[app_context][user][account_number]
access_token: data[aura_user][access_token]
scopes: data[aura_user][scopes]
purposes: data[aura_user][purposes]
device_type: data[app_context][device][type]
catalog_types:
- Default: VOD, LIVE, L7D
- Allowed: VOD, LIVE, L7D, LCH, LSR
- Filtered according to allowed_catalog_types of the device
search_query: built as explained above
show_series: series
profile: data[app_context][user][video_profile_name] (optional; only if present to avoid API 501 errors)
commercialization_types: [SVOD]
max_quality: data[app_context][device][max_quality] (optional)
current_region: data[app_context][location][currentRegion] (optional)
order: personal

Response logic

Depending on the number and type of results, the plugin builds different responses:

1. No results

Plays negative sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.conversational.search.no-results
Status: SUCCESS.NO_CONTENT

2. One result

Live channel:
- Payload: { type: details, data: <channel info> }
- Action: REMOTEON.ZAPTO (with params channelId and deviceId)
- Plays positive sound
- result_intent: CHANNEL.PLAY
- Resource: tv:video.conversational.search.single-result
Non-live content (VOD, L7D, etc.):
- Payload: details of the single item
- Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
- result_intent: MEDIA.SEARCH
- Resource: tv:video.conversational.search.by-default.simple-result

3. Multiple results

Payload: list of items
Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.conversational.search.multiple-results (with param query_displayed)

Resources returned

The TV Recommend plugin may return the following resources:

tv:video.model-validation.request.error → input validation error
tv:video.api.answer.error → API Video error
tv:video.conversational.search.no-results → no content found
tv:video.conversational.search.by-default.simple-result → one non-live result
tv:video.conversational.search.multiple-results → multiple results
tv:video.conversational.search.display.single-result → one live channel (tune channel)

Payload and actions

Payload:
- type: details (single item) or content_list (multiple items)
- data: item(s) from Kernel API
- For multiple results: includes search_query (human-readable string)
Actions:
- Sound feedback (positive/negative)
- For a single live channel: {"name": "REMOTEON.ZAPTO", "params": {"channelId": "$channelId", "deviceId": "$deviceId"}, "target": "stb"}

Status codes

status: Final status request. This field includes the following parameters:
- code: Status code with value: SUCCESS, SUCCESS.NO_CONTENT or ERROR.INTERNAL.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.

Example behavior

“Recommend me something”
- for a single live channel result → CHANNEL.PLAY tune channel with live channel.
- for a multiple results → MEDIA.SEARCH with tv:video.conversational.search.multiple-results.
- for any results → tv:video.conversational.search.no-results.

Docs:

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

TV display plugin

Complex Logic Framework plugin for the TV display use case

Introduction

The TV display plugin resolves the request from a user displaying a channel or content.

It includes some key steps described in the following sections.

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data has an error, the resource returned is:
tv:video.model-validation.request.error.

Display channel or content

The display channel or content is based in the received entities.

The display stage follows the steps set below:

Build the `search_query` param

The display plugin builds a search_query param using label values of entities to prioritize the searched channel content or video content. If the label value is null for an entity, then the canon value is used.

Entities used to search are grouped by:

Channel entities: ent.audiovisual_channel
Title entities: ent.audiovisual_documental_title, ent.audiovisual_film_title, ent.audiovisual_tvseries_title and ent.audiovisual_tvshow_title
Participant entities: ent.audiovisual_actor and ent.audiovisual_director
Genre entities: ent.audiovisual_genre and ent.audiovisual_subgenre

The priority to search using these entities is described as follows:

If there are channel entities and other entities, then the search_query parameter is built only using the first channel entity.
- For instance: channel_name: "La 1"
If there are title entities and other entities, then the search_query parameter is built only using title entities.
- For instance: title: ("Matrix" OR "La princesa prometida")
If there are participant entities and other entities, then the search_query parameter is built only using participant entities.
- All entities (ent.audiovisual_actor and ent.audiovisual_director) are used for fields actor and director.
- For instance: actor: ("Tom Cruise" OR "Martin Scorsese") OR director: ("Tom Cruise" OR "Martin Scorsese")
If there are genre entities and other entities, then the search_query parameter is built only using genre entities.
- The ent.audiovisual_genre is used with the field content_category and the ent.audiovisual_subgenre with field genre.
- For instance: content_category: ("MOV" OR "SER" OR "DOC") AND genre: ("Terror" OR "Acción")
If there are not any entities allowed, then a query param to search is not built.

With this prioritization, the system builds a search_query param that will be used to call the API video query for searching purposes.

Video query API

After preparing the search_query parameter, we will make a query to Video Contents normalized Kernel API by searching through all the possible fields with the remaining words.

To make this API call, several parameters are needed, which are described below:

user_id: Input data[aura_user][user_id]
administrative_number: Input data[app_context][user][account_number]
access_token: Input data[aura_user][access_token]
scopes: Input data[aura_user][scopes]
purposes: Input data[aura_user][purposes]
device_type: Input data[app_context][device][type]
catalog_types: use LIVE value if there are channel entities, else use VOD,LIVE,L7D value for title entities, participant entities or genre entities.
search_query: String with a custom search query based in the received entities.
show_series: series.
commercialization_types: List made by SVOD.
max_quality: Input data[app_context][device][max_quality]
order: personal
commercial_offer: Input data[app_context][user][profile] if exists. Otherwise, do not use this param.
live_at: if there are channel entities use UTC current time at which the request is made. Otherwise, do not use this param.
profile: Input data[app_context][user][video_profile_name] if exists. Otherwise, do not use this param.
current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

Display response

When a user requests for displaying a channel, the following possible scenarios can occur for the response:

a. Receive no results at all. Then, it executes the contingency search.

b. Receive content with channel info. The returned resource is tv:video.display.by-channel.single-result

c. Receive content with channel info has already been broadcast or recieve a video content. The returned resource is video.display.by-default.single-result

d. Receive content with channel info that has not been broadcast yet or the content does not have enough information to be played. The returned resource is video.display.by-default.detail-result

e. Receive more than one type of content with channel info or video content. The returned resource is tv:video.display.by-default.multiple-results

f. Receive an API error. The returned resource is tv:video.api.answer.error

Contingency search

The contingency search is a more in-depth search to get, at least, one response. This search uses the entire utterance in every search field.

Contingency search is based on the following steps:

Normalization section

When a request is made by the user, it is possible to find certain words with no real value for Aura, so the system is not able to redirect them to obtain a response. For this reason, a list of forbidden words known as “ignore-words” will be declared, which will be eliminated.

The first step is to transform the entire utterance received as input to lowercase, removing all non-alphanumeric characters and separators. Once the utterance has been normalized, the words that belong to the list of “ignore-words” are eliminated.

This list is declared in a resource file called normalizer_rules.json. This file can be found in the following path: src.aura_clf_video.resources.[language].normalizer_rules.json Where [language] must be replaced by each language, for example: es-es.

If the language does not have the normalizer rule defined, it will be redirected to a default folder: src.aura_clf_video.resources.default.normalizer_rules.json

If, for example, the language is Spanish, the path to the resource where the normalization rules are defined will be: src.aura_clf_video.resources.es-es.normalizer_rules.json

Normalizer rules structure It is a dictionary where all the items are declared in a list as shown below:
```
{
  "ignore_items": [
    "ignore item 1",
    "ignore item 2"
  ]
}
```
Validation of resource content
The normalization is done sequentially, a previous rule cannot affect a succeeding one.

For example:
- The utterance is “ok aura some”.
- We define “aura” and also “ok aura” in the “ignore-words” list.
- If we remove “aura” firstly from the original utterance, we obtain the following normalized utterance: “ok some”. In this case, “ok aura” does not have any effect.
- In short, the correct order should be: first, remove “ok aura” and, after that, remove “aura”. In this case, we will obtain the final utterance as “some”.

“Ignore-words” will be automatically validated in order to prevent this behavior in every Pull Request.

If after normalization the normalized phrase is empty, the resource returned is: tv:video.display.contingency.no-results

API video query

After normalizing, we will query the Telefonica Kernel video API by searching through all possible fields with the remaining words.

To make this API call, a series of parameters are going to be needed, which are described below:

user_id: Input data[aura_user][user_id]
administrative_number: Input data[app_context][user][account_number]
access_token: Input data[aura_user][access_token]
scopes: Input data[aura_user][scopes]
purposes: Input data[aura_user][purposes]
device_type: Input data[app_context][device][type]
catalog_types: List that is made by VOD, LIVE and L7D.
search_query: Is a joint of the normalized phrase by OR operator. Use this format to search by any fields. Example: “La resistencia Shameless” the search_query is “(La OR resistencia OR Shameless)”.
show_series: series.
profile: Input data[app_context][user][video_profile_name]. This field may not be implemented in some cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem, we should send this field only when input data has this value.
commercialization_types: List made by SVOD.
max_quality: Input data[app_context][device][max_quality]
order: personal
current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

Contingency search response

When performing a contingency search, there are four possible scenarios for the response received by the search:

a. Receive an API error. The returned resource is tv:video.api.answer.error

b. Receive no results at all. The returned resource is tv:video.display.contingency.no-results

c. Receive a single result. The returned resource is tv:video.display.contingency.single-result

d. Receive several results. The returned resource is tv:video.display.contingency.multiple-results

Response

The response follows this response schema.

Where:

intent: input intent.
entities: input entities.
result_intent: This field is always MEDIA.SEARCH except when the resource is:
- video.display.by-channel.single-result, then the field value is CHANNEL.PLAY
- video.display.by-default.single-result, then the field value is CONTENT.PLAY
resources: List of response resources that includes three main parameters:
- type: Type of the response resource.
- name: Name of the response resource. Example: tv:video.display.by-channel.single-result
- params: This field returns any required parameter in the resource.
payload: Information provided by the Kernel API, when we make the display request. If we receive a response, this field includes the following parameters:
- type: The value of this field depends on the type of data included in the field data (info returned by the API):
  - If it is a value: details
  - If it is a list: content_list
- data: It returns the information provided by the Kernel API.
status: Final status request. This field includes the following parameters:
- code: Status code.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.
actions: Actions to follow with the result of request. This plugin could include the following actions:
- REMOTEON.ZAPTO: The target for this action is stb and its parameters are:
  - channelId, channelNumber and deviceId when we have the resource tv:video.display.by-channel.single-result
- REMOTEON.PLAYTO: The target for this action is stb and its parameters are:
  - contentId, deviceId, liveProgramId and catalogType when we have the resource video.display.by-default.single-result and content has already been broadcast.
  - contentId, deviceId and catalogType when we have the resource video.display.by-default.single-result and content is a video content.
- MAKE_SOUND: The target for this action is channel and its unique parameter is sound with the value:
  - positive when we have the resource tv:video.display.by-channel.single-result, video.display.by-default.single-result, video.display.by-default.detail-result, tv:video.display.by-default.multiple-results, tv:video.display.contingency.single-result, tv:video.display.contingency.multiple-results
  - negative when we have the resource tv:video.display.contingency.no-results and tv:video.api.answer.error.
conditions: Condition for the actions to be applied.

Docs:

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

TV none plugin

Complex Logic Framework plugin for the TV none use case

Introduction

The TV none plugin resolves the request from a user getting information about channel.

It includes some key steps described in the following sections.

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data has an error, the resource returned is:
tv:video.model-validation.request.error.

Contingency Search

The contingency search is a more in-depth search to get, at least, one response. This search uses the entire utterance in every search field.

Contingency search is based on the following steps:

Normalization section

If the language does not have the normalizer rule defined, it will be redirected to a default folder: src.aura_clf_video.resources.default.normalizer_rules.json

If, for example, the language is Spanish, the path to the resource where the normalization rules are defined will be: src.aura_clf_video.resources.es-es.normalizer_rules.json

Normalizer rules structure:
It is a dictionary where all the items are declared in a list as shown below:
```
{
  "ignore_items": [
    "ignore item 1",
    "ignore item 2"
  ]
}
```
Validation of resource content:
The normalization is done sequentially, a previous rule cannot affect a succeeding one.

For example:
- The utterance is “ok aura some”.
- We define “aura” and also “ok aura” in the “ignore-words” list.
- If we remove “aura” firstly from the original utterance, we obtain the following normalized utterance: “ok some”. In this case, “ok aura” does not have any effect.
- In short, the correct order should be: first, remove “ok aura” and, after that, remove “aura”. In this case, we will obtain the final utterance as “some”.

“Ignore-words” will be automatically validated in order to prevent this behavior in every Pull Request.

If after normalization the normalized phrase is empty, the resource returned is: tv:video.search.contingency.no-results

API video query

After normalizing, we will query the Telefonica Kernel video API by searching through all possible fields with the remaining words.

To make this API call, a series of parameters are going to be needed, which are described below:

user_id: Input data[aura_user][user_id]
administrative_number: Input data[app_context][user][account_number]
access_token: Input data[aura_user][access_token]
scopes: Input data[aura_user][scopes]
purposes: Input data[aura_user][purposes]
device_type: Input data[app_context][device][type]
catalog_types: List that is made by VOD, LIVE and L7D.
search_query: Is a joint of the normalized phrase by OR operator. Use this format to search by any fields. Example: “La resistencia Shameless” the search_query is “(La OR resistencia OR Shameless)”.
show_series: series.
profile: Input data[app_context][user][video_profile_name]. This field may not be implemented in some cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem, we should send this field only when input data has this value.
commercialization_types: List made by SVOD.
max_quality: Input data[app_context][device][max_quality]
order: personal
current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

Contingency search response

When performing a contingency search, there are four possible scenarios for the response received by the search:

a. Receive an API error. The returned resource is tv:video.api.answer.error

b. Receive no results at all. The returned resource is tv:video.search.contingency.no-results

c. Receive a single result. The returned resource is tv:video.search.contingency.single-result

d. Receive several results. The returned resource is tv:video.search.contingency.multiple-results

Response

The response follows this response schema.

Where:

intent: input intent.
entities: input entities.
result_intent: This field is always MEDIA.SEARCH because it is the response associated to this domain.
resources: List of response resources that includes three main parameters:
- type: Type of the response resource.
- name: Name of the response resource. Example: tv:video.search.contingency.single-result
- params: This field returns any required parameter in the resource.
payload: Information provided by the Kernel API, when we make the search request. If we receive a response. This field includes the following parameters:
- type: The value of this field depends on the type of data included in the field data (info returned by the API):
  - If it is a value: details
  - If it is a list: content_list
- data: It returns the information provided by the Kernel API.
status: Final status request. this field includes field the following parameters:
- code: Status code.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.
actions: Actions to follow with the result of request.
conditions: Condition for the actions to be applied.

Docs:

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

Complex Logic Framework plugin for the TV Recommend use case

Introduction

The TV Recommend plugin resolves requests from a user to obtain personalized recommendations for audiovisual content from Telefónica catalogs.

Intent: intent.tv.recommend
Main result intents: MEDIA.SEARCH (default), CHANNEL.PLAY (when zapping to a live channel).

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data is invalid, the resource returned is:

tv:video.model-validation.request.error.

Entities used for search

The plugin works with the following entity types:

Entity type	Usage in search	Notes
`ent.audiovisual_channel`	Yes	Multiple values accepted, separated by `\|\|`.
`ent.audiovisual_person`	Yes	For participants (actors, directors, presenters, etc.), multiple values accepted with `\|\|`.
`ent.audiovisual_query`	Yes	Free text query, multiple values accepted with `\|\|`.

Multiple entities & values:
You can repeat the same entity type multiple times and/or provide several values in a single entity using the \|\| separator.

Building the search query

The plugin constructs two query strings:

search_query → technical query sent to Kernel API:
- Group query and channel entities in parentheses.
- Joins different entity types with AND.
- Query: split on ||, trim each value, and join with OR inside the parentheses (no quotes).
- Channel: trim each value, wrap each value in quotes, and join with OR inside the parentheses.
- Person: trim each value, wrap each value in quotes, and join with AND (no group parentheses).
- Example:
```
("La 1" OR "La 2") AND "Brad Pitt" AND (mystery OR series)
```
search_query_response → a simplified, user-readable query string included in the payload and telemetry.

If no entities are present, the plugin returns a no results response.

API video query (Handler 4P)

Plugin calls Handler4P.tv_4p_handler.get_user_content_search(...) with the following parameters:

user_id: data[aura_user][user_id]
administrative_number: data[app_context][user][account_number]
access_token: data[aura_user][access_token]
scopes: data[aura_user][scopes]
purposes: data[aura_user][purposes]
device_type: data[app_context][device][type]
catalog_types:
- Default: VOD, LIVE, L7D
- Allowed: VOD, LIVE, L7D, LCH, LSR
- Filtered according to allowed_catalog_types of the device
search_query: built as explained above
show_series: series
profile: data[app_context][user][video_profile_name] (optional; only if present to avoid API 501 errors)
commercialization_types: [SVOD]
max_quality: data[app_context][device][max_quality] (optional)
current_region: data[app_context][location][currentRegion] (optional)
order: personal

Response logic

Depending on the number and type of results, the plugin builds different responses:

1. No results

Plays negative sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.recommend.no-results
Status: SUCCESS.NO_CONTENT

2. One result

Live channel:
- Payload: { type: details, data: <channel info> }
- Action: REMOTEON.ZAPTO (with params channelId and deviceId)
- Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
- result_intent: CHANNEL.PLAY
- Resource: tv:video.recommend.display.single-result
Non-live content (VOD, L7D, etc.):
- Payload: details of the single item
- Plays positive sound
- result_intent: MEDIA.SEARCH
- Resource: tv:video.recommend.by-default.simple-result

3. Multiple results

Payload: content list and search_query (search query response string)
Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.recommend.multiple-results (with param query_displayed)

Resources returned

The TV Recommend plugin may return the following resources:

tv:video.model-validation.request.error → input validation error
tv:video.api.answer.error → API Video error
tv:video.recommend.no-results → no content found
tv:video.recommend.by-default.simple-result → one non-live result
tv:video.recommend.multiple-results → multiple results
tv:video.recommend.display.single-result → one live channel (tune channel)

Payload and actions

Payload:
- type: details (single item) or content_list (multiple items)
- data: item(s) from Kernel API
- For multiple results: includes search_query (human-readable string)
Actions:
- Sound feedback (positive/negative)
- For a single live channel: {"name": "REMOTEON.ZAPTO", "params": {"channelId": "$channelId", "deviceId": "$deviceId"}, "target": "stb"}

Status codes

status: Final status request. This field includes the following parameters:
- code: Status code with value: SUCCESS, SUCCESS.NO_CONTENT or ERROR.INTERNAL.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.

Example behavior

“Recommend me something”
- for a single live channel result → CHANNEL.PLAY tune channel with live channel.
- for a multiple results → MEDIA.SEARCH with tv:video.recommend.multiple-results.
- for any results → tv:video.recommend.no-results.

Docs:

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

TV Retrieve plugin for LLM Search UC

Complex Logic Framework TV Retrieve plugin for the TV LLM Search UC

Introduction

The TV Retrieve plugin for LLM Search UC resolves requests from a user to search and retrieve audiovisual content from Telefónica catalogs.

Intent: intent.tv.retrieve
Main result intents: MEDIA.SEARCH (default), CHANNEL.PLAY (when zapping to a live channel).

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data is invalid, the resource returned is:

tv:video.model-validation.request.error.

Entities used for search

The plugin works with the following entity types:

Entity type	Usage in search	Notes
`ent.audiovisual_channel`	Yes	Multiple values accepted, separated by `\|\|`.
`ent.audiovisual_person`	Yes	For participants (actors, directors, presenters, etc.), multiple values accepted with `\|\|`.
`ent.audiovisual_query`	Yes	Free text query, multiple values accepted with `\|\|`.

Multiple entities & values:
You can repeat the same entity type multiple times and/or provide several values in a single entity using the \|\| separator.

Building the search query

The plugin constructs two query strings:

search_query → technical query sent to Kernel API:
- Group query and channel entities in parentheses.
- Joins different entity types with AND.
- Query: split on ||, trim each value, and join with OR inside the parentheses (no quotes).
- Channel: trim each value, wrap each value in quotes, and join with OR inside the parentheses.
- Person: trim each value, wrap each value in quotes, and join with AND (no group parentheses).
- Example:
```
("La 1" OR "La 2") AND "Brad Pitt" AND (mystery OR series)
```
search_query_response → a simplified, user-readable query string included in the payload and telemetry.

If no entities are present, the plugin returns a no results response.

API video query (Handler 4P)

Plugin calls Handler4P.tv_4p_handler.get_user_content_search(...) with the following parameters:

user_id: data[aura_user][user_id]
administrative_number: data[app_context][user][account_number]
access_token: data[aura_user][access_token]
scopes: data[aura_user][scopes]
purposes: data[aura_user][purposes]
device_type: data[app_context][device][type]
catalog_types:
- Default: VOD, LIVE, L7D
- Allowed: VOD, LIVE, L7D, LCH, LSR
- Filtered according to allowed_catalog_types of the device
search_query: built as explained above
show_series: series
profile: data[app_context][user][video_profile_name] (optional; only if present to avoid API 501 errors)
commercialization_types: [SVOD]
max_quality: data[app_context][device][max_quality] (optional)
current_region: data[app_context][location][currentRegion] (optional)

Response logic

Depending on the number and type of results, the plugin builds different responses:

1. No results

Plays negative sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.retrieve.no-results
Status: SUCCESS.NO_CONTENT

2. One result

Live channel:
- Payload: { type: details, data: <channel info> }
- Action: REMOTEON.ZAPTO (with params channelId and deviceId)
- Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
- result_intent: CHANNEL.PLAY
- Resource: tv:video.retrieve.display.single-result
Non-live content (VOD, L7D, etc.):
- Payload: details of the single item
- Plays positive sound
- result_intent: MEDIA.SEARCH
- Resource: tv:video.retrieve.by-default.simple-result

3. Multiple results

Payload: content list and search_query (search query response string)
Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.retrieve.multiple-results (with param query_displayed)

Resources returned

The TV Retrieve plugin for LLM Search UC may return the following resources:

tv:video.model-validation.request.error → input validation error
tv:video.api.answer.error → API Video error
tv:video.retrieve.no-results → no content found
tv:video.retrieve.by-default.simple-result → one non-live result
tv:video.retrieve.multiple-results → multiple results
tv:video.retrieve.display.single-result → one live channel (tune channel)

Payload and actions

Payload:
- type: details (single item) or content_list (multiple items)
- data: item(s) from Kernel API
- For multiple results: includes search_query (human-readable string)
Actions:
- Sound feedback (positive/negative)
- For a single live channel: {"name": "REMOTEON.ZAPTO", "params": {"channelId": "$channelId", "deviceId": "$deviceId"}, "target": "stb"}

Status codes

status: Final status request. This field includes the following parameters:
- code: Status code with value: SUCCESS, SUCCESS.NO_CONTENT or ERROR.INTERNAL.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.

Example behavior

“Put La 1” → detects ent.audiovisual_channel with value "La 1" → single live channel result → CHANNEL.PLAY tune channel with live channel.
“I want something with Brad Pitt” → detects ent.audiovisual_person with value "Brad Pitt" → multiple results → MEDIA.SEARCH with tv:video.retrieve.multiple-results.
“Mystery series” → detects audiovisual_query with value "Mystery series" → if no results → tv:video.retrieve.no-results.

Docs:

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

TV search plugin

Complex Logic Framework plugin for the TV search use case

Introduction

The TV search plugin resolves the request from a user searching a video content.

It includes some key steps described in the following sections.

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data has an error the resource returned is: tv:video.model-validation.request.error.

Filter invalid entities

The TV search plugin executes the step for entities validation listed below and prepares data before resolving the request:

Check that season/episode entity contains a number. In other case, it removes this entity.

Entertainment Search

The search of video content is based in the received entities.

The search stage follows the following steps:

Build the `search_query` param

The search builds a search_query param using label values of entities to prioritize the searched video content. If the label value is null for an entity, then the canon value is used.

Entities used to search are grouped by:

Title entities: ent.audiovisual_documental_title, ent.audiovisual_film_title, ent.audiovisual_tvseries_title and ent.audiovisual_tvshows_title
Participant entities: ent.audiovisual_actor and ent.audiovisual_director
Genre entities: ent.audiovisual_genre and ent.audiovisual_subgenre

The priority to search using these entities is described as follows:

If there are title entities and other entities, then the search_query parameter is built only using title entities.
- For instance: title: ("Matrix" OR "La princesa prometida")
If there are participant entities and other entities, then the search_query parameter is built only using participant entities.
- All entities (ent.audiovisual_actor and ent.audiovisual_director) are used for fields actor and director.
- For instance: actor: ("Tom Cruise" OR "Martin Scorsese") OR director: ("Tom Cruise" OR "Martin Scorsese")
If there are genre entities and other entities, then the search_query parameter is built only using genre entities.
- The ent.audiovisual_genre is used with the field content_category and the ent.audiovisual_subgenre with field genre.
- For instance: content_category: ("MOV" OR "SER" OR "DOC") AND genre: ("TE" OR "AC")
If there are not any entities allowed, then a query param to search is not built.

With this prioritization, the system builds a search_query param that will be used to call the API video query for searching purposes.

API video query

After preparing the search_query parameter, we will make a query to the Telefonica Kernel video API by searching through all the possible fields with the remaining words. To make this API call, several parameters are needed, which are described below:

user_id: Input data[aura_user][user_id]
administrative_number: Input data[app_context][user][account_number]
access_token: Input data[aura_user][access_token]
scopes: Input data[aura_user][scopes]
purposes: Input data[aura_user][purposes]
device_type: Input data[app_context][device][type]
catalog_types: List of allowed catalog types. The value can now be a list of catalog types provided by the device, as long as the values are one of the following predefined identifiers: VOD, LIVE, L7D, LCH, LSR.
search_query: String with a custom search query based in the received entities.
show_series: series.
profile: Input data[app_context][user][video_profile_name]. This field may not be implemented in certain cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem we should send this field only when input data has this value.
commercialization_types: List made by SVOD.
max_quality: Input data[app_context][device][max_quality]

Search response

When performing a search, the following possible scenarios can occur for the response received by the search:

a. Receive an API error. The returned resource is tv:video.api.answer.error.

b. Receive no results at all. Then, it executes the contingency search if it isn’t disabled by configuration. If it is disabled by configuration, the returned resource is tv:video.search.no-results.

c. Receive a single result by searching for one title entity. The returned resource is tv:video.search.by-title.simple-result and params with the value of the title searched for.

d. Receive several results by searching for one title entity. The returned resource is tv:video.search.by-title.multiple-results and params with the value of the title searched for.

e. Receive a single result by searching for one actor/director entity. The returned resource is tv:video.search.by-participant.simple-result and params with the value of the participant searched for.

f. Receive several results by searching for one actor/director entity. The returned resource is tv:video.search.by-participant.multiple-results and params with the value of the participant searched for.

g. Receive a single result by searching for one genre entity. The returned resource is tv:video.search.by-genre.simple-result and params with the value of the genre searched for.

h. Receive several results by searching for one genre entity. The returned resource is tv:video.search.by-genre.multiple-results and params with the value of the genre searched for.

i. Receive a single result by searching for one genre and one subgenre entity. The returned resource is tv:video.search.by-subgenre.simple-result and params with the value of the genre and subgenre searched for.

j. Receive several results by searching for one genre and one subgenre entity. The returned resource is tv:video.search.by-subgenre.multiple-results and params with the value of the genre and subgenre searched for.

k. Receive a single result in all other cases. The returned resource is tv:video.search.by-default.simple-result.

l. Receive several results in all other cases. The returned resource is tv:video.search.by-default.multiple-results.

Contingency search

The contingency search is a more in-depth search to get, at least, one response. This search uses the entire utterance in every search field.

Contingency search is based on the following steps:

Normalization section

If the language does not have the normalizer rule defined, it will be redirected to a default folder: src.aura_clf_video.resources.default.normalizer_rules.json

If, for example, the language is Spanish, the path to the resource where the normalization rules are defined will be: src.aura_clf_video.resources.es-es.normalizer_rules.json

Normalizer rules structure It is a dictionary where all the items are declared in a list as shown below:
```
{
  "ignore_items": [
    "ignore item 1",
    "ignore item 2"
  ]
}
```
Validation of resource content
The normalization is done sequentially, a previous rule cannot affect a succeeding one.

For example:
- The utterance is “ok aura some”.
- We define “aura” and also “ok aura” in the “ignore-words” list.
- If we remove “aura” firstly from the original utterance, we obtain the following normalized utterance: “ok some”. In this case, “ok aura” does not have any effect.
- In short, the correct order should be: first, remove “ok aura” and, after that, remove “aura”. In this case, we will obtain the final utterance as “some”.

“Ignore-words” will be automatically validated in order to prevent this behavior in every Pull Request.

If after normalization the normalized phrase is empty, the resource returned is: tv:video.search.contingency.no-results

API video query

After normalizing, we will query the Telefonica Kernel video API by searching through all possible fields with the remaining words.

To make this API call, a series of parameters are going to be needed, which are described below:

user_id: Input data[aura_user][user_id]
administrative_number: Input data[app_context][user][account_number]
access_token: Input data[aura_user][access_token]
scopes: Input data[aura_user][scopes]
purposes: Input data[aura_user][purposes]
device_type: Input data[app_context][device][type]
catalog_types: List of allowed catalog types. The value can now be a list of catalog types provided by the device, as long as the values are one of the following predefined identifiers: VOD, LIVE, L7D, LCH, LSR.
search_query: Is a joint of the normalized phrase by OR operator. Use this format to search by any fields. Example: “La resistencia Shameless” the search_query is “(La OR resistencia OR Shameless)”.
show_series: series.
profile: Input data[app_context][user][video_profile_name]. This field may not be implemented in some cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem, we should send this field only when input data has this value.
commercialization_types: List made by SVOD.
max_quality: Input data[app_context][device][max_quality]
current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

Contingency search response

When performing a contingency search, there are four possible scenarios for the response received by the search:

a. Receive an API error. The returned resource is tv:video.api.answer.error

b. Receive no results at all. The returned resource is tv:video.search.contingency.no-results

c. Receive a single result. The returned resource is tv:video.search.contingency.single-result

d. Receive several results. The returned resource is tv:video.search.contingency.multiple-results

Response

The response follows this response schema.

Where:

intent: input intent.
entities: input entities.
result_intent: This field is always MEDIA.SEARCH because it is the response associated to this domain.
resources: List of response resources that includes three main parameters:
- type: Type of the response resource.
- name: Name of the response resource. Example: tv:video.search.contingency.single-result
- params: This field returns any required parameter in the resource.
payload: Information provided by the Kernel API, when we make the search request. If we receive a response. This field includes the following parameters:
- type: The value of this field depends on the type of data included in the field data (info returned by the API):
  - If it is a value: details
  - If it is a list: content_list
- data: It returns the information provided by the Kernel API.
status: Final status request. this field includes field the following parameters:
- code: Status code.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.
actions: Actions to follow with the result of request.
conditions: Condition for the actions to be applied.

Docs:

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

TV VOD EPG information plugin

Complex Logic Framework plugin for the TV VOD EPG information use case

Introduction

The TV VOD EPG information plugin resolves the request from a user getting information about the TV content broadcasted in this specific moment

It includes some key steps described in the following sections.

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data has an error, the resource returned is:
tv:video.model-validation.request.error.

Get VOD EPG information about a playing content

The VOD EPG information about a playing content is based in the catalog type and content id.

To retrieve content information stage follows the steps set below:

Video query API

We will make a query to Video Contents normalized Kernel API to retrieve content.

To make this API call, several parameters are needed, which are described below:

user_id: Input data[aura_user][user_id]
access_token: Input data[aura_user][access_token]
catalog_type: Input data[app_context][playing][catalog_type] where “vod” is “VOD”, “l7d” and “record” is “L7D”, and “live” is “LIVE”.
administrative_number: Input data[app_context][user][account_number]
content_id: Input data[app_context][playing][content_id]
scopes: Input data[aura_user][scopes]
purposes: Input data[aura_user][purposes]
device_type: Input data[app_context][device][type]

VOD EPG information response

When a user requests for getting playing EPG information about a specific content, the following possible scenarios can occur for the response:

a. Receive a content with the EPG information and the request contain devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:tv.moreInfoTvDetail

b. Receive a content with the EPG information and the request does not contain any devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:carousel.info.contentDetail

c. Not received or not found in API any content with the EPG information and the request does not contain any devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:tv.moreInfoTvNotAllowed

d. Not received or not found in API any content with the EPG information and the request contain devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:tv.more_info.notAllowed

e. Receive an API error. The returned resource is tv:video.api.answer.error

Response

The response follows this response schema.

Where:

intent: input intent.
entities: input entities.
result_intent: This field is always MEDIA.SHEET_TV except when the resource is tv:carousel.info.contentDetail or tv:tv.more_info.notAllowed. In this case this field is MEDIA.SHEET_SECOND_SCREEN.
resources: List of response resources that includes three main parameters:
- type: Type of the response resource.
- name: Name of the response resource. Example: tv:tv.moreInfoTvDetail
- params: This field returns any required parameter in the resource.
payload: Information provided by the Kernel API, when we make the VOD EPG information request. For this case, If we receive a response, it is a value and then this field includes the following parameters:
- type: details
- data: It returns the information provided by the Kernel API.
status: Final status request. This field includes the following parameters:
- code: Status code.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.
actions: Actions to follow with the result of request.
conditions: Condition for the actions to be applied.

Docs:

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

aura-nlp-resolution-api plugin

Technical description of the aura-nlp-resolution-api plugin

Introduction

The aura-nlp-resolution-api plugin manages the communication with NLP APIs to return a recognizer response.

Consumes components (IOC)

Name	Type	Description
applicationConfiguration	PluginType.Service	Configuration of applications

Provides components (IOC)

Name	Type	Description
nlpResolutionApi	PluginType.API	Endpoints for the communication with NLP APIs

Aura – plugin

Docs:

agent-dispatcher-api plugin

Introduction

Consumes components (IOC)

Provides components (IOC)

Docs:

aura-generative-api plugin

Introduction

Consumes components (IOC)

Provides components (IOC)

Docs:

Aura bridge global plugins catalog

Global plugins repository

Docs:

Input validation video plugin

Docs:

Agents Manager API plugins

Introduction

Plugins management

Plugin basic structure

Plugins modules

Docs:

Aura gateway API plugins

Introduction

Plugins management

Plugin basic structure

Plugins modules

Docs:

Aura bridge plugins

Introduction

Types of plugins

Plugins management

Plugin basic structure

Plugins modules

API plugin module

Client module

Processor module

Processor flow

Declaring a destination

Sending a specific message on exception

Basic structure of the processor module

Service module

Plugins in specific channels

Plugins for WhatsApp channel

How to disable the WhatsApp channel

Plugins for async-callback

How to disable the async-callback functionality

Plugins for Genesys

How to disable the Genesys functionality

Docs:

Aura mocks server plugins

Introduction

Global plugins catalog

Types of plugins

Plugins management

Plugin basic structure

Plugins modules

Docs:

aura-mocks-administration-api plugin

Description

Administration Endpoints API

GET: /administration/heapStatistics

GET: /administration/heapSnapshot

GET: /administration/cache

GET: /administration/cache/stats

GET: /administration/plugins

Docs:

Agent Deployment Plugin

Introduction

Plugin Management

Plugin Basic Structure

Example index.ts

Example package.json

Plugin Modules

Docs:

aura-mocks-async-callback-api plugin

Description

Endpoints API

GET: /async-callback/notifications

Example `index.ts`

Example `package.json`