Ciclo EGO ↔ iVAN Risk

Simulacion completa: calcular ruta → callback → crear paquete → callback → resultado

Guia del ciclo EGO

Cada paso del proceso explicado — que hace, a donde llama y que datos maneja.

1
Resolver unidad
Convierte el nombre de unidad (ej. HS334) a su ID numerico en GPSGate.
Destino: [iVAN Risk API] GET /api/v1/units/lookup
2
Calcular ruta
Envia origen y destino a iVAN Risk. El servidor calcula la ruta con Valhalla, la densifica (~10k vertices), analiza los riesgos contra los poligonos de municipios en la BD (colores, niveles, distancias). Responde 202 con un job_id (async) o 200 con el resultado completo (idempotencia).
Destino: [iVAN Risk API] POST /api/v1/rutas/calcular
3
Callback ruta
iVAN Risk notifica al webhook de EGO que la ruta esta lista. El payload incluye: route_geojson (todos los vertices), risk_summary (municipios con nombre, nivel, color, distancia), distancia_km, tiempo_min, riesgo_max.
Origen: [iVAN Risk → EGO] POST /api/ivanrisk/webhook (HMAC firmado)
4
Crear paquete
EGO envia el route_geojson y risk_summary (recibidos en el callback) a iVAN Risk para crear el paquete de monitoreo. iVAN Risk genera: UUID, codigo QR, iframe_token, tiles offline. Responde 202 con job_id. Internamente inicia el sync de custom fields a GPSGate.
Destino: [iVAN Risk API] POST /api/v1/rutas/paquete
5
Callback paquete
iVAN Risk notifica que el paquete esta listo. El payload incluye: uuid, codigo, qr_url, iframe_token, tiles_url. Con estos datos EGO puede mostrar el iFrame de monitoreo y el QR.
Origen: [iVAN Risk → EGO] POST /api/ivanrisk/webhook (HMAC firmado)
6
Sync Custom Fields (GPSGate)
Escribe los campos personalizados en la unidad de GPSGate Server1: ivanrisk_uuid, ivanrisk_token, ivanrisk_activo=true. El Click Script de GPSGate lee estos campos para saber que iFrame abrir al hacer click derecho en la unidad.
Destino: [GPSGate Server1] PUT .../users/{unit_id}/customfields
7
Geocerca (Monitoreo Dedicado)
Crea una geocerca tipo Route en GPSGate Server1 con el corredor completo (~10k vertices, radius 500m). GPSGate monitorea desviaciones en tiempo real. Se activa manualmente (el desarrollador de EGO decide cuando iniciar/terminar el monitoreo).
Destino: [GPSGate Server1] POST/DELETE .../geofences

Datos de la ruta

Si se deja vacío, no hay cálculo temporal.
Define si se sugiere segmentar la ruta por descanso.
🛡️ Reglas de Viaje — Evaluación de seguridad

Cargando catálogo de reglas...

🔒 Enforcement = si la regla dispara, el paquete se BLOQUEA. Sin enforcement, la regla solo informa. Sin selección, no se evalúa nada.

Guia de integracion GPSGate Server1

Para integrar iVAN Risk con GPSGate, se requiere configurar una vez lo siguiente:

1. Credenciales Server1 en iVAN Risk

El administrador del tenant debe ingresar a https://ivanrisk.madd.com.mx/admin/clientes y llenar:

  • Usuario API — usuario GPSGate con permisos API
  • Password API — contraseña del usuario
  • App IDs — ID de la aplicación en Server1 (separados por coma)

Sin esto, el sync de custom fields y geocercas fallara.

2. Crear Custom Fields en GPSGate (Assets)

En la ventana de Activos (Assets) de GPSGate, donde se listan los vehiculos:

  • Menu hamburguesa (3 barras) > Administrar campos personalizados
  • Agregar 3 campos tipo Texto: ivanrisk_uuid, ivanrisk_token, ivanrisk_activo

Para activarlos en la plantilla:

  • Menu hamburguesa > Editor de Tipos
  • Seleccionar "Dispatch unit" > Detalles
  • Palomear ✓ ivanrisk_uuid, ivanrisk_token, ivanrisk_activo
  • Guardar

iVAN Risk escribe estos campos via API al crear un paquete (sync automatico). El Click Script los lee para saber que iFrame abrir.

3. Click Script (Right-Click Menu)

En GPSGate, menu hamburguesa (izq superior) >

  • Administracion > Desarrollador > Diseñador de apps
  • Click en boton +App
  • Nombre: IvanRisk
  • Roles: _Administrator, _Dispatch Worker, _Driver, _Operator
  • Click Scripts > boton + Click Script
  • Nombre: IvanRisk, Tipo: UserRightClickMenu, Activado: Yes
  • Click Editar y pegar el script:
var uuid = user.getCustomFieldValue('ivanrisk_uuid');
var token = user.getCustomFieldValue('ivanrisk_token');
var activo = user.getCustomFieldValue('ivanrisk_activo');

if (activo !== 'true' || !uuid || !token) {
    log("iVAN Risk: no hay paquete activo");
} else {
    var url = "https://ivanrisk.madd.com.mx/iframe/monitor/" + uuid
            + "?token=" + encodeURIComponent(token)
            + "&style=google";
    ui.iframe("ivanrisk_monitor", "iVAN Risk - " + user.name,
              url, 1200, 200, 500, 300);
}
  • Click Ejecutar script para validar
  • Click Save
  • Click Guardar (app)
4. Geocercas de Riesgo Municipal — Grupo IVAN-RISK

Para que las alertas de entrada a municipios de alto riesgo funcionen, se requiere configurar una vez en GPSGate Server1:

  • Crear Event Rule: Event Rules → + Regla

Paso 1. Nombre de la regla y descripción

Nombre Ingreso a Municipio de Alto Riesgo IVAN-RISK
Descripción Alerta visual y notificación cuando una unidad en ruta ingresa a un municipio clasificado como de alto riesgo por iVAN Risk.

Paso 2. A quién aplica la regla

Aplica a En Ruta — todos los trackers asignados a una ruta activa

Paso 3. Calendario de actividad

Calendario Siempre activa

Paso 4. Expresiones

Tipo Expresiones de Geocerca
Grupo IVAN-RISK
Condición Dentro (evento inmediato)

Paso 5. Notificaciones

Hay DOS tipos de notificación que configurar en esta sección:

A. Icono + Texto — alerta visual en la tabla de monitoreo

La notificación de tipo "Icono" dispara la alerta visual en la UI de GPSGate. La de tipo "Texto" con el mismo encabezado se fusiona en la misma columna.

Configuración de Icono
Encabezado Riesgo Municipal
Icono ⚠️ Advertencia (Mostrar opciones avanzadas → seleccionar warning)
Configuración de Texto
Encabezado Riesgo Municipal (mismo que arriba para fusionar columna)
Texto activa Dejar vacío — el mensaje real va en el Paso 6

B. ExternalNotification — webhook HTTP a RODOX

Agregar un segundo notificador: Comando → Configurar servidor → ExternalNotification → http. Esta es la que dispara el diagnóstico automático en RODOX.

ExternalNotification → http
URL https://rodox.madd.com.mx/runners/bridge?runner_type=callback&instance_id=5&flow_id=2&callback_url=https://ivanrisk.madd.com.mx/results
Método GET (GPSGate agrega todos los parámetros dinámicos al query string)

⚠️ Importante: NO agregues parámetros manualmente a la URL. GPSGate los añade automáticamente: RULE_NAME, EVENT_TIME, POS_LATITUDE, POS_LONGITUDE, POS_SPEED, USER_USERNAME, IMEI, APP_ID, y todos los Custom Fields del Asset como SIGNAL_* (ej: SIGNAL_IVANRISK_UUID, SIGNAL_IVANRISK_TOKEN, SIGNAL_IVANRISK_ACTIVO).

📋 Prerrequisito: Los Custom Fields deben existir en Assets → Manage Custom Fields y tener valores asignados en los vehículos/usuarios. Además, la Expression ivanrisk_activo = true del Paso 4 garantiza que la regla solo dispare para unidades con monitoreo activo y que GPSGate incluya los SIGNAL_* en el webhook.

Paso 6. Presentación en mapa y Panel de Eventos

Aquí se configuran los mensajes dinámicos que leerá el monitorista usando las variables de la plataforma. Usa el botón Insert o Latest de GPSGate para insertar las variables de forma segura.

Texto activo
(entrada)		 🚨 Unidad entró en zona de riesgo: [GEOFENCE_NAME] — Tracker: [USER_DISPLAYNAME] — [POS_TIME]
Texto inactivo
(salida)		 ✅ Unidad salió de zona de riesgo: [GEOFENCE_NAME]

Paso 7. Flujo de diagnóstico RODOX (automatismo)

Con la configuración anterior, el ciclo completo de diagnóstico es:

1. Unidad entra a geocerca GPSGate evalúa Expression: ¿ivanrisk_activo = true? Si no → no dispara.
2. Event Rule dispara GPSGate construye URL con todos los SIGNAL_* y envía GET a RODOX.
3. RODOX recibe Lee SIGNAL_IVANRISK_UUID del query string → lookup key al paquete.
4. RODOX consulta GET /api/v1/monitoreo/{uuid}/contexto → ruta, riesgo, municipios.
5. RODOX diagnostica Tracker (GPRS/SMS) + contexto iVAN Risk → veredicto: ✅ normal / ⚠️ indeterminado / 🚨 emergencia.
6. Escalamiento Solo si 🚨 emergencia → Voice Alert al monitorista. Si ⚠️ → notificación push.

¿Por qué funciona automáticamente? iVAN Risk crea geocercas vía API con "groups": ["IVAN-RISK"] y escribe los Custom Fields ivanrisk_uuid, ivanrisk_token, ivanrisk_activo en la unidad. Al terminar el monitoreo, borra las geocercas y limpia los custom fields. La regla nunca se toca — solo cubre lo que esté en el grupo y las unidades con ivanrisk_activo = true. [GEOFENCE_NAME] se expande a "Riesgo MUY ALTO - Fresnillo - TKT-12345".

⚠️ Notas: (1) Si en tu pantalla de GPSGate el formato de variable usa corchetes [ ] en lugar de llaves { }, usa el formato que muestre el botón Insert. (2) Los Custom Fields deben existir en Assets → Manage Custom Fields antes de asignarles valor. (3) Verificar en el Swagger de Server1 el nombre exacto del campo para asignar grupo (groups, geofenceGroups, o groupName). (4) La URL de ExternalNotification no debe tener parámetros dinámicos manuales — GPSGate los agrega solo.

Resumen: las credenciales se configuran en el admin de iVAN Risk (paso 1). La Application y Custom Fields en GPSGate Server1 (paso 2). El Click Script en GPSGate (paso 3). El ciclo EGO de arriba automatiza el sync de custom fields (fase 5). La geocerca (fase 6) se maneja con POST/DELETE cuando se active el monitoreo dedicado. Este simulador es el ejemplo de referencia para tu integracion.