CUMULATE protocol

URLs of web-services

These are the URLs of the web-services that implement components of the ADAPT² architecture and protocols.

User Activity report receiver - this service listens to applications that report user activity

http://adapt2.sis.pitt.edu/cbum/um

Report Manager - service that answers queries about users' progress with learning objects and mastery of concepts

http://adapt2.sis.pitt.edu/cbum/ReportManager

Parameter Naming Conventions

The following parameter names (and their possible values) should be used in communication between all applications using ADAPT² protocols.

• usr – user, user login
• sid – session id
• app – application, activity server
  • 1 – Unknown application
  • 2 – QuizPACK
  • 3 – WebEx
  • 4 – WADEIn
  • 5 – KnowledgeSea
  • 6 – AnnotatEd
  • 7 – venn
  • 8 – KnowledgeTree
  • 9 – NavEx
  • 10 – CourseAgent
  • 11 – cWADEIn II
  • 12 – VIBE
  • 13 – VirtPresenter
  • 14 – Problets
  • 15 – VarScope
  • 16 – BooleanTool
  • 17 – Jeliot
  • 18 – free slot
  • 19 – free slot
  • 20 – QuizQUIDE
  • 21 – jWADEIn II
  • 22 – free slot
  • 23 – SQL KnoT
  • 24 – ADAPT² PService
• act – learning action, learning object – minimally invokable piece of learning object (quiz, example etc.)
• sub – sub-action, step of learning action, fragment of learning object – minimal trackable piece of learning object (question of quiz, line of example etc.)
• grp – group name; suggested naming convention for group name is {academic year, semester, group identified or name within semester}, e.g. 200621 – Spring 2006, group 1
• res – result of the interaction – any decimal value e.g. -1, 0, 0.4, 0.7, 1
• svc – service parameter – any character string that can be used to store system state, should not contain ? (question mark), & (ampersand), : (colon), and / (backward slash); however all those symbols can be encoded using Java URLEncoder class that maps them to %XX; service parameter
• lev – Bloom's level - comma separated combinations of the ones below without spaces (e.g. knowledge,comprehension)
  • knowledge (KnowledgeSea)
  • comprehension (WebEx/NavEx, WADEIn in exploration mode)
  • application (QuizPACK/QuizGuide, WADEIn in evaluation mode)
• prc – precision
• ums – user modeling server URL for reporting user activity to
• dom – learning domain (e.g. C programming), will define the concepts ontology
• con - concept - knowledge component of a learning domain
• scp – scope of activities (used for multiple groupings of activities)
• ip – IP address - e.g. IP of an anonymous user

It is advised to use these parameters and values even internally.

Protocol for sending events to the User Model

Brief description: This protocol allows external applications to send the infomation about user actions to the user model. To successfully report user activity the external aplication should describe what learning object the user has been working with, who is the user, and what was the result of the interaction.

Request URL Format:

http://<report_servlet>?app=<application_id> &act=<learning_object> &sub=<learning_object_step> &usr=<user> &gpr=<group> &sid=<session_id> &res=<result> &svc=<service_parameters>

,where:

• app – mandatory, application id, for a list of valid application ids refer to section 2. Parameter naming conventions
• act – mandatory, learning object, the user has been working with
• sub – mandatory/optional (depending on application), the step of the learning object (if such exists)
• usr – mandatory, user whose activity is reported
• grp – mandatory, group, user is member of
• sid – mandatory, the id of the session (for tracking purposes), a token of up to 5 characters
• res – mandatory, the result of interaction, 0 if unsuccessful, 1 if successful, or any value in between in case of partial success, -1 is reserved for "no credit" activity
• svc – optional, an arbitrary string the application might want to store for later (e.g. capturing context), not parsed by user modeling server
• ip - optional, ip address of the remote user

Example request URL:

http://adapt2.sis.pitt.edu/cbum/um?app=3&act=helloworld.c&sub=12&usr=myudelson&grp=200721&sid=FD34A&res=1&svc=adaptive_link

Using Report API to send reports to User Model

A special ReportAPI class can be used to send HTTP Get requests to User Model. Refer to example below. To use ReportAPI class, download paws-cbum-reportapi.jar that contains appropriate classes.

import edu.pitt.sis.paws.cbum.report.*;
...
int app_id = ...;
String act = ...;
String sub = ...;
String sid = ...;
double res = ...;
String grp = ...;
String usr = ...;
String svc = ...;
// initialize ReportAPI object with URL of the User Model
ReportAPI r_api = new ReportAPI("http://adapt2.sis.pitt.edu/cbum/um");
try
{
   //Send report
   r_api.report(app_id, act, sub, sid, res, grp, usr, svc);
}
catch (ServletException se) ...
catch (IOException ioe)...

Sending reports from Applets via relay servlet

When a learning object is implemented as Java Applet it is sometimes not possible to send reports to remote servers via HTTP Get requests due to security limitation. To overcome this obstacle, a local relay servlet can be used. Below is a step-by-step procedure of deploying configuring a relay servlet that we have created.

1. Download paws-cbum-reportapi.jar that contains appropriate classes and put it to WEB-INF/lib' folder of your project
2. Add the following lines to the web.xml file in WEB-INF folder of your project (refer to example below)
3. Send user activity report requests to http://localhost:8080/your_application/your_servlet_pattern. They will be forwarded to remote UM server appropriately. Here your_application (e.g. problets) is a folder of your project, and your_servlet_pattern is the same as configured in web.xml file (e.g. um_relay).

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.4"
   xmlns="http://java.sun.com/xml/ns/j2ee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
   http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
   ...
   <context-param>
      <param-name>umrelay</param-name>
      <param-value>http://adapt2.sis.pitt.edu/cbum/um</param-value>
   </context-param>
   ...
   <servlet>
      <servlet-name>UMActivityReportRelay</servlet-name>
      <servlet-class>edu.pitt.sis.paws.cbum.report.UMActivityReportRelay</servlet-class>
   </servlet>
   <servlet-mapping>
      <servlet-name>UMActivityReportRelay</servlet-name>
      <url-pattern>your_servlet_pattern</url-pattern>
   </servlet-mapping>
   ...
</web-app>

Protocols for requesting user progress

User progress is measured with respect to completeness of exploration of learning objects. Progress is described in terms of: 1) now many steps of the learning objet were explored, 2) how many attempts user has made while exploring. Information about user progress can be requested in XML format and in the format of Java serialized objects.

Getting user progress report in an XML format

Brief description: This protocol allows requesting user progress with a set of learning objects in an XML format. The set of learning objects are constrained by specifying application that serves learning objects and possibly a scope - group of learning objects within that application. In addition to individual user progress an average user progress can be requested (for example to implement social navigation).

Request URL Format:

http://<report_manager>?typ=<information_type>&dir=<upload_request>&frm=<format>&app=<application_id>&usr=<user>&gpr=<group>&scp=<scope>

,where:

• typ – mandatory, type of report, here should always be act (user action, learning object)
• dir – mandatory, direction of communication with report manager, should always be out (report manager only sending information nothing is taken in) for GET requests
• frm – mandatory, format, e.g. for xml report should be xml
• app – mandatory, application id, for a list of valid application ids refer to section Parameter Naming Conventions
• usr – mandatory, user who's progress report is requested
• grp – mandatory, user group, if present an average group report will be added to individual user report

Example request URL:

http://adapt2.sis.pitt.edu/cbum/ReportManager?typ=act&dir=out& frm=xml&app=2&usr=myudelson

XML Example: Below is an example of the returned XML, where learning object 2dimensional_array1 with 3 steps: 1, 2, and 3 that have been performed 25, 12, and 3 times respectively and the user progress for those steps is .3, .2, and .1 respectively.

<?xml version='1.0' encoding='UTF-8'?>
<report>
   <user>myudelson</user>
   <activities>
      <activity>
         <name>2dimensional_array1</name>
         <subactivity>
            <name>0</name>
            <individual>
               <count>25</count>
               <progress>0.3</progress>
            </individual>
         </subactivity>
         <subactivity>
            <name>1</name>
            <individual>
               <count>12</count>
               <progress>0.2</progress>
            </individual>
         </subactivity>
         <subactivity>
            <name>2</name>
            <individual>
               <count>3</count>
               <progress>0.1</progress>
            </individual>
         </subactivity>
      </activity>
   </activities>
</report>

Getting user progress report in the format of Java serialized objects

Brief description: This protocol works in a similar fashion as the one in the previous section Getting user progress report in an XML format. In addition it allows to submit requests for specific set of learning objects within application-scope hierarchy. There are two scenarios for requesting the report:

1. Requesting user progress with learning objects of a whole application or application scope, or
2. Requesting user progress with a limited subset of learning objects of the application or application scope.

In both scenarios receiving of the report is identical. In the second case a list of the requested learning objects' character IDs should be uploaded to the Report Manager web-service.

In order to be able to parse the response of the Report Manager you need to include edu.pitt.sis.paws.cbum.structures.report.ProgressEstimatorReport class from paws-cbum-reportapi.jar file.

Request URL Format:

http://<report_manager>?typ=<information_type>&dir=<upload_request>&frm=<format>&app=<application_id>&usr=<user>&gpr=<group>&scp=<scope>

,where:

• typ – mandatory, type of report, here should always be act (user progress with a learning object)
• dir – mandatory, upload request flag, should be either out (if scenario 1 is used) or in (if scenario 2 is user)
• frm – mandatory, format, for Java serialized objects report should be dat
• app – mandatory, application id, for a list of valid application ids refer to section Parameter Naming Conventions
• usr – mandatory, user whose progress is requested
• grp – mandatory, user group, if present an average group report will be added to individual user report

Example request URL:

http://adapt2.sis.pitt.edu/cbum/ReportManager?typ=act&dir=out&frm=dat&app=2&usr=myudelson

This request will return result equivalent to the XML returned by the example request of the previous section.

Java example 1: Using scenario 1 to request user progress with all learning objects of application with id 12

import java.net.*;
import java.util.*;
import java.edu.pitt.sis.paws.cbum.structures.report.ProgressEstimatorReport;
...
String report_manager_url = "http://adapt2.sis.pitt.edu/cbum/ReportManager";
String user_login = "myudelson";
String application_id= "12";
ArrayList um_response = null; // report will be saved in this variable
try
{
   // requesting report - dir=out
   URL url = new URL(report_manager_url + "?typ=act&dir=out&frm=dat&app=" +
      application_id + "&usr=" + user_login);
   URLConnection conn = url.openConnection();
   ObjectInputStream recv_stream = new ObjectInputStream(conn.getInputStream());
   try
   {
      um_response = (ArrayList)recv_stream.readObject();
   }
   catch(Exception e) { e.printStackTrace(System.err); }
   finally { recv_stream.close(); }
   
   // parsing the report
   double user_progress = 0.0;
   for(int i=0; i<um_response.size(); i++)
   {
      user_progress = ((ProgressEstimatorReport)um_response.get(i)).progress;
      // save user_progress elsewhere
      ...
   }
   ...
}
catch(Exception e) { e.printStackTrace(System.out); }

Java example 2: Using scenario 2 to request user progress with 2 learning objects lo_one and lo_two of application with id 12

import java.net.*;
import java.util.*;
import java.edu.pitt.sis.paws.cbum.structures.report.ProgressEstimatorReport;
...
String report_manager_url = "http://adapt2.sis.pitt.edu/cbum/ReportManager";
String user_login = "myudelson";
String application_id= "12";
ArrayList um_response = null; // report will be saved in this variable
ArrayList request = null; // request will be formed in this variable
try
{
   // create the request
   request = new ArrayList();
   request.add(new ProgressEstimatorReport("lo_one", 0, 0));;
   request.add(new ProgressEstimatorReport("lo_two", 0, 0));;
   
   // upload the request - dir=in
   URL url = new URL(report_manager_url + "?typ=act&dir=in&frm=dat&app=" +
      application_id + "&usr=" + user_login);
   URLConnection conn = url.openConnection();
   conn.setUseCaches(false);
   conn.setDefaultUseCaches(false);
   conn.setDoOutput(true);
   conn.setDoInput(true);
   conn.setRequestProperty("Content-Type","java-internal/" + req.getClass().getName());
   ObjectOutputStream send_strean = new ObjectOutputStream(conn.getOutputStream());
   send_strean.writeObject(req);
   send_strean.flush();
   send_strean.close();
   
   // receiving report
   ObjectInputStream recv_stream = new ObjectInputStream(conn.getInputStream());
   try
   {
      um_response = (ArrayList)recv_stream.readObject();
   }
   catch(Exception e) { e.printStackTrace(System.err); }
   finally { recv_stream.close(); }
   
   // parsing the report
   double user_progress = 0.0;
   for(int i=0; i<um_response.size(); i++}
   {
      user_progress = ((ProgressEstimatorReport)um_response.get(i)).progress;
      // save user_progress elsewhere
   }
   ...
}
catch(Exception e) { e.printStackTrace(System.out); }