Aura – 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

Aura Configuration API definition

Description of Aura configuration API swagger

Download swagger file

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

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

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 Configuration API core definition

Description of Aura configuration API core swagger

Download swagger file

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.

Docs:

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

Aura Configuration API plugins

Description of the different plugins that compose Aura Configuration API

Introduction

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

Preset plugin

Plugin responsible for managing all the information related to channels, including the configuration of each Aura preset, as well as the libraries associated with each preset.

Add preset
Delete preset by id
Get preset by id
Get all presets
Modify preset
Update preset

Access detailed information about the preset plugin.

TV section plugin

Plugin responsible for managing all the information related to TV Sections.

Add TV section
Delete TV section by id
Get TV section by id
Get all TV sections
Modify TV section
Update TV section

Access detailed information about the TV section plugin.

Agent plugin

Plugin responsible for the management of agents.

Access detailed information about the agent plugin.

Agent base plugin

Plugin responsible for the management of agents base.

Access detailed information about the agent base plugin.

Agent deployment plugin

Plugin responsible for managing the deployment of agents.

Access detailed information about the agent deployment plugin.

Routing filter plugin

Plugin responsible for managing the routing filters.

Access detailed information about the routing filter plugin.

Filter engine plugin

Plugin responsible for managing the engine routing filters.

Access detailed information about the engine filter plugin.

Docs:

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

TV section plugin

TV section plugin description for aura-configuration-api

Introduction

The tv-section plugin defines services associated with the management of TV sections in aura-configuration-api server.

All these services are defined in the tv-sections namespace (/tv/sections).

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/tv/sections
aura-services/v2/configuration/tv/sections/{tvSectionId}

Endpoints

Path	Method	Description
/tv/sections/	GET	Get all TV section information
/tv/sections/	POST	Add a new TV section
/tv/sections/{tvSectionId}	GET	Get TV section information using TV section id
/tv/sections/{tvSectionId}	PUT	Replace TV section information associated to TV section id
/tv/sections/{tvSectionId}	PATCH	Update some fields of TV section information using TV section id
/tv/sections/{tvSectionId}	DELETE	Delete TV section information using TV section id

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

Retrieving information from TV sections

Retrieving specific fields from TV section information

It is possible to get only a specific list of fields for TV section 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/tv/sections?includeFields=id,name,canon' \
--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": "tv-section-pid-1",
        "canon": "tv-section-canon"
    }
]

Excluding fields in TV sections information

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

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/tv/sections?excludeFields=metadata,name' \
--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",
        "pid": "tv-section-pid-1"
    }
]

Database

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

Docs:

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

Agent base plugin

Agent base plugin description for aura-configuration-api

Introduction

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

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

Servers definition

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

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

Examples:

aura-services/v2/configuration/agents-base
aura-services/v2/configuration/agents-base/{agentBaseId}

Endpoints

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

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

Retrieving information from agents base

Retrieving specific fields from agent base information

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

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

Response example:

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

Excluding fields in agent base information

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

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

Response example:

[
    {
        "id": "cd2b534c-16c3-4d89-a87e-ec45d3939232",
        "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"
    }
]

Filtering agent base information

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

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

Database

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

Docs:

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

Agent plugin

Agent plugin description for aura-configuration-api

Introduction

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

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

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/agents
aura-services/v2/configuration/agents/{agentId}

Endpoints

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

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

Retrieving information from agents

Retrieving specific fields from agent information

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

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/agents?includeFields=id,name' \
--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": "agent-pid-1"
    }
]

Excluding fields in agent information

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

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/agents?excludeFields=metadata,name' \
--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": "agent-pid-1"
    }
]

Database

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

Docs:

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

Aura Configuration API Engine Filter definition

Description of Aura configuration API Engine Filter swagger

Download swagger file

Docs:

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

Aura Configuration metrics

List of metrics available in Aura Configuration API

http_request_duration_seconds

This metric is intended to store the information related to all the incoming HTTP requests received by aura-configuration-api.

It is stored as a Summary in Prometheus, so every sample, besides the defined labels, also includes its duration.

This metric allows measuring the behavior of the requests from any given endpoint. Specifically, the duration since the request lands in aura-configuration-api until its HTTP response is returned:

The number of requests during a time
The average/min/max duration of these requests

Labels:

method: HTTP method used by the request being stored (GET, POST, PUT, DELETE, etc.)
host: host and domain where the request is being sent
path: specific endpoint of the request
status_code: HTTP status code returned in the response

This metric was stored since Greenday (6.0.0) release.

outgoing_request_duration_seconds

This metric is intended to store the information related to all the outgoing HTTP requests made by aura-configuration-api. It is stored as a Summary in Prometheus, so every sample, besides the defined labels, also includes its duration.

The metric allows measuring the behavior of the requests to any given endpoint:

The number of requests during a time
The average/min/max duration of these requests

Labels:

method: HTTP method used by the request being stored (GET, POST, PUT, DELETE, etc.)
host: host and domain where the request is being sent
path: specific endpoint of the request
status: HTTP status code returned in the response

aura_component_version

This metric is intended to store the number of aura-configuration-api instances (pods) running each version of the code.

It is stored as a Gauge in Prometheus.

Labels:

version: version field in the package.json file included in the running docker container.
component: name of the component that is writing the metric.

aura_server_unhandled_error

This metric is intended to store the number of unhandled errors happening in aura-configuration-api. It is stored as a Counter in Prometheus.

Labels:

error: exception message that forced the unhandled error.

services_status

This metric is intended to store the number of success or errored checks of modules of the server. It is stored as a Counter in Prometheus.

Labels:

moduleId: Id of the module.
status: OK or ERROR

Docs:

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

Aura Configuration API Preset definition

Description of Aura configuration API Preset swagger

Download swagger file

Docs:

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

Aura Configuration API Routing Filter definition

Description of Aura configuration API Routing Filter swagger

Download swagger file

Docs:

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

Telefónica brands management

List of available Telefónica brands defined in Kernel

Introduction

The aura-configuration-api is responsible for the management of the different Telefónica brands for the identification of Aura channels and applications.

These brands are defined in Kernel within the D_Gbl_Brand global dimension entity.

The current document shows the available ones and the identifier, description and date for each of them.

Available brands

List of brands defined in Kernel D_Gbl_Brand global dimension entity.

ID	Description	Date
0101	O2 (Germany) GmbH & Co - DE	20211018T000000
0102	Merit - DE	20211018T000000
0103	Blau - DE	20211018T000000
0104	FONIC - DE	20211018T000000
0105	Ortel - DE	20211018T000000
0106	Ay Yildiz - DE	20211018T000000
0107	NetzClub - DE	20211018T000000
0108	NettoKom - DE	20211018T000000
0109	MSD SuperSelect (Media Saturn = Metro Group) - DE	20211018T000000
0110	Kaufland (k-classic mobil) - DE	20211018T000000
0111	WhatsAppSIM - DE	20211018T000000
0112	TürkeiSIM (previously: Tuerk Telekom) - DE	20211018T000000
0113	blauworld - DE	20211018T000000
0114	Whitelabel - DE	20211018T000000
0115	EinfachPrepaid (previously: Schlecker) - DE	20211018T000000
0116	Mobilka (Ortel) - DE	20211018T000000
0117	novamobil (previously: Norma) - DE	20211018T000000
0118	blauworld (Ortel) - DE	20211018T000000
0119	Tchibo Mobilfunk GmbH & Co KG - DE	20211018T000000
0120	Mobilka - DE	20211018T000000
0121	Aldi Talk - DE	20241018T000000
0201	Vivo - BR	20211018T000000
0202	Terra - BR	20211018T000000
0301	Movistar - AR	20211018T000000
0302	Tuenti - AR	20211018T000000
0401	Movistar - ES	20211018T000000
0402	Tuenti - ES	20211018T000000
0403	O2 - ES	20211018T000000
0501	O2 - GB	20211018T000000
0502	GiffGaff - GB	20211018T000000
0601	Movistar - CL	20211018T000000
0701	Movistar - CO	20211018T000000
0801	Movistar - MX	20211018T000000
0901	Movistar - PE	20211018T000000
1001	Movistar - UY	20211018T000000
1101	Movistar - VE	20211018T000000
1201	Movistar - EC	20211018T000000
1202	Tuenti - EC	20211018T000000
10000	Other - Unknown	20211018T000000

Brands by environment

List of brands defined in Kernel D_Gbl_Brand global dimension entity organized by environment.

ap-* environments

Channels for ap-* environments.

ID	Brand	Date
0101	O2 (Germany) GmbH & Co - DE	20211018T000000
0103	Blau - DE	20211018T000000
0201	Vivo - BR	20211018T000000
0401	Movistar - ES	20211018T000000
0403	O2 - ES	20211018T000000
0501	O2 - GB	20211018T000000
10000	Other - Unknown	20211018T000000

es-* environments

Channels for es-* environments.

ID	Brand	Date
0401	Movistar - ES	20211018T000000
0403	O2 - ES	20211018T000000
10000	Other - Unknown	20211018T000000

br-* environments

Channels for br-* environments.

ID	Brand	Date
0201	Vivo - BR	20211018T000000
10000	Other - Unknown	20211018T000000

de-* environments

Channels for de-* environments.

ID	Brand	Date
0101	O2 (Germany) GmbH & Co - DE	20211018T000000
0103	Blau - DE	20211018T000000
10000	Other - Unknown	20211018T000000

Docs:

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

Aura Configuration API TV Section definition

Description of Aura configuration API TV Section swagger

Download swagger file

Docs:

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

Aura configuration API component module

Component module description for aura-configuration-api

Introduction

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

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

Components will be automatically loaded with Aura deployments.

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/components/
aura-services/v2/configuration/components/{name}

Endpoints

Path	Method	Description
/components/	GET	Get all components information
/components/	POST	Add a new component
/components/{name}	GET	Get component information using name
/components/{name}	DELETE	Delete component information using name

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

Retrieving information from components

Retrieving only some fields in component information

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

Response example:

[
    {
        "id": "ab09f8af-18e2-46ed-b103-934df78277c0",
        "name": "aura-bot",
    }
]

Excluding fields in components information

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

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/components?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": "ab09f8af-18e2-46ed-b103-934df78277c0",
        "name": "aura-bot"
    }
]

Database

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

Docs:

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

Contact channels management

List of available Telefónica contact channels defined in Kernel

Introduction

The aura-configuration-api is responsible for the management of the different Telefónica contact channels for the identification of Aura channels.

These contact channels are defined in Kernel within the D_Gbl_Contact_Channel global dimension entity.

The current document shows the available ones and the identifier, description and date for each of them.

Available contact channels

List of contact channels defined in Kernel D_Gbl_Contact_Channel global dimension entity.

ID	Contact Channel	Date
1	OnLine (Website)	20220210T000000
2	Mobile App (Novum)	20220210T000000
3	Telephone (Voice)	20220210T000000
4	SMS	20220210T000000
5	MMS	20220210T000000
6	EMAIL	20220210T000000
7	WhatsApp	20220210T000000
8	Shop	20220210T000000
9	Facebook	20220210T000000
10	Facebook Messenger	20220210T000000
11	Twitter	20220210T000000
12	Instagram	20220210T000000
13	Tik Tok	20220210T000000
14	Social Network	20220210T000000
15	White Mail	20220210T000000
16	TV	20220210T000000
17	Distributor	20220210T000000
18	Partner	20220210T000000
19	Logistics	20220210T000000
20	Task force	20220210T000000
100	Other	20220210T000000

Contact channels by environment

List of contact channels defined in Kernel D_Gbl_Contact_Channel global dimension entity organized by environment.

ap-* environments

Channels for ap-* environments.

ID	Channel	Date
1	OnLine (Website)	20220210T000000
2	Mobile App (Novum)	20220210T000000
3	Telephone (Voice)	20220210T000000
7	WhatsApp	20220210T000000
9	Facebook	20220210T000000
10	Facebook Messenger	20220210T000000
16	TV	20220210T000000

es-* environments

Channels for es-* environments.

ID	Channel	Date
1	OnLine (Website)	20220210T000000
2	Mobile App (Novum)	20220210T000000
3	Telephone (Voice)	20220210T000000
7	WhatsApp	20220210T000000
16	TV	20220210T000000

br-* environments

Channels for br-* environments.

ID	Channel	Date
1	OnLine (Website)	20220210T000000
2	Mobile App (Novum)	20220210T000000
7	WhatsApp	20220210T000000
9	Facebook	20220210T000000
10	Facebook Messenger	20220210T000000
16	TV	20220210T000000

de-* environments

Channels for de-* environments.

ID	Channel	Date
1	OnLine (Website)	20220210T000000
2	Mobile App (Novum)	20220210T000000
9	Facebook	20220210T000000
10	Facebook Messenger	20220210T000000

Docs:

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

Aura Configuration API Agent definition

Description of Aura configuration API Agent swagger

Download swagger file

Docs:

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

Aura Configuration API Agent base definition

Description of Aura configuration API Agent base swagger

Download swagger file

Docs:

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

Aura configuration API engine filter plugin

Engine filter API plugin description for aura-configuration-api

Introduction

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

All these services are defined in the routing-filters namespace (/routing-filters).

Servers definition

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

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

Examples:

aura-services/v2/configuration/routing-filters/summary/{filterType}
aura-services/v2/configuration/routing-filters/{filterId}/items/{itemId}

Endpoints

Path	Method	Description
/routing-filters/summary/{filterType}	GET	Get all summary for filter by type.
/routing-filters/entities/files	POST	Add entity data to engine filter.
/routing-filters/{filterId}/items/{itemId}	GET	Obtain the elements that have fulfilled the given filter for an itemId.

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

Engine filters steps

When a filter has been created, it is associated to one or more entities. Each time data is uploaded from a service for one of these entities, this data is also uploaded to the dataFilterCollection via the /routing-filters/entities/files endpoint.
This data is stored in the filter’s raw data collection and is periodically processed to obtain the summaries that are stored in the filter’s dataSummaryCollection.
This processing period is defined by the AURA_ROUTING_FILTER_SUMMARY_GENERATION_INTERVAL environment variable which defaults to 30 seconds. Note that data that has been summarized in previous processes is no longer processed again. An example of raw data could be the following:

{
    "seqId" : 1758107048147.0,
    "itemId" : "NsPjrmwbT-WJSlgImZ9NKg",
    "year" : 2025,
    "month" : 8,
    "day" : 13,
    "fieldForMatch" : "MESSAGE",
    "valueForMatch" : "{\"type\":\"suggestion\",\"value\":{\"intent\":\"intent.core-dialogs.ping\",\"entities\":[]}}",
    "expiresAt" : "2025-09-17T11:05:37.147+0000"
},
{
    "seqId" : 1758107048147.0,
    "itemId" : "IN-ewXp7S8u4mL0RlKJStA",
    "year" : 2025,
    "month" : 8,
    "day" : 13,
    "fieldForMatch" : "MESSAGE",
    "valueForMatch" : "{\"type\":\"tv.init.type\",\"value\":{\"intent\":\"tv.init\",\"entities\":[{\"type\":\"tv.init.type\",\"value\":\"post_start\",\"score\":1}]}}",
    "expiresAt" : "2025-09-17T11:05:37.147+0000"
},
{
    "seqId" : 1758107048147.0,
    "itemId" : "fh-71N2FRGKyXL-bCzhQkQ",
    "year" : 2025,
    "month" : 8,
    "day" : 13,
    "fieldForMatch" : "MESSAGE",
    "valueForMatch" : "Poner subtítulos",
    "expiresAt" : "2025-09-17T11:05:37.147+0000"
}
....

And an example of the data already grouped would be:

...
{
    "itemId" : "alrBKOZzQ1CYVHLZ70k6GQ",
    "month" : 8,
    "year" : 2025,
    "expiresAt" : "2025-09-17T11:06:08.069+0000",
    "total" : 3,
    "updatedAt" : "2025-09-17T11:04:39.069+0000"
},
{
    "itemId" : "aQLB8B3vQ6COn7s6caLpew",
    "month" : 8,
    "year" : 2025,
    "expiresAt" : "2025-09-17T11:06:08.070+0000",
    "total" : 12,
    "updatedAt" : "2025-09-17T11:04:39.070+0000"
},
{
    "itemId" : "OcjR3z8lQU-DnFpHV1W1qQ",
    "month" : 8,
    "year" : 2025,
    "expiresAt" : "2025-09-17T11:06:08.071+0000",
    "total" : 1,
    "updatedAt" : "2025-09-17T11:04:39.071+0000"
}
...

When the grouped data is generated, a cache is generated in memory containing the ItemId that match the filter, this is necessary to improve performance when querying items to see if they match a given filter.

Retrieving information from engine filters

Check if a user matches a filter

You can validate whether a user matches a certain filter, and if so, whether they have a predetermined action to perform.

curl --location 'http://aura-configuration-api:8999/aura-services/v2/routing-filters/[FILTER_ID]/items/[ITEM_ID] ' \
--header 'correlator: 1a25aac1-d5fa-42af-9930-3e5706288cea' \
--header 'Authorization: SECRET_API_KEY' \
--header 'Accept: application/json' \

Response example:

{
    "value": false,
    "actions": []
}

Retrieving specific fields from engine filter information

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

curl --location 'http://aura-configuration-api:8999/aura-services/v2/routing-filters/summary/userId ' \
--header 'correlator: 1a25aac1-d5fa-42af-9930-3e5706288cea' \
--header 'Authorization: SECRET_API_KEY' \
--header 'Accept: application/json' \

Response example:

[
   {
    "data": {
        "preset-filter-conversational-search-es": {
            "data": [
                {
                    "month": 8,
                    "itemId": "ksRuPPkRS4ax0IdaZdoFHA",
                    "year": 2025,
                    "total": 40
                },
                {
                    "month": 8,
                    "itemId": "alrBKOZzQ1CYVHLZ70k6GQ",
                    "year": 2025,
                    "total": 120
                },
                {
                    "month": 8,
                    "itemId": "bk3iI3GwQWO2-4YI0etc0w",
                    "year": 2025,
                    "total": 40
                },
                {
                    "month": 8,
                    "itemId": "DYoM_OOPSZ-EMNxiFxWe4w",
                    "year": 2025,
                    "total": 40
                }
            ],
            "actions": [
                {
                  "type": "CUSTOM_MESSAGE",
                  "params": {
                    "intent": "internal.send.custom.message",
                    "entities": [{
                        "type": "message",
                        "value": "core:limit.exceed.llm"
                    }]
                }
            ]
        }
    }
}
]

Database

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

Docs:

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

Aura configuration API routing filter plugin

Routing filter plugin description for aura-configuration-api

Introduction

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

All these services are defined in the routing-filters namespace (/routing-filters).

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/routing-filters
aura-services/v2/configuration/routing-filters/{filterId}

Endpoints

Path	Method	Description
/routing-filters/	GET	Get all routing filters information
/routing-filters/	POST	Add a new routing filter
/routing-filters/{filterId}	GET	Get routing filter information using filter id
/routing-filters/{filterId}	PUT	Replace routing filter information associated to filter id
/routing-filters/{filterId}	PATCH	Update some fields of routing filter information using filter id
/routing-filters/{filterId}	DELETE	Delete routing filter information using filter id
/routing-filters/entities	GET	Get all entities associated with routing filters

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

Database for routing filters data

A database will be created, if it does not exist, to add the necessary collections for the filters to work. The database name is set in the environment variable AURA_ROUTING_FILTERS_DATA_DB and has as default value routing-filters-data-ENV.

Filters collections

Each filter has two collections associated with it, one for the raw data, which can be shared with other filters, and one for the summaries. These collections are created when the filter is created, and are deleted when the filter is deleted. The shared collection will only be deleted if there are no filters using it. The names for these collections are within the filter model.

......
    "dataBase": {
        "dataFilterCollection": {    <---- Raw Data
            "collectionName": "dataFilterTest",
            "expiration": 5184000,         <-- seconds to expire data
            "indexes": [
                { 
                 "seqId": 1 
                }
            ]
        },
        "dataSummaryCollection": {  <---- Summary Data>
            "collectionName": "dataSummaryTest",
            "expiration": 5184000,        <-- seconds to expire data
            "indexes": [
                { 
                 "itemId": 1 
                },
                {
                    "total": 1,
                    "month": 1,
                    "year": 1
                }
            ]
        }
    }
.....

Collections must have an expiration time so that the data does not remain permanently in Mongodb. The value of the expiration field is set to seconds. If create indexes is needed, these can be defined in “indexes” property.

Retrieving information from routing filters

Retrieving specific fields from routing filter information

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

Response example:

[
    {
        "id": "b6340f13-34af-4891-8a88-22bdffe9485b",
        "name": "UserId_LLM_Limits"
    }
]

Excluding fields in filters information

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

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/routing-filters?excludeFields=name,vars,match,metadata,applyFilter, fields, sourceFilters,summary,summaryFilter' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX'

Response example:

[
    {
        "id": "b6340f13-34af-4891-8a88-22bdffe9485b",
        "description": "Limit the number of messages per user in a month for triage preset",
        "type": "userId",
        "entities": [
            "GATEWAYMESSAGE"
        ],
        "dataBase": {
            "dataFilterCollection": {
                "collectionName": "dataFilterTriage",
                "expiration": 89
            },
            "dataSummaryCollection": {
                "collectionName": "dataSummaryTriage",
                "expiration": 89
            }
        }
    }
]

Database

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

Docs:

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

Aura configuration API skill module

Skill module description for aura-configuration-api

Introduction

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

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

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/skills/
aura-services/v2/configuration/skills/{skillId}

Endpoints

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

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

Retrieving information from skills

Retrieving only some fields in skill information

It is possible to get only a specific list of fields for skill 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/skills?includeFields=name,skillEndpoint' \
--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": "aura-bot-skill-1",
        "skillEndpoint": "http://localhost:8081/api/messages"
    },
    {
        "id": "71b626d0-099f-4184-8abb-b035d3aa4b16",
        "name": "aura-bot-skill-2",
        "skillEndpoint": "http://localhost:8082/api/messages"
    }
]

Excluding fields in skills information

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

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/skills?excludeFields=skillEndpoint,metadata' \
--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": "aura-bot-skill-1",
        "apiId": "45494a5b-835a-4fff-a813-b3d2be529asd",
        "channels": ["whatsapp"]
    },
    {
        "id": "71b626d0-099f-4184-8abb-b035d3aa4b16",
        "name": "aura-bot-skill-2",
        "appId": "71b626d0-099f-4184-8abb-b035d3aa4f45",
        "channels": ["novum"]
    }
]

Database

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

Docs:

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

Aura configuration API application module

Application module description for aura-configuration-api

Introduction

The application module defines services associated with the management of applications in aura-configuration-api server. Applications are external services that consume Aura services.

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

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/applications/
aura-services/v2/configuration/applications/{applicationId}

Endpoints

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

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

Application model

Below are the main fields of the application model according to the swagger:

Field	Type	Description
id	string	Unique identifier of the application
name	string	Name of the application
brand	string	Brand associated with the application
nlp	object	NLP configuration (optional)
models	object	Models configuration (optional)
metadata	object	Additional metadata (optional)
agents	string[]	List of agent identifiers associated with the application
suggestions	array	Suggestions associated with the application (optional)

Note: The agents field is an array of strings containing the identifiers of the agents associated with the application. The agents referenced must exist in the system to be inserted. If an agent is deleted, all applications referencing it will be updated accordingly.

Example response (GET /applications/{applicationId})

{
  "id": "962fedef-ee1b-470f-b460-b2a78e02bb36",
  "name": "aura-sql",
  "brand": "Movistar",
  "agents": [
    "agent-1",
    "agent-2"
  ],
  "suggestions": [
    {
      "id": "1",
      "category": "suggestions.number-of-households-per-province-category",
      "value": "suggestions.number-of-households-per-province-value"
    }
  ]
}

Example request (POST /applications)

{
  "id": "new-app-id",
  "name": "new-app",
  "brand": "Movistar",
  "agents": ["agent-1", "agent-2"]
}

Retrieving information from applications

Retrieving only some fields in application information

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

Response example:

    {
        "id": "8832550f-f03c-4e18-bdbe-7c6fc7adf5ff",
        "name": "app",    
        "brand": "Movistar",
    },
    {
        "id": "8832550f-f03c-4e18-bdbe-7c6fc7adf5fg",
        "name": "app2",    
        "brand": "O2",
    }

Excluding fields in applications information

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

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

Response example:

    {
        "id": "8832550f-f03c-4e18-bdbe-7c6fc7adf5ff",
        "name": "app",
        "disabled": false,
        "brand": "Movistar",
        "agents": [],
        "nlp": {
            "channelId": "1234"
        },
        "models": {
            "level": "user",
            "presets": ["atria-rag-gpt-4"]
        }
    }

Database

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

Docs:

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

Aura Configuration API server

aura-configuration-api is the component of Aura in charge of handling and centralizing configuration tasks.
Find in the current documents the description of this component, its architecture, components and processes.

Shared component between Aura Virtual Assistant and ATRIA

Introduction

aura-configuration-api is the component in charge of the management of all the configuration tasks in Aura. It is mainly a web server built on Typescript 4.3 using nodejs as engine. It is api-first designed, using OpenAPI v3 to provide the API definition.

aura-configuration-api server is divided into several modules and plugins, each of them managing different tasks, which are:

Modules

Administration: Administrative management module for general tasks such as exporting and importing configuration.
Channel: Module in charge of managing the configuration of each Aura channel as well as the libraries associated with each channel (replacement for the bot-response.json configuration file).
Skill: Module in charge of managing the configuration of each skill.
Application: Module in charge of managing the configuration of each application.
Component: Module in charge of managing the configuration of each Aura component.

Plugins

Preset: Module in charge of managing the configuration of each preset.
Tv section: Module in charge of managing the configuration of each tv section.
Suggestion: Module in charge of managing the configuration of each suggestions.
Agent: Module in charge of managing the configuration of each agents.
Agent base: Module in charge of managing the configuration of each agents base.
Agent deployment: Module in charge of managing the configuration of each agents deployment.
Routing filter: Module in charge of managing the configuration of each routing filters.
Filter engine: Module in charge of managing filters engine.

Detailed information regarding aura-configuration-api is found in the following documents:

Aura configuration API architecture and components

The following figure shows the main components of the aura-configuration-api.

Server

The web server is implemented using express, which is the main web framework for NodeJS. It uses openapi-backend on top of express, to allow handling the OpenAPI v3 file.

It is in charge of setting up all the rest of the components that are needed during a request processing, as well as reading the aforementioned swagger file and setting up all the routes defined in it.

Middlewares

Each route published in the API definition file is handled by a controller, but before a request lands on its controller, it goes through a series of middlewares that provide some common steps needed by all the controllers of the server.

The following middlewares are executed at each request to the server:

Normal flow

helmet: Secure express app by setting various HTTP headers.
body-parser (urlencoded): It parses URL-encoded bodies using querystring parsing (qs).
body-parser (json): Maximum size of JSON body (current 50 MB).
set-correlator: It sets the correlator to response header and response locals.
log-http-request-response: Log HTTP request and response information.
express-prom-bundle: It saves metrics information using Prometheus.
oas_tools (swaggerMetadata): It interprets swagger resources and attaches metadata to request.
oas_tools (swaggerValidator): It validates requests using swagger definition.
oas_tools (swaggerRouter): It routes validated requests to appropriate controller.
oas_tools (swaggerUi): It serves the swagger documents and Swagger UI.
not-found-handler: It handles requests that have not been routed (Not Found).

Error flow

error-handler: Global error handler.

Controllers & Services

When the previous step is finished, the request lands on the controller. Each controller processes the request through a service, that is in charge of implementing the logic. Once the request has been processed, the controller prepares and sends the response.

There is a controller to manage requests associated with the server itself (generic controller) and a controller for each module, in charge of handling the requests of that module.

The event synchronization service can be enabled by setting the AURA_CONFIGURATION_EVENTS_ENABLED configuration variable to true.

Generic controller

As indicated above, the generic controller handles requests to provide information from the state of the server itself.

healthz: It is used to check if the server is online returning a simple status response: {"status": "ok"}.
metrics: It gets Prometheus metrics information.
heapStatistics: It gets memory usage information.
heapSnapshot: It gets memory head snapshot from v8 engine.
shutdown: Service to be invoked mainly by Kubernetes and allows to do a server graceful shutdown.

Modules controller

The controllers and services information of each module is described in the Modules section.

aura-configuration-api server is divided into several modules and plugins, each of them managing different tasks, which are:

Modules

Administration: Administrative management module for general tasks such as exporting and importing configuration.
Channel: Module in charge of managing the configuration of each Aura channel as well as the libraries associated with each channel (replacement for the bot-response.json configuration file).
Skill: Module in charge of managing the configuration of each skill.
Application: Module in charge of managing the configuration of each application.
Component: Module in charge of managing the configuration of each Aura component.

Access here detailed information of aura-configuration-api modules

Plugins

Preset: Plugin in charge of managing the configuration of each preset.
TV section: Plugin responsible for the management of TV sections.
Suggestion: Plugin responsible for the management of suggestions.
Agent: Plugin in charge of managing the configuration of each agent.
Agent base: Plugin in charge of managing the configuration of each agent base.
Agent Deployment: Plugin responsible for managing the deployment of agents.
Routing filter: Plugin responsible for managing the routing filters.
Engine filter: Plugin responsible for managing the engine filter.

Access here detailed information of aura-configuration-api plugins

Database access

Most aura-configuration-api services access aura-configuration database to get or set the information of each module.

This database is a MongoDB one, with a collection for each module that stores information related to that module. To access this collection, the server implements a data access object with the queries needed by the services. This object follows the DAO (Data Access Object) pattern that provides a single access to the database, isolating the services from the real database schema and internals implementation.

Communication protocol

aura-configuration-api communication protocol is completely synchronous, this means that the answer of a request is included in the HTTP response related to the request.

Docs:

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

Aura Configuration APIs definition

Description of API swaggers for Aura Configuration

Introduction

The following API swaggers are available in aura-configuration-api:

Aura – 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:

Aura Configuration API definition

Docs:

Aura Configuration API environment variables

Docs:

Preset plugin

Introduction

Servers definition

Endpoints

Retrieving information from presets

Retrieving specific fields from preset information

Excluding fields in presets information

Database

Docs:

Synchronization by events

Introduction

Using Redis as Event Manager

Publishers and subscribers

Channel

Event Message

Publishers

Generate events

Subscribers

Using DAPR as Event Manager

Publishers and subscribers

Channel

Event Message

Publishers

Generate events

Example of `metadata`: