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.

El paquete maneja dos BDs de forma independiente (automcae y diurno), cada una con su propia subcarpeta dentro del directorio de datos seguros:

SECURE_DATA_DIR/
├── automcae/
│   ├── access.txt        (se borra tras cifrar)
│   ├── credentials.enc
│   └── secret.key
└── diurno/
    ├── access.txt        (se borra tras cifrar)
    ├── credentials.enc
    └── secret.key

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

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

2. Colocarlo en la subcarpeta correspondiente (SECURE_DATA_DIR/automcae/ o SECURE_DATA_DIR/diurno/), según la BD que se quiera configurar. Ambos access.txt son independientes entre sí.
3. Al ejecutar el paquete por primera vez, cada access.txt se cifra automáticamente en credentials.enc + secret.key (dentro de su misma subcarpeta) 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).

Nota: si ya tenías un access.txt en la raíz de secure_data/ (layout anterior a la separación por BD), debes recifrarlo manualmente en la subcarpeta automcae/ — no hay migración automática.

Variable de entorno COMS_SECURE_DATA_DIR

Define el directorio raíz que contiene las subcarpetas automcae/ y diurno/. 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