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:

<?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>

1. 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).