Servicios web y API
Funciones externas de local_deltamodules (db/services.php), su uso desde el JavaScript global y el servicio MCP para la administración por un agente externo.
Funciones externas (db/services.php)
| Función | Clase | Tipo | AJAX | Uso |
|---|---|---|---|---|
local_deltamodules_create_module | local_deltamodules\external\create_module | write | No | Agente MCP: crear un módulo desde un JSON |
local_deltamodules_get_next_activity | local_deltamodules\external\get_next_activity | read | Sí (sesión) | Botón "Siguiente actividad" |
local_deltamodules_exam_strike | local_deltamodules\external\exam_strike | write | Sí (sesión) | Control de cambio de pantalla en los exámenes |
local_deltamodules_get_completed_cmids | local_deltamodules\external\get_completed_cmids | read | Sí (sesión) | Lista de requisitos del certificado: mostrar solo lo pendiente |
Todas usan las clases de core_external (external_api, external_function_parameters…).
local_deltamodules_create_module
| Parámetro | Tipo | Detalle |
|---|---|---|
definition | PARAM_RAW | JSON con id (nombre corto único), titulo y temas (n, tema, objetivo, url, codigo). URL de YouTube → video interactivo; otra URL → enlace; sin URL → etiqueta "Contenido pendiente de enlazar". |
withcertificate | PARAM_BOOL, por defecto true | Agregar la actividad de certificado al final |
Valida el contexto de sistema y exige moodle/course:create. Llama a builder::create_module() (idempotente por nombre corto) y, si corresponde, a builder::add_certificate(). Devuelve courseid, shortname, courseurl, activities (número de actividades), certificatecmid y message.
Esta función usa el formato heredado de builder::create_module() (curso visible, sin la estructura oficial de academy::create_module(): sin repasos, sin número de ID MNN ni campos de revisión). Los módulos oficiales se crean con el asistente.
local_deltamodules_get_next_activity
Parámetro cmid. Valida el contexto del curso (lo que exige estar matriculado). Recorre las actividades en el orden del índice y devuelve la siguiente que se ve en la página del curso o que está en un tema bloqueado pero visible en gris, que no esté borrándose y que tenga página propia (sin etiquetas). Respuesta:
| Campo | Detalle |
|---|---|
hasnext, cmid, name, url | Siguiente actividad |
available | Si ya se puede abrir para el usuario |
locked | Si está bloqueada, el texto de la restricción ("termina el video…") o la cadena nextlocked |
end | true en la última actividad: el botón vuelve al curso (cadena backtocourse) |
El JavaScript global la consulta en las páginas view.php de las actividades (en el video, dentro de la barra superior del reproductor) y, si la siguiente está bloqueada, vuelve a consultar cada 8 segundos con la pestaña visible (máximo 110 veces).
local_deltamodules_exam_strike
Parámetros attemptid y add (bool). Solo el dueño del intento puede consultarlo. Con add = true y el intento en curso, suma un cambio de pantalla en la preferencia de usuario local_deltamodules_strikes_<attemptid>. Devuelve strikes y max (regla exam_leaves del módulo; 0 = sin control). Contar en el servidor evita que recargar la página o abrir otra pestaña reinicie el conteo.
local_deltamodules_get_completed_cmids
Parámetro courseid. Devuelve los cmids que el usuario actual completó (COMPLETION_COMPLETE o COMPLETION_COMPLETE_PASS) en el curso. El JavaScript global oculta esas actividades de la lista "No disponible hasta que…" del certificado.
Servicio MCP (administración por un agente externo)
setup-mcp-service.php (paso crítico de moodle-config.sh, después de activar enablewebservices = 1 y webserviceprotocols = rest,mcp) deja Moodle listo para que un cliente MCP externo consulte y gestione la plataforma. El protocolo lo aporta el plugin de terceros webservice_mcp (endpoint /webservice/mcp/server.php). Crea de forma idempotente:
| Elemento | Valor |
|---|---|
| Rol | delta_ai_mcp_ro ("Delta AI MCP (gestión completa)"; el nombre corto es histórico), contexto de sistema |
| Usuario de servicio | mcpservice (cuenta técnica; people::all() la clasifica como "admin") |
| Servicio externo | delta_ai_mcp_ro ("Delta AI — Agente MCP (gestión completa)"), restringido a ese usuario |
| Token | Permanente, para ese usuario y servicio. En el registro del despliegue se muestra enmascarado; completo solo con php /setup-mcp-service.php --show-token |
Capacidades del rol: lectura de usuarios, cursos, participantes, calificaciones, completado, certificados e informes (webservice/mcp:use, webservice/rest:use y otras) y gestión: moodle/user:create, moodle/user:update, enrol/manual:enrol, enrol/manual:unenrol, moodle/role:assign, moodle/cohort:assign, moodle/course:create, moodle/course:update, moodle/category:manage. No incluye borrar usuarios.
Funciones expuestas:
| Bloque | Funciones |
|---|---|
| Lectura | core_webservice_get_site_info, core_course_get_courses, core_course_get_courses_by_field, core_course_get_contents, core_course_get_categories, core_enrol_get_enrolled_users, core_enrol_get_users_courses, core_user_get_users, core_user_get_users_by_field, core_completion_get_activities_completion_status, core_completion_get_course_completion_status, gradereport_user_get_grade_items, mod_customcert_list_issues, core_reportbuilder_list_reports, core_reportbuilder_retrieve_report |
| Usuarios y matrículas | core_user_create_users, core_user_update_users, enrol_manual_enrol_users, enrol_manual_unenrol_users, core_cohort_add_cohort_members, core_cohort_delete_cohort_members |
| Cursos | core_course_create_courses, core_course_update_courses, core_course_create_categories, local_deltamodules_create_module |
enforce-course-creation-manual.php excluye a delta_ai_mcp_ro al retirar moodle/course:create a los demás perfiles.
El token da acceso de gestión a la plataforma. Debe tratarse como un secreto: no se copia en la documentación, en tickets ni en el repositorio.
Otros usos de la API de Moodle
local_ai_managerexpone su propia funciónsubmit_query, que el parche del agente intercepta (Asistente de IA).- El JavaScript del chat usa la función de
block_ai_chatpara borrar una conversación (block_ai_chat_delete_conversation).