Documentación del Desarrollo: WS para Reporte de Quizzes

Este documento describe el funcionamiento y la implementación del Web Service (WS) external_quiz_report desarrollado para la obtención de reportes de intentos de quizzes en Moodle. Este WS maneja altos volúmenes de datos mediante una doble paginación: a nivel de quizzes y a nivel de intentos por quiz.

Índice

• Introducción
• Parámetros de Entrada
• Estructura de la Respuesta
• Lógica de Paginación
• Formateo de Respuestas
• Optimización y Caché
• Código Fuente
• Ejemplo de Uso

Introducción

El WS external_quiz_report está diseñado para recuperar información de los quizzes de un curso, incluyendo los intentos de cada quiz, en un entorno Moodle. Considerando que en algunos cursos pueden existir múltiples quizzes y cada uno puede tener numerosos intentos (especialmente en cursos con más de 200 usuarios matriculados), se implementó una doble paginación:

• Paginación a nivel de quizzes: Permite controlar cuántos quizzes se retornarán en cada solicitud.
• Paginación a nivel de intentos: Permite limitar la cantidad de intentos retornados por cada quiz.

Además, se han implementado técnicas de formateo de la respuesta para eliminar saltos de línea en las respuestas y se utiliza un mecanismo de caché para evitar consultas repetitivas a la base de datos.

Parámetros de Entrada

El WS espera los siguientes parámetros:

Estructura de la Respuesta

La respuesta JSON generada por el WS sigue la siguiente estructura:

{
    "quizzes": [
        {
            "nombrequiz": "Nombre del Quiz",
            "intentos": [
                {
                    "intentoid": "Identificador del intento",
                    "usuario": "Nombre del usuario",
                    "resumen": [
                        {
                            "pregunta": "Nombre de la pregunta",
                            "respuesta": "Respuesta del usuario"
                        }
                    ],
                    "fecha_inicio_intento": "Fecha de inicio (formato dd-mm-YYYY HH:MM:SS)",
                    "fecha_finalizacion_intento": "Fecha de finalización (formato dd-mm-YYYY HH:MM:SS)",
                    "resultado": "Estado del intento"
                }
            ],
            "pagination": {
                "current_page": X,
                "per_page": Y,
                "total_records": Z,
                "total_pages": W
            }
        }
    ],
    "quizpagination": {
        "current_page": A,
        "per_page": B,
        "total_records": C,
        "total_pages": D
    }
}

• quizzes: Es un array de quizzes, cada uno con:
  • nombrequiz: El nombre del quiz.
  • intentos: Array paginado de intentos para el quiz, con su información y un array resumen que contiene preguntas y respuestas.
  • pagination: Información de paginación a nivel de intentos para ese quiz.
• quizpagination: Información de paginación global para el listado de quizzes.

Lógica de Paginación

El WS aplica dos niveles de paginación:

1. Paginación de Quizzes:

   • Se obtiene la lista completa de quizzes (filtrados si se envía quizid).
   • Se calcula el número total de quizzes y se utiliza array_slice para extraer el subconjunto correspondiente a la página solicitada (quizpage y quizperpage).
   • Se incluye en la respuesta la estructura quizpagination con la información global (página actual, cantidad por página, total de quizzes y total de páginas).

2. Paginación de Intentos:

   • Para cada quiz, se obtiene la lista completa de intentos.
   • Se calcula el total de intentos y se extrae el subconjunto deseado mediante array_slice usando los parámetros attemptpage y attemptperpage.
   • Se agrega a cada quiz un bloque pagination específico con la paginación de los intentos de dicho quiz.

Formateo de Respuestas

Dentro del procesamiento de cada intento se formatea la respuesta de cada pregunta:

• Se eliminan saltos de línea (\n y \r) de las respuestas mediante str_replace.
• Se utiliza trim para eliminar espacios adicionales.
• Si la respuesta queda vacía después del formateo, se establece a “No respondida”.

Optimización y Caché

Para optimizar las consultas a la base de datos:

• Se utiliza un array $cachedUsernames para almacenar y reutilizar los nombres de usuario, evitando consultas repetitivas para el mismo usuario.

Ejemplo de Uso

• Llamada al WS:
  Se puede invocar el WS mediante una llamada REST incluyendo los parámetros en la URL, por ejemplo:

  /webservice/rest/server.php?wstoken=YOUR_TOKEN&moodlewsrestformat=json&wsfunction=local_bcn_dashboard_external_quiz_report_get_quiz_report&courseid=2&quizpage=1&quizperpage=2&attemptpage=1&attemptperpage=5

  Esto retornará los primeros 2 quizzes con, para cada uno, los primeros 5 intentos.

• Respuesta de Ejemplo:
  La respuesta contendrá dos bloques de paginación: uno global para quizzes (quizpagination) y otro para cada quiz en el bloque pagination (paginar los intentos dentro de ese quiz).

Esta documentación describe el funcionamiento y la estructura del WS, así como los mecanismos aplicados para paginar tanto a nivel de quizzes como de intentos, permitiendo un manejo eficiente de grandes volúmenes de datos.