Aura – configuration

Docs:

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

Aura configuration API admin module

Admin module description for aura-configuration-api

Introduction

The administration module defines services associated with general administration tasks in aura-configuration-api server.

All these services are defined in the admin namespace (/admin).

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/admin/export
aura-services/v2/configuration/admin/import

Endpoints

Path	Method	Description
/admin/export	GET	Export configuration
/admin/import	POST	Import configuration

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

Export modules

Export all

To export all configuration, a GET call to /admin/export path must be made.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/admin/export' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX'

The service will respond with an ExportModel type object:

export interface ExportModel {
    /** Export metadata */
    metadata?: ExportMetadata;
    /** Export data */
    data?: ExportModelData;
}

metadata: It contains information related to the export itself: export date (data), current API version (apiVersion), bot configuration version (version).
data: Module data information indexed by module name.

Further information about ExportModel interface.

Export one or several specific modules

It is possible to export one or several modules using the module parameter in the call to /admin/export endpoint.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/admin/export?modules=channels' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX'

The result will have the same format as for complete export, but in the data field only includes the indicated modules.

Import modules

To import, data from a previous export must be used. The import can be from a complete or partial export of certain modules.

To import all configuration, a POST call to /admin/import path must be made.

curl --location --request POST 'http://aura-configuration-api:8999/aura-services/v2/configuration/admin/import' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX' \
--header 'Content-Type: application/json' \
--data-raw 'PREVIOUS_EXPORT_DATA'

How is an import processed?

During the import process, the following tasks are performed:

For each module to export, the import method of each of those modules is called.
The necessary mappers are executed to adapt the export version to the current server version (if applicable).
The objects of each module are validated with json schema.
The objects are inserted in the appropriate collection.

flowchart TD
    A[Import] --> B{Are there modules?}
    B --> |Yes| Mappers[Apply mappers]
    Mappers --> Validate[Validate using json schema]
    Validate --> Add[Add to collection]
    Add --> B
    B ---->|No| E[End]

Result of the import process

The import service will respond with an ImportResult type object:

export interface ImportResult {
    version: string;
    fromVersion: string;
    modules: ImportModuleResult[];
    status: ProcessStatus;
}

export interface ImportModuleResult {
    name: string;
    patches?: ImportPatches;
    result: ProcessResult;
}

export enum ProcessStatus {
    Ok = 'Ok',
    Error = 'Error'
}

version: Version to which the import has been made.
fromVersion: Original import version.
modules: array of ImportModuleResult with the result of the import of each module.
status: Status with the overall result of the import process. If any module fails the result will be Error.

Database

The database to store the aura-configuration-api information must be named with the following format:

aura-configuration-<ENVIRONMENT_NAME>-<BOT_VERSION>

Example for the ap-next environment and 7.4.0 version:

aura-configuration-ap-next-7-4-0

As a general rule, all those modules that define a DAO will have a collection associated with that module.The currently existing collections are described in the following sections.

Channels collection

This collection stores channel information using channels collection.

Fields

Field name	Type	Required
name	string	true
prefix	string	true
nlp	{}	true
nlp.enabled	boolean	true
auraBotCacheTTL	number	false
id	string	true
dialogLibraries	Array<{}>	false
actions	{}	false
actions.afterLogin	{}	false
actions.afterLogin.action	string	false
actions.afterLogin.type	string	false
actions.afterLogin.data	{}	false
actions.thirdPartyApp	{}	false
actions.thirdPartyApp.action	string	false
actions.thirdPartyApp.type	string	false
actions.thirdPartyApp.data	{}	false
actions.thirdPartyApp.contentType	string	false
rcs	{}	false
rcs.agentId	string	true
rcs.clientToken	string	true
rcs.email	string	true
rcs.privateKey	string	true
requestOptions	{}	false
requestOptions.fileAttachments	{}	false
requestOptions.fileAttachments.enabled	boolean	true
requestOptions.fileAttachments.enabledExtensions	Array<string[]>	false
requestOptions.fileAttachments.customProactiveDialogId	string	false
requestOptions.fileAttachments.validations	{}	false
requestOptions.requestOptionsVersion	{}	false
responseOptions	{}	false
responseOptions.dialogContext	{}	false
responseOptions.dialogContext.disabled	boolean	false
responseOptions.dialogContext.disabledMerge	boolean	false
responseOptions.dialogContext.normalizeTerms	boolean	false
responseOptions.dialogContext.defaultListType	’none’,‘ordinalCardinal’,‘ordinal’,‘cardinal’	false
responseOptions.dialogContext.promptChoice	{}	false
responseOptions.dialogContext.promptChoice.generateList	boolean	false
responseOptions.dialogContext.promptChoice.generate	’never’,‘always’,‘custom’	false
responseOptions.dialogContext.cardActions	{}	false
responseOptions.dialogContext.cardActions.generateList	boolean	false
responseOptions.dialogContext.cardActions.generate	’never’,‘always’,‘custom’	false
responseOptions.dialogContext.returnToClient	boolean	false
responseOptions.dialogContext.processFromClient	boolean	false
responseOptions.versions	{}	false
responseOptions.needsEmptyResponseEvent	boolean	false
responseOptions.outputMessageFormat	‘custom’,’enrich’,‘html5’,‘simple’,‘voice’	false
responseOptions.sendSpeak	boolean	false
responseOptions.disambiguationFormat	‘disabled’,‘prompts’,‘suggestions’	false
responseOptions.textConvert	boolean	false
responseOptions.suggestionType	‘actions’,‘attachment’	false
responseOptions.suggestionsNumber	number	false
responseOptions.tv.actions	Array<Action[]>	false
security	{}	false
security.anonymous	‘anonymous’,‘identifiable’	false
security.allowUserProfile	boolean	false
security.channelId	string	false
security.authScopes	string	true
security.authPurposes	string	true
security.federatedAuthentication	{}	false
security.federatedAuthentication.loginUrl	string	false
security.federatedAuthentication.auraIdSeparator	string	false
security.federatedAuthentication.loginCallback	{}	false
security.federatedAuthentication.loginCallback.method	string	false
security.federatedAuthentication.loginCallback.integrated	boolean	false
security.federatedAuthentication.loginCallback.endpoint	string	false
security.federatedAuthentication.loginCallback.queryParams	string	false
security.federatedAuthentication.loginCallback.headers	Array<string[]>	false
security.federatedAuthentication.loginCallback.body	string	false
security.federatedAuthentication.logoutCallback	{}	false
security.federatedAuthentication.logoutCallback.method	string	false
security.federatedAuthentication.logoutCallback.integrated	boolean	false
security.federatedAuthentication.logoutCallback.endpoint	string	false
security.federatedAuthentication.logoutCallback.queryParams	string	false
security.federatedAuthentication.logoutCallback.headers	Array<string[]>	false
security.federatedAuthentication.logoutCallback.body	string	false
security.termsAndConditions	{}	false
security.termsAndConditions.authenticated	{}	false
security.termsAndConditions.authenticated.version	string	true
security.termsAndConditions.authenticated.service	string	true
security.termsAndConditions.anonymous	{}	false
security.termsAndConditions.anonymous.version	string	true
security.termsAndConditions.anonymous.service	string	true
whatsapp	{}	false
whatsapp.client	{}	false
whatsapp.client.id	string	true
whatsapp.client.secret	string	true
whatsapp.client.purposes	string	false
whatsapp.client.scopes	string	false
whatsapp.phoneNumber	string	false
whatsapp.listOptions	{}	false
whatsapp.listOptions.type	‘button’,’enumeratedList’,’list’	false
whatsapp.listOptions.rules	Array<{}>	false
whatsapp.type	‘whatsapp’	false
metadata	{}	false
metadata.version	string	false
metadata.createdAt	string	false
metadata.updatedAt	string	false

Indexes

[
    {
        "version": 1,
        "name": "idx_channel_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 1.1,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    },
    {
        "version": 1,
        "name": "idx_channel_library",
        "keys": {
            "id": 1,
            "dialogLibraries.name": 1
        }
    }
]

skills collection

This collection stores skills information using skills collection.

Fields

Field name	Type	Required
id	string	true
name	string	true
appId	string	true
skillEndpoint	string	true
channels	Array<string[]>	true
disabled	boolean	false
external	boolean	false
metadata	{}	false
metadata.version	string	false
metadata.createdAt	string	false
metadata.updatedAt	string	false

Indexes

[
    {
        "version": 1.1,
        "name": "idx_skill_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 1.1,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    }
]

applications collection

This collection stores applications information using applications collection.

Fields

Field name	Type	Required
id	string	true
name	string	true
brand	string	true
disabled	boolean	false
agents	string[]	false
nlp.channelId	string	false
models.level	Level	false
models.presets	string[]	true
metadata.version	string	false
metadata.createdAt	string	false
metadata.updatedAt	string	false

Types

Type name	Type	Options
Level	string	Set the different levels of access for the application. It can only be changed by Aura Global Team

Indexes

[
    {
        "version": 1.5,
        "name": "idx_app_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 1.5,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    }
]

presets collection

This collection stores presets information using presets collection.

Fields

Root

Field name	Type	Required
id	string	true
name	string	true
description	string	false
group	string	false
session	Session	false
generative	Generative	false
rag	Rag	false
metadata	Metadata	false

Types

Action

Field name	Type	Required
name	string	true
target	string	false
params	object	false
postBack	object	false

Session

Field name	Type	Required
session.window	number	false
session.timeout	number	false

Generative

Field name	Type	Required
generative.model.id	string	false
generative.model.parameters.max_tokens	number	false
generative.model.parameters.temperature	number	false
generative.model.parameters.top_p	number	false
generative.injectionMaxLength	number	false
generative.prompts.template	string	false
generative.prompts.preamble.text	string	false
generative.prompts.preamble.args.name	string	false
generative.prompts.examples	string[]	false
generative.prompts.promptRegexClean	string	false
generative.prompts.promptMaxLength	number	false

RAG

Field name	Type	Required
rag.type	string	false
rag.references.maximum	number	false
rag.references.baseUrl	string	false
rag.model.id	string	false
rag.model.parameters.max_tokens	number	false
rag.model.parameters.temperature	number	false
rag.model.parameters.top_p	number	false
rag.stages.language	string	false
rag.stages.security.heuristics.example	string	false
rag.stages.security.maxLength	number	false
rag.stages.translation.prompt	string	false
rag.stages.translation.language	string	false
rag.stages.clean.prompt.default	string	false
rag.stages.clean.prompt.es	string	false
rag.stages.context.prompts.recreatedQuestion.default	string	false
rag.stages.context.prompts.recreatedQuestion.es	string	false
rag.stages.context.prompts.sameContext.default	string	false
rag.stages.context.prompts.sameContext.es	string	false
rag.stages.context.stickyContext	string	false
rag.stages.retrieval.sourceDataId	string	false
rag.stages.postFiltering.candidatesPostFiltering	string	false
rag.stages.postFiltering.prompt.default	string	false
rag.stages.postFiltering.prompt.es	string	false
rag.stages.generative.ragStrategy	string	false
rag.stages.generative.prompts.stuff.default	string	false
rag.stages.generative.prompts.stuff.es	string	false
rag.stages.generative.prompts.refine.default	string	false
rag.stages.generative.prompts.refine.es	string	false
rag.outputRefine.candidates	boolean	false
rag.outputRefine.filterOutputMetadata.map.fileType	string	false
rag.outputRefine.filterOutputMetadata.map.pageNumber	string	false
rag.outputRefine.filterOutputMetadata.groupBy	string	false
rag.outputRefine.filterOutputMetadata.aggregate	string	false
rag.outputRefine.filterOutputMetadata.outputFilter	string[]	false
rag.outputRefine.filterOutputMetadata.root	string[]	false

Metadata

Field name	Type	Required
metadata.version	string	false
metadata.createdAt	string	false
metadata.updatedAt	string	false

Indexes

[
    {
        "version": 1.10,
        "name": "idx_preset_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 1.10,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    },
    {
        "version": 1.10,
        "name": "idx_preset_name",
        "keys": {
            "name": 1
        },
        "unique": true
    }
]

suggestions collection

This collection stores suggestion information using suggestions collection.

Fields

Field name	Type	Required
id	string	true
name	string	true
intent	string	true
entities	Array<{}>	true
resources	Array<{}>	true

Indexes

[ 
    {
        "version": 2.1,
        "name": "idx_suggestion_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 2.1,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    },
    {
        "version": 2.1,
        "name": "idx_suggestion_name",
        "keys": {
            "name": 1
        },
        "unique": true
    }
]

tv-section collection

This collection stores TV Section information using the tv-sections collection.

Fields

Field name	Type	Required	Description
id	string	true	Unique identifier for the TV Section (UUID)
pid	string	false	External or process identifier
name	string	false	Name of the TV Section
canon	string	false	Canonical name of the TV Section
type	string	false	Section type (`app` or `section`)
metadata	object	false	Document metadata (version, creation and update dates)

Example of `metadata`:

Field	Type	Description
version	string	Configuration version when the document was created
createdAt	string	Creation date (ISO 8601)
updatedAt	string	Update date (ISO 8601)

Indexes

  {
    "version": 2.0,
    "name": "idx_tvsections_id",
    "keys": { "id": 1 },
    "unique": true
  },
  {
    "version": 2.0,
    "name": "idx_tvsections_pid",
    "keys": { "pid": 1 },
    "unique": true
  },
  {
    "version": 2.0,
    "name": "idx_updated_at",
    "keys": { "metadata.updatedAt": -1 }
  },
  {
    "version": 2.0,
    "name": "idx_tvsections_name",
    "keys": { "name": 1 },
    "unique": true
  }
]

agents collection

This collection stores agent information using the agents collection.

Fields

Field name	Type	Required	Description
id	string	true	UUID that identifies the agent univocally in Aura.
name	string	true	Name that identifies the agent univocally in Aura.
description	string	false	Agent description description.
communication	object	true	Communication configuration of the agent. See `communication` object.
flowConfig	object	false	Configuration of the agent flow.
deploymentName	string	false	Name of the deployment where the agent is running.
metadata	object	false	Document metadata (version, creation and update dates). See metadata object.

communication object (HTTP)

Field	Type	Description
endpoint	string	HTTP endpoint where the agent is listening to.
headers	object	HTTP headers associated with the agent.
communicationType	string	Communication type (`http`).
timeout	number	Timeout for the agent.
retries	number	Number of retries for the agent.

metadata object

Field	Type	Description
version	string	Configuration version when the document was created
createdAt	string	Creation date (ISO 8601)
updatedAt	string	Update date (ISO 8601)

Indexes

[
  {
    "version": 2.0,
    "name": "idx_agent_id",
    "keys": { "id": 1 },
    "unique": true
  },
  {
    "version": 2.0,
    "name": "idx_updated_at",
    "keys": { "metadata.updatedAt": -1 }
  },
  {
    "version": 2.0,
    "name": "idx_agent_name",
    "keys": { "name": 1 },
    "unique": true
  }
]

routing filters collection

This collection stores routing filters information using the routing-filters collection.

Fields

Field name	Type	Required	Description
id	string	true	UUID that uniquely identifies a routing filter in Aura.
name	string	true	Name that uniquely identifies a routing filter in Aura.
description	string	false	Routing Filter description.
type	string	true	Contains the type of filter. Currently, there is only one type ‘userId’.
entities	string[]	true	Contains at least one entity necessary to generate the data for the filter.
dataBase	object	true	Contains an object with the collections necessary to store and process data. See database object.
vars	object	true	Contains an object with the custom variables necessary for any phase of the filter. Encrypted field.
fields	object	true	Contains the field mapping for grouping and its relationship with the previously defined entities. Encrypted field.
sourceFilters	object	false	Contains an object to filter source data when loading from entity data. Encrypted field.
match	object	true	Contains an object with the MongoDB aggregation format that must return grouped data. Encrypted field.
summary	object	true	Contains an object with MongoDB command format to insert these obtained aggregates into a summary collection. Encrypted field.
actions	object[]	true	Contains an array of objects with the actions to be performed on the filtered data.
summaryFilter	object	true	Contains an object with MongoDB command format to select the records that meet the filter. Encrypted field.
metadata	object	false	Document metadata (version, creation and update dates). See metadata object.

database object

Field	Type	Description
dataFilterCollection	object	Contains an object with the name of the collection for raw data and its expiration in seconds. See filterCollection object.
dataSummaryCollection	object	Contains an object with the name of the collection for summary data and its expiration in seconds. See filterCollection object.

filterCollection object

Field	Type	Description
collectionName	string	Contains the name of the collection.
expiration	object	Contains the value in seconds of the expiration of the collection data.
indexes	object[]	A optional array with indexes in mongodb format. Example: `[{"seq1": 1}]`

metadata object

Field	Type	Description
version	string	Configuration version when the document was created
createdAt	string	Creation date (ISO 8601)
updatedAt	string	Update date (ISO 8601)

Indexes

[
    {
        "version": 2.2,
        "name": "idx_routing_filter_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 2.2,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    },
    {
        "version": 2.2,
        "name": "idx_routing_filter_name",
        "keys": {
            "name": 1
        },
        "unique": true
    }
]

A example with a complete filter definition

 {
        "name": "preset-filter-stb-conversational-search",
        "id": "4a879583-5f76-4e6b-87c1-6250e8743dda",
        "description": "Limit the number of messages per user in a month for stb conversational search preset",
        "type": "userId",
        "entities": [
            "GATEWAYMESSAGE"
        ],
        "vars": {
            "llm_execution_limit": 10
        },
        "dataBase": {
            "dataFilterCollection": {
                "collectionName": "dataFilterPreset",
                "expiration": 5356800,
                "indexes": [
                    {
                        "seqId": 1
                    }
                ]
            },
            "dataSummaryCollection": {
                "collectionName": "dataSummaryStbConvSearch",
                "expiration": 5356800,
                "indexes": [
                    {
                        "month": 1,
                        "total": 1,
                        "year": 1
                    },
                    {
                        "itemId": 1,
                        "month": 1,
                        "year": 1
                    }
                ]
            }
        },
        "fields": {
            "MatchingValue": "^ef3d0603-3fef-4109-a577-0ab92f9060df$",
            "forId": "USER_ID",
            "forMatchingField": "AURA_PRESET_NAME",
            "forTime": "MESSAGE_TM"
        },
        "sourceFilters": [
            {
                "field": "USER_ID",
                "op": "notEqual",
                "val": ""
            }
        ],
        "match": [
            {
                "$match": {
                    "fieldForMatch": "{{fields.forMatchingField}}",
                    "seqId": {
                        "$gt": "{{ctx.lastSeqId|number}}"
                    },
                    "valueForMatch": {
                        "$options": "i",
                        "$regex": "{{fields.MatchingValue}}"
                    }
                }
            },
            {
                "$group": {
                    "_id": {
                        "itemId": "$itemId",
                        "month": "$month",
                        "year": "$year"
                    },
                    "seqId": {
                        "$max": "$seqId"
                    },
                    "total": {
                        "$sum": 1
                    }
                }
            },
            {
                "$project": {
                    "_id": 0,
                    "itemId": "$_id.itemId",
                    "month": "$_id.month",
                    "seqId": 1,
                    "total": 1,
                    "year": "$_id.year"
                }
            }
        ],
        "summary": {
            "filter": {
                "itemId": "{{doc.itemId}}",
                "month": "{{doc.month|number}}",
                "year": "{{doc.year|number}}"
            },
            "options": {
                "upsert": true
            },
            "update": {
                "$inc": {
                    "total": "{{doc.total|number}}"
                },
                "$set": {
                    "expiresAt": "{{ctx.expiration|expires}}",
                    "month": "{{doc.month|number}}",
                    "updatedAt": "{{__DATE_NOW__}}",
                    "year": "{{doc.year|number}}"
                }
            }
        },
        "summaryFilter": {
            "filter": {
                "month": "{{ctx.month|number}}",
                "total": {
                    "$gt": "{{vars.llm_execution_limit|number}}"
                },
                "year": "{{ctx.year|number}}"
            },
            "options": {
                "projection": {
                    "_id": 0,
                    "itemId": 1,
                    "month": 1,
                    "total": 1,
                    "year": 1
                }
            }
        },
        "metadata": {
            "updatedAt": "2025-10-03T06:06:49.609Z",
            "version": "10.5.0"
        }
    }

Docs:

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

ATRIA components default configuration

Description of the default configuration (internal configuration) for ATRIA components

Introduction

The default configuration of ATRIA corresponds to the server configuration, that is, the internal configuration for ATRIA components.

Within a specific configuration type, parameters are organized by component:

Fields for atria-model-gateway configuration
Fields for atria-rag-server
Common fields for both components

1. Server configuration

Fields related to the internal configuration of ATRIA components

Target users: ATRIA development and installation teams

The default server configuration fields are non-modifiable by ATRIA constructors (excepting prompts)

1.1. Logging configuration

Configuration field shared between atria-model-gateway and atria-rag-server that enables the configuration of logs in a customizable and independent way

The logging configuration is done through a json configuration file that is set by default, as shown below.

{
  "version": 1,
  "disable_existing_loggers": false,
  "logging": {
    "handlers": {
      "hdl2": {
        "class": "logging.StreamHandler",
        "formatter": "json",
        "level": <AUTOCOMPLETED>
      }
    },
    "loggers": {
      "atria_model_gw": {
         "level": <AUTOCOMPLETED>,
         "handlers":[
            "hdl2"
         ],
         "filters":[],
         "propagate": false
      }
    },
    "root": {
      "level": <AUTOCOMPLETED>,
      "handlers": []
    }
  }
}

Fields

The main fields are explained below. However, for more details, developers are kindly requested to read the General Python logging documentation

Parameter	Subparameters	Definition	Type/Default values
`version`		Version of the logging configuration	number
`disable_existing_loggers`		Boolean value to indicate whether or not the already existing loggers when this call is made are disabled or not	boolean
`handlers`		Dictionary with different logging handlers. Each key is the name of a handler
	`class`	It is configured with Python logging handlers (See Python documentation)
	`formatter`	It configures the format of logs.	`json`, `string`, `console`, `simple`
	`level`	Level of the logging event. It must be filled with the labels	`INFO`, `ERROR`, `WARN` or `DEBUG`
`loggers`		Python dictionary in which each key is a logger name and each value is a dictionary describing how to configure the corresponding logger instance
	`level`	(Optional) Level of the logger.
	`handlers`	(Optional) List with the IDs of the handlers for this logger
	`filters`	(Optional) List with the IDs of the filters for this logger
`root`		Configuration for the root logger.
	`level`	(Optional) Level of the logger.
	`handlers`	(Optional) List with the IDs of the handlers for this logger

1.2. atria-model-gateway default configuration

This section includes the parameters configured by default in atria-model-gateway:

Defaults

General-purpose field with parameters to define the behavior of atria-model-gateway

Defaults fields

Parameter	Subparameters	Definition	Type/Default values
`session_params`		(Optional) Default values for a session	object
	`window`	(Optional) Session window	number
	`timeout`	(Optional) Session expiration time	number
`service_params`		(Optional) Default values for the server	object
	`preflight_max_age`	(Optional) Preflight max age	number
`messages`		(Optional) Message options	object
	`types`	(Optional) Types of messages.	list[string]
`openai_proxy`		Activate OpenAI proxy	boolean
`trimmer`		(Optional) Expression to trim the response	string

If the timeout is 0, the last conversation in the session will not be saved, but the session history will be used.

Defaults by default

The default configuration is described as follows:

defaults:
  # Default values for a session
  session_params:
    window: 2
    timeout: 3600

  # Default values for the server
  service_params:
    preflight_max_age: 86400

  # Message options
  messages:
    types:
      - feedback

  # Activate openai proxy
  openai_proxy: false

Redis

This section includes the Redis connection configuration for atria-model-gateway.

Redis fields

Parameter	Definition	Type/Default values
`connection_mode`	(Mandatory) Connection mode	`single`, `sentinel`, `cluster`
`pool_size`	(Mandatory) Pool size	number
`database`	(Mandatory) Database	number
`password`	(Mandatory) Password	string
`uri`	(Mandatory) URI name	string
`prefix`	(Mandatory) Prefix	string
`sleep_time`	(Optional) Sleep time	number
`max_retries`	(Optional) Maximum number of retries	number

Redis by default

The default configuration for Redis is described as follows:

redis:
  connection_mode: <AUTOCOMPLETED>
  pool_size: 100
  database: <AUTOCOMPLETED>
  password: <AUTOCOMPLETED>
  uri: <AUTOCOMPLETED>
  prefix: <AUTOCOMPLETED>

Redis Subscriber

This section includes the Redis event subscriber connection configuration for atria-model-gateway.

Redis subscriber fields

Parameter	Definition	Type/Default values
`connection_mode`	(Mandatory) Connection mode	`single`, `sentinel`, `cluster`
`pool_size`	(Mandatory) Pool size	number
`database`	(Mandatory) Database	number
`password`	(Mandatory) Password	string
`uri`	(Mandatory) URI name	string
`prefix`	(Mandatory) Prefix	string
`sleep_time`	(Optional) Sleep time	number
`max_retries`	(Optional) Maximum number of retries	number
`channels`	List of channels to subscribe to	list[string]

Redis subscriber by default

The default configuration for Redis is described as follows:

redis_subscriber:
  connection_mode: <AUTOCOMPLETED>
  pool_size: 100
  database: <AUTOCOMPLETED>
  password: <AUTOCOMPLETED>
  uri: <AUTOCOMPLETED>
  prefix: <AUTOCOMPLETED>
  channels:
    - "ApplicationConfiguration"
    - "PresetConfiguration"

Config API

Field with parameters for the API configuration for atria-model-gateway

Config API fields

Parameter	Definition	Type/Default values
`base_url`	(Mandatory) API config URL	string
`api_key`	(Mandatory) APIKey	string

Config API by default

The default configuration is described as follows:

aura_config_api:
  base_url: <AUTOCOMPLETED>
  api_key:  <AUTOCOMPLETED>

Allow logging prompts with INFO level

Field to allow logging prompt with INFO level for atria-model-gateway. It should only be used for debugging errors in environments where there are no debug logs. Due to the size of the prompts, this variable should be set to false once it is not needed.

Allow logging prompts

Parameter	Definition	Type/Default values
`allow_log_prompts`	Allow logging prompts	boolean

Allow logging prompts by default

The default configuration is described as follows:

allow_log_prompts: false

Models

Predefined AI models included in atria-model-gateway by default.

The model(s) to be used must be selected when configuring an application.

Model fields

Parameter	Subparameters	Definition	Type/Default values
`type`		(Mandatory) Identifier type of model	`rag`, `openai`, `mock`, `perplexity`
`name`		(Optional) Model name. If this value does not exist, `id` is used	string
`class_params`		(Mandatory) Preset description	object
	`endpoint`	(Mandatory) Endpoint of the model	string
	`type`	(Mandatory for RAG) Type of the model	`langchain`
	`path`	(Mandatory for RAG) Path of endpoint model	string
	`azure_name`	(Mandatory for OpenAI) Azure name of the model	string
	`model_name`	(Mandatory for OpenAI) Model name	string
	`api_key`	(Mandatory for OpenAI) APIkey to be used in the model call	string
	`api_version`	(Mandatory for OpenAI) API version to be used in the model call	string
	`output`	(Mandatory for mocks) Response to be used in the model call	string
`description_params`		(Optional) Description of the model params	object
	`context_window`	(Optional) Context window of model	number
`tokenizer`		(Optional) Tokenizer of model	string

Models by default

atria-rag model

Model for using the atria-rag-server.

The default configuration is described as follows:

  atria-rag:
    type: rag
    name: Rag server model
    class_params:
      type: langchain
      endpoint: <AUTOCOMPLETED>
      path: <AUTOCOMPLETED>

gpt-4

Model for using Azure OpenAI GPT-4 model.

The default configuration is described as follows:

      gpt-4:
        type: openai
        local: false
        class_params:
          azure_name: deployment_gpt-4
          model_name: gpt-4
          api_key: <AUTOCOMPLETED>
          endpoint: <AUTOCOMPLETED>
          api_version: <AUTOCOMPLETED>
          timeout:
             timeout: 60
             read: 60
        description_params:
          context_window: 300

gpt-4o

Model for using Azure OpenAI GPT-4o model.

The default configuration is described as follows:

      gpt-4o:
        type: openai
        local: false
        class_params:
          azure_name: deployment_gpt-4o
          model_name: gpt-4o
          api_key: <AUTOCOMPLETED>
          endpoint: <AUTOCOMPLETED>
          api_version: <AUTOCOMPLETED>
          timeout:
            timeout: 60
            read: 60
          description_params:
            context_window: 128000

gpt-4o-mini

Model for using Azure OpenAI GPT-4o-mini model.

The default configuration is described as follows:

      gpt-4o-mini:
        type: openai
        local: false
        class_params:
          azure_name: deployment_gpt-4o-mini
          model_name: gpt-4o-mini
          api_key: <AUTOCOMPLETED>
          endpoint: <AUTOCOMPLETED>
          api_version: <AUTOCOMPLETED>
          timeout:
            timeout: 60
            read: 60
          description_params:
            context_window: 128000

o3-mini

Model for using Azure OpenAI o3-mini model.

The default configuration is described as follows:

      o3-mini:
        type: openai
        local: false
        class_params:
          azure_name: deployment_o3-mini
          model_name: o3-mini
          api_key: <AUTOCOMPLETED>
          endpoint: <AUTOCOMPLETED>
          api_version: <AUTOCOMPLETED>
          timeout:
            timeout: 60
            read: 60
          description_params:
            context_window: 128000

gpt-4.1-nano

Model for using Azure OpenAI gpt-4.1-nano model.

gpt-4.1-nano:
  type: openai
  local: false
  class_params:
    azure_name: deployment_gpt-4.1-nano
    model_name: gpt-4.1-nano
    api_key: <AUTOCOMPLETED>
    endpoint: <AUTOCOMPLETED>
    api_version: <AUTOCOMPLETED>
    timeout:
      timeout: 60
      read: 60
    description_params:
      context_window: 128000

perplexity-sonar

This model will be available in ATRIA in upcoming releases. Model for using Perplexity sonar model.

The default configuration is described as follows:

perplexity-sonar:
 type: perplexity
 local: false
 class_params:
   model_name: sonar
   api_key: <AUTOCOMPLETED>
   endpoint: <AUTOCOMPLETED>
   timeout:
     timeout: 20
     read: 45
   http_raise_when_retry_limit_exceeded_recognizer: false
 description_params:
   context_window: 300

Important: This model does not support the same parameters as the previous ones. Check Microsoft document API & feature support.
The following parameters are not supported by the model: temperature, top_p, presence_penalty, frequency_penalty, logprobs, top_logprobs, logit_bias, max_tokens.

1.3. atria-rag-server default configuration

This section includes the parameters configured by default in atria-rag-server:

LLMs

Predefined parameter to define the Large Language Models (LLMs) that call from atria-model-gateway to atria-rag-server.

Currently, only one LLM with the necessary configuration to connect atria-model-gateway to atria-rag-server is defined. It cannot be modified.

LLMs fields

Parameter	Definition	Type/Default values
`name`	(Optional) LLM name. If this value does not exist, `id` is used	string
`model_type`	(Mandatory) Model type	string
`endpoint`	(Mandatory) Endpoint of the model	string

LLm by default

atria-model-gateway:

  atria_model_gateway:
    name: Local Model Gateway
    model_type: llm_manager
    endpoint: http://atria-model-gw:6391/aura-services/v1/atria-model-gw

Embeddings

Parameters to define the embeddings, vector representations to find text blocks that contain the information to resolve the input request.

Two types of Embeddings are available for use:

Local Embeddings: Generated by the atria-rag-server in local mode.
Embeddings OpenAI: Generated by OpenAI.

Embeddings fields

Parameter	Definition	Type/Default values
`name`	(Mandatory) Embedding name	string
`type`	(Mandatory) LLM name. Type of the model	`sentence_transformer`, `azure_openai`
`model`	(Mandatory) Used model	string
`openai_api_version`	(Mandatory to call Azure OpenAI) OpenAI API version	string
`openai_api_type`	(Mandatory to call Azure OpenAI) OpenAI API type	string
`openai_api_key`	(Mandatory to call Azure OpenAI) OpenAI APIKey	string
`azure_endpoint`	(Mandatory to call Azure OpenAI) Azure endpoint	string

Embeddings by default

The predefined embeddings in atria-rag-server are shown below:

Local Sentence Transformer from HuggingFace:

This is an open-source model that appears in sentence-transformers library.

It maps sentences & paragraphs to a 384 dimensional dense vector space and can be used for several tasks like:

Clustering
Multilingual similarity searches
Retrieval-based tasks
Classification

A brief characterization of this embedding regarding different parameters is included below:

Cost: Free to use once downloaded (local execution). No API call costs.
Latency: Low, since it runs locally without external API calls.
Performance: Satisfactory for general-purpose sentence embeddings, supporting multiple languages.
Vector Length: 384 dimensions (smaller than OpenAI’s ADA model).
Hardware Requirements: Needs a GPU for faster inference; otherwise, it can be slow on a CPU.
Model Size: Requires local storage (~120MB).
Quality: Slightly lower accuracy than larger models, especially for complex NLP tasks.

This embedding can be configured with a yaml file:

local_st:
    name: Local Sentence Transformer from HuggingFace
    type: sentence_transformer
    model: paraphrase-multilingual-MiniLM-L12-v2

Distilbert-based Local Sentence Transformer from HuggingFace

This is an open-source model that appears in sentence-transformers library.

It has been trained on 215M (question, answer) pairs from diverse sources.

It maps sentences & paragraphs to a 768 dimensional dense vector space and was designed for several tasks like:

Semantic search
Question answering
Passage retrieval

A brief characterization of this embedding regarding different parameters is included below:

Cost: Free (local execution). No API call costs.
Latency: Fast, optimized for question-answer retrieval tasks.
Performance: Outperforms MiniLM in retrieval-based tasks due to DistilBERT’s training on QA data.
Vector Length: 768 dimensions (higher than MiniLM, better at capturing semantics).
Hardware Requirements: Similar to MiniLM, requires a GPU for optimal performance.
Model Size: Larger than MiniLM (~250MB).
Quality: Primarily trained for English, not as strong for multilingual applications.

This embedding can be configured with a yaml file:

test_distilbert:
    name: Distilbert-based Local Sentence Transformer from HF
    type: sentence_transformer
    model: multi-qa-distilbert-cos-v1

OpenAI Embeddings ADA

This is one of OpenAI’s latest models for generating embeddings and has quickly become a top choice for tasks:

Recommendation systems
Chatbots
Semantic search
Large-scale applications

A brief characterization of this embedding regarding different parameters is included below:

Cost: Paid API model (depends on token usage, $0.0001/1k Tokens). It can be expensive for high-volume applications.
Latency: API calls introduce certain delay, specially in large-scale real-time applications.
Performance: State-of-the-art embeddings with high accuracy for a wide range of NLP tasks.
Hardware Requirements: No local hardware requirements, it works via API.
Vector Length: 1536 dimensions (rich semantic representation).
Quality: Strong performance across multiple languages.

This embedding can be configured with a yaml file:

text-embedding-ada-002:
  name: text-embedding-ada-002 model from Azure OpenAI API
  type: azure_openai
  model: deployment_text-embedding-ada-002
  openai_api_version: <AUTOCOMPLETED>
  openai_api_type: azure
  openai_api_key: <AUTOCOMPLETED>
  azure_endpoint: <AUTOCOMPLETED>

Redis Subscriber

This section includes the Redis event subscriber connection configuration for the atria-rag-server.

Redis subscriber fields

Parameter	Definition	Type/Default values
`connection_mode`	(Mandatory) Connection mode	`single`, `sentinel`, `cluster`
`pool_size`	(Mandatory) Pool size	number
`database`	(Mandatory) Database	number
`password`	(Mandatory) Password	string
`uri`	(Mandatory) URI name	string
`prefix`	(Mandatory) Prefix	string
`sleep_time`	(Optional) Sleep time	number
`max_retries`	(Optional) Maximum number of retries	number
`channels`	List of channels to subscribe to	list[string]

Redis subscriber by default

The default configuration for Redis is described as follows:

redis_subscriber:
  connection_mode: <AUTOCOMPLETED>
  pool_size: 100
  database: <AUTOCOMPLETED>
  password: <AUTOCOMPLETED>
  uri: <AUTOCOMPLETED>
  prefix: <AUTOCOMPLETED>
  channels:
    - "PresetConfiguration"

Prompts

A prompt is defined as an input instruction given to an AI model to generate a response. It guides the AI in the required kind of output.

A prompt by default is defined in ATRIA for different RAG stages. This can be used when a specific prompt is not defined in the preset.

Prompts structure for RAG

The hierarchy of default prompts in RAG stages is shown below:

prompts  
 |___ <stage>
        |___ default
        |       |___ text
        |       |___ args
        |___ <language>
                |___ text
                |___ args

The first level in the prompts configuration are the stages of the RAG process. Each stage has its own configuration and purpose.
Prompts configuration works at language level, so it is possible to have different prompts for different languages, indicated by the language code:
- <language>: Any language prompt configuration (ISO 639-1 Code)
- default: Default prompt configuration (in a specific language)
For each language, the prompts structure must include the fields text and args:
- text: This field contains the text of the prompt that will be sent to the language model. It includes placeholders (e.g., {query}, {target_language}) that are mandatory for the prompt to work. These placeholders will be dynamically replaced with the specific values when the prompt is executed.
- args: Optional field that contains a dictionary of arguments that will be used to replace the placeholders in the text field.

Default prompts in RAG stages

The following stages are currently defined in RAG:

cleanStg

This stage is responsible for cleaning the user query. It ensures that the query is in a proper format before further processing.

See how to include this stage in the default prompt code here

translationStg

This stage handles the translation of the user query into the target language, if necessary.

See how to include this stage in the default prompt code here

contextStg

This stage determines the context of the user query, ensuring it is aligned with the previous conversation or context.

Default prompts in this stage:

sameContext: Configuration to check if the query is in the same context.
recreatedQuestion: Configuration to rewrite the original question. It is composed of following prompts:
- default: Configuration for rewriting the original question.
- system: System prompt configuration.
- human: Human prompt configuration.
system: System prompt configuration.
human: Human prompt configuration.
order: Array of strings with prompts names sorted.

See how to include this stage in the default prompt code here

postFilteringStg

This stage filters the retrieved documents or data to ensure relevance to the user query.

Default prompts in this stage:

relevantDocument: Configuration to check if the document is relevant.
relevantSql: Configuration to check if the SQL data is relevant.

See how to include this stage in the default prompt code here

generativeStg

This stage generates the final response using the retrieved and filtered data.

Default prompts in this stage:

stuff: Configuration for the “stuff” strategy. It is composed of the following sub-stages:
- default: Configuration for the “stuff” strategy.
- system: System prompt configuration.
- human: Human prompt configuration.
notAnswerResponse: Configuration for responses when the question cannot be answered.
informationExtraction: Configuration for extracting information. It is composed of following prompts:
- human1: Human prompt configuration.
- ia: IA prompt configuration.
- human: Human prompt configuration.
responseConsolidation: Configuration for consolidating the response.
sqlPrompt: Configuration for generating SQL query statements.

See how to include this stage in the default prompt code here

RAG default prompt

The current section includes the prompt defined by default for ATRIA RAG capability.

You can also access the yaml file in the Github repository.

In case of any discrepancy between the content of this document and that on GitHub, the GitHub version shall always be considered the most up-to-date

RAG default prompt

prompts:
  cleanStg:
    es:
      text: |
        A continuación hay una consulta del usuario.
        Por favor, limpie la consulta y responda solo con la pregunta del usuario o alguna charla informal.
        -------
        {query}        
    default:
      text:
        A user query follows.
        Please clean the query and respond with just the user question or small talk. The query must be written in English.
        -------
        {query}
  translationStg:
    default:
      text: |
        Translate the following question to {target_language}: {question}

        Instructions:
        1. Maintain the formal tone of the original text.
        2. Do not translate proper names and specific terms (e.g., company names, product names, countries).
        3. Provide the translation in the same format and structure as the original text.

        Translated Text:
        Finally, return the result as a unique JSON object, with the following structure:

        ```
        {{
            "source_languge": The original question language,
            "target_language": The target language,
            "translation": The translation of the question to the target_language. ,
            "possible": true|false,
            "reason": The reason why it is possible or not possible to translate the question.
        }}
        ```        
  contextStg:
    sameContext:
      default:
        text: |
          Below is a conversation followed by a question. You must determine if the question corresponds to the same context as the conversation or if it is from a different context.
          Respond only with: [SAME CONTEXT] o [DIFFERENT CONTEXT]

          Conversation:
          {memory}

          Question:
          {query}          
      es:
        text: |
          A continuación hay una conversación y seguidamente una pregunta. Debes responder si la pregunta corresponde al mismo contexto de la conversación o es una pregunta de un contexto diferente.
          Responde únicamente con: [MISMO CONTEXTO] o [DIFERENTE CONTEXTO]

          Conversación:
          {memory}

          Pregunta:
          {query}          
    recreatedQuestion:
      default:
        default:
          text: |
            Answer with just a new question or the original question.
            Rewrite the original question only if it follows the conversation. Always rewritten question in the same language as the user's question.

            Conversation:
            {memory}

            Original question:
            {query}

            Rewritten question:            
        es:
          text: |
            Responde sólamente con una nueva pregunta.
            Reescribe la pregunta original si es una continuación de la conversación. Utiliza el idioma de la peticion del usuario para rescribir la pregunta.

            Conversación:
            {memory}

            Pregunta original:
            {query}

            Pregunta reescrita:            
      system:
        default:
          text: |
            The user text contains a query, plus the previous conversation turn.
            - If the previous conversation is relevant for the current query, incorporate it into the query and produce a rewritten query
            - else just repeat the current query.

            Always rewrite the question in the same language as the user's question.            
        es:
          text: |
            El texto del usuario contiene una consulta, además del turno anterior de la conversación.

            - Si la conversación anterior es relevante para la consulta actual, incorpórala en la consulta y produce una consulta reescrita.
            - Si no es relevante, simplemente repite la consulta actual.

            Reescribe siempre la consulta en el mismo idioma en que está formulada la consulta del  usuario.            
      human:
        default:
          text: |
            Previous conversation:
            {memory}

            Current query:
            {query}

            Rewritten query:            
        es:
          text: |
            Conversación anterior:
            {memory}

            Consulta actual:
            {query}

            Consulta reescrita:            
      order: ["system", "human"]
  postFilteringStg:
    relevantDocument:
      default:
        text: |
          Below is an excerpt of text followed by a question. You must determine if the excerpt is relevant or irrelevant for answering the question.
          Respond only with: [RELEVANT] o [IGNORABLE]

          Excerpt:
          {extract}

          Question:
          {query}          
      es:
        text: |
          A continuación hay un extracto de texto y seguidamente una pregunta. Debes responder si el extracto es relevante o ignorable para responder la pregunta.
          Responde únicamente con: [RELEVANTE] o [IGNORABLE]

          Extracto:
          {extract}

          Pregunta:
          {query}          
    relevantSql:
      default:
        text: |
          Given the following question:
          `{question}`

          Is it possible to answer, using the data contain in the following table?:
          ```sql
          {sql_table_definition}
          ```


          **Explain briefly, all your decisions**.
          First, identify which tables are necessary to answer the question. Justify why you selected each of these tables.
          Use the following format:
          ```
          I need the following tables to answer the question:
            - <table_name>: <reasoning>
            - <table_name>: <reasoning>
            ...
          ```

          Then, identify which columns are necessary to answer the question. Justify why you selected each of these columns.
          Write the list of columns you identified, and the reasoning after each column, using the following format:
          ```
          I need the following columns to answer the question:
            - <table name>:
              - <column_name>: <reasoning>
              - <column_name>: <reasoning>
              ...
            - <table_name>:
              - <column_name>: <reasoning>
              - <column_name>: <reasoning>
              ...
            ...
          ```

          Then, tell if the tables and columns you identified are enough to answer the question.
          Write the answer using the following format:
          ```
          Possible to answer the question using the former columns:
            - <reasoning>
            - Result: <Yes|No>
          ```

          Then, explain, step by step, how you would write the SQL query to answer the question, using the columns you identified.
           **Use the full qualified names of the columns**. **DO NOT USE THE `JSON_OBJECT` FUNCTION IN THE QUERY**.

          Finally, tell if the question can be answered using this format:

          ```
          {{
              "possible": true|false,
              "reason": The reason why it is possible or not possible to answer the question.
          }}
          ```          
  generativeStg:
    stuff:
      default:
        default:
          text: |
            Use the following context extractions to answer the question at the end.

            Contexto:
            {context}

            If the extracted context do not contain the answer avoid coming up with an answer, and response you do not have information for answering and kindly invite the user to make a new question.

            Question:
            {question}

            Never include information by your own using your own knowledge.
            {extra_prompt}            
        es:
          text: |
            Utilice el siguiente contexto que ha sido extraido  para responder la pregunta del final.

            Contexto:
            {context}

            Usando esta información, responde a la pregunta del usuario.
            Si la información no contiene la respuesta evita firmemente responder, di que desconoces la respuesta e invita educadamente al usuario a que formule una nueva pregunta.

            Pregunta:
            {question}

            Nunca incluyas información utilizando tus propios conocimientos.
            {extra_prompt}            
      system:
        default:
          text: |
            Respond in language {user_query_language}.

            Question:
            {question}            
          args:
            user_query_language: "#.auto.language.user_query"
        es:
          text: |
            Responde en el idioma {user_query_language}.

            Pregunta:
            {question}            
          args:
            user_query_language: "#.auto.language.user_query"
      human:
        default:
          text: |
            You are going to generate an answer for a user question or query.
            To generate the answer, take always into account all the information available in the context provided.

            Context:
            {context}

            Question:
            {question}

            Never include information by your own using your own knowledge.
            {extra_prompt}            
        es:
          text: |
            Vas a generar una respuesta para una pregunta o consulta del usuario.
            Para generar la respuesta, ten siempre en cuenta toda la información disponible en el contexto proporcionado.

            Pregunta:
            {question}

            Contexto:
            {context}

            Nunca incluyas información utilizando tus propios conocimientos.
            {extra_prompt}            
      order: ["system", "human"]
    notAnswerResponse:
      default:
        text: |
          You are a question answering agent. You have tried to answer this question: {query}
          However you do not have information to answer this.
          Please, tell the user that you are not able to answer, apologize and invite the user to make other question.
          Avoid any harmful answer, such as sexual, rude, sexist or racist.
          Respond in language {user_query_language}.

          User question:
          {query}          
        args:
          user_query_language: "#.auto.language.user_query"
      es:
        text: |
          Eres un agente de respuesta a preguntas. Has intentado responder a esta pregunta: {query}
          Sin embargo, no tienes información para responder a esto.
          Por favor, dile al usuario que no puedes responder, discúlpate e invita al usuario a hacer otra pregunta.
          Evita cualquier respuesta dañina, como sexual, grosera, sexista o racista.
          Responde en el idioma {user_query_language}.

          Pregunta del usuario:
          {query}          
        args:
          user_query_language: "#.auto.language.user_query"
    informationExtraction:
      default:
        default:
          text: |
            The original question is this: {question}
            We have provided a previous answer: {existing_answer}
            Only if necessary, refine the answer exclusively with the context below.
            ------------
            {context_str}
            ------------
            Given the new context, refine the original answer to improve the quality of the response.
            If the context is useless, respond with the exact words of the original answer.
            {extra_prompt}            
        es:
          text: |
            La pregunta original es esta: {question}
            Hemos proporcionado una respuesta previa: {existing_answer}
            Sólo si es necesario refina la respuesta exclusivamente con el contexto a continuación.
            ------------
            {context_str}
            ------------
            Dado el nuevo contexto, refina la respuesta original para mejorar la calidad de la respuesta.
            Si el contexto es inútil responde con las mismas palabras de la respuesta original.
            {extra_prompt}            
      human1:
        default:
          text: "{question}"
        es:
          text: "{question}"
      ia:
        default:
          text: "{existing_answer}"
        es:
          text: "{existing_answer}"
      human:
        default:
          text: |
            Refine the existing answer only if necessary, exclusively with the context below.
            ------------
            {context_str}
            ------------
            Given the new context, refine the original answer to improve the quality of the response.
            If the context is useless, respond with the exact words of the original answer.
            {extra_prompt}            
        es:
          text: |
            Refina la respuesta existente, sólo si es necesario, exclusivamente con el contexto a continuación.
            ------------
            {context_str}
            ------------
            Dado el nuevo contexto, refina la respuesta original para mejorar la calidad de la respuesta.
            Si el contexto es inútil responde con las mismas palabras de la respuesta original.
            {extra_prompt}            
      order: ["human1", "ia", "human"]
    responseConsolidation:
      default:
        default:
          text: |
            Below I provide you a context.
            ---------------------
            {context_str}
            ---------------------

            Given exclusively the context, and without using any prior knowledge, respond with a single sentence to the question:
            {question}

            {extra_prompt}            
        es:
          text: |
            A continuación te doy un contexto.
            ---------------------
            {context_str}
            ---------------------

            Dado exclusivamente el contexto, y sin usar ningún conocimiento previo responde con una única frase a la pregunta:
            {question}

            {extra_prompt}            
      system:
        default:
          text: |
            Below I provide you a context.
            ---------------------
            {context_str}
            ---------------------

            Given exclusively the context, and without using any prior knowledge, respond with a single sentence to the question:
            {question}

            {extra_prompt}            
        es:
          text: |
            A continuación te doy un contexto.
            ---------------------
            { context_str }
            ---------------------

            Dado exclusivamente el contexto y sin usar ningún conocimiento previo responde con una única frase a cualquier pregunta.

            { extra_prompt }            
      human:
        default:
          text: "{question}"
        es:
          text: "{question}"
      order: ["system", "human"]
    sqlPrompt:
      default:
        text: |
          Generate a SQL query statement to answer the following question:
          `{question}`

          Use the data contained in the following table, as defined in SQL:
          ```sql
          {sql_table_definition}
          ```

          The following tables, containing auxiliary information, are also available:
          ```sql
          CREATE TABLE D_CBD_Static_Geo_Area_v6 (GEO_AREA_ID VARCHAR, CBD_GEO_AREA_LEVEL1_ID VARCHAR, CBD_GEO_AREA_LEVEL2_ID VARCHAR, CBD_GEO_AREA_LEVEL3_ID VARCHAR, CBD_GEO_AREA_LEVEL4_ID VARCHAR, OB_ALPHA_ID VARCHAR, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_CBD_Static_Geo_Area IS 'Geographical areas. This table contains foreign keys to the different levels of geographical areas. In particular, it contains the foreign keys to these tables: CBD_Static_Geo_Area_Level1, CBD_Static_Geo_Area_Level2, CBD_Static_Geo_Area_Level3, CBD_Static_Geo_Area_Level4. Therefore, this tables is used, via JOIN, to query the geographical information contained in the different levels of geographical areas. For instance, if you have a table T with a field GEO_AREA_ID and you need to check whether this location corresponds to the region of Asturias you will need to look for GEO_AREA_ID in this table, then extract the CBD_GEO_AREA_LEVEL4_ID and query the table CBD_Static_Geo_Area_Level4 to get the name of the region.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.GEO_AREA_ID IS 'Identifier of the geographical area considered. FORMAT: string containing a numerical code. This field does not contain location names.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.CBD_GEO_AREA_LEVEL1_ID IS 'Identifier of the geographical area Level 1 (max level of detail: CP or similar). FORMAT: string containing a numerical code. This field does not contain location names.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.CBD_GEO_AREA_LEVEL2_ID IS 'Identifier of the geographical area Level 2 (City/Town). FORMAT: string containing a numerical code. This field does not contain location names.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.CBD_GEO_AREA_LEVEL3_ID IS 'Identifier of the geographical area Level 3 (Province). FORMAT: string containing a numerical code. This field does not contain location names.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.CBD_GEO_AREA_LEVEL4_ID IS 'Identifier of the geographical area Level 4 (State/Region). FORMAT: string containing a numerical code. This field does not contain location names.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.OB_ALPHA_ID IS 'Alphanumeric Organizational Business ID';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.EXTRACTION_TM IS 'Date-time of the record';

          CREATE TABLE D_CBD_Static_Geo_Area_Level2_v6 (CBD_GEO_AREA_LEVEL2_ID VARCHAR, GEO_AREA_LEVEL_DES VARCHAR, CBD_GEO_AREA_LEVEL3_ID VARCHAR, LONGITUDE_LON_CO DOUBLE, LATITUDE_LAT_CO DOUBLE, GEO_AREA_ID VARCHAR, GEO_STD_AREA_CD VARCHAR, OB_ALPHA_ID VARCHAR, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_CBD_Static_Geo_Area_Level2 IS 'Geographical area level 2 (State)';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.CBD_GEO_AREA_LEVEL2_ID IS 'Identifier of the geographical area Level 2 (City/Town). FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.GEO_AREA_LEVEL_DES IS 'Description associated to the identifier level 2. FORMAT: alphanumeric string containing the name of the city/town.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.CBD_GEO_AREA_LEVEL3_ID IS 'Identifier of the geographical area Level 3 (Province)';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.LONGITUDE_LON_CO IS 'Longitude coordinates (in WGS84) associated with level 2';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.LATITUDE_LAT_CO IS 'Latitude coordinates (in WGS84) associated with level 2';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.GEO_AREA_ID IS 'Identifier of the geographical area considered. FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.GEO_STD_AREA_CD IS 'Standard code of the geo area';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.OB_ALPHA_ID IS 'Alphanumeric Organizational Business ID';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.EXTRACTION_TM IS 'Date-time of the record';

          CREATE TABLE D_CBD_Static_Geo_Area_Level3_v6 (CBD_GEO_AREA_LEVEL3_ID VARCHAR, GEO_AREA_LEVEL_DES VARCHAR, CBD_GEO_AREA_LEVEL4_ID VARCHAR, LONGITUDE_LON_CO DOUBLE, LATITUDE_LAT_CO DOUBLE, ISO_3166_2_CD VARCHAR, GEO_AREA_ID VARCHAR, GEO_STD_AREA_CD VARCHAR, OB_ALPHA_ID VARCHAR, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_CBD_Static_Geo_Area_Level3 IS 'Geographical area level 3 (Region)';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.CBD_GEO_AREA_LEVEL3_ID IS 'Identifier of the geographical area Level 3 (Province). FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.GEO_AREA_LEVEL_DES IS 'Description associated to the identifier level 3. FORMAT: alphanumeric string containing the name of the province.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.CBD_GEO_AREA_LEVEL4_ID IS 'Identifier of the geographical area Level 4 (State/Region). FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.LONGITUDE_LON_CO IS 'Longitude coordinates (in WGS84) associated with level 3';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.LATITUDE_LAT_CO IS 'Latitude coordinates (in WGS84) associated with level 3';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.ISO_3166_2_CD IS 'ISO 3166-2 associated';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.GEO_AREA_ID IS 'Identifier of the geographical area considered. FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.GEO_STD_AREA_CD IS 'Standard code of the geo area';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.OB_ALPHA_ID IS 'Alphanumeric Organizational Business ID';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.EXTRACTION_TM IS 'Date-time of the record';

          CREATE TABLE D_CBD_Static_Geo_Area_Level4_v6 (CBD_GEO_AREA_LEVEL4_ID VARCHAR, GEO_AREA_LEVEL_DES VARCHAR, LONGITUDE_LON_CO DOUBLE, LATITUDE_LAT_CO DOUBLE, HASC_1_CD VARCHAR, GEO_AREA_ID VARCHAR, GEO_STD_AREA_CD VARCHAR, OB_ALPHA_ID VARCHAR, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_CBD_Static_Geo_Area_Level4 IS 'Geographical area level 4 (min. Detail)';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.CBD_GEO_AREA_LEVEL4_ID IS 'Identifier of the geographical area Level 4 (State/Region). FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.GEO_AREA_LEVEL_DES IS 'Description associated to the identifier level 4. FORMAT: alphanumerical string containing the name of the state/region. EXAMPLE VALUES: ''Asturias'', ''Andaluc\u00eda'', etc.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.LONGITUDE_LON_CO IS 'Longitude coordinates (in WGS84) associated with level 4';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.LATITUDE_LAT_CO IS 'Latitude coordinates (in WGS84) associated with level 4';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.HASC_1_CD IS 'Hierarchical administrative subdivision codes ';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.GEO_AREA_ID IS 'Identifier of the geographical area considered. FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.GEO_STD_AREA_CD IS 'Standard code of the geo area';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.OB_ALPHA_ID IS 'Alphanumeric Organizational Business ID';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.EXTRACTION_TM IS 'Date-time of the record';

          CREATE TABLE D_CBD_Static_Station_Type_v6 (STATION_TYPE_CD VARCHAR, TECH_LEVEL_WEIGHT_QT FLOAT, STATION_TYPE_L2_DES VARCHAR, STATION_TYPE_L1_DES VARCHAR, STATION_TYPE_L2_ORDER_NUM INT, STATION_TYPE_L1_ORDER_NUM INT, STATION_TYPE_ORDER_NUM INT, CONSCIOUS_IND BOOLEAN, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_CBD_Static_Station_Type IS 'Station types';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_CD IS 'Device type';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.TECH_LEVEL_WEIGHT_QT IS 'Associated weight for the technologic level of the home';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_L2_DES IS 'Station type level 2';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_L1_DES IS 'Station type level 1';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_L2_ORDER_NUM IS 'Station type order level 2';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_L1_ORDER_NUM IS 'Station type order level 1';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_ORDER_NUM IS 'Station type order';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.CONSCIOUS_IND IS 'Indicates if the related device type has energy efficiency';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.EXTRACTION_TM IS 'Date-time of the record';

          CREATE TABLE D_Segment_v8 (OPERATOR_ID VARCHAR, SEGMENT_ID VARCHAR, SEGMENT_DES VARCHAR, GBL_SEGMENT_ID VARCHAR, SEGMENT_GROUP_ID VARCHAR, SEGMENT_GROUP_DES VARCHAR, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_Segment IS 'Classifications of the customers, attending to different segmentation criteria, for marketing and management issues, according to OB criteria and its correspondence with the global segment classification';
              COMMENT ON COLUMN D_Segment.OPERATOR_ID IS 'Global Operator Identifier (Operator acting as owner of the information present in the current entity)';
              COMMENT ON COLUMN D_Segment.SEGMENT_ID IS 'Organisational segment of the client, in the OB. FORMAT: Numerical code.';
              COMMENT ON COLUMN D_Segment.SEGMENT_DES IS 'Segment description. This is the actual name of the segment. POSSIBLE VALUES: ''NTT'', ''Residencial'', ''Pymes'', ''Residencial/SC'', ''Autonomos'', ''Operadores'', ''Grandes Clientes'', ''Residencial Prepago'', ''Telefonica'', ''Sin Clasificar'', ''Empresas''';
              COMMENT ON COLUMN D_Segment.GBL_SEGMENT_ID IS 'ID of the global segment classification';
              COMMENT ON COLUMN D_Segment.SEGMENT_GROUP_ID IS 'ID code of the segmentation group';
              COMMENT ON COLUMN D_Segment.SEGMENT_GROUP_DES IS 'Description of the segmentation group. POSSIBLE VALUES: ''0.- OPERADORES'', ''1.- U.N. Empresas'', ''2.-U.N. Gran Público'', ''3.- TELEFONICA'', ''4.- SIN CLASIFICAR''';
              COMMENT ON COLUMN D_Segment.EXTRACTION_TM IS 'Date-time of the record';
          ```

          Some of the former tables contains columns in full-qualified format. For instance, these are some examples of full-qualified columns:
          ```
          record_name.field_name
          TEC_PLAT_REC.DEVICE_ID
          record_name.subrecord_name.field_name
          TEC_PLAT_REC.TEC_PLAT_SUBCOMP_REC.DEVICE_ID
          ...
          ```
          Always use the full-qualified format when referring to columns in the tables. For instance, if you need to use the column 'TEC_PLAT_REC.DEVICE_ID', you should not refer to it as 'DEVICE_ID', but as 'TEC_PLAT_REC.DEVICE_ID'.
          **Explain in detail, step by step, all your decisions**.
          If you need to filter by a higher level geographical such as a region (Comunidad Autónoma) you will need to:
          - join the `GEO_AREA_ID` field of the data table (such as `CBD_HGU_Detail_Daily`) with the `GEO_AREA_ID` field in `D_CBD_Static_Geo_Area` table
          - then join the `CBD_GEO_AREA_LEVEL4_ID` field in the `D_CBD_Static_Geo_Area` with the `CBD_GEO_AREA_LEVEL4_ID` field in the `D_CBD_Static_Geo_Area_Level4` table
          - then compare the `GEO_AREA_LEVEL_DES` field in the `D_CBD_Static_Geo_Area_Level4` table with the name of the region (e.g., 'Cantabria'), since the DESCRIPTION field does contain the actual name of the geographical area.
          **Only perform these joins if explicit filtering or grouping by geographical location is necessary**.

          First, identify which tables are necessary to answer the question. Justify why you selected each of these tables.
          Use the following format:
          ```
          I need the following tables to answer the question:
            - <table_name>: <reasoning>
            - <table_name>: <reasoning>
            ...
          ```
          Then, identify which columns are necessary to answer the question. Justify why you selected each of these columns.
          Write the list of columns you identified, and the reasoning after each column, using the following format:
          ```
          I need the following columns to answer the question:
            - <table name>:
              - <column_name>: <reasoning>
              - <column_name>: <reasoning>
              ...
            - <table_name>:
              - <column_name>: <reasoning>
              - <column_name>: <reasoning>
              ...
            ...
          ```
          Then, tell if the tables and columns you identified are enough to answer the question.
          Write the answer using the following format:
          ```
          Possible to answer the question using the former columns:
            - <reasoning>
            - Result: <Yes|No>
          ```
          Then, explain, step by step, how you would write the SQL query to answer the question, using the columns you identified. **Use the full qualified names of the columns**. **DO NOT USE THE `JSON_OBJECT` FUNCTION IN THE QUERY**.
          Finally, write the SQL query to answer the question, using the columns you identified. **DO NOT USE THE `JSON_OBJECT` FUNCTION IN THE QUERY**.
          Return the result as a unique JSON object, with the following structure:
          {{
              "result": <Write the SQL query here. **MAKE SURE THAT THE STATEMENT `SELECT JSON_OBJECT` is not used in the query and Use the full qualified names of the columns. Generate a valid SQL sentence in a single line without new line characters.**>,
              "status": "OK",
              "reason": <a reasoning explaining the query>
          }}
          If the former table does not contain the necessary data to answer the question, return the following JSON object:
          {{
              "result": null,
              "status": "ERROR",
              "reason": <a reasoning explaining the query>
          }}
          Make sure that the JSON object is correctly formatted, and can be parsed by a JSON parser.

Injection

Default injection configuration for atria-rag-server. It is used to avoid prompt injection.

Injection fields

Parameter	Definition	Type/Default values
`heuristics`	Heuristic sentences. Object, where the key is the language and the value is a list of phrases. Now, by default, the heuristics sentences are defined in the config, the file path is no indicated. It is important to note that the phrases added here will be also added to those defined in the security stage securityStg of the preset configuration.	object

| max_length | (Mandatory) Maximum length |number |

Injection by default

The default configuration is described as follows:

injection:
  heuristics:
    es: 
      - responde como
      - responda como
      - respondeme como
      - respondame como
    en: 
      - answer like
      - forget everything
      - forget your
  max_length: 200

Service

Defaults service configuration for atria-rag-server.

Service fields

Parameter	Definition	Type/Default values
`host`	(Mandatory) Host name	string
`port`	(Mandatory) Port id	number

Service by default

The default configuration is described as follows:

service:
  host: 0.0.0.0
  port: <AUTOCOMPLETED>
  log_level: <AUTOCOMPLETED>

Local Storage

Defaults fields related to the configuration of the local storage for documents

Local Storage fields

Parameter	Definition	Type/Default values
`atria_resources_data_folder`	(Mandatory) Folder name for data resources	string
`atria_shared_data_folder`	(Mandatory) Shared data folder name	string

Local Storage by default

The default configuration is described as follows:

local_storage_manager:
  atria_resources_data_folder: "/opt/atria-rag/data"
  atria_shared_data_folder: "/var/atria-rag-data"

Config API

Field with parameters for atria-rag-server API configuration

Config API fields

Parameter	Definition	Type/Default values
`base_url`	(Mandatory) API Config URL	string
`api_key`	(Mandatory) APIKey	string

Config API by default

The default configuration is described as follows:

aura_config_api:
  base_url: <AUTOCOMPLETED>
  api_key:  <AUTOCOMPLETED>

Retrievers

Retriever are responsible for storing the information that have been generated in the documents. Each retriever is associated with a database in order to feed or retrieve information from it.

Currently, there are three different retrievers defined in ATRIA:
-qdrant
-tfidf
-elasticsearch

Retriever fields

Each retriever type has defined specific fields, as shown below:

Parameter	Subparameters	Definition	Type/Default values
`qdrant`	`host`	(Mandatory) Host service Qdrant	string
	`port`	(Mandatory) Port service Qdrant	number
	`prefix`	(Mandatory) Prefix to collection	string
`tfidf`	`dump_name`	(Mandatory) Dump name of service Tfidf	string
`elasticsearch`	`host`	(Mandatory) Host service Elasticsearch	string
	`ca_crt`	(Mandatory) Path certificate Elasticsearch	string
	`username`	(Mandatory) Username service Elasticsearch	string
	`password`	(Mandatory) Password service Elasticsearch	string
	`index_name`	(Mandatory) Index service Elasticsearch	string

Retrievers by default

The default configuration is described as follows:

retrievers:
  qdrant:
    host: <AUTOCOMPLETED>
    port: 6333
    prefix: <AUTOCOMPLETED>
  tfidf:
    dump_name: /var/atria-rag-data/tfidf/dump/

Metadata

Parameter related to the configuration of metadata in atria-rag-server

It is used to setup how metadata is used when providing responses. The retrieving operation produces a list of candidates, each of which may provide a dictionary of metadata. The metadata is used to filter the candidates and provide additional information in the response.

Metadata fields

Parameter	Subparameters	Definition	Type/Default values
`map`	`filetype`	(Optional) Type of file, typically used to specify the format	string
	`page_number`	(Optional) Page number. It could be used to identify particular pages	string
`group-by`		(Optional) Group by field names.	string
`aggregate`		(Optional) Determines how the values of duplicated fields are consolidated during grouping	string
`output_filter`		(Optional) List of fields to be displayed in the metadata	List of string
`root`		(Optional) Primary fields that will structure the final output of the metadata processing	List of string

Metadata by default

The default configuration for metadata is described as follows:

metadata:
  map:
    filetype: content-type
    page_number: page-number
  group-by: url
  aggregate: page-number
  output_filter:
    - title
    - url
    - content-type
    - page-number
    - _zxcv
  root:
    - title
    - url
    - content-type

Language identification

Parameter related to the configuration of Language Identification in atria-rag-server

It is used to identify the language of the user’s question. The result is a dictionary containing the detected language in ISO 639-3 format and its corresponding conversion.
In addition to language identification, the user’s question is preprocessed at this stage, and special characters that may cause recognition errors are removed. For example, line breaks. In case of error, the default language is returned.

This language identification is calculated through fasttext library.

Language identification fields

Parameter	Definition	Type/Default values
`language_default`	(Optional) Language in ISO 639-3 format (two letters). For example: `es`	string
`score_threshold`	(Optional) Score threshold used to respond in the identified language or in the default language. For example: `0.85`	float
`model_path`	(Mandatory) Model path. For example: `/opt/atria-fasttext/fasttext_model.bin`	string
`chars_to_clean`	(Optional) Characters to be cleaned. By default is `['/n']`	list of string

Language Identification by default

The default configuration for language identification is described as follows:

language_identification:
  score_threshold: <AUTOCOMPLETED>
  language_default: <AUTOCOMPLETED>
  model_path: "/opt/atria-fasttext/fasttext_model.bin"

Docs:

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

How to obtain Azure credentials for OpenAI

This process may be required in the first step for training the understanding model: Set up configuration properties.

Prerequisites

Pre-requisites:

Azure account with permissions for applications registration.
Azure CLI installed.

Guidelines

Review azure-cli documentation to validate the commands and parameters.

Follow the guidelines below for obtaining the Azure credentials for OpenAI:

Run the login command (documentation): az login
Sign in with your account credentials in the browser.
You will obtain the different subscriptions within Azure corresponding to the logged account.

Select the specific subscription to be used, with its corresponding field id, and execute the following command to switch to this subscription (documentation): az account set --subscription <subscription_id>
- <subscription_id> is the id of the selected subscription
Create a resource group (documentation): az group create --name <name_resource_group> --location <location>
- <name_resource_group>: name of the resource group
- <location>: one location available for Azure (i.e., northeurope)
Create app (documentation): az ad app create --display-name <display_name>
- <display_name>: name of the service principal
  From the output of az ad app create, we can obtain the field appId. This value is used for the variable OAI_AZURE_TOKEN_CLIENT_ID.
Create password for app (documentation): az ad app credential reset --id <app_id>
- <app_id>: app_id obtained from previous app creation
  From the output of az ad app credential reset, we can obtain the field password. This value is used for the variable OAI_AZURE_TOKEN_CLIENT_SECRET.
  From the output of az ad app credential reset, we can obtain the field tenant. This value is used for the variable OAI_AZURE_TOKEN_TENANT.
Create service principal (documentation): az ad sp create --id <app_id> - AppId: app_id obtained from previous app creation
Assign role contributor (documentation): az role assignment create --assignee <appId> --role Contributor --scope <scope> - <app_id>: app_id obtained from previous app creation
- <Scope>: scope of the role assignment. Read more in (documentation). A possible value is the of the resource group, you can obtain it with the command az group show --name <name_resource_group> | jq .id (documentation).
Create the OpenAI application (documentation): az cognitiveservices account create --kind "OpenAI" --name <name_openai> -g <name_resource_group> --sku s0 -l <location>
- <name_openai>: resource name
- <name_resource_group>: name of resource group (previously generated)
- <location>: location available for Azure (i.e., northeurope)

The values for the parameters required to fill in the build_local_variables.sh script for OpenAI execution must be obtained from the above-defined steps:

export OAI_ID_SUBSCRIPTION="$(az account show | jq -r .id)"
export OAI_RESOURCE_GROUP="<name_resource_group>"
export OAI_ACCOUNT_NAME="<name_openai>"
export OAI_AZURE_TOKEN_CLIENT_ID="<app_id>"
export OAI_AZURE_TOKEN_CLIENT_SECRET="<password>"
export OAI_AZURE_TOKEN_TENANT="$(az account show | jq -r .tenantId)"

Docs:

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

Basic Jenkins configuration

Discover the basic Jenkins configuration

Introduction

Aura uses Jenkins as continuous integration (CI) tool. In particular, the in-house installation in DCIP.

Webhook	URL	Content type
Pull Request	https://ci.tid.es/pro-dcip-aura-01/ghprbhook/	`application/x-www-from-urlencoded`
Push	https://ci.tid.es/pro-dcip-aura-01/github-webhook	`application/x-www-from-urlencoded`

Configuration

Configure a webhook in a github repository

Prerequirement: administrative access to Github repository and to dcip are must.

In the Github web of your repository, go to Settings and to Webhooks, as can be seen in the following picture:
Click on Add webhook, the following window will be shown:
- Fill the URL of the webhook and its content type format
- Choose Let me select indivial events and select only Pull requests. Remember to uncheck Pushes that’s checkec by default.
- Set the webhook as Active and click on the Add webhook button to save the configuration.

Jenkins jobs

ℹ️ Prerequirement: administrative access to dcip is a must.

First thing is to create a new set of Jenkins jobs for your brand new respository, so from the main aura Jenkins page, you should run _component-setup job.
Choose Build with parameters and fill the data of your repository in this case aura-bot-platform. Remember to use ssh as repository URL.

This job will generate a new set of jobs specific for the current repository and with its very same name.

Generate a dedicated slave to run these jobs

Add a Dockerfile to the root of your repository (follow the one in aura-bot-platform). In this case, a new slave definition is needed to run the jobs with a node10 docker container.

To build it, just build the job _docker-slave-setup with parameters:

This will generate automatically the job _docker-slave-builder that will process, configure and publish a docker image based on the provided Dockerfile. Slaves using this image will be available under the label repository-name, in this case: aura-bot-platform.

Build PR job

This is one of the automatically jobs generated by the _component-setup job. It will run whenever a Pull Request is requested in the repository, if it counts on the corresponding webhook.

The basic configuration provided automatically is OK, but in Aura we should apply a couple of changes to handle it properly:

Check Restrict where this project can be run and write the just created aura-bot-platform labeled slaves.
To access github, select the already available credentials (usually contint (contint user for GITHub/PDIHub)).
A couple of environment variables should be configured:
- NPM_TOKEN: it should be added in “Build Environment” section, binding a secret text, with the specific credential.
- DOCKER_HOST: it should be added in “Build Environment” section, binding a secret text, with the specific credential.
The next step is to include execution of the existing delivery/pipelines/pr.sh script during the building phase of the job.
- In Build section, just add an Execute shell step with the following content, depending on the project, further variables should be needed:
```
#!/bin/bash
set -e
export DOCKER_HOST=${DOCKER_HOST_VM}
git remote set-url origin git@github.com:Telefonica/aura-bot-platform.git
delivery/pipelines/pr.sh
```

Docs:

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

Aura Bot components configuration

Configuration of Aura bot dialogs and middlewares

Configuration delivery to dialogs and middlewares

Configuration delivery to dialogs and middlewares is executed by the plugin manager.

aura-bot has the control to prepare and manage all configuration variables and make validations to get ready. In case that any validation fails, the set of libraries wrongly loaded will be shown and the bot will not start. If there is a problem with the scheme of an external library, the broken library should be extracted or fixed.

Configuration of libraries

The configuration of aura-bot libraries is fully defined in libraries configuration.

Docs:

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

Configure users expiration

Guidelines for the activation and configuration of the users expiration feature in Aura.

Introduction

If needed for security reasons, auraId can expire in Aura before the authorizationId expires in Kernel. The time to expire a user can be configured by channel with the configuration variable authorizationIdExpiration.

Furthermore, when the time has expired, the user’s authorizationId in the Kernel will also expire. For this reason, it is necessary to previously configure the specific scope to be able to invalidate it.

The guidelines for both processes are detailed below:

1. Configure the scope in Kernel

As explained above, it is required to configure the scope to allow the deletion of the user’s authorizationId in Kernel.

First of all, we must ensure that the app has the correct permissions, specifically the scope: single-access-sessions-write. If not, it will be necessary to configure it in the app and also to specify it in the channel configuration, following these instructions:

Get the Kernel app name or client_id. To obtain it, execute the following command:

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

$ kubectl -n $AURA_ENVIRONMENT get cm aura-bot -o json | jq -r ".data.AURA_FP_CLIENT_ID"

aura-bot

Request the change to the Kernel operators of your environment: add the scope single-access-sessions-write in aura-bot.
Configure the scope or purpose in the channel configuration of aura-configuration-api, within the security field and changing the value of the properties authPurposes or authScopes. You can also do it through a hot swapping process, following the guidelines in update channels configuration.

Example:

[
    {
        "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
        "name": "novum-mytelco",
        "prefix": "nov",
        "security": {
            "authorizationIdExpiration": 259200,
            "authPurposes": "customer-self-service identify-customer aura-technical-problems-purpose",
            "authScopes": "",
            "channelId": "novum-mytelco"
        },
        "metadata": {
            "updatedAt": "2022-09-06T09:58:19.543Z",
            "version": "7.4.0",
            "createdAt": "2022-09-06T09:58:19.543Z"
        }
    }
]

2. Configure users expiration in the channels configuration file

Configure the time to expire a user in the configuration variable authorizationIdExpiration of aura-configuration-api. You can also do it through a hot swapping process, following the guidelines in update channels configuration.

Response example:

[
    {
        "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
        "name": "novum-mytelco",
        "prefix": "nov",
        "security": {
            "authorizationIdExpiration": 259200,
            "authPurposes": "customer-self-service identify-customer aura-technical-problems-purpose",
            "authScopes": "",
            "channelId": "novum-mytelco"
        }
    }
]

In the previous example, the authenticated users of this channel will expire in 3 hours (259200 seconds). After this time, the user will be deleted from aura-authentication-api database and the bot cache will be discarded.

Docs:

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

Configure your releases

This section group guidelines with the specific configuration required by an OB for installing a particular Aura version

Index

Dependencies update in Prince 10.0.0 release

Docs:

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

Create and configure an agent

Guidelines for the configuration of ATRIA by use cases constructors when developing an experience by means of an agent

Introduction

An agent is a configuration entity in ATRIA that represents an integration point for external channels, services, or platforms.

Agents are referenced by applications to enable channel or service connectivity within the platform.

Guidelines to configure an agent

1. Create a new agent

Build the agent for your use case (json file), using the available agent fields.

When the agent json file is generated, execute this command to include it:

curl --location --request POST 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents/' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data-raw '<NEW AGENT JSON>'

1.1. Modify/update an agent

If once created, certain modifications are required, follow these instructions:

Make the required changes in the agent json file using the available agent fields.

When the agent is modified, execute this command to update it:

curl --location --request PUT 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents/<agentID>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data '<AGENT JSON WITH MODIFICATIONS>'

1.2. Delete an agent

Execute the following command:

curl --location --request DELETE 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents/<agentId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX'

2. Include the agent in the application

If the application for your use case does not exist, first create it following the guidelines for the configuration of an application.

Once the application is created, assign the created agent in the field agents.

If you update or delete an agent, ensure that any application referencing it is also updated accordingly.
Remember that agents must exist to be inserted in an application.

Example to update the list of agents in an application:

curl --location --request PATCH 'https://svc-<env>.auracognitive.com/aura-services/v1/applications/<applicationId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data '{
    "id": "<applicationId>",
    "agents": [
      "<agentId1>",
      "<agentId2>"
    ]
  }'

Agent fields

The fields for the characterization of an agent are summarized below, as defined in the API swagger Aura Configuration ATRIA Agents:

Field	Type	Mandatory	Description
`id`	string	Yes	Unique identifier (UUID) for the agent.
`name`	string	Yes	Name that uniquely identifies the agent in Aura.
`description`	string	No	Description of the agent.
`communication`	object	Yes	Parameters for the configuration of the communication flow. See communication configuration.
`agentBase`	object	No	Configuration of the agent base
`deploymentName`	string	No	Name of the deployment where the agent is running. If the `endpoint` field is not present in `communication`, this field will be used to compose the `endpoint` field to the agent. Both fields are incompatible.
`metadata`	object	No	Document metadata (version, createdAt, updatedAt, etc). See metadata.

Communication configuration (`communication`)

Field	Type	Mandatory	Description
`communicationType`	string	Yes	Type of communication. Only `http` is currently supported.
`endpoint`	string	No	HTTP endpoint where the agent listens.
`headers`	object	No	HTTP headers associated with the agent.
`timeout`	number	No	Timeout for agent communication.
`retries`	number	No	Number of retries for communication.

Agent base (`agentBase`)

Field	Type	Mandatory	Description
`name`	string	Yes	The name that identifies the agent base univocally in Aura.
`configuration`	object	No	The configuration of the agent flow.

Metadata (`metadata`)

Field	Type	Mandatory	Description
`version`	string	No	Configuration version when the document was created.
`createdAt`	string	No	Creation date (ISO 8601).
`updatedAt`	string	No	Last update date (ISO 8601).

Example: Minimal agent configuration

{
  "id": "b1e2c3d4-5678-1234-9abc-def012345678",
  "name": "example-agent",
  "communication": {
    "communicationType": "http",
    "endpoint": "https://agent.example.com/webhook"
  }
}

Example: Full agent configuration

  {
    "id": "1870fa4a-bcc4-4a7c-88fc-c0194555a076",
    "name": "device-recommender-agent",
    "communication": {
      "communicationType": "http",        
    },
    "deploymentName": "mongo-device-recommender-agent",
    "description": "An AI agent built with langgraph that provides personalized recommendations about devices by querying and analyzing data stored in a MongoDB database.",
    "agentBase": {
      "name": "device-recommender-agent",
      "configuration": {
        "conversational_agent": {
          "conversational_prompt": "Adopt the role of Aura",
          "model_params": {
            "temperature": 0.1
          },
          "model_str": "model_gw/gpt-4o-mini"
        },
        "mongo_agent": {
          "database_name": "mongo-recommender",
          "limit_query_result": 10,
          "model_params": {
            "temperature": 0.1
          },
          "model_str": "model_gw/gpt-4o-mini",                    
        }
      },          
    },
    "metadata": {
      "createdAt": "2025-07-11T09:54:33.973Z",
      "updatedAt": "2025-07-11T09:54:33.973Z",
      "version": "10.3.0"
    }
  }

Note:

The id, name, and communication fields are mandatory.

The communicationType must be http.

If an agent is deleted, applications referencing it will be updated.

Docs:

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

Create and configure an agent base

Guidelines for the configuration of ATRIA by use cases constructors when developing an experience by means of an agent

Introduction

An agent-base is a configuration entity in ATRIA that represents an implementation code for an agent.

Agents base are referenced by agents to deploy the configuration of the agent.

Guidelines to configure an agent-base

1. Create a new agent-base

Build the agent-base for your use case (json file), using the available agent base fields.

When the agent-base json file is generated, execute this command to include it:

curl --location --request POST 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents-base/' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data-raw '<NEW AGENT BASE JSON>'

1.1. Modify/update an agent-base

If once created, certain modifications are required, follow these instructions:

Make the required changes in the agent-base json file using the available agent base fields.

When the agent-base is modified, execute this command to update it:

curl --location --request PUT 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents-base/<agentBaseId>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data '<AGENT BASE JSON WITH MODIFICATIONS>'

1.2. Delete an agent-base

Execute the following command:

curl --location --request DELETE 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents-base/<agentBaseId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX'

2. Include the agent-base in the agent

Create the agents configuration, indicating de agentBase.name, as explained in the document guidelines for the configuration of an agent

Agent base fields

The fields for the characterization of an agent-base are summarized below, as defined in the API swagger Aura Configuration ATRIA Agents Base:

Field	Type	Mandatory	Description
`id`	string	Yes	Unique identifier (UUID) for the agent-base.
`name`	string	Yes	Name that uniquely identifies the agent-base.
`description`	string	No	Description of the agent-base.
`language`	string	Yes	Language type that the agent base is associated with. Currently, python.
`tags`	array	No	Tags that the agent base is associated with.
`version`	string	No	Version of the agent base.
`metadata`	object	No	Document metadata (version, createdAt, updatedAt, etc). See metadata.

Metadata (`metadata`)

Field	Type	Mandatory	Description
`version`	string	No	Configuration version when the document was created.
`createdAt`	string	No	Creation date (ISO 8601).
`updatedAt`	string	No	Last update date (ISO 8601).

Example: agent-base configuration

{
  "id": "cd2b534c-16c3-4d89-a87e-ec45d3939232",
  "name": "agent-base-test",
  "description": "An AI agent built with langgraph that provides personalized recommendations about devices by querying and analyzing data stored in a MongoDB database.",
  "language": "python",
  "version": "1.0.0"
}

Note:

The id, name, and language fields are mandatory.

The language must be python.

Docs:

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

Dependencies update in Prince 10.0.0 release

These documents include all the updates in components that have been carried out for the release Prince 10.0.0, along with the corresponding migration or adaptation tasks that should be executed by the OBs Teams.

Index

Python repositories migration for PyUtils, Aura NLP, Aura Complex Logic Framework plugin packages and ATRIA repositories.
Nodejs-related dependencies update in Prince release

Docs:

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

Aura Authentication API environment variables

Notation

List of environment variables defined for Aura Authentication API

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description	Modifiable by OB?
AURA_AUTHENTICATION_BLOCK_MODE	string	DEPRECATED. No longer used during installations. Flag to indicate if the server allows users’ registration, users’ reading or everything. Possible values: `write`, `writeread` and `unblocked`. By default, `unblocked`.	NO
AURA_AUTHORIZATION_HEADER	string	Complete authorization header to be sent to aura-authentication-api, with the following format: `APIKEY xxxxxx`.	YES, but only if the previous APIKey was deprecated.
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT	string	Endpoint for aura-configuration-api.	NO
AURA_DEFAULT_LOCALE	string	Culture code to be used by default in the current deployment: `de-de`, `en-gb`, `es-es`, `pt-br`.	NO
AURA_DEFAULT_TIME_ZONE	string	Timezone where the service is running.	NO
AURA_DIRECTLINE_API_ENDPOINT	string	Direct Line API URL to create tokens and conversations in the current environment. By default, `https://directline.botframework.com/v3/directline/conversations`.	NO
AURA_DIRECTLINE_SECRETS	string	Comma-separated list of strings with all the existing Direct Line secrets of the current instance to be used to generate tokens and conversations.	NO
AURA_ENCRYPTION_ALGORITHM	string	Encryption algorithm that will be used to validate the APIKey. By default: `aes-256-cbc`.	NO. It would break APIKey and state validation.
AURA_ENCRYPTION_IV_LENGTH	number	Size for the initialization vector used by the encryption algorithm that validates the APIKey and the state.	NO. It would break APIKey and state validation.
AURA_ENCRYPTION_IV_POSITION	number	Position where to insert the initialization vector in the final string with the encrypted payload. By default: `35`.	NO. It would break APIKey and state validation.
AURA_ENCRYPTION_KEY	string	Encryption key or comma-separated list of encryption keys to be used in the environment. It is mainly used to decrypt the APIKeys or user state during login and to encrypt sensible data, such as async-callback parameters during login.	NO. It would break database encrypted data and APIKey validation.
AURA_ENVIRONMENT_NAME	string	Name of the environment where the aura-authentication-api is deployed. For example: `ap-next`, `es-dev` or `de-pre`.	NO
AURA_ERROR_CODES_CREDENTIALS	string	Credentials error codes returned by the IDP in `error_codes` field. Used to send the correct error response to the user.	YES, if any code must return this type of response.
AURA_ERROR_CODES_TIMEOUT	string	Timeout error codes returned by the IDP in `error_codes` field. Used to send the correct error response.	YES, if any code must return this type of response.
AURA_ERROR_DESCRIPTIONS_CREDENTIALS	string	Credentials error descriptions returned by IDP in `error_description` field. Used to send the correct error response. For example: `IDPSEGU_ERROR 205, IDPSEGU_ERROR 424`	YES, if any error description must return this type of response.
AURA_ERROR_DESCRIPTIONS_TIMEOUT	string	Timeout error descriptions returned by IDP in `error_description` field. Used to send the correct error response. For example: `IDPSEGU_ERROR 300`	YES, if any error description must return this type of response.
AURA_FP_AUTHSERVER_ENDPOINT	string	URL of the Kernel authentication server. It MUST end with `/`	NO
AURA_FP_CLIENT_ID	string	Client ID to be logged in as Kernel .application.	NO
AURA_FP_CLIENT_ISSUER	string	URL of endpoint where Aura public key is published.	NO
AURA_FP_CLIENT_SECRET	string	Client password to be logged in as Kernel application.	NO
AURA_FP_ISSUER	string	URL of the endpoint serving Aura’s public key of the environment.	NO
AURA_FP_PRIVATE_KEY	string	Base64 string with the Aura private key used to cipher OpenId requests.	NO
AURA_FP_PRIVATE_KEY_ID	string	ID to find the private key in the key storage of the docker container. It is also used to generate the proper output for the public key. By default, `8dfe2155bbfe54079ba640560ae930411e93a008`.	NO, it depends on the `AURA_FP_PRIVATE_KEY`
AURA_HTTP_KEEP_ALIVE	boolean	Flag to indicate whether not the outgoing HTTP connections should be established with keep alive or not. By default, `true`.	NO
AURA_HTTP_KEEP_ALIVE_MSECS	number	Number of milliseconds to keep HTTP connections open. By default, `100000`.	NO
AURA_HTTP_MONKEY_PATCHER_ENABLED	boolean	Flag to indicate whether Monkey Patcher is used in service.	NO
AURA_HTTP_PATHS_LOG_DISABLED	string	Comma-separated string with the outgoing path that should not be logged. By default, `aura-kpis`, `static-resources`, `healthz`, `ping`, `aura-configuration`. The paths in this variable will be added to the default ones.	YES, add the values to be filtered as a comma-separated list of paths.
AURA_HTTP_REQUEST_MAX_SOCKETS	number	Maximum number of HTTP sockets open in the server. By default, `100`	NO. Only if indicated by Aura Global Team.
AURA_HTTP_REQUEST_TIMEOUT	number	Number of milliseconds to wait for an HTTP request to be established. By default, `20000`.	NO. Only if indicated by Aura Global Team.
AURA_IGNORE_LOGGING_PATH	string	Comma-separated string with all the incoming paths which requests should not be logged. By default, `/ping,/local-ping`	YES
AURA_IMAGE_SUCCESS	string	Path to the image file to be added in the HTML templates to indicate, in integrated authentication, that the process was successful. By default, no file is configured. It will be read from `AURA_STATIC_RESOURCE_PROVIDER_ENDPOINT` using `AURA_STATIC_RESOURCE_PROVIDER_SAS_TOKEN` as credentials.	YES
AURA_INTERNAL_RETRIES	number	Number of retries for internal calls. By default, `1`	NO, except if requested
AURA_LOCALE_FOLDER	string	Local path in the aura-authentication-api docker container where locale files are found. By default, `./locale`.	NO
AURA_LOCALE_FORCE_IMPORT	boolean	Flag to indicate whether or not remote locale files are to be used instead the local ones. By default, `false`.	NO
AURA_LOCALE_REMOTE_BACKUP	boolean	Flag to indicate whether or not remote locale files are to be backup before overwriting them. By default, `false`.	NO
AURA_LOCALE_REMOTE_CONTAINER	string	Azure Storage blob container where remote locale files are stored. By default, `static-resources`.	NO
AURA_LOCALE_REMOTE_CONTAINER_PREFIX	string	Azure Storage blob container prefix where remote locale files are stored. By default, `authentication/locale`.	NO
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev`(more visual format). By default: `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in monitoring logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default: `INFO`.	YES, for development set it to `DEBUG`. In pre/production should be `INFO` or `ERROR`. For the analysis of an issue in pre/production it may be changed to `DEBUG`.
AURA_MAKEUP_MODE	string	Allow dev mode of the makeup with the value `local`. By default: `full`.	NO, only for development, set it to `local`.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCESS_KEY	string	Microsoft Storage password of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT	string	Microsoft Storage account of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Microsoft Storage account of the environment.	NO
AURA_MICROSOFT_AZURE_STORAGE_CONFIGURATION_CONTAINER	string	Aura configuration container name. Default: ‘aura-configuration’	NO
AURA_MONGODB_CACHE_COLLECTION	string	Name of the MongoDB collection where cache is stored. By default: `dev-cache`.	NO
AURA_MONGODB_CACHE_INDEX	string	Index used in TwoLevelsCache of aura-behavior-manager. By default, `id`.	YES, only for development environments.
AURA_MONGODB_CACHE_TTL	number	Lifetime of cache used by aura-behavior-manager. It MUST be disabled in PRE and PRO environments. By default, `3600` seconds (1h).	YES, only for development environments.
AURA_MONGODB_PASSWORD	string	MongoDB password to access `MONGODB_USER_DB` in `AURA_MONGODB_URI`.	NO. Only if the credentials must be updated.
AURA_MONGODB_POOL_SIZE	number	Number of connections open with the database in the pool. By default, `60`.	NO. Only if indicated by Aura Global Team.
AURA_MONGODB_SSL	boolean	Flag to indicate whether or not mongodb connection must use SSL. By default, `false`.	NO
AURA_MONGODB_URI	string	MongoDB URI of the MongoDB server of the current environment.	NO
AURA_MONGODB_USER_COLLECTION	string	Name of the MongoDB collection where aura users are stored.	NO
AURA_MONGODB_USER_DB	string	Name of the MongoDB database where aura users are stored.	NO
AURA_MONGODB_USER_LAST_ACCESS_UPDATE_INTERVAL	number	Number of milliseconds to wait to update the last access of user. By default: 86400000 milliseconds	NO
AURA_MONGODB_USERNAME	string	MongoDB username to access `MONGODB_USER_DB` in `AURA_MONGODB_URI`.	NO. Only if the credentials must be updated.
AURA_MONGODB_MAX_POOL_SIZE	number	Maximum number of connections in the MongoDB pool. By default, `60`.	NO
AURA_MONGODB_MIN_POOL_SIZE	number	Minimum number of connections in the MongoDB pool. By default, `2`.	NO
AURA_MONGODB_MAX_IDLE_TIME_MS	number	Maximum idle time in milliseconds for connections in the MongoDB pool. By default, `30000` (30 seconds).	NO
AURA_MONGODB_RETRY_WRITES	boolean	`true` if retry writes are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_RETRY_READS	boolean	`true` if retry reads are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_HEARTBEAT_FREQUENCY_MS	number	Frequency in milliseconds of the heartbeat in the MongoDB connection. By default, `2000` (2 seconds).	NO
AURA_MONGODB_SERVER_SELECTION_TIMEOUT_MS	number	Timeout in milliseconds for server selection in the MongoDB connection. By default, `5000` (5 seconds).	NO
AURA_MONGODB_SOCKET_TIMEOUT_MS	number	Timeout in milliseconds for socket operations in the MongoDB connection. By default, `45000` (45 seconds).	NO
AURA_CONNECTION_TIMEOUT_MS	number	Timeout in milliseconds for establishing a connection to the MongoDB server. By default, `10000` (10 seconds).	NO
AURA_MONGODB_READ_PREFERENCE	string	Read preference for the MongoDB connection. By default, `primaryPreferred`. Possible values: `primary`, `primaryPreferred`, `secondary`, `secondaryPreferred`, `nearest`.	NO
AURA_REDIRECT_URI	string	URL to redirect integrated authentication requests.	NO
AURA_REDIS_MODE	string	Mode of Redis distribution. Values: `CLUSTER`, `SENTINEL`, `SINGLE`. By default: `SENTINEL`.	NO
AURA_REDIS_SENTINEL_INSTANCE_NAME	string	Name of the Redis instance. Use in `SENTINEL` mode.	NO
AURA_REDIS_HOSTS	string	A string with list of nodes separated by ‘,’, including host and port separated by ‘:’. For example: “localhost:port,localhost2:port2”.	NO
AURA_REDIS_DATABASE	number	Database number for `SINGLE` or `SENTINEL` mode. By default: `0`.	YES
AURA_REDIS_PASSWORD	string	String with Redis password.	YES
AURA_ENVIRONMENT_PREFIX	string	Prefix that will be used by all Redis keys when using redis-connector. This allows mixing in a single Redis service messages coming from different environments in the same Azure subscription. By default: ``. (empty)	YES
AURA_REDIS_USE_CONNECTION_POOL	string	Use pool connections for Redis. By default: `true`.	YES
AURA_REDIS_CACHE_TTL	number	Seconds to expire cache documents in Redis cache. By default: `3600` (1h).	YES
AURA_REDIS_CONNECTION_POOL_MIN	number	Minimum number of connections in the pool. By default: `2`.	YES
AURA_REDIS_CONNECTION_POOL_MAX	number	Maximum number of connections in the pool. By default: `100`.	YES
AURA_REDIS_MAX_RECONNECT_RETRIES	number	Number of retries to connect to Redis. By default: `25`	YES
AURA_REDIS_MAX_RECONNECT_INTERVAL	number	Time in milliseconds to wait before reconnecting to Redis. By default: `5000`.	YES
AURA_RESOURCES_FOLDER	string	Local path in the aura-authentication-api docker container where static resources are found. By default, `./settings/resources`.	NO
AURA_SEED_ID	string	Seed used to generate userIds for anonymous users.	NO
AURA_SERVICE_ENVIRONMENT	string	Type of environment: `'DEV', 'PRE', 'PRO'`. By default, `DEV`. It is used during locale translation, to get the correct text reference.	NO
AURA_SERVICE_PORT	number	Port where the aura-authentication-api is listening. By default, `2367`	NO
AURA_STATIC_RESOURCE_PROVIDER_ENDPOINT	string (url)	Azure Storage endpoint where static resources are stored. By default, it is not configured. Only needed if the environment handles integrated authentication and the files have to be uploaded to Azure Storage.	NO
AURA_STATIC_RESOURCE_PROVIDER_SAS_TOKEN	string	Azure Storage SAS token to access the container where the static resources are stored. By default, it is not configured. Only needed if the environment handles integrated authentication and the files have to be uploaded to Azure Storage.	NO. Only if the credentials have to be renewed.
AURA_STATIC_RESOURCES_CONTAINER	string	Azure Storage blob container where static resources are stored. By default, `static-resources`.	NO
AURA_STATIC_RESOURCES_CONTAINER_PREFIX	string	Azure Storage blob container prefix where static resources are stored. By default, `authentication/resources`.	NO
AURA_TRUSTED_HOSTNAMES	string	Comma-separated list of the trusted domains URL of the current environment, to validate non integrated signup and login requests.	YES, all the trusted domains must be added.
AURA_VALID_REGISTER_STATE_MINUTES	number	Number of minutes to expire a received user state during integrated authentication. By default, `10`.	NO
AURA_SHUTDOWN_GRACEFUL_TTL	string	Number of milliseconds to wait until all aura-authentication-api tasks are done before shutting each pod down. By default `25000` (25 seconds)	NO
AURA_VERSION	string	Number of the Aura’s release being executed.	NO
DEV_AURA_AUTH_BEHAVIOR_MICROSOFT_AZURE_STORAGE_SETTINGS_FILE	string	Name of the configuration file route used by aura-behavior-manager. By default, `aura-bot/aura-auth-behavior-manager.json`. It is only valid for development environments.	YES, in development environments
DEV_AURA_AUTH_BEHAVIOR_CRON_PATTERN	string	Cron pattern to set the refresh time of aura-behavior-manager configuration. By default, `/5 * * *` (every 5 minutes). It is only valid for development environments.	YES, in development environments.
DEV_AURA_BEHAVIOR_MANAGER_ACTIVE	boolean	Flag to indicate whether or not aura-behavior-manager module should be activated in the current deployment. It is only valid for development environments.	YES, in development environments.

Docs:

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

Aura Bot environment variables

Updated list of Aura Bot environment variables

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description	Modifiable by OB?
AURA_ACCESS_TOKEN_EXPIRATION_MARGIN	number	Time in milliseconds as margin to validate access token expiration. Default: `300000`.	NO
AURA_ACTIVATE_MINI_BOT	boolean	Flag to activate minibot mode. By default: `false`.	NO. Only valid during development to run Aura minibot.
AURA_ACTIVE_MIDDLEWARES	string	List of configurable middlewares. Order in list is not taken into account. Name/id middlewares cannot have spaces. Example: `BatchOutgoingMessage, Facebook`.	NO. Only guided by Global Team.
AURA_BOT_APIKEY_PATH	string	Path to validate channel APIKey authorization.	NO
AURA_HTTP_KEEP_ALIVE_MSECS	number	Number of milliseconds to keep alive HTTP connections. Used in HTTPMonkeyPatcher module.	NO
AURA_HTTP_KEEP_ALIVE	boolean	Boolean value that indicates the use of keep-alive in HTTP connections. Used in HTTPMonkeyPatcher module.	NO
AURA_HTTP_KEEP_MAX_SOCKETS	number	Maximum number of sockets. Used in HTTPMonkeyPatcher module.	NO
AURA_HTTP_GOT_REQUEST_LOG_ENABLED	boolean	Enable or disable the monkey patching of the HTTP and HTTPs modules using Got library. By default, `false`.	YES
AURA_HTTP_MAX_REQUEST_SIZE	string	Maximum size in bytes of the request body. It is a string because, the allowed values must indicate the units: 10 mb, 200 kb, etc. By default, `20 mb`.	YES, in order to decrease it if it is considered too high. For this purpose, both local and global Operations Teams must review it, because it could lead to DDoS attacks easily.
AURA_AUTHORIZATION_ENDPOINT	string	aura-authentication-api base endpoint.	NO. In any case, it must be the internal k8s URL pointing to the aura-authentication-api.
AURA_AUTHORIZATION_HEADER	string	Complete authorization header to be sent to aura-authentication-api, with the following format: `APIKEY xxxxxx`.	YES, but only if the previous APIKey was deprecated.
AURA_BRIDGE_ENDPOINT	string	Bridge endpoint that will be used by aura-bot to send the use cases responses.	NO
AURA_BRIDGE_ASYNC_CALLBACK_PATH	string	Bridge path that will be used by async-callback responses. Default value: `aura-services/v1/async-callback/notifications`.	NO
AURA_CHANNELDATA_CURRENT_VERSION	string	`channelData` version used internally by aura-bot. By default, `3`.	NO
AURA_CHANNELDATA_DEFAULT_VERSION	string	`channelData` version returned by default in all messages. By default, `1.0.0`.	NO
AURA_CHANNELDATA_RESPONSE_VALIDATION	boolean	Flag to indicate that response validation should be done. By default, `true`.	NO
AURA_CHANNELDATA_VALIDATION	boolean	Flag to indicate that request validation should be done. By default, `true`.	NO
AURA_CHANNELDATA_VALIDATION_VERSIONS	string	`channelData` versions that will be validated. By default, `3`.	NO
AURA_CHANNELDATA_VALIDATION_MIN_VERSION	string	Minimal version to validate. By default, `3`.	NO
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT	string	Complete URL where aura-bot should get the configuration of all the channels available in the environment. It should provide an array of channels fitting Aura channel model.	YES, but only if the generated sas token was
AURA_COGNITIVE_ENDPOINT	string	URL of Aura NLP API.	NO. In any case, it must be the internal k8s URL pointing to the `api-gw`.
AURA_DEFAULT_LOCALE	string	Culture code to be used by default in the current deployment: `de-de`, `en-gb`, `es-es`, `pt-br`.	NO
AURA_DEFAULT_TIME_ZONE	string	Default time zone. For example: `Europe/Madrid`	NO
AURA_DIALOG_CONTEXT_THRESHOLD	number	Minimal score to considered valid a `dialogContext` option. By default, `0.8`	NO without the advice of a language expert that validates the new threshold.
AURA_DIALOG_CONTEXT_ORDINAL_CARDINAL_THRESHOLD	number	Threshold that will be used in case the `dialogContext` elements are in list form and also if the input phrase has some number. By default, `0.95`	NO without the advice of a language expert that validates the new threshold. It must be deeply validated by the Global Team, in the happening of an error in the dialog context recognition.
AURA_DIALOG_CONTEXT_THRESHOLD_RELATION_UTTERANCE	number	If its value is greater than `0`, it will be used to evaluate the relationship between value and utterance by characters and tokens.	NO without the advice of a language expert that validates the new threshold. It must be deeply validated by the Global Team, in the happening of an error in the dialog context recognition.
AURA_ENCRYPTION_ALGORITHM	string	Encryption algorithm used to validate the APIKey.	NO. It would break database encrypted data and APIKey validation.
AURA_ENCRYPTION_IV_LENGTH	number	Size for the initialization vector used by the encryption algorithm that validates the APIKey	NO. It would break database encrypted data and APIKey validation.
AURA_ENCRYPTION_IV_POSITION	number	Position where to insert the initialization vector in the final string with the encrypted payload. Future use.	NO. It would break database encrypted data and APIKey validation.
AURA_EXTENDED_KPI_GENERIC_QUESTION_INTENT	string	Generic question intent used to extract options from entities field.	NO
AURA_EXTENDED_KPI_HANDOVER_DIALOG_PREFIX	string	Dialog prefix for handover dialog.	NO.
AURA_EXTENDED_KPI_REMOVE_HTML_TAGS	boolean	Flag that indicates if it is necessary or not to remove HTML tags from the text.	NO.
AURA_EXTENDED_KPI_SKIP_AURA_ACTION	boolean	Skip message if it is an `aura-action`.	NO.
AURA_ENCRYPTION_KEY	string	Encryption key or comma-separated list of encryption keys to be used in the environment. It is mainly used to decrypt the APIKeys.	NO. It would break database encrypted data and APIKey validation.
AURA_FILE_ENDPOINT	string	URL of the files microservice.	NO.
AURA_FP_AUTHSERVER_ENDPOINT	string	URL of the Kernel authentication server, used to get valid `access_token` or `introspect_token` to handle calls to Kernel data APIS. It MUST end with `/`	NO
AURA_FP_CLIENT_CRED_PURPOSES	string	Purposes used in 2-legged user profile queries in Kernel.	YES
AURA_FP_CLIENT_CRED_SCOPES	string	Scopes used in 2-legged user profile queries in Kernel	YES
AURA_FP_CLIENT_ID	string	Client ID to be logged in as Kernel application.	NO
AURA_FP_CLIENT_SECRET	string	Client password to be logged in as Kernel application.	NO
AURA_FP_ISSUER	string	URL of the endpoint serving Aura’s public key of the environment.	NO
AURA_FP_PRIVATE_KEY	string	Base64 encoded string of the private key of the environment.	NO
AURA_FP_USER_PROFILE_ENDPOINT	string	URL of Kernel UserProfile API.	NO
AURA_SHUTDOWN_GRACEFUL_TTL	number	Number of milliseconds to wait until all bot tasks are done before shutting each pod down. By default, `25000` (25 seconds)	NO
AURA_GATEWAY_API_ENDPOINT	URI string	Endpoint to access the locally deployed ATRIA aura-gateway-api	NO
AURA_GATEWAY_API_ISSUER_URL	string	Aura issuer URL. It is automatically fulfilled by the installer.	NO
AURA_INTENTS_NONE	string	None intents separated by commas. Default: `None,intent.none,intent.tv.none`. Used in the main-dialog.	YES. The default values are always added to the provided list.
AURA_INTERNAL_RETRIES	number	Number of retries for internal calls. By default: `1`	NO, except if requested.
AURA_KPI_FILE_PREFIX	string	String with the prefix used in the KPIs entities files of this service.	NO
AURA_KPIS_LOG_API_REQUEST_BODY	boolean	Flag to log or not the request body of the API calls. Default: `true`	YES. Once disabled, to enable run performance tests to validate if it is possible to write them.
AURA_KPIS_LOG_API_RESPONSE_BODY	boolean	Flag to log or not the response body of the API calls. Default: `true`	YES. Once disabled, to enable run performance tests to validate if it is possible to write them.
AURA_KPI_REMOVE_SPECIAL_CHARACTERS	string	Regular expression on removing special characters. Default:`\n\r`	NO
AURA_KPI_STORE_MODE	string	Destination of the KPIs entities files. Default: `blob`. If `file`, they will be stored locally in the instance, in the folder shown in `KPI_TO_DSV_LOCAL_FILES_DIRECTORY`. For development purposes. If `blob`, they will be stored remotely in the Azure blob container shown in `KPIS_STORE_CONTAINER`. Mandatory in environments running on k8s.	NO, only configurable when running the bot locally.
AURA_KPI_TO_DSV_CACHE_TTL	number	Number with the amount of milliseconds to cache existing requests to calculate their duration. Default: `1800`.	NO
AURA_KPI_TO_DSV_DELIMITER	string	Field delimiter to be used in KPIs entities files. Default: \|	NO. It will break all the analysis and processes running on top of these files.
AURA_KPI_TO_DSV_EXTENSION	string	The extension to be used in KPIs entities files. Default: `txt`	NO. If changed without changing aura-kpis-uploader, the files will not be uploaded to Kernel.
AURA_KPIS_BLOB_STORE_INTERVAL	number	Time interval in milliseconds to upload asyncrhonously logs to the `KPIS_STORE_CONTAINER`. Default: `60000`. Only needed if `KPI_STORE_MODE==blob`.	NO. In pre/production it must be `blob` so the files will be uploaded to Kernel instance afterwards. Setting `file` for development is recommended.
AURA_KPIS_STORE_CONTAINER	string	The name of the Azure Blob container to store KPIs entities files. By default, `aura-kpis`. It MUST be the same than the one configured in `KPIS_UPLOADER` module. Only needed if `KPI_STORE_MODE==blob`.	NO. If changed without changing aura-kpis-uploader, the files will not be uploaded to Kernel.
AURA_LOCALE_FOLDER	string	Full path to the local folder where locale files are stored. By default, `./locale`.	NO
AURA_LOCALE_FORCE_IMPORT	boolean	`true` if locale remote loading must be carried out although there were validation errors. By default, `false`.	YES
AURA_LOCALE_REMOTE_BACKUP	boolean	`true`, if after updating locale files with the remote version, a backup of the former local files should be stored in Azure Storage. By default, `false`.	YES
AURA_LOCALE_REMOTE_CONTAINER_PREFIX	string	Path within `AURA_LOCALE_REMOTE_CONTAINER` where the locale files are stored. By default, `locale`.	NO
AURA_LOCALE_REMOTE_CONTAINER	string	Name of the Azure Storage Blob Container where the locale files will be stored. By default, `static-resources`.	NO
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev`(more visual format). By default, `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in monitoring logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default, `INFO`.	YES, for development set it to `DEBUG`. In pre/production should be `INFO` or `ERROR`. For analysis of an issue in pre/production it may be changed to `DEBUG`.
AURA_LOGGING_EXTRA_TIME_METRICS	boolean	`true` if the time metrics should be logged in the monitoring logs. By default: `false`.	NO
AURA_MAX_ATTACHMENT_JSON_SIZE	number	Maximum size from which Aura response attachments will be zipped. By default, `10000` (10 KB)	NO
AURA_MAX_HISTORY_CHAT_ITERATIONS	number	Maximum number of messages saved in the history conversation.	YES
AURA_MICROSOFT_APP_ID	string	ID of the Microsoft bot application to be used in the deployment.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_APP_PASSWORD	string	Password of the Microsoft bot application to be used in the deployment.	NO. It must be changed by Operations Team.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCESS_KEY	string	Microsoft Storage password of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT	string	Microsoft Storage account of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO. It must be changed by Operations Team.
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Microsoft Storage account of the environment.	NO. It must be changed by Operations Team.
AURA_MICROSOFT_AZURE_STORAGE_CONFIGURATION_CONTAINER	string	Name of the container where basic bot configuration files are stored: Mongo indexes descriptor, aura-behavior-manager configuration, etc. By default, `aura-configuration`.	NO
AURA_MICROSOFT_AZURE_STORAGE_SUGGESTION_TABLE_TTL	number	Number of seconds to store the users’ suggestions. By default, `86400` (one day).	NO
AURA_MICROSOFT_AZURE_STORAGE_SUGGESTION_TABLE	string	Name of the Azure Storage table where users’ sent suggestions will be stored. By default, `AuraUserSuggestionTable`	NO
AURA_MICROSOFT_CHANNEL_SERVICE	string	Microsoft Channel Service.	NO. It must be changed by Operations Team.
AURA_MICROSOFT_OPEN_ID_METADATA	string	Metadata used in Microsoft OpendId validation.	NO. It must be changed by Operations Team.
AURA_MIDDLEWARE_SPEAK_PROCESSOR	string	Used to enable speak property text substitution on the outgoing messages, to produce speakable text. Regular expression of substitution format example: `[["\\*"," asterisk "],["\\#"," hash "]]`	YES. Include all the needed changes to be done automatically between the written and the spoken text.
AURA_MIN_INTENT_SCORE_THRESHOLD_TO_CLEAN_STACK	number	Minimal score to clean the dialog stack in a prompt case. By default, `0.95`	NO. Environment configuration should be delivered with a validated threshold, currently `0`, meaning that any valid NLP result will break the prompt and move the user to the new dialog. Do not change it without validating it with Aura Global Team.
AURA_MONGODB_BOT_COLLECTION_CACHES_INDEX_TTL	number	Number of seconds to keep the user’s data available in aura-bot cache. By default, `3600`.	NO
AURA_MONGODB_BOT_COLLECTION_CACHES	string	MongoDB collection name where aura-bot will store the remote caches used during request processing. By default, `aura-caches`.	NO
AURA_MONGODB_BOT_COLLECTION_CONTEXT_INDEX_TTL	number	Number of seconds to keep the context data available in aura-bot context cache. By default, `3600`.	NO
AURA_MONGODB_BOT_COLLECTION_CONTEXT	string	MongoDB collection name where aura-bot will store the context of the users. By default, `aura-context`.	NO
AURA_MONGODB_BOT_DATABASE	string	MongoDB database name where aura-bot will store all the data needed to handle requests. By default, `aura-bot`.	NO
AURA_MONGODB_CACHE_TTL	number	Lifetime of cache used by aura-behavior-manager. It MUST be disabled in PRE and PRO environments. By default, `3600` seconds (1h).	YES, only for development environments.
AURA_MONGODB_CACHE_DATABASE	string	Database used in cache of aura-behavior-manager. By default, `aura-bot-caches`.	YES, only for development environments.
AURA_MONGODB_CACHE_COLLECTION_DL	string	Collection used in cache of aura-behavior-manager. By default, `dev-cache`.	YES, only for development environments.
AURA_MONGODB_CACHE_INDEX_DL	string	Index used in TwoLevelsCache of aura-behavior-manager. By default, `id`.	YES, only for development environments.
AURA_MONGODB_PASSWORD	string	MongoDB password to access `AURA_MONGODB_BOT_DATABASE` in `AURA_MONGODB_URI`.	NO
AURA_MONGODB_POOL_SIZE	number	Number of connections available in MongoDB pool. By default, `60`.	NO
AURA_MONGODB_SSL	boolean	`true` if access to `AURA_MONGODB_URI` is `SSL`. By default, `false`.	NO
AURA_MONGODB_URI	string	MongoDB URI of the server handling. `AURA_MONGODB_BOT_DATABASE`.	NO
AURA_MONGODB_USERNAME	string	MongoDB username to access `AURA_MONGODB_BOT_DATABASE` in `AURA_MONGODB_URI`.	NO
AURA_MONGODB_MAX_POOL_SIZE	number	Maximum number of connections in the MongoDB pool. By default, `60`.	NO
AURA_MONGODB_MIN_POOL_SIZE	number	Minimum number of connections in the MongoDB pool. By default, `2`.	NO
AURA_MONGODB_MAX_IDLE_TIME_MS	number	Maximum idle time in milliseconds for connections in the MongoDB pool. By default, `30000` (30 seconds).	NO
AURA_MONGODB_RETRY_WRITES	boolean	`true` if retry writes are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_RETRY_READS	boolean	`true` if retry reads are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_HEARTBEAT_FREQUENCY_MS	number	Frequency in milliseconds of the heartbeat in the MongoDB connection. By default, `2000` (2 seconds).	NO
AURA_MONGODB_SERVER_SELECTION_TIMEOUT_MS	number	Timeout in milliseconds for server selection in the MongoDB connection. By default, `5000` (5 seconds).	NO
AURA_MONGODB_SOCKET_TIMEOUT_MS	number	Timeout in milliseconds for socket operations in the MongoDB connection. By default, `45000` (45 seconds).	NO
AURA_CONNECTION_TIMEOUT_MS	number	Timeout in milliseconds for establishing a connection to the MongoDB server. By default, `10000` (10 seconds).	NO
AURA_MONGODB_READ_PREFERENCE	string	Read preference for the MongoDB connection. By default, `primaryPreferred`. Possible values: `primary`, `primaryPreferred`, `secondary`, `secondaryPreferred`, `nearest`.	NO
AURA_PHONE_COUNTRY_CODE	string	Two letters ISO-3166 country code to obtain phonenumber without country prefix. It must be one of `BR`, `DE`, `ES`, `UK`.	YES, if the expected country code is not correctly configured.
AURA_PROMETHEUS_REGEX	string	Stringified object that contains regex to apply to prometheus paths in order to group equivalent requests in prometheus. Example: `'{"subscribed_products/$1/users//products": "/subscribed_products\\/(v\\d)\\/users\\/.\\/products/"}'`. By default: `'{}'`	YES
AURA_PRESUGGESTIONS_INTENT	string	Intent that forces to ask for pre-suggestions in the suggestions dialog. By default: `'intent.getOnboarding'`	NO, only if another intent was configured to obtain presuggestions.
AURA_REQUEST_ENABLE_NAGLE	boolean	Boolean to enable Nagle. By default: `false`.	NO
AURA_REQUEST_TIMEOUT	number	Number of milliseconds to wait for a request. By default: `30000`, 30 seconds.	YES, in case of network issues.
AURA_RETRIES_CODES	string[]	Array of strings with error codes. By default: [‘ECONNRESET’].	NO, except if requested.
AURA_SEED_ID	string	Seed used to generate userIds for anonymous users.	NO
AURA_ROOT_INTENT	string	Default intent that aura-bot sets if it has not been possible to determine the user’s intention during recognition/routing process. By default, the `none` intent will be returned.	NO
AURA_SERVER_PORT	number	Port where aura-bot will be listening to requests. By default, `8080`.	NO
AURA_SERVICE_ENVIRONMENT	string	Type of environment: `'DEV', 'PRE', 'PRO'`. By default, `DEV`. It is used during locale translation, to get the correct text reference and, in development environments, to allow aura-behavior-manager execution.	NO
AURA_SERVICE_URL_DIRECTLINE	string	Default URL for Direct Line services. By default, `https://directline.botframework.com/`.	NO
AURA_STATIC_RESOURCE_ENDPOINT	string	URL of the server publishing aura-bot static resources.	NO
AURA_STATIC_RESOURCE_SAS_TOKEN	string	Credentials to access the server publishing aura-bot static resources.	NO. Only if Operations Team needs to change it.
AURA_SUGGESTIONS_V3_NUMBER	number	Number of suggestions configured to be returned in channelData version 3. By default, `5`.	No, only changed if the Global Team or the LCDO Dev Team requires it.
AURA_SUPERAGENT_DEADLINE_TIMEOUT	number	Number of milliseconds to wait until the `superagent` deadline timeout, as specified here. It is optional and, by default, it is not configured.	No, only changed if the Global Team or the LCDO Dev Team requires it.
AURA_SUPERAGENT_RESPONSE_TIMEOUT	number	Number of milliseconds to wait until the `superagent` response timeout, as specified here. It is optional and, by default, it is not configured.	No, only changed if the Global Team or the LCDO Dev Team requires it.
AURA_SUPERAGENT_RETRY_ATTEMPTS	number	Number of retry attempts (not counting the first attempt) to be applied on `superagent` requests, as specified here. It is optional and, by default, it is not configured.	No, only changed if the Global Team or the LCDO Dev Team requires it.
AURA_TEMPORARY_REMOTE_CONTAINER	string	Container to upload temporary resources. By default, `aura-temporary-resources`	NO
AURA_TERMS_AND_CONDITIONS_API_KEY	string	APIKey to call Aura Terms and Conditions API.	NO
AURA_TERMS_AND_CONDITIONS_ENDPOINT	string	Aura Terms and Conditions API basic endpoint.	NO
AURA_TERMS_AND_CONDITIONS_EXPIRATION	number	Terms and conditions expiration time. By default, `86400000` (1 day).	NO, only changed if the Global Team requires it.
AURA_URL_SAS_EXPIRATION	number	Expiration time for sas URLs generated for temporary resources. By default, `600` (minutes).	YES if LCDO or Operations Team prefer another duration time.
AURA_USER_ENCRYPT_CACHE	boolean	`true` to encrypt data stored in users’ cache. By default, `true`.	NO
AURA_USER_LOCAL_CACHE_TTL	number	Number of seconds to keep the user’s data available in aura-bot users’ local cache. By default, `300` sec.	NO
AURA_VERSION	string	Number of the Aura release being executed.	NO
AURA_HTTP_PATHS_LOG_DISABLED	string	HTTP paths separated by commas which requests would not be logged. By default: `aura-kpis,static-resources`. Used in http-monkey-patcher.	YES, if there is a path that should not be logged. The default values are always added to the provided list.
DEV_AURA_BOT_BEHAVIOR_CRON_PATTERN	string	Cron pattern to set the refresh time of aura-behavior-manager configuration. By default, `/5 * * *` (every 5 minutes). It is only valid for development environments.	YES, in development environments.
DEV_AURA_BOT_BEHAVIOR_MICROSOFT_AZURE_STORAGE_SETTINGS_FILE	string	Name of the configuration file route used by aura-behavior-manager. By default, `aura-bot/aura-bot-behavior-manager.json`. It is only valid for development environments.	YES, in development environments
DEV_AURA_BEHAVIOR_MANAGER_ACTIVE	boolean	Flag to indicate whether or not aura-behavior-manager module should be activated in the current deployment. It is only valid for development environments.	YES, in development environments.
AURA_KPIS_BLOB_TIME_WAIT_IF_EXISTS	number	Time to wait in milliseconds if the KPIs blob exists to avoid duplicate headers. By default: `1000`.	YES

Docs:

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

Aura Configuration API environment variables

List of environment variables handled by Aura Configuration API

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description	Modifiable by OB?
AURA_BRANDS	string[]	List of available Telefónica brands configured in Kernel. Check them in the document Telefónica brands management.	YES
AURA_CONFIGURATION_APPLICATIONS_COLLECTION	string	Collection name to store Applications information. By default: `applications`.	NO
AURA_CONFIGURATION_APPLICATIONS_ENCRYPTED_FIELDS	string[]	List of fields that will be saved encrypted in a application document. By default: `['callback']`.	YES, but only for adding fields
AURA_CONFIGURATION_CHANNELS_COLLECTION	string	Collection name to store channel information. By default: `channels`.	NO
AURA_CONFIGURATION_CHANNELS_ENCRYPTED_FIELDS	string[]	List of fields that will be saved encrypted in a channel document. By default: `['security', 'whatsapp']`.	YES, but only for adding fields
AURA_CONFIGURATION_COMPONENTS_COLLECTION	string	Component name to store component information. By default: `components`.	NO
AURA_CONFIGURATION_DATABASE_NAME	string	Aura channels configuration database name. By default: `aura-configuration`.	NO
AURA_CONFIGURATION_EVENTS_ENABLED	boolean	Enable or disable the service synchronization by events.	true
AURA_CONFIGURATION_MAX_LENGTH_TO_LOG_BODY_FIELD	number	Maximum characters length to display body field in logs. By default `1024` characters.	NO
AURA_CONFIGURATION_SERVER_PORT	number	Aura channels configuration server port. By default: `8999`.	NO
AURA_CONFIGURATION_SKILLS_COLLECTION	string	Collection name to store Skills information. By default: `skills`.	NO
AURA_CONFIGURATION_SKILLS_ENCRYPTED_FIELDS	string[]	List of fields that will be saved encrypted in a skill document. By default: `[]`.	YES, but only for adding fields
AURA_CONTACT_CHANNELS	string[]	List of contact channels that will be used.	YES
AURA_ENCRYPTION_ALGORITHM	string	Encryption algorithm that will be used to validate the APIKey. By default: `aes-256-cbc`.	NO
AURA_ENCRYPTION_IV_LENGTH	number	Size for the initialization vector used by the encryption algorithm that validates the APIKey. By default: `16`.	NO
AURA_ENCRYPTION_IV_POSITION	number	Position where to insert the initialization vector in the final string with the encrypted payload. By default: `35`.	NO
AURA_ENCRYPTION_KEY	string	Encryption key or comma-separated list of encryption keys to be used in the environment. It is mainly used to decrypt the APIKeys.	NO. It would break database encrypted data and APIKey validation.
AURA_ENVIRONMENT_NAME	string	Name of the environment where aura-bridge is deployed. Used during aura-bridge make-up to handle the indexes of the database properly. For example: `ap-next`, `es-dev`, `de-pre`	NO
AURA_HTTP_PATHS_LOG_DISABLED	string[]	Paths to be ignored in the logHttpRequestResponse middleware: By default: `['/metrics']`.	YES
AURA_HTTP_MAX_REQUEST_SIZE	string	Maximum size of incoming requests bodies in bytes allowed by the server. By default: `20mb`.	YES
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev` (more visual format). By default: `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in monitoring logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default: `INFO`.	YES, for development set it to ‘DEBUG’. In pre/production should be ‘INFO’ or ‘ERROR’. For analysis of an issue in pre/production it may be changed to ‘DEBUG’
AURA_MAKEUP_MODE	string	Allow dev mode of the makeup with the value `local`. By default: `full`.	NO
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Microsoft Storage account of the environment.	NO
AURA_MICROSOFT_AZURE_STORAGE_AVRO_SCHEMAS_FOLDER	string	Contains the Microsoft Azure Storage Avro schemas folder. Default: ‘avro/schemas’.	NO
AURA_MICROSOFT_AZURE_STORAGE_CONFIGURATION_CONTAINER	string	Aura configuration container name. Default: ‘aura-configuration’.	NO
AURA_MONGODB_PASSWORD	string	MongoDB password to access `AURA_MONGODB_BOT_DATABASE` in `AURA_MONGODB_URI`.	NO
AURA_MONGODB_SSL	boolean	`true` if access to `AURA_MONGODB_URI` is `SSL`. By default: `false`.	NO
AURA_MONGODB_URI	string	MongoDB URI of the server handling `AURA_MONGODB_BOT_DATABASE`.	NO
AURA_MONGODB_USERNAME	string	MongoDB username to access `AURA_MONGODB_BOT_DATABASE` in `AURA_MONGODB_URI`.	NO
AURA_MONGODB_POOL_SIZE	number	Number of connections available in MongoDB pool. By default: `60`.	NO
AURA_MONGODB_MAX_POOL_SIZE	number	Maximum number of connections in the MongoDB pool. By default, `60`.	NO
AURA_MONGODB_MIN_POOL_SIZE	number	Minimum number of connections in the MongoDB pool. By default, `2`.	NO
AURA_MONGODB_MAX_IDLE_TIME_MS	number	Maximum idle time in milliseconds for connections in the MongoDB pool. By default, `30000` (30 seconds).	NO
AURA_MONGODB_RETRY_WRITES	boolean	`true` if retry writes are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_RETRY_READS	boolean	`true` if retry reads are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_HEARTBEAT_FREQUENCY_MS	number	Frequency in milliseconds of the heartbeat in the MongoDB connection. By default, `2000` (2 seconds).	NO
AURA_MONGODB_SERVER_SELECTION_TIMEOUT_MS	number	Timeout in milliseconds for server selection in the MongoDB connection. By default, `5000` (5 seconds).	NO
AURA_MONGODB_SOCKET_TIMEOUT_MS	number	Timeout in milliseconds for socket operations in the MongoDB connection. By default, `45000` (45 seconds).	NO
AURA_CONNECTION_TIMEOUT_MS	number	Timeout in milliseconds for establishing a connection to the MongoDB server. By default, `10000` (10 seconds).	NO
AURA_MONGODB_READ_PREFERENCE	string	Read preference for the MongoDB connection. By default, `primaryPreferred`. Possible values: `primary`, `primaryPreferred`, `secondary`, `secondaryPreferred`, `nearest`.	NO
AURA_REDIS_CONFIGURATION_PREFIX	String	Prefix for the key in Redis used to store configuration values. By default: `aura-config:`.	No
AURA_REDIS_CONNECTION_POOL_MIN	Number	Minimum number of connections in the pool. Default: `2`.	No
AURA_REDIS_CONNECTION_POOL_MAX	Number	Maximum number of connections in the pool. Default: `100`.
AURA_REDIS_DATABASE	Number	Database number for Single or Sentinel mode. By default: `0`.
AURA_REDIS_HOSTS	String	String with a list of nodes (host:port) separated by comma. For example: “localhost:port,localhost2:port2”. Default: ‘127.0.0.0:6379’	No
AURA_REDIS_MAX_RECONNECT_INTERVAL	Number	Time in milliseconds to wait before reconnecting to Redis. By default: `5000`.	No
AURA_REDIS_MAX_RECONNECT_RETRIES	Number	Number of retries to connect to Redis. By default: `25`.	No
AURA_REDIS_MODE	String	Mode of Redis distribution. Values: `Cluster`, `Sentinel` or `Single`. By default: `Single`.	No
AURA_REDIS_PASSWORD	String	A string with the password of Redis.	No
AURA_REDIS_SENTINEL_INSTANCE_NAME	String	Name of the Redis instance. Used in `Sentinel` mode.	No
AURA_REDIS_USE_CONNECTION_POOL	Boolean	Flag to indicate the use of a connection pool for Redis connections. Default: `true`.	No
AURA_SERVER_REMOTE_CONTAINER_PREFIX	string	Remote container prefix. Default: `aura-configuration-api`.	NO
AURA_SWAGGER_FROM_REMOTE	boolean	It indicates that swagger configuration will be loaded from remote. Default: `true`.	NO
AURA_SWAGGER_LOCAL_PATH	string	Swagger local path. Default: `swagger.yaml`.	NO
AURA_SWAGGER_PLUGIN_PATH	string	Swagger plugin path. Default: `swagger.yaml`.	NO
AURA_SWAGGER_LOCAL_CORE_PATH	string	Swagger local core path. Default: `swagger-core.yaml`.	NO
AURA_SWAGGER_REMOTE_CONTAINER_PREFIX	string	Remote container prefix to store the swagger information. Default: `swagger`.	NO
AURA_SHUTDOWN_GRACEFUL_TTL	number	Time in milliseconds to complete the SHUTDOWN signal and process all the messages in queue before SIGTERM. By default: `25 * 1000`.	YES
AURA_VERSION	string	Aura release	NO

Docs:

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

Aura Groot environment variables

Updated list of aura-groot environment variables

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description	Modifiable by OB?
AURA_ACTIVATE_MINI_BOT	boolean	Flag to activate minibot mode. By default: `false`.	NO. Only valid during development to run Aura minibot.
AURA_ALLOWED_CALLERS	string	List of allowed callers separated by commas. By default: [`*`]	YES
AURA_AUTHORIZATION_APIKEY_PATH	string	Path to validate channel APIKey authorization	NO
AURA_AUTHORIZATION_ENDPOINT	string	aura-authentication-api base endpoint.	NO. In any case, it must be the internal k8s URL pointing to the aura-authentication-api.
AURA_AUTHORIZATION_HEADER	string	Complete authorization header to be sent to aura-authentication-api, with the following format: `APIKEY xxxxxx`.	YES, but only if the previous APIKey was deprecated.
AURA_CHANNELDATA_CURRENT_VERSION	string	`channelData` version used internally by aura-groot. By default, `3`.	NO
AURA_CHANNELDATA_DEFAULT_VERSION	string	`channelData` version returned by default in all messages. By default, `1.0.0`.	NO
AURA_CHANNELDATA_RESPONSE_VALIDATION	boolean	Flag to indicate that response validation should be done. By default, `true`.	NO
AURA_CHANNELDATA_VALIDATION	boolean	Flag to indicate that request validation should be done. By default, `true`.	NO
AURA_CHANNELDATA_VALIDATION_VERSIONS	string	`channelData` versions that will be validated. By default, `3`.	NO
AURA_CHANNELDATA_VALIDATION_MIN_VERSION	string	Minimal version to validate. By default, `3`.	NO
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT	string	Endpoint for aura-configuration-api.	NO
AURA_DEFAULT_LOCALE	string	Culture code to be used by default in the current deployment: `de-de`, `en-gb`, `es-es`, `pt-br`.	NO
AURA_DEFAULT_TIME_ZONE	string	Default time zone. For example: `Europe/Madrid`	NO
AURA_ENCRYPTION_ALGORITHM	string	Encryption algorithm used to validate the APIKey	NO. It would break database encrypted data and APIKey validation.
AURA_ENCRYPTION_IV_LENGTH	number	Size for the initialization vector used by the encryption algorithm that validates the APIKey	NO. It would break database encrypted data and APIKey validation.
AURA_ENCRYPTION_IV_POSITION	number	Position where to insert the initialization vector in the final string with the encrypted payload. Future use.	NO. It would break database encrypted data and APIKey validation.
AURA_ENCRYPTION_KEY	string	Encryption key or comma-separated list of encryption keys to be used in the environment. It is mainly used to decrypt the APIKeys.	NO. It would break database encrypted data and APIKey validation.
AURA_ENVIRONMENT_NAME	string	Name of the environment where the aura-authentication-api is deployed. For example: `ap-next`, `es-dev` or `de-pre`.	NO
AURA_EXTERNAL_HOST_SERVICE_URL	string	URL of the external host service.	NO. In any case, it must be the internal k8s URL pointing to the `host-service`.
AURA_HOST_SERVICE_URL	string	URL of the host service.	NO. In any case, it must be the internal k8s URL pointing to the `host-service`.
AURA_HTTP_PATHS_DISABLED_FOR_LOGS	stringArray	Paths which will be filtered in logs. Used in HTTPMonkeyPatcher module.	NO
AURA_HTTP_KEEP_ALIVE	boolean	Use of keep-alive in HTTP connections. Used in HTTPMonkeyPatcher module.	NO
AURA_HTTP_KEEP_ALIVE_MSECS	number	Number of milliseconds to keep alive HTTP connections. Used in HTTPMonkeyPatcher module.	NO
AURA_HTTP_MONKEY_PATCHER_ENABLED	boolean	Enable or disable the monkey patching of the HTTP and HTTPs modules. By default, `false`.	YES
AURA_HTTP_REQUEST_MAX_SOCKETS	number	Maximum number of HTTP sockets open in the server. By default, `100`	NO. Only if indicated by Aura Global Team.
AURA_IGNORE_LOGGING_PATH	string	Comma-separated string with all the incoming paths which requests should not be logged. By default, `/healthz`	YES
AURA_INTERNAL_DELAY_MS	number	The time in milliseconds between retries. By default, `10000`	NO, except if requested
AURA_INTERNAL_RETRIES	number	Number of retries for internal calls. By default, `1`	NO, except if requested
AURA_KPI_ENABLED	Boolean	Boolean value, indicating whether aura-groot writes entity files or not. By default: `true`	NO, excepting if requested by Product or Operations teams
AURA_KPI_FILE_PREFIX	string	String with the prefix used in the KPIs entities files of this service. By default, `groot/GROOT`	NO
AURA_KPI_REMOVE_SPECIAL_CHARACTERS	string	Regular expression for removing special characters Default:`\n\r`	NO
AURA_KPI_STORE_MODE	string	It indicates which is the destination of the KPIs entities files. Default: `blob`. If `file`, they will be stored locally to the instance, in the folder shown in `KPI_TO_DSV_LOCAL_FILES_DIRECTORY`. For development purposes. If `blob`, they will be stored remotely in the Azure blob container shown in `KPIS_STORE_CONTAINER`. Mandatory in environments running on k8s.	NO, only configurable when running aura-groot locally.
AURA_KPI_TO_DSV_CACHE_TTL	number	Number with the amount of milliseconds to cache existing requests to calculate their duration. Default: 1800.	NO
AURA_KPI_TO_DSV_DELIMITER	string	Field delimiter to be used in KPIs entities files. Default: \|	NO. It will break all the analysis and processes running on top of these files.
AURA_KPI_TO_DSV_EXTENSION	string	Extension to be used in KPIs entities files.Default: `txt`	NO. If changed without changing aura-kpi-uploader, the files will not be uploaded to Kernel.
AURA_KPIS_BLOB_STORE_INTERVAL	number	Time interval in milliseconds to upload asyncrhonously logs to the `KPIS_STORE_CONTAINER`. Default: `60000`. Only needed if `KPI_STORE_MODE==blob`.	NO. In pre/production, it must be blob so the files will be uploaded to Kernel instance afterwards. Setting file for development is recommended.
AURA_KPIS_LOG_API_REQUEST_BODY	boolean	Flag to log or not the request body of the API calls. Default: `true`	YES. Once disabled, to enable run performance tests to validate if it is possible to write them.
AURA_KPIS_LOG_API_RESPONSE_BODY	boolean	Flag to log or not the response body of the API calls. Default: `true`	YES. Once disabled, to enable run performance tests to validate if it is possible to write them.
AURA_KPIS_STORE_CONTAINER	string	The name of the Azure Blob container to store KPIs entities files. By default, `aura-kpis`. It MUST be the same than the one configured in `KPIS_UPLOADER` module. Only needed if `KPI_STORE_MODE==blob`.	NO. If changed without changing aura-kpi-uploader, the files will not be uploaded to Kernel.
AURA_LOCALE_FOLDER	string	Full path to the local folder where locale files are stored. By default, `./locale`.	NO
AURA_LOCALE_FORCE_IMPORT	boolean	`true` if locale remote loading must be carried out although there were validation errors. By default, `false`.	YES
AURA_LOCALE_REMOTE_CONTAINER	string	Name of the Azure Storage Blob Container where the locale files will be stored. By default, `static-resources`.	NO
AURA_LOCALE_REMOTE_CONTAINER_PREFIX	string	Path within `AURA_LOCALE_REMOTE_CONTAINER` where the locale files are stored. By default, `locale`.	NO
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev`(more visual format). By default, `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in monitoring logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default, `INFO`.	YES, for development set it to `DEBUG`. In pre/production should be `INFO` or `ERROR`. For analysis of an issue in pre/production it may be changed to `DEBUG`.
AURA_MAKEUP_MODE	string	Allow dev mode of the make-up with the value `local`. By default, `full`.	NO, only for development, set it to `local`.
AURA_MAX_HISTORY_CHAT_ITERATIONS	number	Number of history chat iterations saved in conversation history. By default, `6`	NO
AURA_MESSAGES_REQUEST_PATH	string	Path exposed to receive incoming messages. By default, `/api/messages`	NO
AURA_MICROSOFT_APP_ID	string	ID of the Microsoft bot application to be used in the deployment.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_APP_PASSWORD	string	Password of the Microsoft bot application to be used in the deployment.	NO. It must be changed by Operations Team.
AURA_MICROSOFT_APP_TYPE	string	Type of the Microsoft bot application to be used in the deployment. By default: `MultiTenant`	NO. Only if Operations Team changes it.
AURA_MICROSOFT_APP_TENANT_ID	string	Tenant ID of the Microsoft bot application to be used in the deployment.	NO. Only if operations team changes it.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCESS_KEY	string	Microsoft Storage password of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT	string	Microsoft Storage account of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO. It must be changed by Operations Team.
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Microsoft Storage account of the environment.	NO. It must be changed by Operations Team.
AURA_MICROSOFT_AZURE_STORAGE_CONFIGURATION_CONTAINER	string	Name of the container where basic bot configuration files are stored: Mongo indexes descriptor, aura-behavior-manager configuration, etc. By default, `aura-configuration`.	NO
AURA_MIDDLEWARE_SPEAK_PROCESSOR	string	Used to enable speak property text substitution on the outgoing messages, to produce speakable text. Regular expression of substitution format example: `[["\\*"," asterisk "],["\\#"," hash "]]`	YES. It includes all the needed changes to be done automatically between the written and the spoken text.
AURA_MONGODB_BOT_COLLECTION_CONTEXT_INDEX_TTL	number	Number of seconds to keep the context data available in aura-groot context cache. By default, `3600`.	NO
AURA_MONGODB_BOT_COLLECTION_CONTEXT	string	MongoDB collection name where aura-groot will store the context of the users. By default, `aura-context`.	NO
AURA_MONGODB_BOT_DATABASE	string	MongoDB database name where aura-groot will store all the data needed to handle requests. By default, `aura-groot`.	NO
AURA_MONGODB_CACHE_TTL	number	Lifetime of cache used by aura-behavior-manager. It MUST be disabled in PRE and PRO environments. By default, `3600` seconds (1h).	YES, only for development environments.
AURA_MONGODB_CACHE_DATABASE	string	Database used in cache of aura-behavior-manager. By default, `aura-groot-caches`.	YES, only for development environments.
AURA_MONGODB_CACHE_COLLECTION_DL	string	Collection used in cache of aura-behavior-manager. By default, `dev-cache`.	YES, only for development environments.
AURA_MONGODB_CACHE_INDEX_DL	string	Index used in TwoLevelsCache of aura-behavior-manager. By default, `id`.	YES, only for development environments.
AURA_MONGODB_CACHE_METRIC_TTL	number	Lifetime of metric cache. By default, `60` seconds (1 minute).	YES.
AURA_MONGODB_CACHE_METRIC_COLLECTION	string	Collection used in metric-cache. By default, `metric-cache`.	YES
AURA_MONGODB_CACHE_METRIC_INDEX	string	Index used in TwoLevelsCache of metric-cache. By default, `correlator`.	YES
AURA_MONGODB_PASSWORD	string	MongoDB password to access `AURA_MONGODB_BOT_DATABASE` in `AURA_MONGODB_URI`.	NO
AURA_MONGODB_POOL_SIZE	number	Number of connections available in MongoDB pool. By default, `60`.	NO
AURA_MONGODB_SSL	boolean	`true` if access to `AURA_MONGODB_URI` is `SSL`. By default, `false`.	NO
AURA_MONGODB_URI	string	MongoDB URI of the server handling. `AURA_MONGODB_BOT_DATABASE`.	NO
AURA_MONGODB_USERNAME	string	MongoDB username to access `AURA_MONGODB_BOT_DATABASE` in `AURA_MONGODB_URI`.	NO
AURA_MONGODB_MAX_POOL_SIZE	number	Maximum number of connections in the MongoDB pool. By default, `60`.	NO
AURA_MONGODB_MIN_POOL_SIZE	number	Minimum number of connections in the MongoDB pool. By default, `2`.	NO
AURA_MONGODB_MAX_IDLE_TIME_MS	number	Maximum idle time in milliseconds for connections in the MongoDB pool. By default, `30000` (30 seconds).	NO
AURA_MONGODB_RETRY_WRITES	boolean	`true` if retry writes are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_RETRY_READS	boolean	`true` if retry reads are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_HEARTBEAT_FREQUENCY_MS	number	Frequency in milliseconds of the heartbeat in the MongoDB connection. By default, `2000` (2 seconds).	NO
AURA_MONGODB_SERVER_SELECTION_TIMEOUT_MS	number	Timeout in milliseconds for server selection in the MongoDB connection. By default, `5000` (5 seconds).	NO
AURA_MONGODB_SOCKET_TIMEOUT_MS	number	Timeout in milliseconds for socket operations in the MongoDB connection. By default, `45000` (45 seconds).	NO
AURA_CONNECTION_TIMEOUT_MS	number	Timeout in milliseconds for establishing a connection to the MongoDB server. By default, `10000` (10 seconds).	NO
AURA_MONGODB_READ_PREFERENCE	string	Read preference for the MongoDB connection. By default, `primaryPreferred`. Possible values: `primary`, `primaryPreferred`, `secondary`, `secondaryPreferred`, `nearest`.	NO
AURA_REQUEST_ENABLE_NAGLE	boolean	Boolean to enable Nagle. By default: `false`.	NO
AURA_REQUEST_TIMEOUT	number	Number of milliseconds to wait a request. By default: `30000`, 30 seconds.	YES, in case of network issues.
AURA_SERVER_BODY_LIMIT	string	Maximum size in bytes of the request body. It is a string because the allowed values must indicate the units: 10 mb, 200 kb, etc. By default, `20 mb`.	YES, in order to decrease it, if it is considered too high. To increase it, both local and global Operational Teams must review it, because it could lead to DDoS attacks easily.
AURA_SERVER_PORT	number	Port where aura-groot will be listening to requests. By default, `8080`.	NO
AURA_SERVICE_ENVIRONMENT	string	Type of environment: `'DEV', 'PRE', 'PRO'`. By default, `DEV`. It is used during locale translation, to get the correct text reference and, in development environments, to allow aura-behavior-manager execution.	NO
AURA_SERVICE_URL_DIRECTLINE	string	Default URL for Direct Line services. By default, `https://directline.botframework.com/`.	NO
AURA_SHUTDOWN_GRACEFUL_TTL	number	Number of milliseconds to wait until all aura-groot tasks are done before shutting each pod down. By default `25000` (25 seconds)	NO
AURA_SKILLS_BLOCKED_TIMEOUT	number	Number of seconds to block a skill after a timeout. By default, `600` (10 minutes).	NO
AURA_SKILLS_RESPONSE_PATH	string	Path where the skills will return the answers. By default, `/api/skills`.	NO
AURA_SUPERAGENT_DEADLINE_TIMEOUT	number	Number of milliseconds to wait until the `superagent` deadline timeout, as specified here. It is optional and, by default, is not configured.	No, only changed if the Global Team or the LCDO Dev Team requires it.
AURA_SUPERAGENT_RESPONSE_TIMEOUT	number	Number of milliseconds to wait until the `superagent` response timeout, as specified here. It is optional and, by default, it is not configured.	No, only changed if the Global Team or the LCDO Dev Team requires it.
AURA_SUPERAGENT_RETRY_ATTEMPTS	number	Number of retry attempts (not counting the first attempt) to be applied on `superagent` requests, as specified here. It is optional and, by default, it is not configured.	No, only changed if the Global Team or the LCDO Dev Team requires it.
AURA_RETRIES_CODES	string[]	Array of strings with error codes. By default, [‘ECONNRESET’]	NO, except if requested
AURA_VERSION	string	Number of the Aura release being executed.	NO
AURA_HTTP_PATHS_LOG_DISABLED	string	HTTP paths separated by commas which requests would not be logged. By default: `aura-kpis,static-resources`. Used in http-monkey-patcher.	YES, if there is a path that is not wanted to be logged. The default values are always added to the provided list.
DEV_AURA_BEHAVIOR_MANAGER_ACTIVE	boolean	Flag to indicate whether or not aura-behavior-manager module should be activated in the current deployment. It is only valid for development environments.	YES, in development environments.
DEV_AURA_GROOT_BEHAVIOR_CRON_PATTERN	string	Cron pattern to set the refresh time of aura-behavior-manager configuration. By default, `/5 * * *` (every 5 minutes). It is only valid for development environments.	YES, in development environments.
DEV_AURA_GROOT_BEHAVIOR_MICROSOFT_AZURE_STORAGE_SETTINGS_FILE	string	Name of the configuration file route used by aura-behavior-manager. By default, `aura-groot/aura-groot-behavior-manager.json`. It is only valid for development environments.	YES, in development environments

Docs:

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

Aura Redis Mongo Synchronizer environment variables

Notation

List of environment variables defined for aura-redis-mongo-sync component

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description	Modifiable by OB?
AURA_LOGGING_EXTRA_TIME_METRICS	Boolean	Extra time metrics for logging. By default: `false`.	No
AURA_LOGGING_LEVEL	String	Level to be used in monitoring logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default: `INFO`.	Yes
AURA_MONGODB_BOT_COLLECTION_CACHES_INDEX_TTL	Number	Lifetime, in seconds, for the index of the caches collection. By default: `3600`	No. Only if validated with Aura Global team, because it is related to other values.
AURA_MONGODB_BOT_COLLECTION_CONTEXT	String	Name of the collection where the context is stored. By default: `aura-context`.	No
AURA_MONGODB_BOT_DATABASE	String	Name of the database where the bot collections are stored. By default: `aura-bot`	No
AURA_MONGODB_PASSWORD	String	Password of the user that accesses MongoDB.	No. Only if MongoDB credentials must be changed.
AURA_MONGODB_POOL_SIZE	Number	Pool size of the MongoDB. By default: `60`.	No.
AURA_MONGODB_SSL	Boolean	Flag to indicate if MongoDB connection uses SSL or not. By default: `true`.	No
AURA_MONGODB_URI	String	URI of the MongoDB	No
AURA_MONGODB_USERNAME	String	Username of the MongoDB	No
AURA_REDIS_CONFIGURATION_PREFIX	String	Prefix for Redis configuration keys. By default: `aura-config:`	No
AURA_REDIS_CONTEXT_CACHE_PREFIX	String	Prefix for Redis context cache keys. By default: `context:`	No
AURA_REDIS_SUBSCRIPTIONS_EVENTS	String	Comma-separated list of the types of Redis messages to trigger subscriptions events. By default: `expired,evicted`	No
AURA_REDIS_CONTEXT_CACHE_SHADOW_KEY_PREFIX	String	Prefix for Redis shadow key cache keys. By default: `shadow-key:`	No
AURA_REDIS_CONTEXT_CACHE_ACTIVE_CONTEXT_PREFIX	String	Prefix for Redis active context cache keys. By default: `active-context:`	No
AURA_REDIS_CONTEXT_CACHE_LOCK_PREFIX	String	Prefix for Redis lock context cache keys. By default: `lock-context:`	No
AURA_REDIS_CONTEXT_CACHE_MIN_SHARD_BY_NODE	Number	Number of minimal shards assigned to a service. By default: `1`	No
AURA_REDIS_CONTEXT_CACHE_CHECK_INDEX_SHARD_INTERVAL	Number	Number of seconds to wait before recalculate shards to subscribe events. By default: `60`.	No
AURA_REDIS_CONTEXT_CACHE_CHECK_UNPROCESSED_INTERVAL_MIN	Number	Minimum number of seconds to wait before checking unprocessed contexts. By default: `10`.	No
AURA_REDIS_CONTEXT_CACHE_CHECK_UNPROCESSED_INTERVAL_MAX	Number	Maximum number of seconds to wait before checking unprocessed contexts. By default: `120`.	No
AURA_REDIS_CONTEXT_CACHE_CHECK_UNPROCESSED_FACTOR	Number	Factor to increment or decrement interval to check unprocessed contexts. By default: `1.1`.	No
AURA_REDIS_CONTEXT_CACHE_UNPROCESSED_RANGE	Number	Number of unprocessed contexts to check by turn. By default: `10`.	No
AURA_REDIS_CONTEXT_CACHE_UNPROCESSED_RANGE_FACTOR	Number	Factor to divide the unprocessed range. By default: `5`.	No
AURA_REDIS_CONTEXT_CACHE_SHARD_COUNT	Number	Number of shards to generate lists for storing unprocessed context. For performance reasons, it is important to configure the same number as the number of pods of the aura-redis-mongo-synchronizer.	No
AURA_REDIS_CONTEXT_CACHE_TTL	Number	Time in seconds to store a context in cache. By default: `60`.	No
AURA_REDIS_LOCK_CONTEXT_CACHE_TTL	Number	Time in seconds to store a lock context in cache. By default: `60`.	No
AURA_REDIS_MODE	String	Mode of Redis distribution. Values: `Cluster`, `Sentinel` or `Single`. By default: `Single`.	No
AURA_REDIS_PREFIX	String	Prefix that will be used by all Redis keys when using redis-connector. This allows mixing in a single Redis service messages coming from different environments in the same Azure subscription.	No
AURA_REDIS_SENTINEL_INSTANCE_NAME	String	Name of the Redis instance. Used in `Sentinel` mode.	No
AURA_REDIS_HOSTS	String	A string with a list of nodes (host:port) separated by comma. For example: “localhost:port,localhost2:port2”. Default: ‘127.0.0.0:6379’	No
AURA_REDIS_DATABASE	Number	Database number for Single or Sentinel mode. By default: `0`.
AURA_REDIS_PASSWORD	String	A string with the password of Redis.	No
AURA_REDIS_MAX_RECONNECT_RETRIES	Number	Number of retries to connect to Redis. By default: `25`.	No
AURA_REDIS_MAX_RECONNECT_INTERVAL	Number	Time in milliseconds to wait before reconnecting to Redis. By default: `5000`.	No
AURA_REDIS_USE_CONNECTION_POOL	Boolean	Flag to indicate to use a connection pool for Redis connections. Default: `true`.	No
AURA_REDIS_CONNECTION_POOL_MIN	Number	Minimum number of connections in the pool. Default: `2`.	No
AURA_REDIS_CONNECTION_POOL_MAX	Number	Maximum number of connections in the pool. Default: `100`.	No
AURA_REQUEST_TIMEOUT	Number	Number of seconds to wait a request. By default: `30 * 1000`.	No
AURA_SERVER_PORT	Number	Port where the server will be listening. By default: `8989`	No
AURA_SERVER_RETRIES	Number	Number of retries made by the server in case of error in an HTTP request. By default: `3`.	No
AURA_SERVER_RETRY_DELAY	Number	Delay between retries in case of error. By default: `100`.	No
AURA_SERVER_RETRY_FACTOR	Number	Factor to multiply delay for every HTTP request retried. By default: `10`.	No
AURA_SERVICE_ENVIRONMENT	Number	Type of environment: `'DEV', 'PRE', 'PRO'`. By default, `DEV`. It is used during locale translation, to get the correct text reference.	No
AURA_SHUTDOWN_GRACEFUL_TTL	Number	Time in milliseconds to complete the SHUTDOWN signal and p process all the messages in queue before SIGTERM. By default: `25 * 1000`	No
AURA_VERSION	String	Aura version. It is set by the deployment process.	No

Docs:

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

Guidelines for technical developers

Scope: Comprehensive guidelines for the development of an agent and its integration into ATRIA

Technical developers

Introduction

ATRIA offers a framework for the development of agents to be used for the creation of experiences.

Agents can be developed both using their own tools or taking advantage of the libraries and tools that ATRIA provides. The current document will focus on the second option.

Agents development workflow

Prerequisites

Two main prerequisites are required prior to the development of an agent:

Python version: 3.13. or higher
ATRIA agents-server dependencies must be installed.

Workflow

The orderly steps for the creation and subsequent deployment of an agent are included below:

Docs:

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

Kernel configuration: General steps

General guidelines for the execution over Kernel of tasks required for Aura features

Introduction

Certain Aura features requires the execution of preliminary tasks over Kernel to access its integrated resources and capabilities, such as APIs, datasets, etc.

The following sections outline the tasks that are common to all Aura features. Additionally, each of them will have their own specific requirements.

1. Check APIs publication in Kernel

If the Aura feature uses a Kernel API, check if the API is published in Kernel: List of available APIS on Telefónica Kernel.
If not, follow the guidelines in the document Publish an API in Kernel.

2. Check datasets publication in Kernel

Only necessary if the Aura feature requires datasets

Identify the required datasets for the configuration of the feature:
- Aura entities
Check that these datasets are published in Kernel: List of available datasets on Telefónica Kernel.
If not, ask the Kernel Team to publish the datasets in Kernel productive environment with the latest version.

3. Create a Kernel application

Accessing Kernel data requires the previous generation of an application (Kernel client), which must be configured with permissions to access specific datasets.

For certain Aura features, a specific Kernel application must be created from scratch. Other ones require the use of already existing Kernel applications, such as aura-bot-[environment], that must be specifically configured for this feature (Step 4).

Ask the Kernel Team to create a new application with a specific name (id) in Kernel for your intended environment.
Once the app is created, two parameters will be provided for securely accessing:
- client_id: unique identifier of the consuming app acting as Kernel API client.
- client_secret: password.

4. Assign purpose/scopes to the application

Only in the case of data that contain personal information (PI-scopes), it is necessary to create a purpose in Kernel, that defines the reason for accessing information-related data. In this scenario, ask the Kernel Team to generate a purpose for the new application or the existing one required by the Aura feature.
Ask the Kernel Team to generate the scopes required for the Aura feature, that define the access level to datasets (writing/reading permissions to/from Kernel datasets).

Take into account the following considerations:
- If a purpose is required, the scopes must be associated to it.
- There are global admin scopes that are always mandatory for every app in order to write/read datasets:
  - admin:datasets:read
  - data:read
  - data:write
- Additionally, each Aura feature requires its specific scopes.
- The version number is not needed in the scopes.

Guidelines for Kernel configuration in specific Aura features

List of published guidelines that include specific Kernel configuration:

Billing module operation

Docs:

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

Preset plugin

Preset plugin description for aura-configuration-api

Introduction

The preset plugin defines services associated with the management of presets in aura-configuration-api server.

All these services are defined in the presets namespace (/presets).

Servers definition

By default, the servers defined in the swagger include the base path (for v1): /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/presets
aura-services/v2/configuration/presets/{presetId}

Endpoints

Path	Method	Description
/presets/	GET	Get all presets information
/presets/	POST	Add a new preset
/presets/{presetId}	GET	Get preset information using preset id
/presets/{presetId}	PUT	Replace preset information associated to preset id
/presets/{presetId}	PATCH	Update some fields of preset information using preset id
/presets/{presetId}	DELETE	Delete preset information using preset id

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

Retrieving information from presets

Retrieving specific fields from preset information

It is possible to get only a specific list of fields for preset 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/presets?includeFields=id,name,generative' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: XXX'

Response example:

[
    {
        "id": "ab744582-c5a6-48e1-95bb-f509bdb55512",
        "name": "preset_2",
        "generative": {
            "model": {
                "id": "gpt-4o-mini",
                "parameters": {
                    "top_p": 1,
                    "max_tokens": 250,
                    "temperature": 1
                }
            },
            "prompts": {
                "template": "string",
                "preamble": {
                    "text": "Hola.",
                    "args": {
                        "brand": "Movistar",
                        "country": "Spain",
                        "year": "2024"
                    }
                },
                "promptMaxLength": 1500
            }
        }
    }
]

Excluding fields in presets information

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

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

Response example:

[
    {
        "id": "ab744582-c5a6-48e1-95bb-f509bdb55512",
        "name": "preset_2",
        "session": {
            "window": 8
        }
    }
]

Database

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

Docs:

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

Guidelines for the integration of a use case into Aura suggestions

Discover how to integrate a developed use case into Aura suggestions, so it can be recommended to the users in order to enrich their experience in Aura

Introduction

Aura suggests options based on an AI algorithm to provide additional information to the users, proposing new use cases always aligned with the initial user’s request.

The objective of the suggestions is to foster the users’ engagement with Aura, letting them go on with the conversation with two objectives:

Discover new functionalities: suggestions can help the users discover what Aura can offer.
Interaction follow-up: suggestions simplify and (somehow) predict the follow-up messages from the user. In some scenarios, the user wants to dig deeper in a set of actions given the context of the conversation. Suggestions can help to make the interaction easier and faster.

The suggestions-dialog is in charge of requesting suggestions to the Aura Suggestions API and preparing the corresponding activity with the format handled by the user channel.

Aura suggestions response model is used in every channel where Aura is available, and its visual components are adapted to the different constraints of the different channels.

How to integrate a use case into Aura suggestions

If, when developing a use case, you want it to be suggested by Aura, you have to set the property suggestions to true in the use case dialog, as shown in the following example for the balance-topup dialog (bill):

{
  "name": "bill",
  "dialogs": [
    {
      "id": "balance-topup",
      "suggestions": true,             // Suggestions enabled
      "authorization": {
        "purposes": "customer-self-service",
        "scopes": "mobile-balance-top-up-write"
      },
    }
  ]
}

In the previous example, the suggestions-dialog is executed after the balance-topup dialog.

Docs:

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

Synchronization by events

Description of the synchronization by events process

Introduction

Event-driven synchronization is a system that allows updating the configuration of any module in the components in real time.

This is done through events, which are emitted when a certain module modifies its configuration data, and allows the Aura components that are subscribed to the events to update their configuration in real time.

The synchronization by events operates as follows:

A service updates a certain configuration element.
The new updated data is stored in MongoDB.
An Event is published by the Event Manager. The current system supports two Event Managers, Redis Pub/Sub and DAPR.
When the event is issued, the services subscribed to the configuration events receive the Event.
The changes are requested through the aura-configuration-api.

Event management can be activated or deactivated in both the event transmission and reception parts. The environment variable that has the aura-configuration-api and the components that support this system is called AURA_CONFIGURATION_EVENTS_ENABLED. The environment variable AURA_CONFIGURATION_EVENTS_MANAGER determines the engine used for event handling, possible values are “REDIS” or “DAPR”.

Using Redis as Event Manager

Publishers and subscribers

In order for a component to update the configuration data that has been modified by another service, two types of elements are required:

Publishers, which are the ones that notify of the change
Subscribers, which are the ones that will receive an event indicating that a change has occurred and where it has taken place.

All this is managed through the broadcasting of events in Redis through a specific channel using the Pub/Sub module.

Channel

The name of the channel has the following structure: [AURA_REDIS_DATABASE]__:[AURA_REDIS_CONFIGURATION_PREFIX][ConfigCollectionName]*

This pattern will be used by most of the current components. If any of them need to manage identifiers within the channel, such as Agents, they will be subscribed to the channel: [AURA_REDIS_DATABASE]__:[AURA_REDIS_CONFIGURATION_PREFIX][ConfigCollectionName]:[Id]

Being:

AURA_REDIS_DATABASE: Environment variable with the number of database in Redis.
AURA_REDIS_CONFIGURATION_PREFIX: Environment variable whose default value is aura-config.
ConfigCollectionName: One of the following values: ChannelConfiguration, ApplicationConfiguration, SkillConfiguration, TvSectionsConfiguration, PresetConfiguration, AgentConfiguration.

Example:
1__:aura-config:ChannelConfiguration

Event Message

When the event is sent, it has the following format:

{ 
    collection: [ConfigCollectionName]  
    op:         [OPERATION];
    id:         [IDENTIFIER];
    configData: [CONFIGURATION_DATA]; 
    metadata:   [EVENT_METADATA]                (Dapr)
    pubSubName: [DAPR_PUBSUB_NAME];             (Dapr)
    crc:        [INTEGRITY];                    (Not implemented)
}

The different types of operations are (EventConfigOperation):

Create: When a record is created in the configuration. It will carry the identifier of the new record.
Update: When a record is modified in the configuration. It will carry the identifier of the updated record.
Delete: When a record is deleted in the configuration. It will carry the identifier of the deleted record.

The configuration data contains the updated or new configuration data. This field is not mandatory, and if the configuration data is empty the subscriptor refreshes its configuration calling directly the configuration API.

Examples:

Without configuration data

{
    "op":Create",
    "id":"88834434"
}

With configuration data
{
    "op":Create",
    "id":"88834434", 
    "configData": 
        {
            "name":"Expample1",
             "id":"88834434",
             .... 
         }
}

Publishers

The publishers are inside the aura-configuration-api.

When one of the configuration models writes to the MongoDB database, the event must be generated through Redis. This is done by instantiating an element of the RedisEventPublisher class. The creation of these update records in Redis has two requirements that must be met:

The API must contain an endpoint to obtain all the data from the model named GetAll.
The API must contain an endpoint to obtain an element of the model selected by its identifier named GetById.

To write the records in Redis that will generate the events, we will use the DAO of the model, specifically the method writeConfigurationEvent that is in charge of generating the registry for the event in Redis.

    // aura-configuration-api/src/common/dao.ts
    /**
     * Write configuration event.
     * @param {EventConfigOperation} operation Operation type
     * @param {string} id Id of the configuration
     * @param {T} data Data to write
     * @param {KeyValueType} metadata Metadata to write
     */
    protected async writeConfigurationEvent(operation: EventConfigOperation, id?: string, data?: T, metadata?: KeyValueType) {
        this.configurationEventPublish.op = operation;
        this.configurationEventPublish.id = id;
        this.configurationEventPublish.configData = data;
        this.configurationEventPublish.metadata = Object.assign({}, this.configurationEventPublish.metadata, metadata);

        await this.eventPublisher.publish(this.configurationEventPublish);
    }}

The eventPublisher can be one of Redis or DAPR. For Redis, the class with the methods to publish the event is included in /aura-configuration-api/src/utils/event-publishers/redis-event-publisher.ts

Generate events

When an event is generated, the operation that has been performed is indicated with the identifier of the record affected by the change.

    /**
     * Update channel.
     *
     * @throws {NoDataError} When it hasn't been updated
     * @throws {Error} When channel is invalid
     * @param {ChannelConfiguration} channel Channel configuration
     */
    public async update(channel: ChannelConfiguration) {
        channel.metadata = {
            ...(await this.channelCollection.findOne<ChannelConfiguration>(
                { id: channel.id }, { projection: { metadata: 1 } })
            )?.metadata,
            ...channel.metadata
        };
        const updateResult = await this.channelCollection.replaceOne(
            { id: channel.id }, this.prepareChannelToInsert(channel));
        if (updateResult?.modifiedCount === 0) {
            throw new NoDataError(`Channel with id: ${channel.id} cannot be found`);
        } else {
            await this.writeConfigurationEvent(EventConfigOperation.Update, channel.id);
        }
    }

Subscribers

Subscribers are inside the aura-utilities/aura-configuration library, and are the clients of each of the models in the aura-configuration-api.

These subscribers inherit their class from a base class BaseConfiguration that contains the necessary methods to manage the data. Some methods are common to all and others are specific. They include methods to manage the data locally, that is, if we receive the content of the changes in the event itself, we should be able to apply them on the current module without having to call the aura-configuration-api* to obtain them.

An example for the method of point 3 could be the following:

    /**
      * Update channel configuration.
      *
      * @param {Configuration} configuration Configuration object.
      * @param {EventConfigModel} message Event configuration model.
      * @returns {Promise<void>} Promise.
      */
    public async updateConfiguration(message: EventConfigModel<T>): Promise<void> {
        try {
            this.logger.debug({
                msg: 'UpdateChannelConfiguration executed', message,
                corr: CorrelatorUtil.auraSystem
            });

            switch (message.op) {
                case EventConfigOperation.Create:
                    try {
                        await this.createConfigurationById(message);
                    } catch (error) {
                        // if there is an error updating a single channel, update all the config with the current values
                        await this.load();
                    }
                    break;
                case EventConfigOperation.Update: {
                    try {
                        await this.updateConfigurationById(message);
                    } catch (error) {
                        // if there is an error updating a single channel, update all the config with the current values
                        await this.load();
                    }
                }
                    break;
                case EventConfigOperation.Delete:
                    if (this.removeLocal(message.id)) {
                        this.logger.debug({
                            msg: `Channel removed with id: ${message.id}`, corr: CorrelatorUtil.auraSystem
                        });
                    } else {
                        this.logger.warning({
                            msg: `Channel not found to remove with id: ${message.id}`, corr: CorrelatorUtil.auraSystem
                        });
                        await this.load();
                    }
                    break;

                default:
                    this.logger.warning({
                        msg: `Unknown operation: ${message.op} for configuration update: ${message.id}`,
                        corr: CorrelatorUtil.auraSystem
                    });
                    break;

            }
        } catch (error) {
            this.logger.error({
                msg: 'updateChannelConfiguration failed.', error: error.message, stck: error,
                corr: CorrelatorUtil.auraSystem
            });
        }
    }

The methods createConfigurationById and updateConfigurationById contain the logic to apply the changes locally or through the aura-configuration-api*.

    /**
     * Create channel configuration by id.
     * @param {Configuration} configuration Configuration object.
     * @param {EventConfigModel<ChannelConfiguration>} message Event configuration model.
     * @returns {Promise<void>} Promise.
     */
    private async createConfigurationById(message: EventConfigModel<T>): Promise<void> {
        // if the message has the configuration data, create the channel directly.
        if (message.configData && this.addLocal(message.configData)) {
            this.logger.debug({
                msg: `Channel added with new configuration: ${message.id}`, corr: CorrelatorUtil.auraSystem
            });
        } else {
            await this.loadById(message.id);
        }
    }

Using DAPR as Event Manager

Publishers and subscribers

In order for a component to update the configuration data that has been modified by another service, two types of elements are required:

Publishers, which are the ones that notify of the change.
Subscribers, which are the ones that will receive an event indicating that a change has occurred and where it has taken place.

All this is managed through DAPR Pub/Sub block. The engine selected to manage the PubSub is Redis. Unlike the pure PubSub management in Redis, which has the problem that if a subscriber does not receive the event, it will not be resent, with DAPR this does not happen since it takes care of the Event lifetime internally and manages the retries if needed.

Channel

In the DAPR Pub/Sub block, the concept of a channel is not applicable. In order to subscribe to an event, the name of the Pub/Sub module and the topic to be subscribed are required.

pubsubname: AURA_DAPR_CONFIGURATION_PUBSUB_NAME
topic: ConfigCollectionName

Being:

AURA_DAPR_CONFIGURATION_PUBSUB_NAME: Name of PubSub module defined in DAPR for Configuration Events.
ConfigCollectionName: One of the following values: ChannelConfiguration, ApplicationConfiguration, SkillConfiguration, TvSectionsConfiguration, PresetConfiguration, AgentConfiguration.

Event Message

DAPR uses a global event management model called CloudEvents. CloudEvents is a specification for describing event data in common formats to provide interoperability across services, platforms and systems.

For compatibility reasons with the Event Managr in Redis, the name of the model used for Redis has been included within the field data of CloudEvents.

Example CloudEvent
{
  "data": {
    "collection": "ChannelConfiguration",
    "id": "c71dc728-5fe2-4735-927d-0c419b35ec59",
    "metadata": {
      "ttlInSeconds": "60"
    },
    "op": "Update",
    "pubSubName": "pubsub-config-ap-four"
  },
  "datacontenttype": "application/json",
  "expiration": "2025-06-30T08:16:05Z",
  "id": "a8340fb8-9071-4da9-91d6-7a14a409d459",
  "pubsubname": "pubsub-config-ap-four",
  "source": "aura-configuration-api",
  "specversion": "1.0",
  "time": "2025-06-30T08:15:05Z",
  "topic": "ChannelConfiguration",
  "traceid": "00-00000000000000000000000000000000-0000000000000000-00",
  "traceparent": "00-00000000000000000000000000000000-0000000000000000-00",
  "tracestate": "",
  "type": "com.dapr.event.sent"
}

Inside the data property, it has the following format:

{ 
    collection: [ConfigCollectionName]  
    op:         [OPERATION];
    id:         [IDENTIFIER];
    configData: [CONFIGURATION_DATA]; 
    metadata:   [EVENT_METADATA]                (Dapr)
    pubSubName: [DAPR_PUBSUB_NAME];             (Dapr)
    crc:        [INTEGRITY];                    (Not implemented)
}

The different types of operations are (EventConfigOperation):

Create: When a record is created in the configuration. It will carry the identifier of the new record.
Update: When a record is modified in the configuration. It will carry the identifier of the updated record.
Delete: When a record is deleted in the configuration. It will carry the identifier of the deleted record.

The configuration data contains the updated or new configuration data. This field is not mandatory and if the configuration data is empty, the subscriptor refreshes its configuration calling the aura-configuration-api.

The metadata is used to manage the behavior of the event. In this case it uses a { "ttlInSeconds": "60" } to set the expiration time of the event. The pubSubName contains the AURA_DAPR_CONFIGURATION_PUBSUB_NAME.

Examples:

Without configuration data:


{
    "collection": "ChannelConfiguration",
    "id": "c71dc728-5fe2-4735-927d-0c419b35ec59",
    "metadata": {
      "ttlInSeconds": "60"
    },
    "op": "Update",
    "pubSubName": "pubsub-config-ap-four"
  }

With configuration data:

{
    "collection": "ChannelConfiguration",
    "id": "c71dc728-5fe2-4735-927d-0c419b35ec59",
    "metadata": {
      "ttlInSeconds": "60"
    },
    "op": "Update",
    "pubSubName": "pubsub-config-ap-four",
    "configData": 
        {
            "name":"Expample1",
             "id":"88834434",
             .... 
         }
}

Publishers

The publishers are inside the aura-configuration-api.

The API must contain an endpoint to obtain all the data from the model named GetAll.
The API must contain an endpoint to obtain an element of the model selected by its identifier named GetById.

To write the records in Redis that will generate the events, we will use the DAO of the model. The method writeConfigurationEvent generates the registry for the event in Redis.

    // aura-configuration-api/src/common/dao.ts
    /**
     * Write configuration event.
     * @param {EventConfigOperation} operation Operation type
     * @param {string} id Id of the configuration
     * @param {T} data Data to write
     * @param {KeyValueType} metadata Metadata to write
     */
    protected async writeConfigurationEvent(operation: EventConfigOperation, id?: string, data?: T, metadata?: KeyValueType) {
        this.configurationEventPublish.op = operation;
        this.configurationEventPublish.id = id;
        this.configurationEventPublish.configData = data;
        this.configurationEventPublish.metadata = Object.assign({}, this.configurationEventPublish.metadata, metadata);

        await this.eventPublisher.publish(this.configurationEventPublish);
    }

The eventPublisher can be Redis or DAPR. For DAPR, the class with the methods to publish the event is in /aura-configuration-api/src/utils/event-publishers/dapr-event-publisher.ts

Generate events

When an event is generated, the operation that has been performed is indicated with the identifier of the record affected by the change.

    /**
     * Update channel.
     *
     * @throws {NoDataError} When it hasn't been updated
     * @throws {Error} When channel is invalid
     * @param {ChannelConfiguration} channel Channel configuration
     */
    public async update(channel: ChannelConfiguration) {
        channel.metadata = {
            ...(await this.channelCollection.findOne<ChannelConfiguration>(
                { id: channel.id }, { projection: { metadata: 1 } })
            )?.metadata,
            ...channel.metadata
        };
        const updateResult = await this.channelCollection.replaceOne(
            { id: channel.id }, this.prepareChannelToInsert(channel));
        if (updateResult?.modifiedCount === 0) {
            throw new NoDataError(`Channel with id: ${channel.id} cannot be found`);
        } else {
            await this.writeConfigurationEvent(EventConfigOperation.Update, channel.id);
        }
    }

Subscribers

Subscribers in DAPR can be created in several ways. In this case, the “Programatic” type is used, that is, we are going to include an endpoint in our components so that DAPR can subscribe them to the PubSub. The endpoint (/dapr/subscribe) must respond with a subscription model that contains the pubSubName, the topic and the endpoint that is going to be in charge of processing the event. This type of subscription forces us to define 2 methods for DAPR.

Example:

    /**
     * Dapr Subscriptions.
     *
     */
    public daprSubscriptions() {
        this.app.get('/dapr/subscribe', (request: express.Request, response: express.Response) => {
            const subscriptions =
                [
                    {
                        pubsubname: ConfigurationManager.instance.environmentConfiguration.AURA_DAPR_CONFIGURATION_PUBSUB_NAME,
                        topic: ConfigCollectionName.ChannelConfiguration,
                        routes: {
                            default: '/dapr/processConfigurationEvents',
                        }
                    }
                ];

            response.status(200).send(subscriptions);
        });
    }

In the previous example, we are going to subscribe to one topic, that will receive the events about the channel configuration collection.

Once the event is received, we can use the same library that we use in Redis, aura-utilities/aura-configuration, since we share the data model.

Example:

    /**
     * Process configuration events.
     *
     */
    public processConfigurationEvents() {
        this.app.post('/dapr/processConfigurationEvents', async (request: express.Request, response: express.Response) => {
            try {
                const event = HTTP.toEvent({ headers: request.headers, body: request.body.toString() });
                const cloudEvent = (event || {}) as CloudEvent;
                const configModel = (cloudEvent.data || {}) as EventConfigModel<ChannelConfiguration>;
                switch (configModel.collection) {
                    case ConfigCollectionName.ChannelConfiguration:
                        // Update current channels configuration
                        this.logger.debug({
                            msg: 'Processing channel configuration events',
                            corr: CorrelatorUtil.auraSystem
                        });
                        await AuraCurrentChannelsConfiguration.instance
                            .updateConfiguration(configModel as EventConfigModel<ChannelConfiguration>);
                        break;
                    default:
                        this.logger.warning({
                            msg: `Unknown collection in configuration event: ${configModel.collection}`,
                            corr: CorrelatorUtil.auraSystem
                        });
                }
                response.status(200).send({ status: DaprResponseStatus.SUCCESS });
            } catch (error) {
                this.logger.error({
                    msg: 'Error processing configuration events',
                    error: error.message,
                    corr: CorrelatorUtil.auraSystem
                });
                response.status(500).json({ status: DaprResponseStatus.DROP, error: 'Internal Server Error' });
            }
        });
    }

It is important to indicate in the reponse that the event has been successfully processed.

Docs:

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

Aura KPIs Adapter Manager

Module to manage the copy of CSV files to Kernel and to generate Avro dimensional files and Avro Entity files.

⚠️ Although the definition of the module refers to Avro files, it also handles CSV files, until all CSV files are migrated to Avro in upcoming releases

Definition

Set of classes that will be in charge of processing the necessary operations to copy the KPIs in CSV format to Kernel and to process or generate the KPIs of the entities and dimensions in Avro format.

This is done from a definition file that, by default, is called aura-avro-adapter.json and is defined in the AURA_SOURCE_PATH_AVRO_ADAPTERS environment variable. This file is remotely loaded from the Storage AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT and the path AURA_KPIS_ENTITIES_CONTAINER/schemas/AURA_SOURCE_PATH_AVRO_ADAPTERS. If the file does not exist remotely, a local one is loaded by default.

Adapter Definition File Model

For each KPI file to be managed, a model is defined containing an array with all the adaptation operations to be performed. The content format of this file is JSON.

Name	Type	Definition
name	string	Name of the adapter. To manage Avro files, this field contains the name of the Avro schema itself
schema	AvroAdapterSchema	Type of KPI, entity or dimensional
avroSchema	string	If the destination file is an Avro file, this field contains the Avro schema to generate the file.
source	AvroAdapterSource	Contains the necessary data from where you are going to copy or transform the data, if applicable.
fields	AvroAdapterField	Contains a set of properties with a model defined in AvroAdapterFieldModel
targetType	AvroAdapterTargetType	Type file to generate. Values: `csv` or `avro`.
versionSchema	string	If the file to generate is Avro, this field contains the version of its schema
stopWithErrors	boolean	When `true`, if another adapter has generated an error, this one will not be executed
expiresAt	date	If set, it indicates which date the intended KPI will no longer be processed. This is used when there are different versions of AVRO templates and you want to keep both versions until the end of a cycle, which is usually monthly.
order	number	Contains the execution order, the order 1 will be the first to execution. By default the order is MAX_SAFE_INTEGER.

AvroAdapterSchema

Name	type	Definition
dimensional	string	Type of KPI is dimensional.
entity	string	Type of KPI is an entity.

AvroAdapterSource

Name	type	Definition
data	AvroAdapterSourceDataType	Type of file to use as source.
id	any	KPI identifier, for example: `GATEWAY`, `AUDIT`, `BOT`, etc.
avroSchema	string	Name of the schema file. Required if the source is an Avro file, as its schema needs to read it.
avroSchemaVersion	string	Version of the schema, required if the source is an Avro file.
csvFolder	string	Name of the folder where this CSV is stored, required if the source is a partial CSV.
entityName	string	Entity name of the CSV to load, required if the source is a partial CSV.
useDefaultTimeFilter	boolean	If `true`, the adapter will ignore the pre-calculated date range at the beginning of the process and will use the default one, which is calculated based on `AURA_DAYS_INTERVAL` as the start date and the end date by subtracting `AURA_KPIS_TIME_FILE_IS_IN_USE_AMOUNT` * `AURA_KPIS_TIME_FILE_IS_IN_USE_UNIT` from the current date. The default is 30 days prior to the current time.
version	string	Version of the adapter. It is used to propagate changes in a release and to update the remote file where the adapter models are stored in `aura-avro-adapter.json`. Format: x.y.z
removeAfterProcessing	boolean	Remove source data after processing. The data won’t store in processed data folder.

AvroAdapterSourceDataType

Name	type	Definition
avro	string	Name of the source file for Avro.
object	string	Name of the source file for the Javascript object.
csv	string	Name of the source file for CSV.
partialCsv	string	Name of the source file when it is referred to specific data from a CSV file.

AvroAdapterField

Name	type	Definition
any	AvroAdapterFieldModel	Name of the field.

AvroAdapterFieldModel

Name	type	Definition
sourceName	string	Name of the source field from which data is obtained.
nullable	boolean	It indicates whether the target field can be null or not.
preCalculated	AvroPreCalculatedType	String that indicates the type of calculation needed. For example, the required format for dates or numbers.
targetType	Avrofieldbasetype	Type of data for the target data.
defaultValue	string	number
symbols	any[]	Array with the values searched in the origin data. If the data does not match one of those values, it will generate an error.
format	string	Specific format to be sent, for precalculated fields.
description	string	Human-readable description of the field.
symbolsValues	string	If we want to change the value of the destination based on the values defined in the `symbols` field, we can define it in this field in the form of an object.
valueIfExist	string	If the source data exists, it will be changed to the one defined in this field.

AvroPreCalculatedType

Name	type	Definition
DATE_ISO_8691	string	Format used for dates. The input date will be converted to this format. If there is no input date, the current date is obtained.
CUSTOM_DATE_FORMAT	string	Custom format for dates. Example: MM/DD/YYY
DURATION_ISO_8601	string	Format used to set a duration.
COUNTRY_ISO_3166_ALPHA_3	string	Format to indicate a country that complies with the ISO 3166 format.

Avrofieldbasetype

Name	type	Definition
string	string	Type string.
number	string	Type number.
enum	string	Type enumerable.
array	string	Type array.
boolean	string	Type boolean.

AvroAdapterTargetType

Name	type	Definition
csv	string	CSV file.
avro	string	Avro file.

Types of adapters

The Adapter manager can perform several types of processes, that will be explained in the following sections.

Copy CSV files

This adapter will copy the CSV files generated from the Aura servers (aura-bot, aura-groot, aura-nlp, etc.) to the Kernel storage.

{
        "version": "1.0.0",
        "name": "E_Aura_BOT",
        "schema": "entity",
        "avroSchema": "",
        "source": {
            "data": "csv",
            "id": "BOT"
        },
        "targetType": "csv",
        "fields": {}
    }

Generate Dimensional KPIs in Avro

This adapter will generate an Avro file with Aura available RECOGNIZER data, as they are defined only in aura-kpis-uploader and not in aura-configuration-api.

  {
        "version": "1.0.0",
        "name": "D_Aura_Recognizer",
        "schema": "dimensional",
        "avroSchema": "aura-recognizer-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "object",
            "id": "RECOGNIZER"
        },
        "targetType": "avro",
        "fields": {
            "AURA_RECOGNIZER_ID": {
                "sourceName": "id",
                "targetType": "string"
            },
            "AURA_RECOGNIZER_NAME": {
                "sourceName": "name",
                "targetType": "string"
            },
            "EXTRACTION_TM": {
                "sourceName": "EXTRACTION_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            }
        }
    }

Copy Avro files

This adapter copies the KPIs generated in Avro by aura-gateway-api to be processed by aura-databricks-jobs.

    {
        "version": "1.0.0",
        "name": "Aura_Gateway_Message",
        "schema": "entity",
        "avroSchema": "aura-gateway-message-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "object",
            "id": "GATEWAY"
        },
        "targetType": "avro",
        "fields": {}
    }

Generate Avro from another Avro

This is an adapter that generates an AURA_AUDIT file based on the data from the AVRO file of the aura-gateway-api KPIs.

{       "version": "1.0.0",
        "name": "Aura_Audit",
        "stopWithErrors": true,
        "schema": "entity",
        "avroSchema": "aura-audit-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "avro",
            "id": "AUDIT",
            "avroSchema": "aura-gateway-message-asvc.json",
            "avroSchemaVersion": "6.0.0"
        },
        "targetType": "avro",
        "fields": {
            "INTERACTION_ID": {
                "sourceName": "CORR_ID",
                "targetType": "string"
            },
            "AURA_TM": {
                "sourceName": "MESSAGE_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            },
            "AURA_CHANNEL_ID": {
                "sourceName": "AURA_CHANNEL_ID",
                "targetType": "string",
                "nullable": "true"
            },
            "AURA_APP_ID": {
                "sourceName": "AURA_APP_ID",
                "targetType": "string"
            },
            "COUNTRY_3_ALPHA_CD": {
                "sourceName": "COUNTRY_3_ALPHA_CD",
                "targetType": "string",
                "preCalculated": "COUNTRY_ISO_3166_ALPHA_3"
            },
            "AURA_SERVICE_NAME_CD": {
                "sourceName": "AURA_PRESET_NAME",
                "targetType": "string",
                "defaultValue": "nlpaas",
                "valueIfExist" : "ai"
            },
            "AURA_PRESET_NAME": {
                "sourceName": "AURA_PRESET_NAME",
                "targetType": "string",
                "nullable": "true"
            },
            "AURA_COMPONENT_ID": {
                "sourceName": "AURA_COMPONENT_ID",
                "targetType": "string"
            },
            "AURA_COMPONENT_HOST_ID": {
                "sourceName": "AURA_COMPONENT_HOST_ID",
                "targetType": "string"
            },
            "AURA_VERSION_ID": {
                "sourceName": "AURA_VERSION_ID",
                "targetType": "string"
            },
            "DAY_DT": {
                "sourceName": "DAY_DT",
                "targetType": "string",
                "preCalculated": "CUSTOM_DATE_FORMAT",
                "format": "YYYY-MM-DD"
            },
            "BRAND_ID": {
                "sourceName": "BRAND_ID",
                "targetType": "string"
            }
        }
    }

Generate Avro from data in CSV file

This is an adapter that generates an AURA_AUDIT file based on the data from the CSV file of the aura-groot Message KPIs.

{
        "version": "1.0.0",
        "name": "Aura_Audit",
        "stopWithErrors": true,
        "order": 2,
        "schema": "entity",
        "avroSchema": "aura-audit-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "partialCsv",
            "id": "AUDIT",
            "csvFolder": "groot",
            "entityName":"GROOTMESSAGE"
        },
        "targetType": "avro",
        "fields": {
            "INTERACTION_ID": {
                "sourceName": "CORR_ID",
                "targetType": "string"
            },
            "AURA_TM": {
                "sourceName": "MSG_DT",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            },
            "AURA_CHANNEL_ID": {
                "sourceName": "CHANNEL_ID",
                "targetType": "string",
                  "nullable": "true"
            },
            "AURA_APP_ID": {
                "sourceName": "AURA_APP_ID",
                "targetType": "string",
                "nullable": "true"
            },
            "COUNTRY_3_ALPHA_CD": {
                "sourceName": "COUNTRY_CD",
                "targetType": "string",
                "preCalculated": "COUNTRY_ISO_3166_ALPHA_3"
            },
            "AURA_SERVICE_NAME_CD": {
                "sourceName": "AURA_SERVICE_NAME_CD",
                "targetType": "string",
                "defaultValue": "message"

            },
            "AURA_PRESET_NAME": {
                "sourceName": "AURA_PRESET_NAME",
                "targetType": "string",
                "nullable": "true"
            },
            "AURA_COMPONENT_ID": {
                "sourceName": "AURA_COMPONENT_ID",
                "targetType": "string"
            },
            "AURA_COMPONENT_HOST_ID": {
                "sourceName": "AURA_COMPONENT_HOST_ID",
                "targetType": "string"
            },
            "AURA_VERSION_ID": {
                "sourceName": "VERSION_ID",
                "targetType": "string"
            },
            "DAY_DT": {
                "sourceName": "MSG_DT",
                "targetType": "string",
                "preCalculated": "CUSTOM_DATE_FORMAT",
                "format": "YYYY-MM-DD"
            },
            "BRAND_ID": {
                "sourceName": "BRAND_ID",
                "targetType": "string"
            }
        }
    }

Another example, deleting CSV source file data when the adapter finalize its execution.

{
        "version":"1.0.1",
        "name": "Aura_Gateway_Message_converter",
        "stopWithErrors": true,
        "order": 1,
        "schema": "entity",
        "avroSchema": "aura-gateway-message-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "partialCsv",
            "id": "GATEWAY",
            "csvFolder": "gwapi",
            "entityName": "GATEWAYMESSAGE",
            "removeAfterProcessing": true
        },
        "targetType": "avro",
        "fields": {
                "MESSAGE_ID": {
                "sourceName": "MESSAGE_ID",
                "targetType": "string",
                "defaultValue": "NO_MESSAGE_ID"
            },
            "MESSAGE_TM": {
                "sourceName": "MESSAGE_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            },
            "AURA_APP_ID": {
                "sourceName": "AURA_APP_ID",
                "targetType": "string",
                "nullable": "true"
            },
            "COUNTRY_3_ALPHA_CD": {
                "sourceName": "COUNTRY_3_ALPHA_CD",
                "targetType": "string",
                "preCalculated": "COUNTRY_ISO_3166_ALPHA_3"
            },
            "AURA_PRESET_NAME": {
                "sourceName": "AURA_PRESET_NAME",
                "targetType": "string",
                "nullable": "true"
            },
            "DAY_DT": {
                "sourceName": "MESSAGE_TM",
                "targetType": "string",
                "preCalculated": "CUSTOM_DATE_FORMAT",
                "format": "YYYY-MM-DD"
            },
            "BRAND_ID": {
                "sourceName": "BRAND_ID",
                "targetType": "string"
            },
            "AURA_NLP_IND": {
                "sourceName": "AURA_NLP_IND",
                "targetType": "boolean"
            },
            "CORR_ID": {
                "sourceName": "CORR_ID",
                "targetType": "string",
                "defaultValue": "NO_CORR_ID"
            }
        }
    }

Use filters in Avro files

With this model, it is possible to filter records from the Avro files that should not be loaded into these files:

export interface AvroAdapterSource {
    data: AvroAdapterSourceDataType;
    id: any;
    avroSchema?: string;
    avroSchemaVersion?: string;
    csvFolder: string;
    entityName: string;
    filter?: (SourceFilter | LogicalFilter);

}
export interface SourceFilter {
    field: string;
    value: any;
    operator: FilterOperator;
}
export interface LogicalFilter {
    logic: LogicalOperator.and | LogicalOperator.or;
    filters: (SourceFilter | LogicalFilter)[];
}
export enum FilterOperator {
    equal = 'equal',
    notEqual = 'notEqual',
    greaterThan = 'greaterThan',
    lessThan = 'lessThan'
}
export enum LogicalOperator {
    and = 'and',
    or = 'or'
}

These filters could be configured in aura-avro-adapter.json in two ways:

With logical filter, with several conditions. For example:

    {
        "version": "1.0.0",
        "name": "Aura_Audit",
        "stopWithErrors": true,
        "schema": "entity",
        "avroSchema": "aura-audit-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "partialCsv",
            "id": "AUDIT",
            "csvFolder": "groot",
            "entityName": "GROOTMESSAGE",
            "filter": {
                "logic": "and",
                "filters": [
                    {
                        "field": "CHANNEL_ID",
                        "value": "",
                        "operator": "notEqual"
                    },
                    {
                        "field": "ACTION_CD",
                        "value": "receive",
                        "operator": "equal"
                    }
                ]
            }
        }

Or it could be configured in aura-avro-adapter.json with simple filter. For example:

{
        "version": "1.0.0",
        "name": "Aura_Audit",
        "stopWithErrors": true,
        "schema": "entity",
        "avroSchema": "aura-audit-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "avro",
            "id": "AUDIT",
            "avroSchema": "aura-gateway-message-asvc.json",
            "avroSchemaVersion": "6.0.0",
            "filter": {
                "field": "AURA_APP_ID",
                "value": null,
                "operator": "notEqual"
            }
        },
        "targetType": "avro",
        "fields": {
            "INTERACTION_ID": {
                "sourceName": "CORR_ID",
                "targetType": "string"
            },
            "AURA_TM": {
                "sourceName": "MESSAGE_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            },
            "AURA_CHANNEL_ID": {
                "sourceName": "AURA_CHANNEL_ID",
                "targetType": "string",
                "nullable": "true"
            },
            "AURA_APP_ID": {
                "sourceName": "AURA_APP_ID",
                "targetType": "string",
                "nullable": "true"
            },
            "COUNTRY_3_ALPHA_CD": {
                "sourceName": "COUNTRY_3_ALPHA_CD",
                "targetType": "string"
            },
            "AURA_SERVICE_NAME_CD": {
                "sourceName": "AURA_PRESET_NAME",
                "targetType": "string",
                "defaultValue": "nlpaas",
                "valueIfExist": "ai"
            },
            "AURA_PRESET_NAME": {
                "sourceName": "AURA_PRESET_NAME",
                "targetType": "string",
                "nullable": "true"
            },
            "AURA_COMPONENT_ID": {
                "sourceName": "AURA_COMPONENT_ID",
                "targetType": "string"
            },
            "AURA_COMPONENT_HOST_ID": {
                "sourceName": "AURA_COMPONENT_HOST_ID",
                "targetType": "string"
            },
            "AURA_VERSION_ID": {
                "sourceName": "AURA_VERSION_ID",
                "targetType": "string"
            },
            "DAY_DT": {
                "sourceName": "DAY_DT",
                "targetType": "string",
                "preCalculated": "CUSTOM_DATE_FORMAT",
                "format": "YYYY-MM-DD"
            },
            "BRAND_ID": {
                "sourceName": "BRAND_ID",
                "targetType": "string"
            }
        }
    },

Docs:

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

Aura environments configuration

The current document describes how Aura environments should be configured to be used by channels

Integration for channels in Spain

Aura environment name: es-stg
Aura Bot app in Kernel: aura-bot-es-stg
Kernel Apps to be redirected to this aura-services deployment: novum-es, movistar-plus, mh, stb-es
- These Apps should be the ones created by the managers of the channels, not sure about their real ids or if they exist or not.
redirect_uris:
- https://svc-es-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/logout
- https://svc-es-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/
Aura-Services endpoint: https://svc-es-stg.auracognitive.com/aura-services/v1/users (Aura-Services API in 4P-GW)
issuer: https://svc-es-stg.auracognitive.com/aura-services/v1/openid/issuer/.well-known/openid-configuration

Integration for channels in Brazil

name: br-stg
Aura Bot app in Kernel: aura-bot-br-stg
Kernel Apps to be redirected to this aura-services deployment:novum-br, stb-br
- These Apps should be the ones created by the managers of the channels, not sure about their real ids or if they exist or not.
redirect_uris:
- https://svc-br-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/logout
- https://svc-br-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/
Aura-Services endpoint: https://svc-br-stg.auracognitive.com/aura-services/v1/users (Aura-Services API in 4P-GW)
issuer: https://svc-br-stg.auracognitive.com/aura-services/v1/openid/issuer/.well-known/openid-configuration

Integration for channel in UK

name: uk-stg
Aura Bot app in Kernel: aura-bot-uk-stg
Kernel Apps to be redirected to this Aura-Services deployment: novum-uk
- These APPs should be the ones created by the managers of the channels, not sure about their real ids or if they exist or not.
redirect_uris:
- https://svc-uk-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/logout
- https://svc-uk-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/
Aura-Services endpoint: https://svc-uk-stg.auracognitive.com/aura-services/v1/users (Aura-Services API in 4P-GW)
issuer: https://svc-uk-stg.auracognitive.com/aura-services/v1/openid/issuer/.well-known/openid-configuration

Integration for channels in Germany

name: de-stg
Aura Bot app in Kernel: aura-bot-de-stg
Kernel Apps: novum-de
- These Apps should be the ones created by the managers of the channels, not sure about their real ids or if they exist or not.
redirect_uris:
- https://svc-de-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/logout
- https://svc-de-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/
Aura-Services endpoint: https://svc-bde-stg.auracognitive.com/aura-services/v1/users (Aura-Services API in 4P-GW)
issuer: https://svc-de-stg.auracognitive.com/aura-services/v1/openid/issuer/.well-known/openid-configuration

Docs:

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

How to obtain Azure credentials for CLU

This process may be required in the first step for training the understanding model: Set up configuration properties.

Prerequisites

Pre-requisites:

Azure account with permissions for applications registration.
Azure CLI installed.

Guidelines

Follow the guidelines below for obtaining the Azure credentials for CLU:

Create the CLU application:
az cognitiveservices account create --kind "TextAnalytics" --name <clu_name> -g <name_resource_group> --sku S -l <location> --custom-domain <clu_name>
- <clu_name>: resource name
- <name_resource_group>: name of resource group (previously generated)
- <location>: location available for Azure (i.e., northeurope)

The value for the parameters required to fill in the build_local_variables.sh script for CLU execution must be obtained from the above-defined steps:

export CLU_USER="<user_name>"
export CLU_RESOURCE_NAME="<clu_name>"
export CLU_SUBSCRIPTION_KEYS="$(az cognitiveservices account keys list --name <clu_name> -g <name_resource_group> | jq -r .key1)"

Docs:

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

Aura Configuration API channel module

Description of the channel module in aura-configuration-api

Channel module

The channel module defines services associated with channel management in aura-configuration-api server.

All these services are defined in the channel namespace (/channel).

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/channels/
aura-services/v2/configuration/channels/{channelId}/libraries

Endpoints

Path	Method	Description
/channels/	GET	Get all channels information
/channels/	POST	Add a new channel
/channels/{channelId}	GET	Get channel information using channel id
/channels/{channelId}	PUT	Replace channel information associated to channel id
/channels/{channelId}	PATCH	Update some fields of channel information using channel id
/channels/{channelId}	DELETE	Delete channel information using channel id
/channels/{channelId}/libraries	POST	Add a new library configuration to channel id
/channels/{channelId}/libraries	DELETE	Remove all libraries configuration from channel id
/channels/{channelId}/libraries/{libraryId}	GET	Get library configuration from library id and channel id
/channels/{channelId}/libraries/{libraryId}	PUT	Replace library configuration associated to library and channel id
/channels/{channelId}/libraries/{libraryId}	DELETE	Delete library information using library and channel id

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

Retrieving information from channels

Retrieving only some fields in channel information

It is possible to get only a specific list of fields for channel 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/channels?includeFields=name,prefix' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: XXX'

Response example:

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

Excluding fields in channel information

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

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

Response example:

[
    {
        "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
        "name": "novum-mytelco",
        "prefix": "nov",
        "security": {
            "authPurposes": "customer-self-service identify-customer aura-technical-problems-purpose",
            "authScopes": "",
            "channelId": "novum-mytelco"
        },
        "metadata": {
            "updatedAt": "2022-09-06T09:58:19.543Z",
            "version": "7.4.0",
            "createdAt": "2022-09-06T09:58:19.543Z"
        }
    }
]

Database

The complete definition of the data model can be found in the channels collection section in the Administration module.

Docs:

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

Aura Complex Logic Framework configuration

Description of the configuration required by the Complex Logic Framework, both operational configuration and configuration of plugins

Introduction

The configuration of the Complex Logic Framework has two different purposes, each of them supported by a configuration file:

General operational configuration
General configuration for the Complex Logic Framework performance.
Plugins configuration
Specific configuration for each plugin developed over the CLF.

General operational configuration

The file bootstrap.cfg contains the Complex Logic Framework operational config sections. This file is included in the CLF repository, within the folder:
~/aura-complex-logic-[country_code]/config/etc/bootstrap.cfg

⚠️ OBs must not modify these fields. If any modification is required, it must be adjusted after approval by the Aura Platform Team

The file follows the general structure shown hereunder:

[logging]
handlers = { . . . }
loggers = { . . . }
root = { . . . }

Logging

[logging]
handlers = {
      'hdl1':{
         'class':'logging.StreamHandler',
         'formatter':'console',
         'level': 'DEBUG'
      },
      'hdl2':{
         'class':'logging.StreamHandler',
         'formatter': 'simple',
         'level': 'DEBUG'
      }
   }
loggers = {
      'plugins': {
         'level': 'DEBUG',
         'handlers':[
            'hdl1'
         ],
         'filters': [],
         'propagate': False
      }
    }
root = {
      'level': 'DEBUG',
      'handlers':[
         'hdl2'
      ]
    }

The main fields are explained below. However, for more details, developers are kindly requested to read the Python logging documentation.

handlers: This field configures a dictionary with different logging handlers. Each key is the name of a handler, and is composed of the following parameters:
- class: It is configured with Python logging handlers (See Python documentation).
- formatter: It configures the format of logs. It must be filled with the labels json, string, console or simple.
- level: It is referred to the level of the logging event. It must be filled with the labels INFO, ERROR, WARN or DEBUG.
loggers: The corresponding value is a Python dictionary in which each key is a logger name and each value is a dictionary that describes how to configure the corresponding Logger instance:
- level (optional parameter): Level of the logger.
- handlers (optional parameter): List of IDs of the handlers for this logger.
- filters (optional parameter): List of IDs of the filters for this logger.
root: This field includes the configuration for the root logger.
- level (optional parameter): Level of the logger.
- handlers (optional parameter): List of IDs of the handlers for this logger.

Plugins Configuration

The file complex_logic.json includes the specific configuration for each plugin. It is included in the following path of the CLF repository:
~/aura-complex-logic-[country_code]/config/plugins/complex_logic.json

⚠️ OBs must not modify these files. If any modification is required, it must be adjusted after approval by the Aura Platform Team

{
     "aura_clf_XX.plugins.plugin_1_name.plugin_1_class_name": {
         "config": {
             "sound_disabled_channels": ["channel_1", "channel_2"],
         }
     },
     ...
     "aura_clf_XX.plugins.plugin_N_name.plugin_N_class_name": {}
}

Each plugin requires a specific configuration. This will be defined in a JSON file with the following structure:

Class path: Path and identifier for the plugin.
Open dictionary including the specific configuration of the plugin.

Enabling/disabling sound responses

Within the configuration dictionary of each plugin, you can include the sound_disabled_channels field to specify in which channels sound responses (both positive and negative) should be disabled for that plugin. This field must be a list of channel prefixes.

For example, if a channel prefix is included in this list, the plugin will not play any sound in its responses when the interaction occurs through that channel.

Currently, the configuration added in this file is not included in the production phase, therefore this file should only list the Plugins class path and keep an empty dictionary as configuration.

Disabling contingency or fallback modes for tv search use case

For the tv search use case, in the configuration dictionary of the plugin aura_clf_video.plugins.tv_search_plugin.TvSearchPlugin, you can include the contingency_disabled_channels field to specify if the contingency or fallback search mode is disabled for a specific channel. This field must be a list of channel prefixes.

{
    "aura_clf_video.plugins.tv_search_plugin.TvSearchPlugin": {
        "config": {
            "contingency_disabled_channels": ["channel_1", "channel_2"],
        }
    },
    ...
}

Docs:

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

Aura Databricks Jobs configuration

This document describes the internal configuration of the aura-databricks-jobs component that will be enabled in every Aura release from the current one onwards.

⚠️ The users can modify this configuration at a certain extent, described in Aura Databricks Jobs user guide

Prerequisites

Python version 3.9 or higher

# determine python version
python --version

aura-pytraces: Aura repository for Python traces functionalities.

Execution of the tool in Databricks cluster

1. Configuration of the Databricks cluster

Firstly, it is necessary to follow the steps defined in Kernel documentation for the correct installation of the cluster: Create a Databricks cluster.

In addition, to configure our environment and Python package in the Databricks cluster, it is necessary to configure a docker image that we will have previously registered: docker_image: auraregistry.azurecr.io/aura/tools/aura-databricks-jobs:$VERSION

Configuration example obtained by applying the steps in the Kernel documentation and configuring docker image URL:

{
    "spark_version": "12.2.x-scala2.12",
    "spark_conf": {
        "spark.driver.memory": "4g",
        "spark.jars.packages": "com.telefonica.baikal:spark-sdk_2.12:2.2.1,org.apache.spark:spark-avro_2.12:3.3.2",
        "spark.jars.repositories": "https://4p-public-artifacts.s3.amazonaws.com/baikal/releases/,https://repo.osgeo.org/repository/release/",
        "spark.debug.maxToStringFields": "100"
    },
    "spark_env_vars": {
        "PYSPARK_PYTHON": "/databricks/python3/bin/python3",
        "JNAME": "zulu11-ca-amd64"
    },
    "init_scripts": [
        {
            "workspace": { "destination": "/InitScripts//init_script.sh"}
        }
    ],
    "docker_image": {
        "url": "auraregistry.azurecr.io/aura/tools/aura-databricks-jobs:{$VERSION}",
        "basic_auth": {
            "username": "$USERNAME",
            "password": "$PASSWORD"
        }
    }
}

Example of configuring the init script as indicated in the Kernel documentation:

#!/bin/bash
wget -O /databricks/jars/config-1.3.4.jar https://repo1.maven.org/maven2/com/typesafe/config/1.3.4/config-1.3.4.jar
rm -f /databricks/jars/*--com.typesafe__config__1.2.1.jar

2. Configuration of the job’s variables

The job will be configured with some input parameters that are included in the variable: config_dict.

You can review all variables in Job’s variables.

config_dict = {
    'AURA_ENVIRONMENT_NAME': 'DEV',
    'AURA_DATABRICKS_EXECUTION_PERIOD': 24,
    'AURA_FP_SPARK_BASE_URL': '',
    'AURA_FP_SPARK_CLIENT_ID': 'aura-bot-xxx',
    'AURA_FP_SPARK_CLIENT_SECRET': '',
    'AURA_FP_SPARK_PURPOSES': '',
    'AURA_FP_SPARK_SCOPES': '',
    'AURA_FP_SPARK_JARS_PACKAGES': 'com.telefonica.baikal:spark-sdk_2.12:2.2.1,org.apache.spark:spark-avro_2.12:2.2.1',
    'AURA_FP_SPARK_JARS_REPOSITORIES':
        'https://4p-public-artifacts.s3.amazonaws.com/baikal/releases/,https://repo.osgeo.org/repository/release/',
    'AURA_FP_SPARK_SUFFIX_DATASET_TEST': '',
    'AURA_KPI_AVRO_SOURCE_PATH': 'avro',
    'AURA_KPI_AVRO_REPORTS_DESTINATION_PATH': 'avro/reports',
    'AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT': '',
    'AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCESS_KEY': '',
    'AURA_MICROSOFT_AZURE_STORAGE_KPIS_CONTAINER_NAME': 'aura-kpis',
    'AURA_KPI_AVRO_SCHEMAS_NOT_TO_UPLOAD': 'entity:E_Aura_GROOT',
    'AURA_KPI_AVRO_PROCESSED_FOLDER_PATH': 'processed'
}

if __name__ == "__main__":
    asyncio.run(import_avro_files_job(config_dict))

3. Configuration of job in Databricks cluster

To execute the job in Databricks, you should create a new job, following the guidelines Create and run Databricks Jobs and copying the template avro_to_dataset_job_cli.py without these unnecessary params:

AURA_FP_SPARK_JARS_PACKAGES
AURA_FP_SPARK_JARS_REPOSITORIES

Execution of the tool in local environment

To install Apache Spark on your local machine and run Python scripts, follow the steps below.

1. Install Java 11

Apache Spark requires Java to run. We recommend using Java 11, as indicated in the Kernel documentation Spark SDK.

You can install Java 11 using a package manager or downloading the installer: Download.

On Ubuntu/Debian:

sudo apt update
sudo apt install openjdk-11-jdk

On macOS (using Homebrew):

brew install openjdk@11

On Windows: Download the JRE installer from the Oracle website, run the installer and follow the on-screen instructions.

Finally, verify the installation with:

java -version

2. Install requirements via pip

pip install -r requirements.txt

These requirements include PySpark library and automatically includes a lightweight version of Spark, so you can run Spark jobs locally without needing to install Spark separately.

pip install pyspark

3. Config spark Session

By default, the Databricks cluster is configured with the required jar files and packages. But in local mode, you must indicate this configuration when you create the Spark session using the jobs variables: AURA_FP_SPARK_JARS_PACKAGES and AURA_FP_SPARK_JARS_REPOSITORIES.

Example:

AURA_FP_SPARK_JARS_PACKAGES = 'com.telefonica.baikal:spark-sdk_2.12:2.2.1,org.apache.spark:spark-avro_2.12:3.3.2'
AURA_FP_SPARK_JARS_REPOSITORIES = 'https://4p-public-artifacts.s3.amazonaws.com/baikal/releases/,https://repo.osgeo.org/repository/release/'

4. Execute job

You can execute the job with the configured variables:

python avro_to_dataset_job_cli.py

Docs:

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

Guidelines for the configuration of an application

Comprehensive instructions for the configuration of an application to communicate with aura-gateway-api

Introduction

Prior to the development of a use case that needs aura-gateway-api to connect with an external service, the configuration of an application is required to set the specific parameters of the ATRIA AI-driven capability to be used.

Additionally, if certain changes must be made on an existing application through a hot swapping process, follow the guidelines Hot swapping of Aura applications configuration

Guidelines to create and configure an application

The creation of an application requires the following steps:

Create a task for the configuration of an application in JIRA.
Copy the tables below and paste them into the JIRA task.
Fill in all the fields corresponding to your specific ATRIA capability in the table’s column “Value in app”.
Do not modify the content of the remaining columns aside from “Value in app”.
The application must be available in the applications list of the environment, which is available through the aura-configuration-api server.
The edited sheet will serve as the basis for the subsequent validation of the application by Aura Global Team and its uploading to the system.

Mandatory parameters: parameter_name
Optional parameters: parameter_name

Application basic data

Parameter	Definition	Type	Value in app
disabled	Boolean value to enable or disable the application. By default: `false`	Boolean	complete
id	Unique application identifier	UUID	complete
name	Unique application name	String	complete
brand	Identifier of the Telefónica Brand associated to the application. Available values in the document Telefónica brands management	String	complete
nlp	Parameters to use the NLP as a Service capability Mandatory for using this capability	N/A	Go to NLP as a Service section
models	Parameters to use the Generative AI capability or RAG capability Mandatory for using these capabilities	N/A	Go to Using Generative AI / RAG section
agents	Identifiers of the agents associated with the application. Mandatory if the application requires integration with agents.	String[]	complete

Using NLP as a Service: nlp parameter

The use of the NLP as a Service capability by a channel requires the previous registration of the channel in Aura using the channels registration template.

Parameter	Definition	Type	Value in app
channelId	Identifier of the channel willing to use NLP as a Service	String	complete

Using Generative AI / RAG: models parameter

The use of Generative AI or RAG capabilities by applications requires the definition of the following parameters:

Parameter	Definition	Type
level	. It indicates if level application in atria-model-gateway, meaning that it has specific access and control privileges. . Default value `user`	String
presets	. Include here all the presets (configurable entities that define the instructions to work with the AI model for the resolution of a use case) that will be assigned to this application. . For this purpose, follow the guidelines to include a preset in the application . Take into account that a preset must be previously created in ATRIA	String[]

Docs:

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

Conversational dialog

Description of the conversational-dialog global use case available for Aiwi

Introduction

The conversational-dialog allows users to interact with an LLM with a predefined prompt.

This prompt should return a json formatted object to be mapped in a standard Aiwi response message.

Specific configuration

The conversational-dialog is designed to handle user’s requests using LLMs in ATRIA.

Currently, this dialog is available for Aura channelData V1 version and can only be used for the channel AIWI.

For this use case, the required specific configuration is set below:

    {
      "name": "conversational",
      "dialogs": [
        {
          "id": "conversational-dialog",
          "allowAnonymous": true,
          "triggerConditions": [
            {
              "intent": "None"
            }
          ],
          "bypass": {
            "duration": 30,
            "payloadName": "conversational",
            "initialData": {},
            "recognizersEnabled": false,
            "recognizersBreakIntents": {}
          }
        }
      ]
    }

Specific values

Key	Value	Description
bypass.duration	30 (minutes)	This value overwrites the default aura-bot value for bypass lasting 10 minutes.
bypass.payloadName	conversational	Name of the interface that will be used as bypass payload for this dialog.
bypass.initialData	empty	It should contain any data needed by the dialog to be initialized.
bypass.recognizersEnabled	false	This value overwrites the default aura-bot way of working with recognizers when it is in bypass mode. If it is set to `true`, recognizers are executed, and their result is stored in the bypass payload to be used, if needed, afterwards.
bypass.recognizersBreakIntents	empty	Used to handle when the user requested any other use case during the execution of the dialog. To enable this config, `bypass.recognizersEnabled` should be enabled.

Environment variables

Property	Type	Description	Modifiable by OB?
AURA_GATEWAY_API_ENDPOINT	URI string	Endpoint to access the locally deployed ATRIA aura-gateway-api	NO
AURA_GATEWAY_API_ISSUER_URL	string	Aura issuer URL. It is automatically fulfilled by the installer.	NO
CONVERSATIONAL_COMMAND_KEY	string	Key of the command in the returned json from prompt.	YES
CONVERSATIONAL_MESSAGE_KEY	string	Key of the message in the returned json from prompt.	YES

Configuration by channel

From Prince’s release onwards, the configuration of applicationId and presetId per channel and intent has been added to the channel model.

For this use case, the required specific configuration per channel is set below (added dialogs section under atria property at Main-Recognizer-Video-Triage-29855):

{
  "atria": {
    "dialogs":{
      "None": {
        "applicationId": "816bdab6-3ea3-4a77-bdea-12945d6d7053",
        "presetId": "ef3d0603-3fef-4109-a577-0ab92f9060df"
      }
    }
  }
}

Specific values by channel

Intent	Key	Value	Description	Modifiable by OB?
intent.tv.custom_recommendation	applicationId	1eb11727-14f2-447f-acc0-a2211ab55870	ATRIA application identifier	NO
intent.tv.custom_recommendation	presetId	e0cdcae2-025d-4624-8096-d6bf4b5eaaff	ATRIA preset identifier to be used within the use case.	NO

Docs:

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

Create and configure a preset

Guidelines for the configuration of ATRIA by use cases constructors when developing an experience by means of a preset

This guidelines correspond to a specific stage in the processes for building experiences using Generative AI or RAG, which are fully explained in:

Introduction

A preset is a configurable entity that defines the instructions to work with the AI model for the resolution of a use case.

These instructions include, apart from other parameters, the prompt with text to guide the AI model with the generation of the response. For example:

“Maintain the formal tone of the original text”
“If the previous conversation is relevant for the current query, incorporate it into the query and produce a rewritten query”

When developing an experience in ATRIA, use cases constructors must configure a preset for the specific ATRIA application to be used.

ATRIA use cases constructors can use the currently available default presets or they can modify them or create new ones via API.

In both scenarios, a further step is required to include the preset in the application.

Guidelines to configure a preset

1. Create a new preset

Build the preset for your use case (json file), using the available preset fields.
Do you get lost with all the preset configuration parameters? In best practices for ATRIA configuration, you can find the most commonly used parameters by experiences constructors grouped by their purpose (“I want to increase security”, “I want to activate the multi-language feature”, etc.)

When the preset json file is generated, execute this command to include it:

  curl --location --request POST 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/presets/' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: APIKEY XXX' \
    --data-raw '<NEW PRESET JSON>'

1.1. Modify/update a preset

If once created, certain modifications are required, follow these instructions:

Make the required changes in the preset json file using the available preset fields.

When the preset is modified, execute this command to include it:

  curl --location --request PUT 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/presets/<presetID>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data '<PRESET JSON WITH MODIFICATIONS>'

1.2. Delete a preset

Execute the following command:

  curl --location --request DELETE 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/presets/<presetId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX'

2. Include the preset in the application

An application is defined as an entity that allows the connection of a channel, service or skill with with ATRIA.

If the application for your use case does not exist, firstly it is required to create it following the guidelines for the configuration of an application.

Once the application is created, assign the created preset. Two scenarios arise here:

2.1. If an existing preset is modified

Get the list of presets assigned to the application to be used from aura-configuration-api:

  curl --location 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/applications/<applicationID>' \
  --header 'Authorization: APIKEY '

Check if your preset is already included in the list and, consequently, associated to your application.
If not, declare the created preset in the application following the guidelines for the configuration of an application: Use Generative AI/RAG, within the field presets.

2.2. If a new preset is created

Update aura-configuration-api to indicate to the application the complete list of presets to be used.

It is necessary to include the entire list of presets associated to the application (the existing presets and the created/modified ones)

    curl --location --request PATCH 'https://svc-<env>.auracognitive.com/aura-services/v1/applications/:applicationId' \
    --header 'Accept: application/json' \
    --header 'Authorization: APIKEY XXX' \
    --data '{
        "id": "<applicationId>",
        "models": {
            "level": <levelType>, 
            "presets": [
                <complete-new-list-of-presets>
            ]
        }
    }'

The level field, that indicates the different levels of access to the application, can only be changed By the Global Team. This command is a specific scenario in the process of modifying API configuration, described in the document Hot swapping of Aura applications configuration.

Declare the created preset in the application following the guidelines for the configuration of an application: Use Generative AI/RAG, within the field presets.

Preset fields

The fields for the characterization of a preset are summarized below, which are defined in the API swagger Aura Configuration API Preset.

If there is any discrepancy between the parameters definitions included in this document and those in the API swagger, definitions established in the API shall prevail.

id: Mandatory. Preset identifier. The type is string.
name: Mandatory. Preset name. If this value does not exist, id is used. The type is string.
description: Optional. Preset description. If this value does not exist, id is used. The type is string.
group: Mandatory. This parameter is used to group requests regarding the AI technologies used to generate KPIs. The type is string. Feasible values: simple_ai (Generative AI preset) and enriched_ai (RAG preset).
session: Optional. Parameters for session configuration.
- window: Optional. The size of the session window, in queries. The type is number.
- timeout: Optional. The time in seconds after which the session will be closed if no queries are received. If it is 0, the session history will be used, but the current interaction will not be saved. The type is number.
generative: Mandatory if Generative AI is used. It indicates the use of Generative AI in the use case. If this field exists, the rag field must not exist.
- model: Mandatory. Model configuration.
  - id: Mandatory. Unique identifier of the model
  - parameters. Optional. Dictionary with all possible parameters for the model. For generative, check them here.
- injectionMaxLength. Optional. Maximum length of the input user. The type is number.
- prompts: Optional. Parameters to define the prompts with instructions used as input by the AI model to automatically generate responses.
  . The object may include properties such as text, additional parameters, and specific configurations to control the behavior of the generative model.
  . If no prompt is defined, the resolution of the use case is entirely delegated to the LLM model.
  - template: Optional. Template that includes the user’s input. It must include {MSG} for the user’s utterance. This will override (or add, if not defined) the template for the user message, as defined in the preset (Note: templates allow framing the user message to mitigate prompt injection attacks). The type is string.
  - preamble: Optional. List of phrases to be included in the model prompt.
  - examples: Optional. Examples to enrich the prompt. The type is string.
  - promptMaxLength: Optional. Maximum length of the completed prompt. Used to avoid calling LLMS with wrong prompts.
  - promptRegexClean: Optional. Regex pattern to clean the query before sending it to the model. This is useful to remove unwanted characters or patterns from the query. The type is number.
rag: Mandatory if RAG technology is used. It indicates the RAG configuration. If this field exists, the generative field must not exist.
- ragType: Optional. RAG type. Values: questions-answers (by default) or sql
- model: Mandatory. Parameters for the configuration of the RAG model.
  - id: Mandatory. Unique identifier of the model to be used. The type is string.
  - parameters: Optional. Dictionary with all the possible parameters for the model.
- references: Optional. Configuration for managing references in the system. It control de number of references the system relies on to generate a response.
  - maximum: Optional. Maximum number of returned references. The type is number.
  - baseUrl: Optional. Base URL of references that will be shown to the user as part of the response. For the types of data unstructured, csvand text (defined in the field loaderType), it is required to add here the path to the public URL to be shown in the response as a clickable reference.
- stages: Mandatory. Stages of the RAG model.
  - promptSystemLanguage: Optional. Parameter to select a specific language from the ones defined in the prompt. Type: string in ISO 639-3 format. For example: es.
  - defaultUserLanguage: Optional. Parameter used in multi-language feature. It indicates the default response language to be used if the system is not able to automatically recognize the language. Type: string in ISO 639-3 format. For example: es.
  - securityStg: Stage with parameters related to security used to avoid prompt injection.
    - injectionMaxLength: Mandatory. Maximum length of the input user. If length is greater, an error is sent. The type is number.
    - heuristics: Optional. Heuristics configuration.
      - es: List of heuristic sentences in Spanish. The type is list.
      - en: List of heuristic sentences in English. The type is list.
  - translationStg: Stage used to translate the prompt.
    - enabled: Mandatory. Boolean value to activate or not the translation stage. The type is boolean.
    - language: Mandatory. Two-letter ISO 639-1 language code into which user input is translated to match the language of the data. The type is string. If this field exists, the prompts field must not exist.
    - prompt: Mandatory. List of prompts to be used in the LLM call.
      . The type is PromptLanguage.
      . If this field exists, the language field must not exist.
      . If this field is empty, the default prompt for this stage will be used.
  - contextStg: Stage used to know if the user’s phrase has the same context of the conversation.
    - enabled: Mandatory. Boolean value to activate or not the context stage. The type is boolean.
    - stickyContext: Mandatory. Strategy to include the context into the new query. If not specified, the optional context in the request is ignored. The type is string. Values:
      - ask_llm: An LLM-call is made to discern whether the context applies to the current query. If so, a recreate_question is performed. If not, the context is ignored and a clear_context field is added into the response.
      - include_context: The context will be inserted as is into the query. prompts should not by empty for this option.
      - recreate_question: An LLM-call will try to recreate the question by using the context.
    - prompts: Optional. List of prompts to be used in the LLM call.
      . The type is StickyContextPrompts.
      . If this field is empty, the default prompt for this stage will be used.
  - cleanStg: Stage used to remove prompt injection attempts using an LLM call.
    - enabled: Mandatory. Boolean value to activate or not the clean stage. The type is boolean.
    - prompt: Optional. Prompt to be used in the LLM call.
      . The type is PromptLanguage. For example: “Please clean up the query and reply only with the user’s question”.
      . If this field is empty, the default prompt for this stage will be used.
  - retrievalStg: Mandatory. Stage related to the retrieval phase, which is the process of obtaining relevant documents by comparing the query against indexed data or vectors.
    The stage is crucial for identifying and retrieving the documents or data that best match the input query, ensuring that only the most relevant results are returned.
    - sources: Mandatory. Sources data.
      - name: Mandatory. Name of the source data. The type is string.
      - embeddings: Mandatory. Embeddings model identifier that the ATRIA source data is associated with.
      - docs: Mandatory. Field with parameters related to the configuration of documents. The type is object.
        
        extension: Mandatory. Extensions of documents. The type is string. The extensions must be separated by a comma.
        
        loader: Mandatory. Project loader configuration.
        
        loaderType: Mandatory. Type of loader. Values: unstructured, csv, text, jsond, jsonl or url_list
        
        options: Optional. Object that configures how the document loader operates. It allows specifying the mode of loading and any post-processing actions to be applied to the loaded data.
        
        loaderMode: Optional. Modes for loader running. The type is string. The possible values are:
        
        single: Document will be returned as a single document representing the whole
        
        elements: The loader splits the document into different elements such as: Title, NarrativeText, etc. This allows a more granular processing and analysis
        
        postProcessors: Optional. Post processor loader. It allows to perform operations in the loaded document such as cleaning, transforming, enriching, etc. The type is string.
      - splitter: Optional. Project splitter for dividing large text inputs into smaller, manageable chunks, that can be more easily processed by language models, ensuring efficient and accurate processing.
        
        splitterType: Mandatory. Method used to split the text. Value: recursivechar (Recursively divides the text based on a character, typically looking for specific breakpoints such as punctuation or whitespace)
        
        options: Optional. Project splitter options.
        
        chunkSize: Optional. Maximum size of chunks to be returned. The type is number.
        
        chunkOverlap: Optional. Overlap in characters between chunks. The type is number.
      - retrievers: Mandatory. List of retrievers used to query and retrieve relevant data or documents from a collection based on a given query.
        
        retrieverType: Mandatory. Type of the retriever. Possible values: qdrant, tfidf, or elasticsearch.
        
        config: Optional. Configuration parameters for retrievers. The type is dictionary.
        
        numDocs: Optional. Number of documents to retrieve. The type is number.
        
        loadChunkSize: Optional. Chuck size used to load the documents in qdrant. The type is number. By default, 1000.
  - postFilteringStg: Stage in charge of processing candidates before they enter the RAG chain.
    . It prompts the project LLM for each candidate, using the query and the candidate text. The LLM determines whether the candidate text is related to the query, and if not, the candidate will be filtered out.
    . If this option is not enabled, no post-processing or filtering will take place.
    - enabled: Mandatory. Boolean value to activate or not the post-filtering stage. The type is boolean.
    - candidatesPostFiltering: Mandatory. Post-retrieval filtering applied to the candidates. It must be llm_filter (for each candidate, a very short request is made to the LLM to identify whether the candidate is relevant to answer the query. If ’no’ is decided, the candidate is filtered out)
    - prompt: Optional. Prompt to be used in the LLM call.
      . The type is PromptLanguage.
      . If this field is empty, the default prompt for this stage will be used.
  - generativeStg: Stage for handling the question and answer process.
    . It defines the strategy to solve the question, the prompts used in different stages of the process and the templates for generating responses
    - ragStrategy: Optional. Strategy to combine documents to generate a response. By default, stuff:
      - stuff: Mandatory. If stuff prompt is used, ragStrategy must be set to stuff.
      - refine: Mandatory. If informationExtraction or responseConsolidation prompts are used, ragStrategy must be set to refine.
    - prompts Optional. List of prompts to be used in the LLM call.
      . The type is GenerationPrompts.
      . If this field is empty, the default prompt for this stage will be used.
      - #.auto.language.user_query: Parameter that activates the automatic detection of language in the user’s query (multi-language feature).
        . This parameter is included in the args field of the prompt.
        . If you use the prompt by default, the multi-language feature is already activated.
        . Example:
        ... default: text: | Respond in language {user_query_language}. Question: {question} args: user_query_language: "#.auto.language.user_query" ...
- outputRefine: Optional. It is used to set up how to provide responses. The retrieving operation produces a list of candidates, each of which may provide a dictionary of metadata.
  - candidates: Optional. It indicates whether to return the candidates in raw (useful for evaluation purposes) or not. The type is boolean, by default, false.
  - filterOutputMetadata: Optional. It is used to set up how metadata is used when providing responses. The retrieving operation produces a list of candidates, each of which may provide a dictionary of metadata.
    - map: Optional. Maps attribute names in the original data to standard or more user-friendly names for later use.
      - fileType: Optional. String representing the type of file, typically used to specify the format or content type of the file being referenced. By default, content-type
      - pageNumber: Optional. String representing a page number. It could be used to identify particular pages within a document or resource. By default, page-number
    - groupBy: Optional. groupBy and aggregate are expressed in post-map field names. By default, url
    - aggregate: Optional. It determines how the values of duplicated fields are consolidated during grouping, specifying the handling of aggregated field information. By default, page-number
    - outputFilter: Optional. List of fields to be displayed in the metadata. Type is list.
    - root: Optional. Defines the primary fields that will structure the final output of the metadata processing. Fields listed under root will remain at the top level of the response entries, while all other metadata fields will be nested under a metadata. Type is list.

Example of preset for Generative AI capability

      {
        "id": "e27ca464-488a-435d-a508-da8a262d905f",
        "name": "openai",
        "description": "openai model",
        "brand": "",
        "contact": "",
        "group": "simple_ai",
        "session": {
          "window": 0
        },
        "generative": {
          "model": {
            "id": "openai",
            "parameters": {
              "top_p": 0.9
            }
          },
          "prompts": {
              "preamble": {
                "text": "Habla como si fueras {name}",
                "args": {
                  "name": "Napoleon"
                }
              },
              "examples":[
                "Naciste en galicia",
                "Di que tu padre era gallego"
              ],
              "promptRegexClean": "[#\\n\"]+"
          }
        }
      }

Example of preset for RAG capability

    {
        "id": "1cafcb5c-7951-4645-86d4-055d3b46fe79",
        "name": "atria-rag-gpt-35-turbo",
        "group": "enriched_ai",
        "description": "Atria rag GPT 3.5",
        "session": {
            "window": 3
        },
        "rag": {
            "ragType": "questions-answers",
            "model": {
                "id": "gpt-35-turbo",
                "parameters": {
                    "max_tokens": 4000,
                    "temperature": 1,
                    "top_p": 1
                }
            },
            "references": {
                "maximum": 3,
                "baseUrl": "project-gpt-35-turbo/pdfs"
            },
            "stages": {
                "language": "en",
                "translationStg": {
                    "enabled": true,
                    "language": "en"
                },
                "contextStg": {
                    "enabled": true,
                    "stickyContext": "ask_llm"
                },
                "cleanStg": {
                    "enabled": true
                },
                "retrievalStg": {
                    "sources": {
                        "name": "project-gpt-35-turbo",
                        "embeddings": "text-embedding-ada-002",
                        "docs": [
                            {
                                "extension": "pdf",
                                "loader": {
                                    "loaderType": "unstructured",
                                    "options": {
                                        "loaderMode": "single"
                                    }
                                }
                            },
                            {
                                "extension": "txt",
                                "loader": {
                                    "loaderType": "url_list"
                                }
                            }
                        ],
                        "splitter": {
                            "splitterType": "recursivechar",
                            "options": {
                                "chunkSize": 60,
                                "chunkOverlap": 20
                            }
                        },
                        "retrievers": [
                            {
                                "retrieverType": "qdrant",
                                "config": {
                                    "loadChunkSize": 10000
                                }
                            },
                            {
                                "retrieverType": "tfidf"
                            }
                        ]
                    }
                },
                "postFilteringStg": {
                    "enabled": true
                },
                "generativeStg": {
                    "ragStrategy": "stuff"
                }
            },
            "outputRefine": {
                "candidates": false
            }
        }
    }

Docs: TV LLM Conversational None: Dialog Configuration

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

Configuration of the generic-ai-dialog for TV LLM Conversational None UC

How the generic-ai-dialog must be configured for this use case

Specific configuration

The TV LLM Conversational None UC is triggered by the generic-ai-dialog-v1 for channelData v1 or generic-ai-dialog-v3 for channelData v3. For this use case, the required specific configuration is set below:

Example v1:

    {
    "name": "generic-ai",
    "dialogs": [
        {
            "id": "generic-ai-dialog-v1",
            "onlyIn": [
                "set-top-box"
            ],
            "triggerConditions": [
                {
                    "intent": "intent.conversational.none",
                    "settings": {
                        "locales": {
                            "error": [
                                "tv.error.fpaOrCognitive"
                            ]
                        }
                    }
                }
            ]
        }
    ]
    }

Example v3:

    {
        "channelDataVersion": "v3",
        "id": "generic-ai-dialog-v3",
        "onlyIn": [
            "set-top-box",
            "global-video-platform"
        ],
        "triggerConditions": [
            {
                "intent": "intent.conversational.none",
                "settings": {
                    "locales": {
                        "error": [
                            "core:flc.answer.error"
                        ]
                    }
                }
            }
        ]
    }

Docs:

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

Configuration of the tv-custom-recommendation-dialog

How the tv-custom-recommendation-dialog must be configured for this use case

Specific configuration

The tv-custom-recommendation-dialog is specifically designed to resolve the advanced TV recommendation, using LLMs in ATRIA.

Currently, this dialog is available for Aura channelData V1 and V3 versions.

For this use case, the required specific configuration is set below:

    {
      "id": "tv-custom-recommendation",
      "channelDataVersion": "v3", // Only in Aura channelData V3 version
      "triggerConditions": [
        {
          "intent": "intent.tv.custom_recommendation"
        }
      ],
      "bypass": {
        "duration": 4,
        "payloadName": "openai",
        "initialData": {},
        "recognizersEnabled": true,
        "recognizersBreakIntents": {
          "intent.tv.display": [
            "[Display Channel]",
            "[Display Contents]"
          ],
          "intent.navigation.section_show": [
            "[Sections]"
          ]
        }
      }
    }

Specific values

Key	Value	Description
bypass.duration	4 (minutes)	This value overwrites the default aura-bot value for bypass lasting 10 minutes.
bypass.payloadName	openai	Name of the interface that will be used as bypass payload for this dialog.
bypass.initialData	empty	It should contain any data needed by the dialog to be initialized.
bypass.recognizersEnabled	true	This value overwrites the default aura-bot way of working with recognizers when it is in bypass mode. If it is set to `true`, recognizers are executed, and their result is stored in the bypass payload to be used, if needed, afterwards.
bypass.recognizersBreakIntents	Array of intents and their tagged topic matches	Used to handle when the user requested any other use case during the execution of the advanced custom recommendation.

Environment variables

Property	Type	Description	Modifiable by OB?
AURA_GATEWAY_API_ENDPOINT	URI string	Endpoint to access the locally deployed ATRIA aura-gateway-api	NO
AURA_GATEWAY_API_ISSUER_URL	string	Aura issuer URL. It is automatically fulfilled by the installer.	NO
TVCUSTOMRECOMMENDATION_COMMAND_REGEXP	string	Regex to match the command for TV custom recommendation	NO
TVCUSTOMRECOMMENDATION_GET_TOPIC_REGEXP	string	Regex to match the topic command for TV custom recommendation	NO
TVCUSTOMRECOMMENDATION_CLEAN_TOPIC_REGEXP	string	Regex to replace the command by text for TV custom recommendation response	NO
TVCUSTOMRECOMMENDATION_MAX_ITERATIONS	number	Maximum number of question and answer cycles allowed by the dialog, to avoid an infinite conversation between the user and the LLM. By default, `5`.	YES

Configuration by channel

From Prince’s release onwards, the configuration of applicationId and presetId per channel and intent has been added to the channel model.

For this use case, the required specific configuration per channel is set below (added dialogs section under atria property at Main-Recognizer-Video-Triage-29855):

    ...,
    "atria": {
      "dialogs": {
        "intent.tv.custom_recommendation": {
          "applicationId": "816bdab6-3ea3-4a77-bdea-12945d6d7053",
          "presetId": "ef3d0603-3fef-4109-a577-0ab92f9060df"
        }
      }
    }

Specific values by channel

Intent	Key	Value	Description	Modifiable by OB?
intent.tv.custom_recommendation	applicationId	816bdab6-3ea3-4a77-bdea-12945d6d7053	ATRIA application identifier	NO
intent.tv.custom_recommendation	presetId	ef3d0603-3fef-4109-a577-0ab92f9060df	ATRIA preset identifier to be used within the use case.	NO

Dialog flows

The following diagrams are a simplification of the whole flow, this means that not all the components of Aura or Kernel are included, for the sake of the readability of the diagrams.

Please, take into account, that:

AuraBot includes DirectLine, aura-groot and aura-bot components.
ATRIA includes aura-gateway-api, atria-model-gw and OpenAI models calls.
AuraTVAPI includes the calls to Kernel.

Standard execution

actor User
participant STB #ebdff7
participant AuraBot
participant AuraNLP
participant Atria
participant AuraTVAPI

User -> STB ++:  Recomendación personalizada
STB -> AuraBot ++: sendActivity("Recomendación personalizada")
AuraBot -> STB: 200 OK
AuraBot -> AuraNLP ++: recognize("Recomendación personalizada")
AuraNLP -> AuraBot --: 200 OK (intent.tv.custom_recommendation)
AuraBot -> AuraBot: openDialog("custom_recommendation")
group custom_recommendation dialog
AuraBot -> AuraBot: init bypass mode
AuraBot -> Atria ++: prompt(app, preset, "custom_recommendation")
Atria -> AuraBot: "¡Hola! ¿En qué puedo ayudarte hoy? ¿Qué tipo de contenido estás buscando?" 200 OK
AuraBot -> AuraBot: sendToUser("¡Hola! ¿En qué puedo ayudarte hoy? ¿Qué tipo de contenido estás buscando?")
end
AuraBot -> STB: sendActivity("¡Hola! ¿En qué puedo ayudarte hoy? ¿Qué tipo de contenido estás buscando?")
User -> STB: Estoy tristón y quiero animarme
STB -> AuraBot: sendActivity("Estoy tristón y quiero animarme")
AuraBot -> STB: 200 OK
group custom_recommendation dialog
AuraBot -> Atria: prompt(app, preset, "Estoy tristón y quiero animarme")
Atria -> AuraBot: "¿Te gustaría ver algo emocionante o prefieres algo más relajado?" 200 OK
AuraBot -> AuraBot: sendToUser("¿Te gustaría ver algo emocionante o prefieres algo más relajado?")
end
AuraBot -> STB: sendActivity("¿Te gustaría ver algo emocionante o prefieres algo más relajado?")
User -> STB: Emocionante
STB -> AuraBot: sendActivity("Emocionante")
AuraBot -> STB: 200 OK
group custom_recommendation dialog
AuraBot -> Atria: prompt(app, preset, "Emocionante")
Atria -> AuraBot: "¿Te gustan las historias de héroes o tal vez algo de alto voltaje? O quizás prefieres persecuciones y carreras." 200 OK
AuraBot -> AuraBot: sendToUser("¿Te gustan las historias de héroes o tal vez algo de alto voltaje? O quizás prefieres persecuciones y carreras.")
end
AuraBot -> STB: sendActivity("¿Te gustan las historias de héroes o tal vez algo de alto voltaje? O quizás prefieres persecuciones y carreras.")
User -> STB: Héroes
STB -> AuraBot: sendActivity("Héroes")
AuraBot -> STB: 200 OK
group custom_recommendation dialog
AuraBot -> Atria: prompt(app, preset, "Héroes")
Atria -> AuraBot: "¿Quieres ver algo sobre héroes salvando el mundo o más bien sobre héroes en situaciones peligrosas?" 200 OK
AuraBot -> AuraBot: sendToUser("¿Quieres ver algo sobre héroes salvando el mundo o más bien sobre héroes en situaciones peligrosas?")
end
AuraBot -> STB: sendActivity("¿Quieres ver algo sobre héroes salvando el mundo o más bien sobre héroes en situaciones peligrosas?")
User -> STB: Salvando el mundo
STB -> AuraBot: sendActivity("Salvando el mundo")
AuraBot -> STB: 200 OK
group custom_recommendation dialog
AuraBot -> Atria: prompt(app, preset, "Salvando el mundo")
Atria -> AuraBot --: "[RESULT TAG]" 200 OK
AuraBot -> AuraTVAPI ++: searchTVContentByTag("[RESULT TAG]")
AuraTVAPI -> AuraBot --: contents 200 OK
AuraBot -> AuraBot: sendToUser("Este es el contenido que puedo recomendarte", contents)
end
AuraBot -> STB: sendActivity("Este es el contenido que puedo recomendarte", contents)

The user requests another use case while the recommendation dialog is open

actor User
participant STB #ebdff7
participant AuraBot
participant AuraNLP
participant Atria
participant AuraTVAPI

User -> STB ++:  Recomendación personalizada
STB -> AuraBot ++: sendActivity("Recomendación personalizada")
AuraBot -> STB: 200 OK
AuraBot -> AuraNLP ++: recognize("Recomendación personalizada")
AuraNLP -> AuraBot --: 200 OK (intent.tv.custom_recommendation)
AuraBot -> AuraBot: openDialog("custom_recommendation")
group custom_recommendation dialog
AuraBot -> AuraBot: init bypass recognizing mode
AuraBot -> Atria ++: prompt(app, preset, "custom_recommendation")
Atria -> AuraBot: "¿Qué tipo de emociones prefieres experimentar al ver una película o serie?" 200 OK
AuraBot -> AuraBot: sendToUser("¿Qué tipo de emociones prefieres experimentar al ver una película o serie?")
end
AuraBot -> STB: sendActivity("¿Qué tipo de emociones prefieres experimentar al ver una película o serie?")
User -> STB: Emociones fuertes
STB -> AuraBot: sendActivity("Emociones fuertes")
AuraBot -> STB: 200 OK
AuraBot -> AuraNLP ++: recognize("Emociones fuertes")
AuraNLP -> AuraBot --: None 200 OK
AuraBot -> AuraBot: storeIntentResolutionInContext(None)
group custom_recommendation dialog
AuraBot -> Atria: prompt(app, preset, "Emociones fuertes")
Atria -> AuraBot: "¿Prefieres historias de acción intensa o situaciones peligrosas en las que los protagonistas tienen que luchar por sobrevivir?" 200 OK
AuraBot -> AuraBot: sendToUser("¿Prefieres historias de acción intensa o situaciones peligrosas en las que los protagonistas tienen que luchar por sobrevivir?")
end
AuraBot -> STB: sendActivity("¿Prefieres historias de acción intensa o situaciones peligrosas en las que los protagonistas tienen que luchar por sobrevivir?")
User -> STB: Abre Netflix por favor
STB -> AuraBot: sendActivity("Abre Netflix por favor")
AuraBot -> STB: 200 OK
AuraBot -> AuraNLP ++: recognize("Abre Netflix por favor")
AuraNLP -> AuraBot --: {intent: intent.navigation.section_show, entities: [section: netflix]} 200 OK
AuraBot -> AuraBot: storeIntentResolutionInContext({intent: intent.navigation.section_show, entities: [section: netflix]})
group custom_recommendation dialog
AuraBot -> Atria: prompt(app, preset, "Abre Netflix por favor")
Atria -> AuraBot: "[Sections]" 200 OK
AuraBot -> AuraBot: redirectToDialog({intent: intent.navigation.section_show, entities: [section: netflix]})
end
group section_show dialog
AuraBot -> AuraBot: sendToUser(openSectionNetflix)
end
AuraBot -> STB: sendActivity(openSectionNetflix)

Docs:

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

How the generic-dialog must be configured for this use case

Specific configuration

The TV Recommend use case is triggered by the generic-dialog-v3.
For this use case, the required configuration is:

{
  "id": "generic-dialog-v3",
  "channelDataVersion": "v3",
  "triggerConditions": [
    {
      "intent": "intent.tv.recommend",
      "settings": {
        "locales": {
          "error": [
            "core:flc.answer.error"
          ]
        },
        "needTvResolution": true,
        "payloadType": "tv"
      }
    }
  ]
}

Docs:

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

Configuration of the generic-ai-dialog for TV LLM Search UC

How the generic-ai-dialog must be configured for this use case

Specific configuration

The TV LLM Search UC is triggered by the generic-ai-dialog-v1 for channelData v1 or generic-ai-dialog-v3 for channelData v3. For this use case, the required specific configuration is set below:

Example v1:

    {
        "id": "generic-ai-dialog-v3",
        "onlyIn": [
            "movistar-plus"
        ],
        "triggerConditions": [
            {
                "intent": "intent.tv.retrieve",
                "settings": {
                    "locales": {
                        "error": [
                            "tv:tv.error.fpaOrCognitive"
                        ]
                    },
                    "payloadType": "tv"
                }
            }
        ]
    }

Example v3:

    {
        "id": "generic-ai-dialog-v1",
        "onlyIn": [
            "movistar-plus"
        ],
        "triggerConditions": [
            {
                "intent": "intent.tv.retrieve",
                "settings": {
                    "locales": {
                        "error": [
                            "tv:tv.error.fpaOrCognitive"
                        ]
                    },
                    "payloadType": "tv"
                }
            }
        ]
    }

Docs:

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

Configuration of the generic-dialog for Section Show use case

How the generic-dialog must be configured for this use case

Specific configuration

The Section Show use case is triggered by the generic-dialog-v3.

For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            {
                "intent": "intent.navigation.section_show",
                "settings": {
                    "locales": {
                        "error": [
                            "tv:tv.error.fpaOrCognitive"
                        ]
                    },
                    "actions": [
                        {
                            "name": "NAVIGATION_SECTION_SHOW"
                        },
                        {
                            "name": "MAKE_SOUND"
                        }
                    ],
                    "sound": "positive",
                    "needPlayingContent": false,
                    "payloadType": "tv"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic-dialog for the Audiovisual App Opening use case

How the generic-dialog must be configured for this use case

Specific configuration

The Audiovisual App Opening use case is triggered by the generic-dialog-v3.

For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.app_open",
            "settings": {
                "locales": {
                    "error": [
                        "tv:video.section.not_available"
                    ]
                },
                "actions": [
                    {
                        "name": "GOTOAPP"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "sound": "positive",
                "needPlayingContent": false,
                "payloadType": "tv"
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic dialog for TV content get info use case

How the generic dialog must be configured for this use case

Specific configuration

The TV content get info use case is triggered by the generic dialog v3. For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.content_get_info",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "needTvResolution": true
            }
        }
    ],
    "onlyIn": [
        "movistar-plus",
        "set-top-box"
    ]
}

Specific values

Key	Value	Description
triggerConditions[?].settings.needTvResolution	true	Get resolution from resolution API

Docs:

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

Configuration of the generic-dialog for TV display use case

How the generic-dialog must be configured for this use case

Specific configuration

The TV display use case is triggered by the generic-dialog-v3. For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.display",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "needTvResolution": true
            }
        }
    ],
    "onlyIn": [
        "movistar-plus",
        "set-top-box"
    ]
}

Specific values

Key	Value	Description
triggerConditions[?].settings.needTvResolution	true	Get resolution from resolution API

Docs:

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

Configuration of the generic-dialog for Change language use case

How the generic-dialog must be configured for this use case

Specific configuration

The Change language use case is triggered by the generic-dialog-v3.

For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.language_change",
            "settings": {
                "locales": {
                    "error": [
                        "tv:tv.error.fpaOrCognitive"
                    ]
                },
                "actions": [
                    {
                        "name": "REMOTEON_AUDIO_SUBTITLES"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv"
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic dialog for TV move backwards use case

How the generic dialog must be configured for this use case

Specific configuration

The TV move backwards use case is triggered by the generic dialog v3. For this use case, the required specific configuration is set below:

Configuration for Brazil OB in STB channel. In this configuration, no default value is defined, as the STB device will resolve it when receiving an empty value in the parameter levels. A new entity is now recognized: ent.time_length_hour. Additional recognition was required by the aura-bot in order to obtain the total number of seconds to be returned in the parameter levels. To obtain that convertion into seconds, a new function has been created in utiles called: getSecondsLevelsWithTimerRecognizer.

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "suggestions": false,
    "triggerConditions": [
        {
            "intent": "intent.tv.move_backwards",
            "settings": {
                "locales": {
                    "success": [
                        "tv:tv.moveBackwards"
                    ],
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "actions": [
                    {
                        "name": "SEND_KEY"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv",
                "functions": {
                    "params": [
                        "currentIntent",
                        "persistentData",
                        "genericUtils",
                        "configuration"
                    ],
                    "algorithm": "return new Promise(async (resolve, reject) => { try { const params = { levels: await genericUtils.getSecondsLevelsWithTimerRecognizer(currentIntent, configuration) }; persistentData.dialogData.actionParams['SEND_KEY'] = params; resolve(); } catch (error) { reject(error); } });"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic dialog for TV move forwards use case

How the generic dialog must be configured for this use case

Specific configuration

The TV move forwards use case is triggered by the generic dialog v3. For this use case, the required specific configuration is set below:

Configuration for Spain OB in MP, MH and STB channels. In this configuration, there is still a default value of 60 seconds if no time entity is identified. Only the minutes and seconds entities are handled.

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "suggestions": false,
    "triggerConditions": [
        {
            "intent": "intent.tv.move_forwards",
            "settings": {
                "locales": {
                    "success": [
                        "tv:tv.moveForwards"
                    ],
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "actions": [
                    {
                        "name": "SEND_KEY",
                        "params": {
                            "keyCode": "MOVE_FORWARD",
                            "levels": "60"
                        }
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv",
                "functions": {
                    "params": [
                        "currentIntent",
                        "persistentData"
                    ],
                    "algorithm": "currentIntent.entities.map((ent) => { if (!isNaN(ent.entity)) { persistentData.dialogData.actionParams.SEND_KEY = { levels: ent.type === 'ent.time_length_sec' ? Number(ent.entity) : Number(ent.entity) * 60}}})"
                }
            }
        }
    ],
    "onlyIn": [
        "movistar-plus",
        "set-top-box"
    ]
}

Configuration for Brazil OB in STB channel. In this configuration, no default value is defined, as the STB device will resolve it when receiving an empty value in the parameter levels. A new entity is now recognized: ent.time_length_hour. Additional recognition was required by the aura-bot in order to obtain the total number of seconds to be returned in the parameter levels. To obtain that convertion into seconds, a new function has been created in utiles called: getSecondsLevelsWithTimerRecognizer.

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "suggestions": false,
    "triggerConditions": [
        {
            "intent": "intent.tv.move_forwards",
            "settings": {
                "locales": {
                    "success": [
                        "tv:tv.moveForwards"
                    ],
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "actions": [
                    {
                        "name": "SEND_KEY"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv",
                "functions": {
                    "params": [
                        "currentIntent",
                        "persistentData",
                        "genericUtils",
                        "configuration"
                    ],
                    "algorithm": "return new Promise(async (resolve, reject) => { try { const params = { levels: await genericUtils.getSecondsLevelsWithTimerRecognizer(currentIntent, configuration) }; persistentData.dialogData.actionParams['SEND_KEY'] = params; resolve(); } catch (error) { reject(error); } });"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic dialog for TV none use case

How the generic dialog must be configured for this use case

Specific configuration

The TV none use case is triggered by the generic dialog v3. For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.none",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "needTvResolution": true
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Specific values

Key	Value	Description
triggerConditions[?].settings.needTvResolution	true	Get resolution from resolution API

Docs:

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

Configuration of the generic-dialog for TV search use case

How the generic-dialog must be configured for this use case

Specific configuration

The TV search use case is triggered by the generic-dialog-v3. For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.search",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "needTvResolution": true,
                "payloadType": "tv"
            }
        }
    ],
    "onlyIn": [
        "movistar-plus",
        "set-top-box"
    ]
}

Specific values

Key	Value	Description
triggerConditions[?].settings.needTvResolution	true	Get resolution from resolution api

Docs:

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

Configuration of the generic-dialog for Subtitles remove use case

How the generic-dialog must be configured for this use case

Specific configuration

The Subtitles remove use case is triggered by the generic-dialog-v3.

For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.subtitles_remove",
            "settings": {
                "locales": {
                    "error": [
                        "tv:tv.error.fpaOrCognitive"
                    ]
                },
                "actions": [
                    {
                        "name": "REMOTEON_AUDIO_SUBTITLES",
                        "params": {
                            "subtitles": "None"
                        }
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv"
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic dialog for TV VOD EPG information use case

How the generic dialog must be configured for this use case

Specific configuration

The TV VOD EPG information use case is triggered by the generic dialog v3. For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.vod_epg_information",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "payloadType" : "tv",
                "functions" : {
                    "params" : [
                        "currentIntent",
                        "persistentData"
                    ],
                    "algorithm" : "const entityType = currentIntent?.entities?.[0]?.type; switch (entityType) { case 'ent.device_tv': case 'ent.device_mobile': case 'ent.device_phone': persistentData.dialogData.dialogSetting.forcedIntentResult = { name: 'MEDIA.SHEET_TV', entities: [ { type: entityType, entity: currentIntent.entities?.[0]?.entity } ] }; break; default: persistentData.dialogData.dialogSetting.forcedIntentResult = { name: 'MEDIA.SHEET_SECOND_SCREEN', entities: [] }; break; }"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Specific values

Key	Value	Description
triggerConditions[?].settings.functions.params	String[]	Params for algorithm
triggerConditions[?].settings.functions.algorithm	String	Logic to get intentResult by entities

Docs:

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

Aura file manager environment variables

List of environment variables used by aura-file-manager

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description	Modifiable by OB
AURA_4P_TOKEN_DELAY_RETRY	number	When retrieving a Kernel token, if an error occurs, delay time in milliseconds between retries. Default value: `100`.	NO
AURA_AUTHORIZATION_HEADER	string	Complete authorization header to be sent to aura_bridge, with the following format: `APIKEY xxxxxx`.	YES, but only if the previous APIKey was deprecated.
AURA_BRIDGE_ASYNC_CALLBACK_PATH	string	Path of async-callback. By default: `aura-services/v1/async-callback/notifications`.	NO
AURA_BRIDGE_APIKEY	string	APIKey needed to call aura-bridge.	NO
AURA_BRIDGE_CALLBACK_RETRIES	number	Number of retries made by aura-bridge in case of error in an HTTP request. By default: `3`.	NO, only if checked and validated with Aura Global Team.
AURA_BRIDGE_CALLBACK_RETRY_DELAY	number	Delay between retries in case of error. By default: `100`.	NO, only if checked and validated with Aura Global Team.
AURA_BRIDGE_CALLBACK_RETRY_FACTOR	number	Factor to multiply delay for every HTTP request retried. By default: `10`.	NO, only if checked and validated with Aura Global Team.
AURA_BRIDGE_ENDPOINT	string	Endpoint for aura-bridge.	NO
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT	string	Endpoint for aura-configuration-api.	NO
AURA_ENCRYPTION_ALGORITHM	string	Encryption algorithm that will be used to encrypt async-callback parameters. By default: `aes-256-cbc`	NO. It would break APIKey validation.
AURA_ENCRYPTION_IV_LENGTH	number	Size for the initialization vector used by the encryption algorithm. By default: `16`	NO. It would break APIKey validation.
AURA_ENCRYPTION_IV_POSITION	number	Position where to insert the initialization vector in the final string with the encrypted payload. By default: `35`.	NO. It would break APIKey validation.
AURA_ENCRYPTION_KEY	string	Encryption key or comma-separated list of encryption keys to be used in the environment. It is mainly used to encrypt sensible data, such as async-callback parameters.	NO. It would break database encrypted data and APIKey validation.
AURA_ENVIRONMENT_NAME	string	Name of the environment where the aura-authentication-api is deployed. For example: `ap-next`, `es-dev` or `de-pre`.	NO
AURA_ENVIRONMENT_PREFIX	string	Prefix that will be used by all Redis keys when using redis-connector. This allows mixing in a single Redis service messages coming from different environments in the same Azure subscription. By default: ``. (empty)	YES
AURA_FILE_MANAGER_SERVER_PORT	number	Port where the API is listening. By default, `8015`	NO
AURA_FILE_MANAGER_TYPES	string[]	Array with the valid default file types, it can be overriden by the channel configuration. Default value: `['pdf', 'docx', 'pptx', 'xlsx', 'aac', 'm4a', 'amr', 'mp3', 'ogg', 'mp4', '3gpp', 'jpg', 'jpeg', 'png']`	NO, it must be done through channel config.
AURA_FILE_MANAGER_MONGODB_COLLECTION_FILES_QUEUE	string	Collection where the files objects will be stored. By default: `files-queue`.	NO
AURA_FILE_MANAGER_MONGODB_DATABASE_NAME	string	Database name where will be included all the aura-file-manager collections. By default: `aura-file-manager`.	NO
AURA_FILE_MANAGER_MONGODB_MAX_RETRIES_QUEUE	number	Number of file processing attempts. Not to be confused with message sending retries. By default: `3`.	NO
AURA_FILE_MANAGER_MONGODB_MAX_PROCESSING_TIME	number	Maximum time in milliseconds that the file is in the `PROCESSING` state before trying to process it again. By default: `300000` milliseconds.	NO
AURA_FP_AUTHSERVER_ENDPOINT	string	URL of the Kernel authentication server. It MUST end with `/`	NO
AURA_HTTP_KEEP_ALIVE	boolean	Flag to indicate whether or not the outgoing HTTP connections should be established with keep alive or not. By default, `true`.	NO
AURA_HTTP_KEEP_ALIVE_MSECS	number	Number of milliseconds to keep HTTP connections open. By default, `100000`.	NO
AURA_HTTP_KEEP_MAX_SOCKETS	number	Number of sockets to keep HTTP connections open. By default, `200`.	NO
AURA_HTTP_MAX_REQUEST_SIZE	string	Maximum size in bytes of body request. Allowed values must indicate the units: 10 mb, 200 kb, etc. By default, `50mb`.	NO
AURA_HTTP_PATHS_LOG_DISABLED	string	Comma-separated string with the outgoing path that should not be logged. By default, `.well-known/openid-configuration`, `aura-configuration`, `metrics,` `healthz`. The paths in this variable will be added to the default ones.	YES, add the values to be filtered as a comma-separated list of paths.
AURA_INTERNAL_RETRIES	number	Number of retries for internal calls. By default, `1`	NO, except if requested
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev`, the latter a more visual format. By default: `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in monitoring logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default: `INFO`.	YES, for development set it to `DEBUG`. In pre/production should be `INFO` or `ERROR`. For analysis of an issue in pre/production it may be changed to `DEBUG`.
AURA_MAKEUP_MODE	string	It allows dev mode of the make-up with the value `local`. By default: `full`.	NO, only for development, set it to `local`.
AURA_MAKEUP_MONGODB_INDEX_FILE	string	Name of the file that contains the definition of Mongo indexes. By default: `aura-file-manager-mongodb-indexes.json`	NO
AURA_MAX_FILE_SIZE_BYTES	number	Maximum file size in bytes by default. It can be overridden by channel configuration. Default value: `16384000`.	NO, it must be done through channel config.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO. Only if operations team changes it.
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Microsoft Storage account of the environment.	NO. Only if operations team changes it.
AURA_MICROSOFT_AZURE_STORAGE_CONFIGURATION_CONTAINER	string	Name of the container where basic aura-bot configuration files are stored: Mongo indexes descriptor, behavior manager, etc. By default, `aura-configuration`.	NO
AURA_MICROSOFT_AZURE_STORAGE_SAS_URL_VALIDITY	number	Number of milliseconds of validity for generated SAS tokens. By default: `3600000`	YES, if Operations Team prefers another duration time.
AURA_MICROSOFT_AZURE_STORAGE_STATIC_CONTAINER_NAME	string	Name of Azure blob container to be used as repository.	NO. Only if Operations Team changes it.
AURA_MIN_FILE_SIZE_BYTES	number	Minimum file size in bytes by default. It can be overridden by channel configuration. Default value: `256`.	NO, it must be done through channel config.
AURA_MONGODB_PASSWORD	string	MongoDB password to access `AURA_MONGODB_BOT_DATABASE` in `AURA_MONGODB_URI`.	NO
AURA_MONGODB_POOL_SIZE	number	Number of connections available in MongoDB pool. By default, `60`.	NO
AURA_MONGODB_SSL	boolean	`true` if access to `AURA_MONGODB_URI` is `SSL`. By default, `false`.	NO
AURA_MONGODB_SUFFIX	string	Suffix of Mongo database name. Its value at run-time will be the value from AURA_ENVIRONMENT_NAME-AURA_VERSION.replace(/./g,’-’)`.	NO
AURA_MONGODB_URI	string	MongoDB URI of the server handling `AURA_MONGODB_BOT_DATABASE`.	NO
AURA_MONGODB_USERNAME	string	MongoDB username to access `AURA_MONGODB_BOT_DATABASE` in `AURA_MONGODB_URI`.	NO
AURA_QUEUE_MANAGER_CHECK_QUEUE_INTERVAL_TTL	number	In milliseconds. The time interval used by the queue manager to check if the queue system has pending messages. By default, `1000`.	NO
AURA_QUEUE_MANAGER_CONCURRENT_TASK	number	Number of concurrently processed tasks. By default, `5`.	NO
AURA_QUEUE_MANAGER_INTERVAL	number	In milliseconds. Time interval for processing messages in the queue. By default: `200`..	NO
AURA_QUEUE_MANAGER_MAX_ELEMENTS	number	Maximum number of elements in the queue. By default: `4`.	NO
AURA_QUEUE_MANAGER_AGENT_INTERVAL	number	Time interval in milliseconds for the queue agent to check if the queue system has pending messages. By default: `20000`.	NO
AURA_QUEUE_TYPE	string	Type of queue system to be used (MONGO/REDIS). By default: `REDIS`.	NO
AURA_REDIS_COMPONENT_CONFIG_PREFIX	string	Prefix for Redis configuration keys. By default: `aura-config:`.	NO
AURA_REDIS_MODE	string	Mode of Redis distribution. Values: `CLUSTER`, `SENTINEL`, `SINGLE`. By default: `SENTINEL`.	NO
AURA_REDIS_PREFIX	string	Redis prefix.	NO
AURA_REDIS_SENTINEL_INSTANCE_NAME	string	Name of the Redis instance. Used in `SENTINEL` mode.	NO
AURA_REDIS_HOSTS	string	String with a list of nodes separated by ‘,’, including host and port separated by ‘:’. For example: “localhost:port,localhost2:port2”.	NO
AURA_REDIS_DATABASE	number	Database number for `SINGLE` or `SENTINEL` mode. By default: `0`.	YES
AURA_REDIS_PASSWORD	string	String with Redis password.	YES
AURA_REDIS_USE_CONNECTION_POOL	boolean	Use pool connections for Redis. By default: `true`.	YES
AURA_REDIS_CONNECTION_POOL_MIN	number	Minimum number of connections in the pool. By default: `2`.	YES
AURA_REDIS_CONNECTION_POOL_MAX	number	Maximum number of connections in the pool. By default: `100`.	YES
AURA_REDIS_MAX_RECONNECT_RETRIES	number	Number of retries to connect to Redis. By default: `25`	YES
AURA_REDIS_MAX_RECONNECT_INTERVAL	number	Time in milliseconds to wait before reconnecting to Redis. By default: `5000`.	YES
AURA_REDIS_QUEUE_PREFIX	number	Prefix for Redis keys used by the queue system. By default: `file_manager:queue:`.	YES
AURA_REDIS_QUEUE_SHARD_COUNT	number	Number of shards to generate lists for store unprocessed context. By default: `5`	YES
AURA_SHUTDOWN_GRACEFUL_TTL	string	Number of milliseconds to wait until all authentication-api tasks are done before shutting each pod down. By default `25000` (25 seconds)	NO
AURA_VERSION	string	Number of the Aura release being executed.	NO
AURA_KPIS_BLOB_TIME_WAIT_IF_EXISTS	number	Time to wait in milliseconds if the KPIs blob exists to avoid duplicate headers. By default: `1000`.	YES

Docs:

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

Environment variables

List of environment variables handled by aura-databricks-jobs and avro-to-dataset-job-cli

Aura Databricks Jobs variables

List of environment variables handled by aura-databricks-jobs.

Properties marked in bold are mandatory
Properties marked in italics are optional

Property	Type	Description	Modifiable by OB?
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `console`, `json`, `string` or `simple`. By default: `simple`.	NO.
AURA_LOGGING_LEVEL	string	Level to be used in monitoring logs, from more to less verbose: `'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF', 'NOTSET', 'CRITICAL`. By default: `INFO`.	YES, for development set it to `DEBUG`. In pre/production, it should be `INFO` or `ERROR`. For the analysis of an issue in pre/production, it may be changed to `DEBUG`.
AURA_VERSION	string	Number of the Aura’s release being executed.	NO

Avro to Dataset job cli variables

List of job’s variables handled by avro-to-dataset-job-cli

Properties marked in bold are mandatory
Properties marked in italics are optional

Property	Type	Description	Modifiable by OB?
AURA_ENVIRONMENT_NAME	string	Name of the environment where aura-databricks-jobs is deployed. For example: `ap-next`, `es-dev`, `de-pre`	NO
AURA_FP_SPARK_BASE_URL	string	Base URL for Kernel Spark SDK.	NO
AURA_FP_SPARK_CLIENT_ID	string	Client ID for Kernel Spark SDK.	NO
AURA_FP_SPARK_CLIENT_SECRET	string	Client secret for Kernel Spark SDK.	NO
AURA_FP_SPARK_JARS_PACKAGES	string	The jar packages configured only for local run, because in Databricks cluster this configuration is set previously.	NO
AURA_FP_SPARK_JARS_REPOSITORIES	string	The repositories configured only for local run, because in Databricks cluster this configuration is set previously.	NO
AURA_FP_SPARK_SCOPES	string	Scopes for Kernel Spark SDK.	NO
AURA_FP_SPARK_PURPOSES	string	Purposes for Kernel Spark SDK.	NO
AURA_FP_SPARK_SUFFIX_DATASET_TEST	string	Suffix used in tests with Kernel Spark SDK. By default: ``.	NO. It is used for testing in the development environment.
AURA_KPI_AVRO_ADAPTER_CONFIG_PATH	string	File path for getting Aura Avro adapter configuration.	NO
AURA_KPI_AVRO_PROCESS_ERROR_FILENAME	string	File name that records an error in the last execution. By default: `databricks.ERROR`.	NO
AURA_KPI_AVRO_PROCESSED_FOLDER_PATH	string	Destination path for the processed KPIs Avro files.	NO
AURA_KPI_AVRO_SOURCE_PATH	string	Source path for the KPIs Avro data.	NO
AURA_KPI_AVRO_SOURCE_SIZE_REPORT_PATH	string	The file path for getting size report. By default: `avro/sizeReport.json`.	NO
AURA_KPI_AVRO_REPORTS_MODE	string	Behavior of avro-to-dataset-job-cli regarding the generation of reports. Possible values: `all`: a report is generated for each processed file; `none`: it does not generate any report; `error`: it generates a report if an error has occurred. By default: `all`.	NO
AURA_KPI_AVRO_REPORTS_DESTINATION_PATH	string	Destination path for the KPIs Avro reports.	YES
AURA_KPI_AVRO_REPORTS_SAS_EXPIRATION	integer	Time to expiration in minutes for the report SAS URL generated when an error occurs. Default: `43200` (30 days).	NO
AURA_KPI_AVRO_SCHEMAS_NOT_TO_UPLOAD	string	Schemas not to be uploaded in the KPIs Avro data, included in a list formatted as follows: `schema_1:dataset_id_1,schema_1:dataset_id_2,schema_2;dataset_id_3` Example: `dimensional:D_Aura_Channel,entity:E_Aura_GROOT`.	NO
AURA_KPI_AVRO_SCHEMAS_PATH	string	Schema path where Avro schemas are stored. By default, `schemas`.	NO
AURA_MICROSOFT_AZURE_RETRY_TOTAL	integer	Total number of allowed retries. Default value: `3`.	NO
AURA_MICROSOFT_AZURE_RETRY_BACKOFF_FACTOR	float	Backoff factor to apply between attempts after the second try (most errors are resolved immediately by a second try without a delay). In ’exponential’ mode, retry policy will sleep for: `{backoff factor} * (2 ** ({number of total retries} - 1))` seconds. If the backoff_factor is 0.1, then the retry will sleep for [0.0s, 0.2s, 0.4s, …] between retries. The default value is `0.3`.	NO
AURA_MICROSOFT_AZURE_RETRY_BACKOFF_MAX	integer	Maximum backoff time in seconds. Default value: `5`.	NO
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT	string	Microsoft Storage account of the environment.	NO
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO
AURA_MICROSOFT_AZURE_STORAGE_KPIS_CONTAINER_NAME	string	Name of the container where the KPIs are stored.	NO
SPARK_CONTEXT_LOG_LEVEL	string	Log level for the Spark context.	NO

Docs:

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

Aura KPIs Uploader environment variables

List of environment variables handled by Aura KPIs uploader

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description	Modifiable by OB?
AURA_AUTHORIZATION_HEADER	string	Complete authorization header to be sent to `AURA_CHANNELS_CONFIGURATION_API_ENDPOINT`, with the following format: `APIKEY xxxxxx`	YES, but only if the previous APIKey was deprecated
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT	string	Complete URL where aura-bot should get the configuration of all the channels available in the environment.	YES, but only if the generated SAS token was deprecated.
AURA_DAYS_INTERVAL	number	Interval of days to get the processed KPIs files. By default: `30`	NO
AURA_DEFAULT_LOCALE	string	Culture code to be used by default in the current deployment: `de-de`, `en-gb`, `es-es`, `pt-br`.	NO
AURA_ENVIRONMENT_NAME	string	Name of the environment where aura-kpis-uploader is deployed. For example: `ap-next`, `es-dev`, `de-pre`	NO
AURA_FILES_PREFIX	string	Paths where aura-bot, aura-nlp or aura-authentication-api entity KPIs files are stored.	NO
AURA_FOLDER_DESTINATION	string	Root folder name in destination where the KPIs files are stored. By default: `AURA_DATA`.	NO
AURA_KPIS_ENTITIES_CONTAINER	string	Name of the Azure Blob container to store Aura entities files. By default, `aura-kpis`. It MUST be the same than the `AURA_KPIS_STORE_CONTAINER` configured in aura-bot, aura-authentication-api, aura-kpis and aura-nlp.	NO
AURA_KPI_FILES_EXTENSION	string	Extension to be used in KPIs files. Default: `txt`. It MUST be the same than the `AURA_KPI_TO_DSV_EXTENSION` configured in aura-bot, aura-authentication-api, aura-kpis and aura-nlp.	NO
AURA_KPI_FILES_NOT_TO_UPLOAD	string	String separated by comma with the files to not upload to the destination folder with format Component:Entity. For example: `BOT:MESSAGE,BOT:API`	NO
AURA_KPIS_TIME_FILE_IS_IN_USE_AMOUNT	number	Contains the amount of time it considers a file to be in use and does not process it. By default: `1`
AURA_KPIS_TIME_FILE_IS_IN_USE_UNIT	string	Time unit that together with AURA_KPIS_TIME_FILE_IS_IN_USE_AMOUNT determines whether or not a file should be processed: Values: “year”, “years”, “y”, “month”, “months”, “M”, “week”, “weeks”, “w”, “day”, “days”, “d”, “hour”, “hours”, “h”, “minute”, “minutes”, “m”. By default: `hour`
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev` (which is a more visual format). By default: `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in monitoring logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default: `'INFO'`.	YES, for development environment, set it to debug. In pre/production environment, it should be ‘INFO’ or ‘ERROR’. For analysis of an issue in pre/production, it may be changed to ‘DEBUG’.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCESS_KEY	string	Microsoft Storage password of the source deployment.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT	string	Microsoft Storage account of the source environment.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY_DESTINATION	string	Microsoft Storage password of destination.	NO
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT_DESTINATION	string	Microsoft Storage account of destination.	NO
AURA_MICROSOFT_AZURE_STORAGE_CONTAINER_DESTINATION	string	Microsoft Storage container of destination.	NO
AURA_VERSION	string	Number of Aura release being executed.	NO
PUSHGATEWAY_ENDPOINT	string	Prometheus push gateway endpoint.	NO
PROMETHEUS_JOB_NAME	string	Prometheus job name. By default: `aura_kpi_uploader_job`.	NO
AURA_SOURCE_PATH_AVRO_ADAPTERS	string	Relative path to file with the dimensions and entities to transform Avro.	NO
AURA_KPIS_AVRO_DESTINATION_PATH	string	Path to store the Avro files in Aura Azure Container. Default: ‘avro’	YES
AURA_KPIS_REPORTS_DESTINATION_PATH	string	Path to store the reports in Aura Azure Container. Default: ‘reports’	YES
AURA_KPIS_REPORTS_MODE	string	Behavior of aura-kpis-uploader regarding the generation of reports. Possible values: `all`: a report is generated for each processed file; `none`: it will not generate any report; `error`: it generates a report if an error has occurred. By default: `error`.	NO
AURA_SOURCE_PATH_AVRO_ADAPTERS	string	Adapters to transform data, ‘/schemas/aura-csv-adapter.json’ for CSV transform and ‘/schemas/aura-avro-adapter.json’ to transform in CSV and Avro. By default: `schemas/aura-csv-adapter.json`.	YES
AURA_SAS_STORAGE_FILE_TTL	number	TTL in minutes for SAS when generates URL to File Storage. By default: `15`.	YES
AURA_KPIS_BLOB_TIME_WAIT_IF_EXISTS	number	Time to wait in milliseconds if the KPIs blob exists to avoid duplicate headers. By default: `1000`.	YES
AURA_KPIS_REPORTS_SAS_EXPIRATION	number	Time to expiration in minutes for the report SAS URL generated when an error occurs. Default: `43200` (30 days).	YES
AURA_DATABRICKS_OK_FILENAME	string	Name of the file to validate if DataBricks process was successful. Inside the file, there is a date to validate last success execution. Default: `databricks.OK`	YES
AURA_DATABRICKS_ERROR_FILENAME	string	Name of the file to validate if DataBricks process was failed. Default: `databricks.ERROR`	YES
AURA_DATABRICKS_EXECUTION_PERIOD	number	Period of DataBricks execution in hours. By default: `24`.	YES
AURA_KPIS_AVRO_SIZE_REPORT_FILENAME	string	Contains the name of the file to store size of AVRO files. By default: `sizeReport.json`.	YES
AURA_KPI_MAX_BLOCK_SIZE_FOR_APPEND_BLOB	number	Maximum buffer size for append blob uploading. Default: `100000000` (100MiB)	YES. It can be changed by a value lower than the maximum one established by default
AURA_KPI_NUM_MAX_FILES_FOR_EXECUTION	number	Number of files by entity to process in a single execution. Default: `12`	YES
AURA_KPI_HOURS_TO_SUBTRACT_TO_GET_NUM_MAX_FILES	number	Number of hours to subtract in order to get the number of files to process in a single execution. Default: `10`	YES

Docs:

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

Guidelines for use cases constructors

Scope: Comprehensive guidelines for the use of agents in an ATRIA experience

Use cases constructors

Index of contents

Docs:

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

Kernel datasets upload handling

Guidelines for the enabling and disabling of Kernel datasets upload in non-productive environments.

Introduction

After the deployment of Aura in any environment, all its components will generate KPI entities files that will be uploaded into Kernel in CSV or Avro format, as datasets. These procedures increment the cost, both in Aura and in Kernel instances:

More consumption of Azure Storage
More time of execution of the Databricks cluster of Aura
Need for more storage in Kernel, both in Azure for the CSVs and for Avro datasets

Moreover, the data generated in these environments is almost never analyzed nor used.

Because of this, the proposal is to disable the uploading and to minimize the storage of these files, to minimize the costs, once the sanity test set was executed and the process has been validated.

If, eventually, there is a need to test the process again or to upload some data to validate algorithms or to use the Aura billing module, everything can be enabled again.

Prerequisites

A kubeconfig of the Aura environment must be configured.
az client installed in your PC.
Credentials to access the Azure subscription.
Substitute <YOUR-ENV> with the corresponding pre-production environment: es-pre, es-cert, br-pre, de-pre, de-int, etc.
The installation output file (output_install/<YOUR_ENV>_info.json) to get:
- The token and the URL of the Databricks cluster.
  - Substitute <DATABRICKS_TOKEN> with Databricks cluster token.
  - Substitute <DATABRICKS_URL> with the domain of the Databricks cluster URL.
- The job_id of the databricks job in charge of uploading the datasets to Kernel
  - Substitute <DATABRICKS_JOB_ID> with the job_id.
- The Azure Storage account name and the blob container where the KPI entities files are stored.
  - Substitute <AZURE_COMMON_STORAGE> with STORAGE_ACCOUNT_NAME and <KPI_BLOB_CONTAINER_NAME> with its value.

PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE=output_install/<YOUR_ENV>_info.json
STORAGE_ACCOUNT_NAME=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .common_azure_storage_account_name)
STORAGE_ACCESS_KEY=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .common_azure_storage_access_key)
KPI_BLOB_CONTAINER_NAME=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .kpi_blob_container_name)
DATABRICKS_JOB_ID=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .databricks.job_id)
DATABRICKS_URL=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .databricks.url)
DATABRICKS_TOKEN=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .databricks.token)

Disable data uploading

Disable aura-kpis-uploader CSV files upload

Suspend aura-kpi-uploader job:

kubectl -n <YOUR-ENV> patch cronjobs kpi-uploader -p '{"spec" : {"suspend" : true }}'

Disable aura-databricks-job Avro files upload

Pause aura-databricks-job job:
- Substitute <DATABRICKS_JOB_ID> with the DATABRICKS_JOB_ID obtained from the installation output file.

curl -XPOST --header 'Authorization: <DATABRICKS_TOKEN>' https://<DATABRICKS_URL>/api/2.1/jobs/update --data '{
   "job_id": <DATABRICKS_JOB_ID>,
   "new_settings":{
      "schedule":{
         "pause_status":"PAUSED"
      }
   }
}'

Remove old KPI entity files generated by Aura and ATRIA components

This step will be fulfilled by applying a removal policy on the Azure blob container where the components write the KPIs.

There are two ways of applying this change:

Apply the policy from Azure portal
Apply the policy using az client

Apply the policy from Azure portal

Access Azure portal
Look for <AZURE_COMMON_STORAGE> account and <KPI_BLOB_CONTAINER_NAME>
Apply management-policy to <KPI_BLOB_CONTAINER_NAME> and to <KPI_BLOB_CONTAINER_NAME>/processed

Apply the policy using az client

To execute this step, first log in to the Azure subscription with az login.

PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE=output_install/<YOUR_ENV>_info.json
STORAGE_ACCOUNT_NAME=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .common_azure_storage_account_name)
STORAGE_ACCESS_KEY=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .common_azure_storage_access_key)
RESOURCE_GROUP=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .common_resource_group)

az storage account management-policy show -g ${RESOURCE_GROUP} --account-name ${STORAGE_ACCOUNT_NAME} -o json > policy.json

KPI_BLOB_CONTAINER_NAME=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .kpi_blob_container_name)

sed -i "s|${KPI_BLOB_CONTAINER_NAME}/proccesed||g" policy.json

az storage account management-policy create -g ${RESOURCE_GROUP} --account-name ${STORAGE_ACCOUNT_NAME} --policy policy.json

Enable data uploading

Execute Aura installer and everything will be reconfigured again, running the deploy_core stage.

Docs:

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

Aura Configuration API modules

Description of the different modules that compose Aura Configuration API

Introduction

Currently, aura-configuration-api contains the following modules:

Administration module

Module in charge of administration tasks:

Export of complete server information.
Export of information by modules.
Import of complete server information.
Import of information by modules.

Access detailed information about Administration module.

Channel module

Module responsible for managing all the information related to channels, including the configuration of each Aura channel as well as the libraries associated with each channel (replacement for the bot-response.json configuration file).

Add channel
Delete channel by id
Get channel by id
Get all channels
Get changed channels
Modify channel
Update channel

Access detailed information about Channel module.

Component module

Module responsible for managing all the information related to components, including the configuration of each Aura component.

Add new components
Delete component by name
Get component by name
Get all components
Update component by name
Modify component by name

Access detailed information about Component module.

Skill module

Module responsible for managing all the information related to skills, defining the following operations:

Add skill
Delete skill by id
Get skill by id
Get all skills
Get changed skills
Modify skill
Update skill

Access detailed information about Skill module.

Application module

Module responsible for managing all the information related to applications, defining the following operations:

Add application
Delete application by id
Get application by id
Get all applications
Get changed applications
Modify application
Update application

Access detailed information about Application module.

Library

Module responsible for managing all the information related to libraries, defining the following operations:

Add library by channel id
Delete all libraries by channel id
Delete library by id and channel id
Get library by id and channel id
Update library by channel id

From the functional point of view, this module depends on the aura-configuration-api channel module: server definition.

Prometheus

Module responsible for exposing metrics for monitoring and observability of Aura Configuration API using Prometheus. It provides metrics such as:

Aura component version (gauge)
Unhandled server errors (counter)
Outgoing message duration (summary)
Outgoing request duration (summary)

These metrics help track the health, performance, and errors of the API. Paths in metrics are normalized for aggregation. For more details, see the Prometheus metrics registration source code.

Access detailed information about Prometheus module.

Aura – configuration

Docs:

Aura configuration API admin module

Introduction

Servers definition

Endpoints

Export modules

Export all

Export one or several specific modules

Import modules

How is an import processed?

Result of the import process

Database

Channels collection

Fields

Indexes

skills collection

Fields

Indexes

applications collection

Fields

Types

Indexes

presets collection

Fields

Root

Types

Action

Session

Generative

RAG

Metadata

Indexes

suggestions collection

Fields

Indexes

tv-section collection

Fields

Example of metadata:

Indexes

agents collection

Fields

communication object (HTTP)

metadata object

Indexes

routing filters collection

Fields

database object

filterCollection object

metadata object

Indexes

Docs:

ATRIA components default configuration

Introduction

1. Server configuration

1.1. Logging configuration

Fields

1.2. atria-model-gateway default configuration

Defaults

Defaults fields

Defaults by default

Redis

Redis fields

Redis by default

Redis Subscriber

Redis subscriber fields

Redis subscriber by default

Config API

Config API fields

Config API by default

Allow logging prompts with INFO level

Allow logging prompts

Allow logging prompts by default

Models

Model fields

Models by default

atria-rag model

gpt-4

gpt-4o

gpt-4o-mini

Example of `metadata`: