Plugin Moodle

El plugin local_ssea es el puente entre tu Moodle y SoftSys Edu Analytics. Observa 15 eventos estándar de Moodle, los encola y los envía de forma resiliente al backend de SSEA.

Prerequisites

• Moodle 4.1 o superior (recomendado 4.5+).
• PHP 7.4+ (alineado con los requisitos de Moodle 4.x).
• Acceso de administrador en Moodle.
• Credenciales de tenant proporcionadas por SoftSys Solutions:
  • Tenant ID (UUID)
  • API key (formato ssea_ + 32 caracteres hex)
• Egress HTTPS permitido desde tu servidor Moodle hacia ingest.softsysanalytics.com y api.softsysanalytics.com.

Instalación

Opción A — Zip (recomendado)

1. Descarga el último local_ssea.zip del canal de release acordado con SoftSys Solutions (los clientes reciben acceso al paquete por el canal de soporte).

2. En Moodle, ve a Administración del sitio → Plugins → Instalar plugins.

3. Sube el archivo ZIP.

4. Sigue el asistente de instalación.

5. Cuando termine, completa la configuración inicial (siguiente sección).

Opción B — Manual

1. Copia el directorio del plugin dentro de <moodle_root>/local/ssea/.

   Precaución

   El directorio debe llamarse exactamente ssea, no local_ssea. La ruta final debe ser <moodle_root>/local/ssea/.

2. Ajusta permisos al usuario del servidor web (en Debian/Ubuntu típico):

   sudo chown -R www-data:www-data <moodle_root>/local/ssea

3. Visita https://<tu_moodle>/admin/index.php — Moodle detectará el plugin y ejecutará la migración de base de datos.

4. Completa la configuración inicial.

Configuración

Recomendado — OAuth 2.0 en un clic (plugin v0.3.0+)

Desde la versión 0.3.0 el plugin soporta conexión OAuth 2.0 Authorization Code. Un solo botón, cero credenciales a mano, con firma CSRF state y binding del redirect_uri al host de Moodle.

Ve a /local/ssea/connect.php (o Administración del sitio → Plugins → Plugins locales → SSEA Analytics → Connect) y haz click en “Connect to SoftSys Edu Analytics”.

1. El plugin genera un state (32 bytes random) y te redirige a https://app.softsysanalytics.com/connect/moodle con el state + redirect_uri + moodle_url.

2. Si no has iniciado sesión en el dashboard, entras con Google o API Key. El ?next= preserva tu intención a través del login.

3. Pantalla de consentimiento — muestra el host de Moodle que solicita la conexión. Si no reconoces la URL, presiona Cancel.

4. Click Allow. El dashboard:

   • Genera una api_key nueva (scope ingest+read) + un viewer_shared_secret per-tenant.
   • Guarda el payload en KV con TTL 120s bajo un authorization_code opaco.
   • Redirige tu navegador a <moodle>/local/ssea/connect_callback.php?code=…&state=….

5. El plugin valida el state con hash_equals, hace un POST server-to-server a /v1/oauth/moodle/token para redimir el código, y persiste los 7 configs necesarios (api_key, viewer_shared_secret, tenant_id, api_url, ingest_url, connection_id, connected_at).

6. Verás ”✓ Successfully connected”. El plugin queda listo — las credenciales nunca pasaron por tu navegador.

Consejo

Reconexión / rotación: el mismo botón te permite hacer Reconnect — genera credenciales frescas, revoca las anteriores, y el plugin se reconfigura automáticamente. Útil si sospechas compromiso de una key.

Nota

Por qué OAuth y no pegar API keys: el flujo antiguo (pegar api_key a mano en un form) dejaba a usuarios Google OAuth atrapados — no había lugar para generar la key. Además el viewer_shared_secret era un Cloudflare Worker secret write-only que nadie podía leer. OAuth resuelve ambos problemas: credenciales se generan server-side, se transfieren server-to-server, y se vinculan al host del Moodle por diseño.

Configuración manual (legacy — plugin < v0.3.0 o troubleshooting)

Si usas una versión antigua del plugin o necesitas overrides manuales:

Administración del sitio → Plugins → Plugins locales → SSEA Analytics

O directamente: /admin/settings.php?section=local_ssea

Ajustes obligatorios (manual)

Ajuste	Descripción	Ejemplo
Habilitado	Interruptor maestro del plugin	Sí
Server URL	Endpoint de ingesta de SSEA	https://ingest.softsysanalytics.com
API key	Clave API del tenant	ssea_abc123...
Tenant ID	UUID asignado por SoftSys	f47ac10b-58cc-...

Ajustes opcionales

Ajuste	Por defecto	Descripción
Delivery mode	batch	sync (inmediato), async (adhoc task), batch (cola DB)
Batch size	50	Eventos por batch (1–500)
Request timeout	5 s	Timeout HTTP
SSL verify	Sí	Solo desactivar en dev local con certificados inválidos
Debug logging	No	Log verbose en el debug log de Moodle
No enviar IP (no_ip)	No	Excluir IP del payload antes de enviar — útil para cumplir políticas internas estrictas
Use Meridian UI (use_meridian_ui)	1 fresh / 0 upgrade	Activa el layout admin rediseñado (v0.5.0+). Ver sección abajo.

Meridian UI (v0.5.0+)

A partir de v0.5.0 el plugin incluye un rediseño visual completo del área admin llamado Meridian: sidebar sub-nav de 212px, tipografía Inter Tight + JetBrains Mono, paleta verde petróleo sobre warm off-white, zero-radius, panels con borders colapsados. Todas las 6 páginas administrativas del plugin comparten el mismo shell:

• Overview (/local/ssea/overview.php) — 6 tiles que enlazan a cada sección con badge de estado
• Connection (/local/ssea/connect.php) — OAuth status + Tenant KV grid + Reconnect/Disconnect
• Settings (/local/ssea/settings_ui.php?section=settings) — master switch, event tracking, advanced (con chip “Advanced”)
• Data sync (/local/ssea/settings_ui.php?section=datasync) — configuración de bulk migration
• At-risk (/local/ssea/settings_ui.php?section=atrisk) — threshold + frecuencia de notificaciones
• Status (/local/ssea/status.php) — stat strip (enabled / pending / failed 24h / ingest) + config + tabla de errores + progress por dominio

Habilitar / deshabilitar Meridian

Controlado por local_ssea | use_meridian_ui:

• Instalaciones nuevas — el flag arranca en 1 (Meridian activo por defecto)
• Upgrades desde v0.4.x — el upgrade step 2026042120 lo setea en 0 (UI legacy preservada) para no romper flujos existentes; el admin lo activa cuando quiera

Para activar manualmente en un upgrade:

1. Administración del sitio → Plugins → Plugins locales → SSEA Analytics → Settings
2. Expandir la sección Advanced
3. Marcar “Use Meridian UI” y guardar
4. La próxima carga de cualquier página del plugin usa el nuevo layout

Si se presenta algún glitch visual (ej. el theme de Moodle overridea clases), se puede desactivar temporalmente reverting use_meridian_ui=0. El comportamiento de save/validation de settings es idéntico en ambos layouts — Meridian solo envuelve el render, toda la lógica va por admin_write_settings().

URLs legacy vs Meridian

Página	Legacy	Meridian
Overview	/admin/category.php?category=local_ssea_category	/local/ssea/overview.php
Settings	/admin/settings.php?section=local_ssea	/local/ssea/settings_ui.php?section=settings
Data sync	/admin/settings.php?section=local_ssea_datasync	/local/ssea/settings_ui.php?section=datasync
At-risk	/admin/settings.php?section=local_ssea_atrisk	/local/ssea/settings_ui.php?section=atrisk

Connection y Status usan la misma URL en ambos layouts — el switch se hace internamente según el flag. Las URLs legacy de Settings/Data sync/At-risk siguen funcionando siempre; si el admin tiene bookmarks apuntando a /admin/settings.php?section=... no se rompen.

Modos de entrega (delivery modes)

El plugin soporta tres modos de enviar eventos al ingest:

Batch (por defecto, recomendado)

Los eventos se escriben a la tabla local_ssea_queue y se envían en lotes cada 5 minutos por la scheduled task process_queue_task. Ofrece el mejor rendimiento y resiliencia: si el ingest está temporalmente caído, los eventos se acumulan de forma segura y se envían cuando se recupera.

Async (adhoc task)

Cada evento se encola como una adhoc task de Moodle y se entrega cuando el task runner de Moodle (cron.php) la procesa. Mejor UX que el modo sync (no añade latencia a las páginas), pero depende de la frecuencia del cron de Moodle.

Sync (inmediato)

Los eventos se envían directamente durante la request HTTP de Moodle. Simple pero añade latencia a cada página que dispara un evento. Solo recomendado para sitios de muy bajo tráfico o para debugging.

Consejo

Para producción, usa siempre batch. Es el modo con mejor equilibrio entre rendimiento, resiliencia y simplicidad operativa.

Eventos capturados

El plugin observa 15 eventos Moodle estándar: sesión, matrícula, navegación de cursos, visualización de recursos, intentos y envíos de quiz, entregas de tareas, posts de foro, calificaciones y completitud.

Ver el catálogo completo en Tipos de eventos.

Capabilities del plugin

El plugin declara cuatro capabilities de Moodle para controlar el acceso a sus vistas:

Capability	Descripción	Roles típicos
local/ssea:viewlearnerreport	Ver el reporte personal del learner	Student, Teacher, Manager
local/ssea:viewinstructorreport	Ver los reportes de instructor	Teacher, Manager
local/ssea:managesettings	Gestionar la configuración del plugin	Manager
local/ssea:viewreports	Ver reportes agregados de administración	Manager

Tareas programadas

El plugin registra dos scheduled tasks en Moodle:

Tarea	Clase	Frecuencia por defecto
SSEA: Process event queue	\local_ssea\task\process_queue_task	Cada 5 minutos (*/5 * * * *)
SSEA: Migrate Moodle data	\local_ssea\task\migrate_data_task	Diaria (deshabilitada por defecto — ver abajo)

La tarea de migración de datos sincroniza al backend el estado actual de usuarios, cursos, matrículas, actividades y calificaciones. Útil para pobla el dashboard con el histórico existente cuando instalas el plugin en un Moodle con contenido. Está deshabilitada por defecto — actívala cuando quieras ejecutar la sincronización inicial.

Para habilitarla:

Administración del sitio → Servidor → Tareas programadas → SSEA Migrate Data → Editar → Habilitar

Troubleshooting

No llegan eventos a SSEA

1. Verifica que el plugin está habilitado: Administración del sitio → Plugins → SSEA → “Habilitado: Sí”.

2. Prueba la conexión: la página de ajustes del plugin incluye un botón “Probar conexión”.

3. Revisa la cola: ejecuta (desde la UI de Moodle o la DB):

   SELECT COUNT(*) FROM mdl_local_ssea_queue WHERE status = 'pending';

4. Verifica que el cron de Moodle está corriendo. Sin cron, la tarea process_queue_task nunca se ejecuta y los eventos se acumulan. Desde consola:

   php admin/cli/cron.php

   O verifica tu crontab / systemd unit.

5. Revisa errores: Moodle Debug Log, y si el plugin tiene una tabla de errores:

   SELECT * FROM mdl_local_ssea_errors ORDER BY created_at DESC LIMIT 20;

Error 401 (API key rechazada)

• Verifica que la API key empieza con ssea_ y tiene la longitud correcta.
• Verifica que el Tenant ID coincide con el que te entregó SoftSys Solutions.
• Si sospechas que la clave fue revocada, contacta al equipo de soporte para que emitan una nueva.

Error 402 (cuota del plan excedida)

Tu tenant ha superado la cuota diaria de eventos de tu plan. Las opciones son:

• Esperar al reset de medianoche UTC.
• Hacer upgrade a un plan con mayor cuota. Ver Planes y límites.

Errores SSL en Moodle on-premise

Si tu servidor Moodle tiene un bundle de CAs desactualizado, la verificación TLS puede fallar contra Cloudflare. Actualiza el bundle de CAs del sistema:

sudo apt-get update && sudo apt-get install --only-upgrade ca-certificates

Solo como último recurso en entornos internos, puedes desactivar SSL verify en los ajustes del plugin. Nunca en producción pública.

La cola crece indefinidamente

1. Verifica que process_queue_task se está ejecutando: Administración del sitio → Tareas programadas.
2. Revisa los errores: SELECT * FROM mdl_local_ssea_errors WHERE error_type = 'delivery_failed' LIMIT 10;
3. Si el ingest está caído temporalmente, los eventos se acumulan sin perderse — se enviarán cuando el ingest recupere.

El plugin no aparece en los ajustes

Verifica que el directorio del plugin se llama exactamente ssea (no local_ssea):

<moodle_root>/local/ssea/    ← correcto
<moodle_root>/local/local_ssea/  ← incorrecto

Actualización del plugin

1. Descarga el ZIP nuevo o copia los archivos nuevos en <moodle_root>/local/ssea/.
2. Visita /admin/index.php — Moodle detecta la nueva versión y ejecuta los upgrades de DB (son incrementales, no hay pérdida de datos).
3. Los ajustes existentes se conservan.

Desinstalación

Administración del sitio → Plugins → Plugins locales → SSEA → Desinstalar

La desinstalación:

• Elimina las tablas locales del plugin (cola, errores, metadata).
• No elimina los datos que ya se enviaron a SSEA (viven en el backend del tenant).
• Deja de generar eventos inmediatamente.

Si además quieres borrar los datos del tenant del backend, contacta al equipo de soporte — ver Retención de datos.

Privacidad

El plugin implementa el proveedor estándar de la Privacy API de Moodle (classes/privacy/provider.php):

• Cuando Moodle elimina un usuario, el plugin deja de generar eventos para ese user_id inmediatamente.
• Los flujos estándar de export / right-to-be-forgotten de Moodle incluyen la data del plugin.
• La API key del plugin se guarda en la config de Moodle y nunca se loggea en texto plano.
• Los eventos no incluyen el contenido de las actividades (respuestas de quiz, texto de foros, archivos subidos). Solo metadata.

Ver Seguridad y privacidad para el modelo completo.

Relacionado

• Inicio rápido
• Tipos de eventos
• API — Ingesta de eventos
• Retención de datos
• Seguridad y privacidad