coms-consume-roan

Paquete de Python que consulta tickets (incidentes) del webservice SOAP COMS de CA ServiceDesk y los inserta en la base de datos MySQL automcae mediante stored procedures. Pensado para ejecutarse agendado (Control-M), sin intervención manual, en un servidor con acceso a la red interna / VPN.

Tabla de contenido

• ¿Qué hace?
• Arquitectura del paquete
• Requisitos
• Instalación
• Configuración de credenciales
• Flujo de ejecución
• Uso
• Logs
• Tests
• Build y publicación
• Estado actual / notas importantes
• Licencia
• Autor

¿Qué hace?

1. Se conecta al webservice SOAP consulta_tck_complete de ServiceDesk (COMS) y trae los incidentes del grupo Diagnostico Enlaces y Equipos dentro de una ventana de tiempo.
2. Filtra los tickets por categoría permitida (enlaces, redes regionales, satelital, PBX de hardware).
3. Clasifica cada ticket:
   • RE (resuelto) → tabla talistincidente (o talistincidente_pbx si el resumen empieza con PBX).
   • OP (abierto) → tabla talistincidente_val (o talistincidente_pbx si es PBX).
4. Inserta los tickets vía stored procedures (sp_inslistincidente, sp_inslistincidente_val, sp_inslistincidente_pbx).
5. Lleva un control de ejecuciones (tabla de control) para saber qué rango de horas ya se consultó y si la ejecución fue exitosa.

Arquitectura del paquete

coms_consume_roan/
├── main.py                    # Orquestador: RequestTicketsWS (nocturno / diurno)
├── config/
│   └── database.py            # Conexión pymysql, resuelve credenciales al conectar
├── secure/
│   └── secure.py               # Cifrado/descifrado de credenciales (access.txt -> credentials.enc)
├── src/
│   ├── consumo_coms.py         # SoapIntegracionComs: consulta SOAP + clasificación + insert
│   └── exceptions/
│       └── exceptions.py       # CredentialsNotFoundError
├── data/
│   ├── dto/
│   │   └── dto_database.py     # DatabaseIncidenteDTO (dataclass, mapea columnas del SP)
│   └── dao/
│       └── dao_db.py           # DatabaseIncidenteDAO, DatabaseConexionesDAO, DatabaseConexionesControlM, DatabaseEjecutarSP
└── utils/
    └── utils.py                # Cálculo de timestamps (zona America/Mexico_City) y normalización de datos

Dependencias propias del autor (no en PyPI público general): secure-credentials-roan (cifrado de credenciales) y w-log-roan (logging estandarizado).

Requisitos

• Python 3.10 o superior.
• Acceso a la base de datos MySQL automcae y al WSDL de ServiceDesk: requiere estar dentro de la red interna / VPN.
• Los stored procedures (sp_inslistincidente*, sp_selsdbuscatck, sp_seltacontrolejecucionescoms, sp_updtacontrolejecucionescoms, sp_updresetcntlejec) ya deben existir en la base de datos.
• Permisos de escritura en C:\logs\ (rutas de log fijas, ver sección Logs).

Instalación

pip install coms-consume-roan
pip install --index-url https://{username}:{password}@gitea.example.com/api/packages/{owner}/pypi/simple --no-deps {package_name}

Configuración de credenciales

La conexión a la base de datos no usa variables de entorno para host/usuario/password: usa un archivo cifrado en disco.

1. Crear un archivo access.txt con este formato:

   host=...
   user=...
   password=...
   database=...
   port=...
   

2. Colocarlo en el directorio de datos seguros (ver variable de entorno abajo).
3. Al ejecutar el paquete por primera vez, access.txt se cifra automáticamente en credentials.enc + secret.key (en el mismo directorio) y el access.txt original se borra.
4. En ejecuciones posteriores, las credenciales se descifran en memoria cada vez que se abre una conexión (no se cachean en disco en texto plano).

Variable de entorno COMS_SECURE_DATA_DIR

Define dónde viven access.txt / credentials.enc / secret.key. Si no se define, se usa secure_data/ anclado a la raíz del proyecto (solo válido para desarrollo local, no para una instalación vía pip en site-packages).

$env:COMS_SECURE_DATA_DIR = "C:\ruta\a\secure_data"

Recomendado: definir esta variable de entorno de forma permanente en el servidor donde se agenda el proceso (Control-M), apuntando a una ruta segura fuera del propio paquete instalado.

Flujo de ejecución

El paquete expone dos rutinas dentro de RequestTicketsWS (main.py):

• call_connWS_nocturno(): pensado para la ejecución agendada por Control-M (3 veces al día).
  1. DatabaseConexionesControlM.get_tabla_ejecuciones() consulta el SP sp_seltacontrolejecucionescoms y obtiene el número de ejecución (noEjec) y el rango de horas a consultar (horaInic, horaFin).
  2. Se calcula el rango de timestamps: la hora de inicio se toma del día anterior y la hora de fin del día actual (zona horaria America/Mexico_City, convertida a UTC/unix).
  3. Se llama a SoapIntegracionComs().consulta_tck_complete(...), con hasta 10 reintentos si falla.
  4. Según la respuesta, se marca la ejecución como exitosa (1) o fallida (0) vía DatabaseConexionesControlM.update_control_ejecuciones().
• call_connWS_diurno(): variante que usa el timestamp actual y una ventana fija de 30 minutos hacia atrás (get_current_timestamp / get_timestamp_minus_30_minutes), en vez de la tabla de control de ejecuciones.

Dentro de consulta_tck_complete (consumo_coms.py):

1. Arma los parámetros de búsqueda del SOAP (CAOpenDateInit, CAOpenDateFinal, CAGroup, etc.) y llama al WSDL obtenido previamente vía DatabaseConexionesDAO.get_url_buscar_tck() (SP sp_selsdbuscatck).
2. Parsea la respuesta JSON (UDSObjectList).
3. Por cada ticket: valida categoría permitida (allow_categories), mapea atributos al DTO (llenar_DTO_multiple), detecta si es PBX (check_pbx_status, regex ^PBX en el resumen) y clasifica por estado (RE / OP).
4. Inserta en lote por tabla (insert_data_incidente, insert_data_incidente_op, insert_data_incidente_pbx), cada inserción usa una variable de sesión MySQL @paerror para validar si el SP tuvo éxito.

Uso

Instalado, expone el comando de consola:

coms-consume

Equivalente en desarrollo (sin instalar el paquete):

python -m coms_consume_roan.main

Nota: este comando reemplaza al antiguo python main.py. Si el proceso está agendado en Control-M, hay que actualizar el comando invocado.

Logs

Cada módulo escribe su propio log bajo C:\logs\<módulo>\<módulo>_AAAAMMDD.log, con una subcarpeta errors\ para los mensajes de nivel error. Módulos con log propio: main, consumo_coms, database, secure, dao_db. Ruta no configurable actualmente (fija en cada archivo fuente).

Tests

Pruebas unitarias con unittest en tests/. Todas las conexiones externas (BD, WS SOAP, cifrado de credenciales) están mockeadas — no requieren VPN, BD real ni access.txt.

python -m unittest discover -s tests -v

Build y publicación

python -m build
twine check dist/*
twine upload dist/*

Estado actual / notas importantes

• La función main() del entry point (coms-consume) actualmente solo instancia RequestTicketsWS() y registra el log de inicio; no invoca call_connWS_nocturno() ni call_connWS_diurno() automáticamente. Si se desea que Control-M dispare el flujo completo, se debe ajustar main() para llamar al método correspondiente según el horario de ejecución.
• Las categorías de ticket permitidas están hardcodeadas en SoapIntegracionComs.allow_categories() (enlaces, redes regionales, satelital, hardware router/switch PBX); cualquier ticket fuera de esas categorías se descarta silenciosamente.
• El paquete depende de dos librerías propias del autor no publicadas en el índice público de PyPI: secure-credentials-roan y w-log-roan.

Licencia

MIT License. Ver archivo LICENSE.

Autor

Angel Rogelio Argonza Roblero