Integración de aplicaciones externas: Integration Service
El módulo publica un API a través de la funcionalidad de Servicios Externos de Moodle. Nuestra aplicación de gestión de licencias utiliza depende de la activación del protocolo REST en Moodle.
Todas las funciones tienen dos parámetros comunes:
- wsfunction. string. Este parámetro tomará el valor de la columna Función de la tabla de más abajo.
- wstoken. string. Es un token de autenticación que facilitará el administrador Moodle. Por motivos de seguridad, es recomendable que este parámetro se pase por POST.
- moodlewsrestformat. string. El formato de respuesta que esperamos. Puede tomar los valores 'xml' o 'json'. Nosotros utilizaremos json.
| Función | Parámetros | Salida | Descripción |
|---|
| local_lpi_get_pending_files | - page. int. El número de página que queremos obtener..
- count. int. El número de elementos por página a devolver.
- search. string. Una cadena de búsqueda que permite filtrar resultados. Busca en autor, título, fragmento y título de fragmento.
| Array de objetos con los siguientes campos: - count. int. El número de elementos totales existentes. No sólo el número de elementos de data en el resultado.
- data. array. Unarray de objetos con los siguientes campos:
- id. int. El id del metadato
- title. string. El título de la obra
- author. string. El autor de la obra
- fragment. string. El fragmento de la obra
- state. string. El estado de la obra. Siempre devuelve el valor 'gt10'.
- metadatauserid. int. El id moodle del usuario que rellenó los metadatos
- metadatauseridnumber. string. El idnumber moodle del usuario que rellenó los metadatos. En el caso de la UJI este valor corresponde al perid del usuario.
- metadatauseremail. string. La dirección de correo del usuario que rellenó los metadatos.
- metadatatimecreated. int. El timestamp unix del momento en que el usuario rellenó los metadatos.
| Obtiene un listado paginado de peticiones de tramitación de licencias. Únicamente obtiene los metadatos de aquellos datos de ficheros que han sido clasificados en la opción "Es una obra completa (o fragmento superior al 10%) para la que no tengo autorización o licencia (tramitación de licencia con coste económico)". |
| local_lpi_get_file_metadata | - id. int. El id del metadato.
| Array de objetos con los siguientes campos: - id. int. El id del metadato.
- title. string. El título del a obra.
- author. string. El autor de la obra.
- fragmenttitle. string. El título del fragmento.
- fragmentauthor. string. El autor del fragmento.
- publisher. string. La editorial de la obra.
- url. string. La url de descarga del fichero.
- identification. string. El identificador de la obra
- firstpage. string. La primera página
- lastpage. string. La última página.
- totalpages. string. El número total de páginas.
- enroled. int. El número de estudiantes matriculados en el curso moodle.
- metadatauserid. int. El id de usuario moodle del usuario que ha registrado el metadato.
- metadatauseridnumber. int. El idnumber moodle del usuario que ha registrado el metadato. En el caso de la UJI esto es el perid del usuario.
- metadatauseremail. string. El email del usuario que ha subido el metadato.
- metadatatimecreated. int. El timestamp en el que el usuario rellenó los metadatos.
- uploaduserid. int. El id de usuario moodle del usuario que subió el fichero.
- uploadtimecreated. int. El timestamp en el que el usuario subió el fichero.
- mimetype. string. El mimetype del fichero.
- filename. string. El nombre del fichero.
- filesize. int. El tamaño del fichero.
| Obtiene todos los metadatos asociados a un fichero en concreto que se encuentre en el estado de espera de tramitación de licencia. Es decir, que haya sido catalogado por el profesorado como "Es una obra completa (o fragmento superior al 10%) para la que no tengo autorización o licencia (tramitación de licencia con coste económico)". |
| local_lpi_set_file_authorization | - id. int. El id del metadato.
- authz. string. Indica la autorización otorgada
- ok. Se permite la publicación
- forbidden. Se deniega la publicación
- documentcontent. string. El tipo de documento establecido.
- administrative
- ownedbyteachers
- editedbyuniversity
- publicdomain
- lt10fragment
- havelicense
- other
- notprintable
- timeendlicense. int. Timestamp de la fecha de fin de licencia. Tiene aplicación para los valores havelicense y other de document_content.
- denyreason. string. Una descripción con el motivo de denegación en caso de que sea forbidden.
| Objeto con las siguientes propiedades: - id. int. El id del metadato.
- authz. string. El valor de autorización establecido.
- document_content. string. El tipo de contenido establecido.
- timeendlicense. El timestamp de la fecha de fin de licencia (si aplica)
- denystate. string. El motivo de denegación (si aplica)
| Permite establecer el contenido de un fichero y la autorización o no para publicarlo siempre y cuando éste haya sido catalogado como "Es una obra completa (o fragmento superior al 10%) para la que no tengo autorización o licencia (tramitación de licencia con coste económico)".
|
Integración de aplicaciones externas: Audit Service
El servicio de auditoría permite obtener información sobre la catalogación de ficheros a las entidades de gestión de derechos.
| Función | Parámetros | Salida | Descripción |
|---|
| get_auditable_file_metadata | - page. int. El número de página que queremos obtener..
- count. int. El número de elementos por página a devolver.
| Array de objetos con los siguientes campos: - count. int. El número de elementos totales existentes. No sólo el número de elementos de data en el resultado.
- data. array. Unarray de objetos con los siguientes campos:
- id. int. El id del metadato
- state. string. El contenido del documento.
- coursetimecreated. int. El timestamp del momento en que se creó el curso.
- timemodified. int. El timestamp de la última actualización del metadato.
- license. string. La licencia declarada.
- title. string. El título de la obra
- author. string. El autor de la obra
- publisher. string. La editorial de la obra.
- identification. string. El identificador de la obra.
- pages. string. Las páginas utilizadas de la obra.
- totalpages. int. El número total de páginas.
- enroled. int. Número de alumnos matriculados.
- timeendlicense. int. La fecha de fin de licencia.
- comments. string. Observaciones añadidas por el profesorado.
- courseid. string. Identificador disociado de curso.
- downloadurl. string. URL de descarga del asset.
| Obtiene un listado de metadatos de ficheros auditables. Son auditables aquellos ficheros que no hayan sido clasificados como documentos administrativos y que hayan sido tramitados.
|
Tratamiento de errores
Detectaremos un error si se cumple alguna de las siguientes condiciones:
- Se devuelve un HTTP Status Code distinto a 200.
- Se devuelve un HTTP Status Code de 200 y en el cuerpo de la respuesta uno de los campos es errorcode.
Para el segundo campo, podemos obtener más información:
- errorcode. Un código de error
- message. Un mensaje de error
- exception. La excepción que se ha lanzado
Decarga de ficheros
La llamada de obtención de ficheros es especial. No podemos utilizar las APIs que ya existen en Moodle por lo resquisitos de seguridad que tienen las nuestras. En particular, NO se pueden descargar ficheros que no estén declarados como duda.
$ curl MOODLE_WWWW_ROOT/local/lpi/download_file.php?token=ELTOKEN&id=ID_DEL_METADATO
Si todo ha ido bien, devolverá el contenido del fichero con el content-type correspondiente.
Si ocurre un error obtenemos un json como el indicado en la sección "Tratamiento de errores".
Ejemplos de peticiones
Obtener la primera página de ficheros pendientes de revisar de 100 en 100:
$ curl MOODLE_WWWW_ROOT/webservice/rest/server.php?wsfunction=local_lpi_get_pending_files&wstoken=EL_TOKEN_MOODLE&moodlewsrestformat=json&page=0&count=100&search=
Obtener la segunda página de ficheros pendientes de revisar de 100 en 100:
$ curl MOODLE_WWWW_ROOT/webservice/rest/server.php?wsfunction=local_lpi_get_pending_files&wstoken=EL_TOKEN_MOODLE&moodlewsrestformat=json&page=1&count=100&search=
Obtener los metadatos detallados de un metadato con id 2
$ curl MOODLE_WWWW_ROOT/webservice/rest/server.php?wsfunction=local_lpi_get_file_metadata&wstoken=EL_TOKEN_MOODLE&moodlewsrestformat=json&id=1
Establecer estados de metadatos:
Ejemplos de respuestas
{
"count":1,
"data":[
{
"id":1,
"title":"IMS GLC",
"author":"Alice Bob Eve",
"fragment":false,
"state":"gt10",
"metadatauserid":4,
"metadatauseridnumber":"",
"metadatauseremail":"someone@uji.es",
"metadatatimecreated":1512128304
}
]
}
{
"id":1,
"title":"IMS GLC",
"author":"Alice Bob Eve",
"fragmenttitle":null,
"fragmentauthor":null,
"publisher":"Alfaguara",
"url":"MOODLE_WWWROOT/local\/lpi\/download_file.php?id=1",
"identification":"1234567",
"firstpage":null,
"lastpage":null,
"totalpages":null,
"enroled":0,
"metadatauserid":4,
"metadatauseridnumber":"",
"metadatauseremail":"aliceevebob@uji.es",
"metadatatimecreated":1512128304,
"uploaduserid":4,
"uploadtimecreated":1510251419,
"mimetype":"application\/pdf",
"filename":"www.imsglobal.org-cc-ccv1p1-imscc_profilev1p1-Overview.pdf",
"filesize":57027
}
{
"exception":"local_lpi\\exception\\not_supported_state_exception",
"errorcode":"error_notsupportedstate",
"message":"Cannot set state ok to metadata 1"
}