-
Notifications
You must be signed in to change notification settings - Fork 19
JClic Reports developers guide
The aim of the system is to collect information about the JClic activities made by students, and comprehensibly show this information to teachers.
The reporting system assumes that there are some users who use JClic in a runtime environment, resulting in working sessions during which they play activities. As a result of playing this activities, some results are obtained, which are the main object of this system. Users, in turn, may belong to a particular group. In this document the term "execution environment" is used to refer equally to JClic Player (Java standalone application), JClic applet (application embedded in a web page) or a JClic.js element (HTML5 player of JClic activities, also embedded in a web page).
The most notable elements of the information generated in a working session with JClic are:
-
Session properties
- User ID (text)
- Name of the JClic project that has initiated the working session (text)
- Time of session start (long integer). The system encodes time by a long integer representing the number of milliseconds since January 1, 1970.
- Session code (unique identifier generated by the system when a new session is requested)
- Optionally: other codes defined by the runtime environment. Currently "key" and "context" fields are used, both of type "text". In virtual learning environments (like Moodle), "key" could identify a specific activity inside a course or a virtual classroom, and "context" could serve to identify a working session of a particular student with this activity.
-
Activity properties
- Activity name (text)
- Número mínimo de acciones necesarias para resolverla (entero)
- Opcionalmente: Código descriptivo de la actividad (texto). El código opcional se puede utilizar como filtro en las consultas en las que nos interese obtener información sobre una determinada actividad o grupo de actividades.
-
Resultados de la realización de la actividad
- Actividad resuelta (si/no)
- Tiempo empleado (en milisegundos, entero)
- Número total de acciones realizadas por el usuario (entero)
- Número de acciones correctas (entero)
- Puntuación obtenida (entero entre 0 y 100) La puntuación es un valor entre 0 y 100 que se calcula mediante un algoritmo específico que tiene en cuenta el número de acciones correctas respecto al número de acciones necesarias para resolver la actividad.
El sistema de informes de JClic puede almacenar también información sobre los usuarios (nombre, contraseña, icono o avatar, etc.), y sobre los grupos a los que pertenecen (nombre del grupo, descripción, logotipo gráfico, etc.).
Algunas características de funcionamiento del sistema se rigen por una serie de variables que puede ajustar el administrador. Una de estas variables (USER_TABLES) indica si el sistema ofrece gestión de grupos y usuarios. Sus posibles valores son true o false. Cuando el valor de esta variable es false, el entorno de ejecución debe proporcionar un identificador de usuario.
El sistema de informes de JClic presenta tres modalidades de funcionamiento:
-
Recopilación interna de datos durante la sesión de trabajo
En esta modalidad no se escribe ninguna información en base de datos. Los datos de la sesión actual se acumulan en la memoria para ser presentados en la ventana de información que aparece al hacer clic en el botón Informes de usuario desde el entorno de ejecución JClic. Los informes de usuario aparecen al hacer clic en el botón que muestra el logotipo de JClic. Desde JClic Player se puede acceder también a esta funcionalidad desde el menú Actividad, o con la combinación de teclas [Ctrl]+i. -
Conexión directa a una base de datos
El entorno de ejecución JClic se conecta directamente por JDBC o ODBC a la base de datos especificada, y utiliza esta conexión tanto para identificar al usuario que está realizando las actividades como para guardar los resultados obtenidos. -
Conexión TCP/IP
En esta modalidad se precisa de un servidor y un cliente. El cliente puede ser cualquier entorno de ejecución de JClic. La comunicación entre servidor y cliente se realiza mediante el protocolo HTTP. Los datos transmitidos se encapsulan en formato XML, de manera similar a como actúa un Web service.
JClic incluye el servidor de informes JClic Reports, que es una solución completa para la recopilación, almacenamiento y presentación de resultados de los ejercicios JClic. Para más información sobre las características de JClic Reports se aconseja visitar:
http://clic.xtec.net/es/jclic/reports/index.htm
Esta solución, distribuida bajo licencia GPL al igual que el resto de módulos de JClic, está basada en Java y puede funcionar como aplicación independiente o integrada en un servidor de aplicaciones J2EE.
El código fuente de JClic Reports se encuentran disponible en:
https://projectes.lafarga.cat/projects/jclic
Para comprender el funcionamiento del sistema conviene estudiar las clases:
edu.xtec.jclic.report.Reporter edu.xtec.jclic.report.TCPReporter edu.xtec.jclic.report.TCPReportBean edu.xtec.jclic.report.ActivityReg
Que se encuentran en el directorio src/core.
El cliente debe tener la información necesaria para conectarse al servidor por TCP/IP. Esta información consiste básicamente en:
- Nombre o dirección IP del servidor
- Número de puerto de conexión (por defecto 80)
- Nombre o camino del servicio de recepción de informes JClic (por defecto /JclicReportService)
La información de conexión se proporciona al entorno de ejecución de diversas maneras:
- En JClic Player, desde la ventana de diálogo Herramientas – Configuración – pestaña Informes.
- En JClic Applet, incluyendo una llamada a la función setReporter en el script HTML que genera el applet. Esta función requiere dos parámetros:
- El nombre de la clase, que es “TCPReporter”
- Un conjunto de parámetros de funcionamiento, separados por “;” y presentados en una única cadena de texto delimitada por apóstrofes (') . Los parámetros actualmente reconocidos por el sistema son:
- path - Nombre del servidor y puerto
- service - Nombre o camino del servicio de recepción de datos
- user - Código del usuario al que se asignarán los datos
- key - Parámetro opcional 1
- context - Parámetro opcional 2
- lap - Tiempo que se aconseja dejar entre transacciones cliente servidor, expresado en segundos.
- El nombre de la clase, que es “TCPReporter”
setReporter('TCPReporter', 'path=myserver.mysite.com:9000;service=/jclic/report.php;lap=20;user=test01;key=k01;code=c01;context=ctx01');
El cliente envía una petición HTTP de tipo POST al servidor por el puerto indicado. En el cuerpo de la petición se incluye un bloque de contenido consistente en un documento XML. Por ejemplo, para informar de un inicio de sesión se envía una petición de este tipo:
<?xml version="1.0" encoding="UTF-8"?> <bean id="add session"> <param name="key" value="k01" /> <param name="user" value="test01" /> <param name="time" value="1152007500828" /> <param name="context" value="ctx01" /> <param name="project" value="superdom" /> </bean>
El servidor responde con otro documento XML en el que se proporciona la información requerida o simplemente se realiza un acuse de recibo o notificación de datos. En el caso anterior, la respuesta del servidor podría ser:
<?xml version="1.0" encoding="UTF-8"?> <bean id="add session"> <param name="session" value="test01_1152007500828" /> </bean>
Los documentos XML siempre tienen la misma estructura:
- Un elemento principal llamado “bean”, con una propiedad “id” que indica el tipo de objeto proporcionado. Los tipos de identificadores utilizados actualmente por el sistema son:
- get property - Obtener el valor de un determinado parámetro de funcionamiento
- get_properties - Obtener todos los parámetros de funcionamiento (es el único identificador que se escribe con un guión entre las dos palabras)
- add session - Iniciar una nueva sesión
- add activity - Reportar una nueva actividad
- get groups - Obtener la lista de grupos
- get users - Obtener la lista de usuarios de un determinado grupo
- get user data - Obtener información sobre un determinado usuario
- get group data - Obtener información sobre un determinado grupo
- new group - Crear un nuevo grupo
- new user - Crear un nuevo usuario
- multiple - Identifica a un objeto que contiene uno o más objetos
- error - Se ha producido algún problema en la transacción.
- Subelementos de tipo param (con las propiedades name y value)
- Otros subelementos específicos del tipo de datos proporcionados o requeridos (group, user, activity, action, error, etc.).
El diálogo típico entre un cliente JClic y un servidor de informes tiene las siguientes fases:
- El cliente solicita al servidor la relación de sus parámetros de funcionamiento, transmitiéndole la orden get_properties.
- El servidor responde con la lista completa de sus parámetros de funcionamiento. Los principales son:
| PARÁMETRO | TIPO | DESCRIPCIÓN |
|---|---|---|
| USER_TABLES | true/false | Si es true, el sistema dispone de tablas de grupos y usuarios. En caso contrario, el cliente está obligado a proporcionar un identificador de usuario para continuar. |
| ALLOW_CREATE_GROUPS | true/false | Indica si el sistema permite a los clientes la creación de nuevos grupos. |
| ALLOW_CREATE_USERS | true/false | Indica si desde el cliente se pueden crear nuevos usuarios. |
| TIME_LAP | entero | Los clientes JClic acumulan la información de las actividades, y la transmiten en paquetes cada cierto tiempo. El valor por defecto del intervalo entre conexiones es de 20 segundos, pero el servidor puede preferir otros valores. |
Si el cliente cuenta ya con un identificador de usuario va directamente al paso número 7.
- El cliente envía al servidor la orden get groups.
- El servidor responde con la lista de grupos disponible.
El cliente muestra la lista de grupos al usuario para que seleccione el suyo. Si la variable ALLOW_CREATE_GROUPS indica true, se le permitirá también definir un grupo nuevo.
- El cliente envía al servidor la orden get users, pasando como parámetro group el identificador del grupo seleccionado en el paso anterior.
- El servidor responde con la relación de usuarios del grupo indicado. Los usuarios pueden opcionalmente tener una contraseña asignada, que el servidor pasará encriptada como un dato más en la lista de usuarios. La encriptación y desencriptación de datos se realiza mediante la clase edu.xtec.util.Encryption, que se encuentra en el directorio src/utilities del código fuente.
El cliente muestra la lista al usuario para que seleccione su nombre o su icono en la lista y, si corresponde, le solicita la contraseña.
- El cliente solicita al servidor iniciar una nueva sesión, mediante la orden add session. Le proporciona el identificador del usuario, la fecha y hora local (en forma de entero largo) y el nombre del proyecto que se va a ejecutar.
- El servidor responde con el código de sesión que ha sido asignado a la petición. A partir de este momento el cliente debe usar este código en todas las transacciones relacionadas con esta sesión.
- A medida que el usuario va completando actividades, los datos se acumulan en el cliente. Cada cierto tiempo (el lapso de segundos indicado por el parámetro TIME_LAP), el cliente envía al servidor un paquete con los datos de todas las actividades finalizadas durante el intervalo. El paquete es del tipo multiple y contiene uno o más bloques de información add activity, con los datos correspondientes a cada actividad.
- El servidor responde con un mensaje de aceptación de tipo add activity.
- Si se produce algún contratiempo, el servidor puede responder con un mensaje de tipo error. La descripción del error estará en la propiedad value del primer subelemento.
A continuación se muestra un ejemplo de los mensajes intercambiados entre cliente y servidor durante una sesión de trabajo. Para mayor legibilidad se han suprimido las cabeceras HTTP de la petición y la respuesta:
1 - Mensaje del cliente solicitando los parámetros de funcionamiento:
<?xml version="1.0" encoding="UTF-8"?> <bean id="get_properties" />
2 - Respuesta del servidor:
<?xml version="1.0" encoding="UTF-8"?> <bean id="get_properties"> <param name="TIME_LAP" value="10" /> <param name="ALLOW_CREATE_GROUPS" value="false" /> <param name="USER_TABLES" value="true" /> <param name="ALLOW_CREATE_USERS" value="true" /> <param name="SHOW_GROUP_LIST" value="true" /> <param name="SHOW_USER_LIST" value="true" /> </bean>
3 – Mensaje solicitando la lista de grupos:
<?xml version="1.0" encoding="UTF-8"?> <bean id="get groups" />
4 – Respuesta del servidor:
<?xml version="1.0" encoding="UTF-8"?> <bean id="get groups"> <group id="test" name="Test" /> </bean>
5 – Observamos que solo hay definido un grupo. Mensaje del cliente solicitando la lista de usuarios del grupo "test":
<?xml version="1.0" encoding="UTF-8"?> <bean id="get users"> <param name="group" value="test" /> </bean>
6 – Respuesta del servidor. Se observa que solo el usuario test03 tiene una contraseña definida:
<?xml version="1.0" encoding="UTF-8"?> <bean id="get users"> <user id="test01" name="Antoni Aguilar" group="test" /> <user id="test02" name="Jaume Berenguer" group="test" /> <user id="test03" name="Isabe Campà" pwd="1cc012366601c" group="test" /> <user id="test04" name="Yolanda Escribano" group="test" /> <user id="test05" name="Juan Fernández" group="test" /> <user id="test06" name="Dolors Garcia" group="test" /> <user id="test07" name="Raul Gracia" group="test" /> <user id="test08" name="Sara Güell" group="test" /> <user id="test09" name="Manuel Hernández" group="test" /> <user id="test10" name="Imma Herrera" group="test" /> <user id="test11" name="Soledad Jaramillo" group="test" /> <user id="test12" name="Jordi Linares" group="test" /> </bean>
7 – Mensaje del cliente solicitando iniciar una sesión con el usuario test01 y un proyecto que tiene por nombre superdom:
<?xml version="1.0" encoding="UTF-8"?> <bean id="add session"> <param name="user" value="test01" /> <param name="time" value="1152003524515" /> <param name="project" value="superdom" /> </bean>
8 – Respuesta del servidor, indicando el código de sesión que ha sido asignado:
<?xml version="1.0" encoding="UTF-8"?> <bean id="add session"> <param name="session" value="test01_1152003524515" /> </bean>
9 – El cliente informa de la realización de dos actividades:
<?xml version="1.0" encoding="UTF-8"?> <bean id="multiple"> <bean id="add activity"> <param name="num" value="0" /> <param name="session" value="test01_1152003524515" /> <activity name="serord01.puz" start="1152003529218" time="5313" solved="false" score="2" minActions="5" actions="3" /> </bean> <bean id="add activity"> <param name="num" value="1" /> <param name="session" value="test01_1152003524515" /> <activity name="serord02.puz" start="1152003534531" time="5062" solved="false" score="0" minActions="5" actions="3" /> </bean> </bean>
10 – El servidor responde con un mensaje de aceptación. Para simplificar, se indica solamente el número de la última actividad del grupo:
<?xml version="1.0" encoding="UTF-8"?> <bean id="add activity"> <param name="activity" value="1" /> </bean>
9bis – El cliente informa de otra actividad realizada:
<?xml version="1.0" encoding="UTF-8"?> <bean id="multiple"> <bean id="add activity"> <param name="num" value="2" /> <param name="session" value="test01_1152003524515" /> <activity name="serord03.puz" start="1152003539593" time="13782" solved="true" score="5" minActions="5" actions="3" /> </bean> </bean>
10bis – El servidor responde con otro mensaje de aceptación:
<?xml version="1.0" encoding="UTF-8"?> <bean id="add activity"> <param name="activity" value="2" /> </bean>
... a partir de ahí se irían produciendo mensajes del tipo 9 y 10 entre cliente y servidor, hasta finalizar la sesión.
En este segundo ejemplo, el applet obtiene el identificador de usuario por parámetro, con lo que no será necesario realizar la solicitud de listas de grupos y usuarios como en el caso anterior. El código HTML que invoca el applet podría ser:
<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>El superdòmino</title>
<script language="JavaScript"
src="http://clic.xtec.net/dist/jclic/jclicplugin.js"
type="text/javascript"></script>
</head>
<body bgcolor=#ffffff>
<div align="center">
<script language="JavaScript">
setJarBase('http://clic.xtec.net/dist/jclic');
setExitUrl('http://www.yahoo.com');
setLanguage('ca', 'ES');
setReporter('TCPReporter','path=myhost.mysite.com:9000;service=/JClicReportService;lap=20;user=test01;key=k01;code=c01;context=ctx01');
setSkin('@orange.xml');
writePlugin('superdom.jclic.zip', '800', '550');
</script>
</div>
</body>
</html>
Como se puede observar, se utiliza una llamada a la función de JavaScript setReporter (definida en jclicplugin.js) para pasar al applet los parámetros de conexión, el identificador de usuario y un par de parámetros adicionales.
Los mensajes intercambiados entre cliente y servidor podrían ser los siguientes:
1 – El cliente solicita la lista de parámetros
<?xml version="1.0" encoding="UTF-8"?> <bean id="get_properties" />
2 – El servidor se la proporciona
<?xml version="1.0" encoding="UTF-8"?> <bean id="get_properties"> <param name="TIME_LAP" value="10" /> <param name="ALLOW_CREATE_GROUPS" value="false" /> <param name="USER_TABLES" value="true" /> <param name="ALLOW_CREATE_USERS" value="true" /> <param name="SHOW_GROUP_LIST" value="true" /> <param name="SHOW_USER_LIST" value="true" /> </bean>
3 – El cliente ya conoce el identificador de usuario, que ha obtenido vía parámetro de construcción del applet. Inicia la sesión:
<?xml version="1.0" encoding="UTF-8"?> <bean id="add session"> <param name="key" value="k01" /> <param name="user" value="test01" /> <param name="time" value="1152007500828" /> <param name="context" value="ctx01" /> <param name="project" value="superdom" /> </bean>
4 – El servidor responde con el código de sesión asignado:
<?xml version="1.0" encoding="UTF-8"?> <bean id="add session"> <param name="session" value="test01_1152007500828" /> </bean>
5 – El cliente informa de la realización de un grupo de cuatro actividades:
<?xml version="1.0" encoding="UTF-8"?> <bean id="multiple"> <bean id="add activity"> <param name="num" value="0" /> <param name="session" value="test01_1152007500828" /> <activity name="senya-04.ass" start="1152007506187" time="3172" solved="true" score="1" minActions="1" actions="1" /> </bean> <bean id="add activity"> <param name="num" value="1" /> <param name="session" value="test01_1152007500828" /> <activity name="senya-08.ass" start="1152007510718" time="1922" solved="true" score="1" minActions="1" actions="1" /> </bean> <bean id="add activity"> <param name="num" value="2" /> <param name="session" value="test01_1152007500828" /> <activity name="senya-12.ass" start="1152007513968" time="2594" solved="true" score="1" minActions="1" actions="2" /> </bean> <bean id="add activity"> <param name="num" value="3" /> <param name="session" value="test01_1152007500828" /> <activity name="senya-06.ass" start="1152007517718" time="907" solved="false" score="0" minActions="1" actions="0" /> </bean> </bean>
6 – El servidor responde con un acuse de recibo. Nótese que solamente se indica el número de orden de la última actividad del grupo:
<?xml version="1.0" encoding="UTF-8"?> <bean id="add activity"> <param name="activity" value="3" /> </bean>
A partir de ahí se repiten mensajes de tipo 5 y respuestas de tipo 6, hasta finalizar la sesión.
- User's guide of JClic
- JClic startup parameters
- How to make a CD-ROM with JClic activities
- How to translate JClic into your language
- JClic Reports Server with Tomcat and MySQL on Ubuntu
- Publish JClic projects on Internet with Netlify