Documentación del Proyecto: Anubis Modular

Versión 1.0 - Estado al 06 de Octubre de 2025

Introducción

Anubis Modular es un orquestador de automatización diseñado para ejecutar flujos de trabajo en la plataforma BMC Helix ITSM. Su objetivo principal es eliminar tareas manuales repetitivas, mejorar la eficiencia y asegurar la consistencia en los procesos de gestión de incidentes.

La arquitectura del sistema es modular y declarativa, lo que permite definir, configurar y extender nuevas automatizaciones de forma rápida y sencilla sin necesidad de modificar el núcleo del sistema.

Arquitectura del Sistema

El sistema se compone de varios módulos clave que trabajan en conjunto. El orquestador es el cerebro que coordina el trabajo, mientras que los flujos, conectores y acciones definen qué hacer y cómo hacerlo.

graph TD subgraph "Fuentes de Datos" A[API Externa] B[Archivo .csv/.txt] C[Base de Datos] end subgraph "Anubis Core" D[Conectores] --> E{Orquestador} F["Definiciones de Flujo (\.js)"] --> E E -- Crea Job --> G["Cola de Trabajos (Job Queue)"] H[Worker] -- Obtiene Job --> G H -- Ejecuta Pasos --> I[Acciones] end subgraph "Módulos de Soporte" J[Browser Manager] <--> I K[Database Manager] <--> E K <--> H L[Logger] <--> E L <--> H L <--> I M[Notification Manager] <--> H end subgraph "Sistemas Externos" N[BMC Helix ITSM] O[Microsoft Teams] end subgraph "Entrada Alternativa" P[API Server] -- Crea Job --> G end I -- Interactúa con --> N M -- Envía Notificación --> O A --> D B --> D C --> D

Componentes Principales

Orquestador (orchestrator.js): Es el corazón del sistema. Opera con un modelo de Scheduler/Worker.
- El Scheduler se ejecuta a intervalos regulares, consulta las fuentes de datos a través de los Conectores y, si encuentra nuevos ítems, crea "Jobs" (trabajos) y los añade a la cola.
- El Worker toma trabajos de la cola uno por uno, ejecuta la secuencia de pasos definida en el Flujo correspondiente y gestiona el ciclo de vida del job (RUNNING, COMPLETED, FAILED).

Flujos (src/flows/): Son archivos JavaScript que definen una automatización completa de manera declarativa. Cada flujo especifica qué conector usar para obtener los datos y una lista de pasos (acciones) a ejecutar.

// Ejemplo de un flujo simple (testFindINC.js)
export default {
    name: "prueba repetir busqueda inc",
    enabled: false,
    dataSource: {
        connector: "mockDataConnector",
        config: { filePath: "./prueba-manual.csv" }
    },
    steps: [
        { type: "navigate", url: "..." },
        { type: "findAndNavigateToIncident", inc: "{{inc}}" },
        { type: "screenshot" },
    ]
};

Conectores (src/connectors/): Módulos responsables de obtener y parsear datos de diversas fuentes (APIs, archivos de texto, etc.). Transforman los datos brutos en un formato estandarizado que el orquestador puede procesar. Cada ítem debe tener una idempotencyKey para evitar duplicados.
Acciones (src/actions/): Son las unidades de trabajo más pequeñas y reutilizables. Cada acción es una función que encapsula una interacción específica con la página web usando Playwright (ej: click.js, fill.js, findAndNavigateToIncident.js).
Módulos Core (src/core/): Proporcionan servicios transversales esenciales:
- browserManager.js: Gestiona la instancia del navegador y la sesión de login en Remedy, asegurando que siempre haya una sesión válida para los jobs.
- databaseManager.js: Administra la base de datos SQLite (anubis.db) para registrar todos los jobs, su estado y gestionar la idempotencia.
- notificationManager.js: Centraliza el envío de notificaciones a Microsoft Teams.
- logger.js: Sistema de logging robusto que crea archivos de log por flujo y para el sistema en general.
API Server (src/api/apiServer.js): Un servidor Express que expone un endpoint (/jobs) para gatillar flujos de trabajo de forma remota mediante peticiones HTTP.

Estado Actual del Proyecto

El proyecto se encuentra en un estado funcional, con las capacidades esenciales implementadas y operativas.

Completado Funcionalidades Esenciales

Núcleo del Orquestador: El ciclo Scheduler/Worker es estable y procesa trabajos de la cola de manera secuencial.
Sistema de Flujos, Acciones y Conectores: La arquitectura modular funciona correctamente. Es posible agregar nuevos flujos, acciones y conectores sin modificar el núcleo.
Gestión de Sesión: El browserManager maneja el login y la persistencia de la sesión de Remedy de forma robusta.
Persistencia y Logging: Todos los trabajos son registrados en la base de datos, y la ejecución de cada flujo genera logs detallados.
Notificaciones Básicas: El sistema notifica a Teams el resultado (éxito/fallo) de cada job.

Implementado Parcialmente Gatillado de Flujos por API

El servidor API (apiServer.js) está implementado y es capaz de recibir peticiones para crear nuevos trabajos.

Qué funciona: El endpoint POST /jobs puede crear un job en la base de datos y encolarlo para su procesamiento por el worker.
Qué falta: Aunque existe un middleware de autenticación (auth.js), la integración completa y la estrategia de gestión de tokens con los sistemas clientes necesita ser robustecida y documentada. El uso práctico de la API aún no está extendido.

Puntos de Mejora Oportunidades Identificadas

Control de Notificaciones: El sistema actual notifica todo. Sería ideal tener un control más granular para definir qué notificar, cómo (formato) y cuándo (solo en fallos, siempre, etc.), posiblemente configurable desde la definición del flujo.
Observabilidad: Actualmente, el estado se revisa a través de logs y la base de datos. La creación de un dashboard web simple que lea de anubis.db proporcionaría una visión rápida y centralizada del estado de los jobs, errores y rendimiento.
Disponibilidad de Datos: La información generada por Anubis (qué se procesó, cuándo, resultados) es valiosa. Se podría crear un mecanismo para exportar estos datos y disponibilizarlos como un dataset para la plataforma de monitoreo "MOBS Smart Table".

Funcionalidades Implementadas

Basado en los flujos definidos en src/flows/, Anubis actualmente puede realizar las siguientes tareas de forma autónoma:

sequenceDiagram participant C as Conector participant O as Orquestador participant W as Worker participant B as BMC Helix participant T as Teams C->>O: Provee lista de incidentes O->>W: Encola y despacha Job (ej. INC123) W->>B: Navega y busca INC123 W->>B: Ejecuta acciones (ej. agrega nota) W->>T: Notifica "Éxito en INC123"

Flujos de Trabajo Activos

Procesamiento de Notas y Estado de Incidentes (processIncidentNoteAndStatus.js)
Este flujo lee un archivo con resultados de llamadas a clientes, busca cada incidente en Remedy, y agrega una nota de trabajo con los detalles de la llamada. Si el incidente está "Resuelto" y el cliente confirma el cierre, el flujo intenta avanzar el estado a "Cerrado".
Categorización Automática de Incidentes BREDS (categorizacionBREDs.js)
Para incidentes de tipo BRED, este flujo navega a la pestaña "Telco", extrae información clave (TS1-TS2), la cruza con un dataset de tipos de servicio, y rellena automáticamente la categorización y la nota de resolución con la información más probable antes de guardar el incidente.
Cambio de Motivo de Estado (changeStatusToNoContact.js)
Un flujo específico que lee una lista de incidentes y un motivo de estado deseado (ej. "Op - Sin Contacto con Cliente"). Para cada uno, busca el incidente y actualiza su "Motivo del estado" (Status Reason) al valor especificado, automatizando cambios masivos.

Roadmap y Próximas Funciones

A continuación se proponen las próximas mejoras y funcionalidades para futuras versiones de Anubis Modular.

Propuestas a Corto Plazo

Finalizar API:
- Definir y documentar formalmente los endpoints y sus payloads.
- Estabilizar el mecanismo de autenticación y autorización.
- Crear un endpoint adicional GET /jobs/{jobId} para consultar el estado de un trabajo.
Módulo de Notificaciones v2:
- Permitir configurar el comportamiento de las notificaciones dentro de la definición del flujo (ej. notifyOn: 'failure').
- Soportar plantillas de mensajes más complejas para incluir más datos del job en las notificaciones.

Propuestas a Mediano/Largo Plazo

Dashboard de Observabilidad:
Crear una pequeña aplicación web (puede ser otro contenedor o un simple HTML) que se conecte a anubis.db y muestre en tiempo real:
- Estado de los últimos jobs (cola, en progreso, fallidos, completados).
- Estadísticas de ejecución por flujo (tiempo promedio, tasa de error).
- Un visor de logs simplificado para los jobs fallidos.
Integración con MOBS Smart Table:
Diseñar y construir un "conector de salida" que periódicamente lea los resultados de los jobs de la base de datos y los envíe o exponga en el formato requerido por MOBS Smart Table, convirtiendo a Anubis en una fuente de datos para el monitoreo.
Refactorización y Limpieza:
El código en las carpetas deprecated/ y referencias/ (anubis-general.js, etc.) representa la versión anterior del sistema. Se debe planificar una revisión para asegurar que toda la lógica útil ha sido migrada al nuevo modelo modular y luego eliminar el código antiguo para simplificar el proyecto.

Apéndice: Estructura de Archivos

Una visión general de la organización del código fuente del proyecto.

anubis-modular/
├── logs/                 # Archivos de log generados por el sistema y flujos
│   └── screenshots/      # Capturas de pantalla automáticas (ej. en errores)
├── src/                  # Código fuente principal de la aplicación
│   ├── actions/          # Módulos de acciones reutilizables (ej. click, fill)
│   ├── api/              # Lógica del servidor API (Express)
│   ├── connectors/       # Módulos para obtener datos de diferentes fuentes
│   ├── core/             # Módulos centrales (orquestador, logger, db, etc.)
│   ├── flows/            # Definiciones de los flujos de trabajo
│   ├── config.js         # Configuración centralizada (lee .env)
│   └── orchestrator.js   # El orquestador principal (scheduler y worker)
├── tests/                # Scripts de prueba para funcionalidades específicas
├── .env                  # Variables de entorno (credenciales, URLs) - NO versionar
├── index.js              # Punto de entrada de la aplicación
├── anubis.db             # Base de datos SQLite
└── package.json          # Dependencias y scripts del proyecto