Tags:
Categories:

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"
        }
    }
Last modified May 18, 2026: Remove KGB (52b04d91)