Conceptos
Casi toda configuración del CMS combina los mismos pocos objetos. Entender esa cadena resuelve la mayor parte de las dudas de uso.
Aplicación
Representa un sistema integrado (ERP, MES, WMS, balanza, PLC…). Tiene una sigla corta — usada en las URL y en los informes — y es la unidad de agrupación del sistema: interfaces, definiciones, tokens, alertas e informes siempre se organizan por Aplicación.
La Aplicación también es la unidad de monitoreo de disponibilidad: el CMS verifica en ciclos su conexión (keep-alive), registra los períodos online/offline y genera el informe de uptime.
El selector en la parte superior define la Aplicación en foco: al elegir una, las pantallas muestran solo lo que le pertenece, y esa elección acompaña la navegación.
Las herramientas de tickets (Help Desk) también son Aplicaciones, de una categoría propia. Aparecen en Interfaces, Definición de Mensaje y en los filtros de Mensajes, pero quedan fuera del selector de Aplicación en foco y de los registros de la planta.
Interfaz
Una interfaz de procesamiento. Define cómo se consumen los mensajes de ese flujo:
- Orden secuencial — un mensaje a la vez, preservando el orden de llegada.
- Paralelo — varios mensajes simultáneos, con concurrencia configurable.
La Interfaz puede ser bloqueada (manualmente o de forma automática por una regla de error de negocio). Mientras está bloqueada, los mensajes siguen entrando pero no se entregan — lo que evita disparar cientos de errores contra un sistema destino que ya se sabe indisponible.
Definición de Entrega
El contrato de entrega: a dónde va el mensaje y cómo.
Tipo de entrega
Define el protocolo usado para entregar el mensaje en el destino:
| Tipo | Qué hace |
|---|---|
HTTP_POST | Envía el payload por POST al endpoint del destino — el caso más común |
HTTP_PUT | Envía por PUT, para API REST que esperan sustitución del recurso |
HTTP_PATCH | Envía por PATCH, para actualización parcial del recurso |
HTTP_DELETE | Llama al endpoint por DELETE, para eliminar el recurso |
HTTP_SOAP | Arma y envía el envelope SOAP al web service del destino |
MQTT_PUBLISH | Publica el payload en un tópico del broker MQTT |
SQL_SERVER_EXEC | Ejecuta un comando o procedure en el SQL Server destino |
ORACLE_EXEC | Ejecuta un comando o procedure en el Oracle destino |
POSTGRES_EXEC | Ejecuta un comando en el PostgreSQL destino |
SQLITE_EXEC | Ejecuta un comando en la base SQLite de destino — el archivo .db de la conexión |
INFLUXDB_WRITE | Graba puntos en una serie temporal del InfluxDB destino |
MONGODB_WRITE | Graba el mensaje como documento en una colección de MongoDB — insertando, o actualizando un documento existente |
SAP_RFC_CALL | Llama a un módulo de función / BAPI en SAP con los datos del mensaje |
OPC_UA_WRITE | Escribe valores en tags de un servidor OPC UA (pasa por el gate de escritura) |
MODBUS_WRITE | Escribe valores en registros Modbus TCP (pasa por el gate de escritura) |
PI_WEB_API_WRITE | Escribe valores en tags del PI System (AVEVA/OSIsoft) |
SPARKPLUG_CMD | Publica un comando en el namespace Sparkplug B, sobre la misma conexión MQTT |
FILE_WRITE | Graba el contenido en un archivo del directorio configurado en la conexión |
Campos comunes a todos los tipos
| Campo | Qué define |
|---|---|
| Sigla | Identificador de la definición, único en todo el sistema — no solo en la Interfaz. Entra en la URL de recepción, así que cambiarla después rompe a quien ya integra |
| Aplicación e Interfaz | A quién pertenece la definición y por cuál interfaz pasan los mensajes |
| Tipo de mensaje | ASSINCRONA — persiste, encola y responde al instante; SINCRONA — espera la respuesta del destino antes de responder a quien llamó |
| URL de recepción | Dirección pública generada para esta definición: POST /api/{sigla-de-la-interfaz}/{sigla-de-la-definicion} |
| Content-Type | Cabecera usada en el envío al destino (por defecto application/json) |
| Validar Content-Type | Activado, rechaza el mensaje cuyo content-type no corresponde al esperado |
| Encoding | Codificación del cuerpo enviado (por defecto UTF-8) |
| Tamaño máximo del payload | Límite aceptado en la recepción; por encima de eso el mensaje se rechaza |
| Decodificación del mensaje | Convierte el cuerpo antes de procesar: NENHUM, BASE64, XML_UNESCAPED, URL_ENCODED, HEX, CHARSET_LATIN1, HTML_ENTITIES |
| Transformador | Script aplicado al payload antes de la entrega (opcional) |
| Modelo de Contenido | Texto con {{alias}} que reemplaza el payload como contenido entregado (opcional). Resuelve contra la salida del Transformador |
| Timeout de envío | Segundos de espera por la respuesta del destino antes de considerar falla (por defecto 30) |
| Máximo de reintentos | Cuántas veces repetir una falla técnica (por defecto 3). Entre intentos el sistema espera 10 segundos |
| Credencial de destino | Credencial usada para autenticar la llamada de salida |
| Reenviar respuesta | Activado, devuelve a quien llamó la respuesta que retornó el destino |
| Activar WebService (WSDL) | Publica el endpoint SOAP con WSDL dinámico para esta definición |
| WS-Security en el Header | Acepta autenticación por UsernameToken en el envelope SOAP |
| Exponer como tool MCP | Deja que un agente de IA llame a esta Entrega, por el Servidor MCP de integraciones |
| Activo | Apaga la definición sin borrarla — deja de recibir mensajes |
Campos por tipo de entrega
| Tipo | Campos específicos |
|---|---|
HTTP_POST · HTTP_PUT · HTTP_PATCH · HTTP_DELETE | Host de destino y URI que componen la dirección llamada |
HTTP_SOAP | Host de destino, URI y SOAP Action del web service |
MQTT_PUBLISH | QoS — 0 (como máximo una vez) o 1 (al menos una vez). El broker viene de la conexión de la aplicación de destino |
SQL_SERVER_EXEC · ORACLE_EXEC · POSTGRES_EXEC · SQLITE_EXEC | Comando SQL ejecutado en la base destino. Los placeholders :payload, :datetime y :transformer se convierten en parámetros bindeados, nunca en texto concatenado |
SAP_RFC_CALL | Nombre de la función/BAPI, mapeo de los parámetros IMPORT y TABLES, el payload de entrada esperado (con campos obligatorios) y commit tras la llamada — muchas BAPI de escritura exigen commit explícito |
OPC_UA_WRITE | Tags de escritura (alias → NodeId), y el gate opcional: tag y valor de disparo que liberan la escritura, además del valor grabado después de escribir |
MODBUS_WRITE | Tags de escritura (alias → tabla y dirección), y el gate opcional: tabla, dirección y valor de disparo, además del valor grabado después de escribir |
PI_WEB_API_WRITE | Tags de escritura (alias → ruta en el PI), origen del timestamp (ahora o un campo del payload) y el modo de escritura |
INFLUXDB_WRITE | Measurement, mapeo de las columnas (cada alias se vuelve tag o field), precisión, origen del timestamp y el bucket de destino |
MONGODB_WRITE | Colección de destino, modo de grabación (insertar uno, insertar por lote, actualizar o crear, solo actualizar), los campos de la clave en los modos que coinciden con documento existente, y el campo de fecha de grabación |
FILE_WRITE | Ruta del archivo dentro del directorio base, modo de escritura (crear nuevo o anexar), encoding y escritura atómica |
SPARKPLUG_CMD | Grupo, Edge Node y Device del namespace, y las métricas del comando (alias → nombre y tipo de la métrica) |
En las tags de escritura, el productor del mensaje envía un objeto plano {alias: valor} — no
necesita conocer los NodeId ni las direcciones internas del PLC, solo los alias configurados aquí.
Cada mensaje puede traer solo un subconjunto de los alias: se graba lo que venga.
Definición de Recolección
El espejo de la Definición de Entrega para el sentido inverso: en vez de esperar que alguien envíe, el CMS va a buscar el mensaje.
Tipo de recolección
Define de dónde y cómo se obtiene el dato:
| Tipo | Qué hace |
|---|---|
HTTP_GET / HTTP_POST | Llama a un endpoint externo en un intervalo programado |
MQTT_TOPIC_SUBSCRIBER | Se suscribe a un tópico MQTT y reacciona a cada publicación |
SQL_SERVER / ORACLE / POSTGRES / SQLITE | Ejecuta una consulta y convierte el resultado en mensajes |
SAP_RFC | Llama a un módulo de función / BAPI en SAP |
SAP_IDOC | Recibe IDocs enviados por SAP |
OPC_UA_TRIGGER | Observa una tag OPC UA y dispara cuando cambia |
MODBUS_TRIGGER / MODBUS_POLL | Observa un cambio o recorre registros Modbus TCP |
INFLUXDB | Ejecuta una consulta Flux, InfluxQL o SQL en una serie temporal |
MONGODB | Lee documentos de una colección por filtro (find) o pipeline (aggregate) |
SPARKPLUG_SUBSCRIBER | Se suscribe a un namespace Sparkplug B y recibe nacimientos y cambios de métrica |
PI_WEB_API | Lee tags del PI System: valor actual, histórico, interpolado o resumen |
FILE_WATCH | Observa un directorio y convierte en mensaje cada archivo que llega |
Campos comunes a todos los tipos
| Campo | Qué define |
|---|---|
| Sigla | Identificador de la recolección, único en todo el sistema. Entra en la URL de la API dinámica de recolección |
| Aplicación e Interfaz | A quién pertenece la recolección y por cuál interfaz pasa el resultado |
| Reenvíos | Las Interfaces/Definiciones de destino a donde sigue el payload recolectado. Una recolección puede alimentar varios destinos a la vez |
| Parámetros de entrada | Campos que un productor externo puede enviar a POST /api/collect/{interfaz}/{recoleccion}, y que la recolección usa para armar la búsqueda. Con ellos, la recolección pasa a correr bajo demanda |
| Activar WebService (WSDL) | Publica la misma API dinámica también en SOAP, en la operación ExecutarColeta. Exige parámetros de entrada |
| Exponer como tool MCP | Deja que un agente de IA ejecute esta recolección, por el Servidor MCP de integraciones. Exige parámetros de entrada |
| Transformador | Script aplicado al payload recolectado, antes del reenvío (opcional) |
| Máximo de reintentos | Cuántas veces repetir una falla (por defecto 3), con 10 segundos entre ellas |
| Activo | Apaga la recolección sin borrarla — detiene la programación o la suscripción |
| Resultado de la última ejecución | Estado, hora y mensaje de error de la última búsqueda. Solo aplica a los tipos pull: los tipos por evento tienen estado de conexión en tiempo real |
La periodicidad de los tipos pull pertenece a la Interfaz (intervalo en milisegundos o expresión cron), no a la Recolección. Encender, apagar y ejecutar al instante están en la pantalla Programadores.
Campos por tipo de recolección
| Tipo | Campos específicos |
|---|---|
HTTP_GET · HTTP_POST | URL de origen, parámetros fijos, template de payload (en el POST), credencial de origen, content-type de envío y timeout de la recolección (por defecto 30 s) |
MQTT_TOPIC_SUBSCRIBER | Conexión externa del broker, tópico suscrito y QoS |
SQL_SERVER · ORACLE · POSTGRES · SQLITE | Conexión externa, query SELECT, modo de resultado, columna clave y comando posterior a la recolección — el comando que marca como leído lo que se acaba de traer |
SAP_RFC | Conexión externa, nombre de la función/BAPI, mapeo de los parámetros IMPORT y TABLES, y las variables de entrada que vienen de afuera |
SAP_IDOC | Conexión externa (el listener) y los filtros de tipo de IDoc, tipo de mensaje y socio, que deciden cuáles IDocs recibe esta recolección |
OPC_UA_TRIGGER | Conexión externa, NodeId y valor de disparo que activan la recolección, tags de lectura (alias → NodeId) y el reset tras la lectura — valor grabado de vuelta en la tag de disparo para “consumir” la señal |
MODBUS_TRIGGER · MODBUS_POLL | Conexión externa, tabla, dirección y valor de disparo, tags de lectura (alias → tabla y dirección), intervalo de barrido, reset tras la lectura y emitir solo si cambió |
INFLUXDB | Conexión externa, consulta, lenguaje (Flux, InfluxQL o SQL) y el bucket/database de esta recolección |
MONGODB | Conexión externa, operación (find o aggregate), colección, filtro o pipeline en JSON, proyección, orden, límite de documentos, formato del payload y el comando pos-recolección que marca los documentos leídos |
SPARKPLUG_SUBSCRIBER | Conexión externa (el broker), grupo, Edge Node y Device suscritos, y si solicita rebirth al conectar |
PI_WEB_API | Conexión externa, tags leídos, modo de lectura (valor actual, histórico, interpolado o resumen), ventana de tiempo, intervalo y el modo de emisión |
FILE_WATCH | Conexión externa (el directorio base), subcarpeta, máscara de archivo, encoding, modo de emisión y la acción tras la lectura — mover, renombrar o dejar como está |
El modo de resultado de las consultas SQL decide la granularidad:
LINHA_UNICA_PAYLOAD_UNICO (todo el resultado se convierte en un mensaje) o UMA_LINHA_POR_PAYLOAD
(cada fila se convierte en un mensaje independiente).
Transformador
Script JavaScript ejecutado en sandbox (node:vm dentro de worker_threads, en un pool
aislado) que recibe el payload y devuelve otro: JSON ↔ XML, remapeo de campos, cálculo de agregados.
El mismo Transformador es reutilizable en Definiciones de Entrega y en Recolecciones. Puede escribirse a mano en el editor Monaco o generarse con IA a partir de un ejemplo de entrada, uno de salida y un prompt — con historial de generaciones y aprobación explícita antes de entrar en uso.
En una Entrega que recibe de varios sistemas en formatos distintos, cada Aplicación productora puede tener un Transformador propio, que convierte el formato de ella al de la Entrega y se ejecuta antes del Transformador de la Entrega — ver Transformador por Aplicación productora.
Conexión Externa
Datos de conexión reutilizables, con botón de probar conexión. Recolecciones y Entregas apuntan a una Conexión en vez de repetir host/puerto/usuario en cada configuración.
| Categoría | Tipos disponibles |
|---|---|
| Bases de datos | SQL Server, Oracle, PostgreSQL (incluye TimescaleDB), SQLite, InfluxDB, MongoDB (incluye Atlas, Azure Cosmos DB y AWS DocumentDB) |
| Planta | OPC UA, MQTT (incluye Sparkplug B), Modbus TCP, PI Web API |
| SAP | SAP RFC / BAPI, SAP IDoc, SAP Gateway (OData), SAP CPI (Cloud Integration) |
| Archivos | Directorio monitoreado y grabado |
El tipo de la conexión vinculada a la Aplicación define qué tipos de Recolección y de Entrega quedan
disponibles en ella — una Aplicación con conexión MongoDB, por ejemplo, solo ofrece Recolección
MONGODB y Entrega MONGODB_WRITE.
Variables
Valores reutilizables que entran por {{nombre}} en las configuraciones de Recolecciones, Entregas
y Transformadores — direcciones, códigos de centro, nombres que cambian de un ambiente a otro.
Existen en dos alcances: Globales (valen en todo el CMS) y Por Aplicación (valen solo dentro
de ella). Cuando el mismo nombre existe en los dos, vale el valor de la Aplicación.
Sirven para sacar de cada configuración lo que cambia entre ambientes: lo que difiere de desarrollo a producción queda en un solo lugar, en vez de disperso por decenas de definiciones.
Credencial
Credenciales de autenticación usadas en las llamadas de salida (HTTP/SOAP): basic, bearer, token en header, WS-Security. Quedan cifradas en reposo y nunca son reexhibidas por la API.
Las integraciones REST puras no necesitan un adaptador dedicado: use HTTP_GET/HTTP_POST +
Credencial + Transformador. Los adaptadores nativos (SAP, OPC UA, Modbus, MongoDB…) existen solo
porque esos protocolos no son HTTP.
Cómo se conecta todo
Aplicación (MES)
└── Interfaz (MES_PALLET) ← orden, concurrencia, bloqueo
├── Definición (AnyToMES_Pallet) ← destino, timeout, reintentos, transformador
│ ├── Credencial ← cómo autenticar en el destino
│ └── Transformador ← cómo convertir el payload
└── Recolección (SAP_ProdOrder) ← origen externo + reenvíos
└── Conexión Externa ← host/puerto/usuario de SAP, MQTT, OPC UA…