Metadata-Version: 2.4
Name: coms-consume-roan
Version: 0.1.4
Summary: Paquete para consumir tickets del webservice COMS de ServiceDesk e insertarlos en base de datos
Author: Angel Rogelio Argonza Roblero
License-Expression: MIT
Keywords: python,coms,servicedesk,soap,tickets
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: zeep>=4.3
Requires-Dist: pytz>=2024.1
Requires-Dist: pymysql>=1.1
Requires-Dist: requests>=2.31
Requires-Dist: urllib3>=2.0
Requires-Dist: secure-credentials-roan>=0.1.1
Requires-Dist: w-log-roan>=0.1.2
Dynamic: license-file

# 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?](#qué-hace)
- [Arquitectura del paquete](#arquitectura-del-paquete)
- [Requisitos](#requisitos)
- [Instalación](#instalación)
- [Configuración de credenciales](#configuración-de-credenciales)
- [Flujo de ejecución](#flujo-de-ejecución)
- [Uso](#uso)
- [Logs](#logs)
- [Tests](#tests)
- [Build y publicación](#build-y-publicación)
- [Estado actual / notas importantes](#estado-actual--notas-importantes)
- [Licencia](#licencia)
- [Autor](#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](#logs)).

## Instalación

```bash
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`).

```powershell
$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:

```bash
coms-consume
```

Equivalente en desarrollo (sin instalar el paquete):

```bash
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`.

```bash
python -m unittest discover -s tests -v
```

## Build y publicación

```bash
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](LICENSE).

## Autor

Angel Rogelio Argonza Roblero
