This page describes the protocol of interaction with CUMULATE and provides an exhaustive references with code examples in Java and sample outputs in XML.

1 URLs of web-services
2 Parameter Naming Conventions
3 Protocol for reporting user activity
- 3.1 Using Report API to send reports to User Model
- 3.2 Sending reports from Applets via relay servlet
4 Protocol for reporting changes in user knowledge (New)
5 Protocol for requesting user progress
- 5.1 Getting user progress report in an XML format
- 5.2 Getting user progress report in the format of Java serialized objects
6 Protocol for requesting user knowledge of concepts
- 6.1 Getting user knowledge of concepts report in an XML format
- 6.2 Getting user knowledge of concepts report in the format of Java serialized objects
7 Protocol for Requesting Concept-Activity Indexing
- 7.1 Getting Concepts for an Activity (List of Activities)
- 7.2 Getting Activities for a Concept (List of Concepts)

URLs of web-services

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

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

^top

Parameter Naming Conventions

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

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 – WOTAN
- 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.

^top

Protocol for reporting user activity

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

^top

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

^top

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.

Download paws-cbum-reportapi.jar that contains appropriate classes and put it to WEB-INF/lib' folder of your project
Add the following lines to the web.xml file in WEB-INF folder of your project (refer to example below)
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>

^top

Protocol for reporting changes in user knowledge (New)

Coming soon...

Protocol 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

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&grp=200721

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. In addition CUMULATE lets you know several other things:

the number of users in the group via member_count attribute of group tag (here 30)
the date-time of the most recent user transaction registered by CUMULATE for this user via user-hash tag
the date-time of the most recent user transaction registered by CUMULATE for this user and the application specified via user-app-hash tag

<?xml version='1.0' encoding='UTF-8'?>
<report>
   <user>myudelson</user>
   <user-app-hash>2007-11-07 16:30:54.497</user-app-hash>
   <user-hash>2007-11-28 12:03:45.250</user-hash>
   <group member_count="30">200721</group>
   <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>

^top

Getting user progress report in the format of Java serialized objects

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:

Requesting user progress with learning objects of a whole application or application scope, or
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 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&grp=200721

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 group = "200721";
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 + "&grp=" + group);
   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 group = "200721";
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 + "&grp=" + group);
   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); }

^top

Protocol for requesting user knowledge of concepts

User knowledge of concepts is measured as probability of knowing a portion of learning domain described by certain concepts. Information about user progress can be requested in XML format and in the format of Java serialized objects.

Getting user knowledge of concepts report in an XML format

This protocol allows various applications to obtain knowledge with respect to multiple Bloom levels for a set of concepts.

Request URL Format:

http://<report_manager>?typ=<information_type>&dir=<upload_request>&frm=<format>&app=<application_id>&usr=<user>&gpr=<group>&dom=<domain>&lev=<Bloom_level(s)>

,where:

typ – mandatory, type of report, here should always be con (concept progress)
dir – mandatory, upload request flag, should always be out (no upload) for GET requests
frm – mandatory, format, format, for XML report should be xml
app – mandatory, application id, for a list of valid application ids refer to Parameter Naming Conventions
usr – mandatory, user whose progress is requested
grp – mandatory, user group
lev – optional, Bloom levels to be reported, allowed values: knowledge, comprehension, application or a delimited list of them, if unspecified – all levels are reported
dom – mandatory, concepts' domain (ontology)

Example request URL:

http://adapt2.sis.pitt.edu/cbum/ReportManager?typ=con&dir=out&frm=xml&app=2&usr=myudelson&grp=200721&lev=application&dom=c_programming

Below is a n example of the returned XML. In addition CUMULATE lets you know several other things:

the date-time of the most recent user transaction registered by CUMULATE for this user via user-hash tag
the date-time of the most recent user transaction registered by CUMULATE for this user and the application specified via user-app-hash tag

<?xml version='1.0' encoding='UTF-8' ?>
<report>
   <user>myudelson</user>
   <concepts>
      <concept>
         <name>add</name>
         <cog_levels>
            <cog_level>
               <name>knowledge</name>
               <value>0.0</value>
            </cog_level>
            <cog_level>
               <name>comprehension</name>
               <value>0.032842249657064476</value>
            </cog_level>
         </cog_levels>
      </concept>
      ...
      </concepts>
</report>

^top

Getting user knowledge of concepts report in the format of Java serialized objects

The protocol is identical to one in the previous section 6.1. In addition it allows to submit requests for specific concepts rather than the whole realm of concepts or a domain of concepts. The report is returned in the form of Java serialized objects.

Request URL Format:

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

,where:

typ – mandatory, type of report, here should always be con (concept)
dir – mandatory, upload request flag, can be in or out, depending on whether you want to upload the ids of the concepts that you'd like to receive the report about
frm – mandatory, format, for Java serialized objects report should be dat
app – mandatory, application id, for a list of valid application ids refer to Parameter Naming Conventions
usr – mandatory, user whose progress is requested
grp – mandatory, user group
dom – mandatory, concepts' domain (ontology), if not specified the whole realm of concepts are reported

Example request URL:

http://adapt2.sis.pitt.edu/cbum/ReportManager?typ=con&dir=in&frm=dat&app=2&usr=myudelson&grp=200721&dom=c_programming

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

Java example 1: Requesting concepts of a specific domain
import java.net.*;
import java.util.*;
...
String report_manager_url = "http://adapt2.sis.pitt.edu/cbum/ReportManager";
String user_login = "myudelson";
String group = "200721";
String concept_cognitive_levels = "application";
String domain = "c_programming";
String application_id= "3";
ArrayList um_response = null; // user model report withh be saved in this variable
try
{
   URL url = new URL(report_manager_url + "?typ=con&dir=out&frm=dat&lev=" +
      concept_cognitive_levels +"&app=" + application_id +
      "&usr=" + user_login + "&grp=" + group + "&dom=" + domain);
   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(); }
}
catch(Exception e) { e.printStackTrace(System.out); }

^top

Protocol for Requesting Concept-Activity Indexing

For each of the activities (aka learning objects) CUMULATE can store a list of knowledge concepts from a particular domain. The following protocols expose this indexing.

Getting Concepts for an Activity (List of Activities)

This protocol lists concepts connected to a given activity (list of activities).

Request URL Format:

http://<report_manager>?typ=<information_type>&frm=<format>&app=<application_id>&act=<activity>&dom=<domain>

,where:

typ – mandatory, type of report, here should always be act2con (activity-to-concept mapping)
dir – mandatory, upload request flag, should be in
frm – mandatory, format, supported formats are XML and RDF - xml and rdf values respectively
app – mandatory, application id mapping of activities of which are requested, for a list of valid application ids refer to Parameter Naming Conventions
act – mandatory, activity, or a comma-delimited list of activities
dom – mandatory, domain of concepts

Example request URL (XML format):

http://adapt2.sis.pitt.edu/cbum/ReportManager?typ=act2con&dir=in&frm=xml&app=3&act=helloworld.c,printing.c&dom=c_programming

And the returned XML result:

<?xml version='1.0' encoding='UTF-8'?>
<report>
	<mappings>
		<mapping>
			<activity>helloworld.c</activity>
			<concept>printf</concept>
			<concept>main_function</concept>
			<concept>include</concept>
			<concept>void</concept>
		</mapping>
		<mapping>
			<activity>printing.c</activity>
			<concept>printf</concept>
			<concept>main_function</concept>
			<concept>include</concept>
			<concept>void</concept>
		</mapping>
	</mappings>
</report>

Example request URL (RDF format):

http://adapt2.sis.pitt.edu/cbum/ReportManager?typ=act2con&dir=in&frm=rdf&app=3&act=helloworld.c,printing.c&dom=c_programming

And the returned RDF result:

<?xml version='1.0' encoding='UTF-8'?>
<rdf:RDF
	xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
	xmlns:dc='http://purl.org/dc/elements/1.1/'>

	<rdf:Description rdf:about='http://adapt2.sis.pitt.edu/webex/webex.rdf#helloworld.c'>
		<dc:subject>printf</dc:subject>
		<dc:subject>main_function</dc:subject>
		<dc:subject>include</dc:subject>
		<dc:subject>void</dc:subject>
	</rdf:Description>
	<rdf:Description rdf:about='http://adapt2.sis.pitt.edu/webex/webex.rdf#printing.c'>
		<dc:subject>printf</dc:subject>
		<dc:subject>main_function</dc:subject>
		<dc:subject>include</dc:subject>
		<dc:subject>void</dc:subject>
	</rdf:Description>
</rdf:RDF>

^top

Getting Activities for a Concept (List of Concepts)

This protocol lists activities connected to a given concepts (list of concepts).

Request URL Format:

http://<report_manager>?typ=<information_type>&frm=<format>&app=<application_id>&con=<concept>&dom=<domain>

,where:

typ – mandatory, type of report, here should always be con2act (concept-to-activity mapping)
dir – mandatory, upload request flag, should be in
frm – mandatory, format, supported formats are XML and RDF - xml and rdf values respectively (RDF is not supported yet)
app – mandatory, application id activities of which concepts are mapped to, for a list of valid application ids refer to Parameter Naming Conventions
dom – mandatory, domain of concepts
con – mandatory, concept, or a comma-delimited list of concepts

Example request URL (XML format)

http://adapt2.sis.pitt.edu/cbum/ReportManager?typ=con2act&dir=in&frm=xml&app=3&con=printf,if_else&dom=c_programming

And the returned XML result:

<?xml version='1.0' encoding='UTF-8'?>
<report>
	<mappings>
		<mapping>
			<concept>printf</concept>
			<activity>abcounting.c</activity>
			<activity>abcounting_case.c</activity>
			<activity>accumulator.c</activity>
			...
		</mapping>
		<mapping>
			<concept>if_else</concept>
			<activity>abcounting.c</activity>
			<activity>babyweighting.c</activity>
			<activity>battleship.c</activity>
			<activity>betterbattle.c</activity>
			...
		</mapping>
	</mappings>
</report>

^top

Navigation menu

CUMULATE protocol

Contents

URLs of web-services

Parameter Naming Conventions

Protocol for reporting user activity

Using Report API to send reports to User Model

Sending reports from Applets via relay servlet

Protocol for reporting changes in user knowledge (New)

Protocol for requesting user progress

Getting user progress report in an XML format

Getting user progress report in the format of Java serialized objects

Protocol for requesting user knowledge of concepts

Getting user knowledge of concepts report in an XML format

Getting user knowledge of concepts report in the format of Java serialized objects

Protocol for Requesting Concept-Activity Indexing

Getting Concepts for an Activity (List of Activities)

Getting Activities for a Concept (List of Concepts)