Documentación del Web Service `get_general_report_json` de Moodle

Descripción General

Este documento describe el funcionamiento del Web Service get_general_report_json, desarrollado para Moodle bajo el plugin local_bcn_dashboard. Este servicio web permite recuperar reportes generales mediante consultas SQL dinámicas construidas según parámetros proporcionados por el usuario. Los resultados se entregan en formato JSON, incluyendo datos solicitados y metadatos de paginación.

Estructura del Web Service

Parámetros de Entrada

fields: Array de cadenas que indican qué campos se incluirán en la respuesta.
filters: Array de objetos que especifican criterios de filtrado, cada uno compuesto por:
- pluginname: Nombre del plugin relacionado al filtro.
- name: Nombre específico del filtro.
- value: Valor para aplicar en el filtro.
page: Número entero para la paginación (por defecto: 1).
perpage: Número entero que determina la cantidad de registros por página (por defecto: 50).

Lógica del Servicio Web

El servicio realiza las siguientes acciones secuenciales:

Validación de parámetros mediante la función interna validate_parameters.
Construcción dinámica del SQL utilizando:
- Cláusulas SELECT dinámicas basadas en los campos solicitados.
- Cláusulas FROM y JOIN generadas según campos específicos del usuario, organizaciones y posiciones.
- Aplicación condicional de filtros.
Ejecución de la consulta SQL:
- Primero, determina el número total de registros sin límite (total_records).
- Luego, aplica paginación con LIMIT y OFFSET.
Preparación de resultados: Cada registro retornado se filtra según los campos especificados.
Construcción de respuesta JSON:
- Se incluye información de paginación (página actual, total de resultados, total de páginas).
- Se establece un estado y un mensaje descriptivo del resultado (status, message).

Ejemplo de Respuesta


{
  "status": true,
  "message": "Success",
  "data": {
    "results": [
      {"Nombre": "Juan Pérez", "Correo": "juan.perez@example.com"},
      {"Nombre": "Ana Gómez", "Correo": "ana.gomez@example.com"}
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total_results": 200,
      "total_pages": 4
    }
  }
}

Refactorización del SQL

Se ha refactorizado la lógica de construcción del SQL, destacando las siguientes mejoras:

Modularidad: Se ha dividido en funciones específicas:
- build_sql_select_clause: Genera dinámicamente la cláusula SELECT según campos definidos.
- build_sql_from_clause: Construye cláusulas FROM y JOIN basadas en campos personalizados.
Validación dinámica de filtros: Los filtros son validados contra un conjunto de filtros posibles definidos en la clase general_report_sql, evitando consultas erróneas.
Paginación eficiente: Uso optimizado del SQL para contar resultados y aplicar límites para rendimiento óptimo.

Construcción dinámica de respuestas JSON

La estructura de la respuesta del Web Service se genera dinámicamente según los resultados reales obtenidos de la base de datos:

Se obtienen columnas de muestra usando get_sample_columns.
Se crea dinámicamente una estructura con la función build_dynamic_structure, asegurando flexibilidad en la respuesta.

Esto permite que el Web Service adapte su respuesta automáticamente ante cambios en la base de datos o en los campos solicitados por el cliente.

Conclusión

Este Web Service está diseñado para ser altamente flexible y eficiente, proporcionando una potente herramienta para la obtención dinámica de reportes en Moodle.

Documentación del Web Service get_general_report_json de Moodle