Difference between revisions of "CUMULATE protocol"
(→Parameter Naming Conventions) |
(→Parameter Naming Conventions) |
||
Line 41: | Line 41: | ||
** '''23''' – SQL KnoT | ** '''23''' – SQL KnoT | ||
** '''24''' – ADAPT² PService | ** '''24''' – ADAPT² PService | ||
+ | ** '''25''' – QuizJET | ||
* '''act''' – learning action, learning object – minimally invokable piece of learning object (quiz, example etc.) | * '''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.) | * '''sub''' – sub-action, step of learning action, fragment of learning object – minimal trackable piece of learning object (question of quiz, line of example etc.) |
Revision as of 14:08, 18 October 2010
This page describes the protocol of interaction with CUMULATE and provides an exhaustive references with code examples in Java and sample outputs in XML.
Contents
- 1 URLs of web-services
- 2 Parameter Naming Conventions
- 3 Protocol for user authentication and activity invocation
- 4 Protocol for reporting user activity
- 5 Protocol for reporting changes in user knowledge
- 6 Protocol for requesting user progress
- 7 Protocol for requesting user knowledge of concepts
- 8 Protocol for Requesting Concept-Activity Indexing
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
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 – SQL-Tutor
- 20 – QuizQUIDE
- 21 – jWADEIn II
- 22 – free slot
- 23 – SQL KnoT
- 24 – ADAPT² PService
- 25 – QuizJET
- 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)
- synthesis
- 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 user authentication and activity invocation
This protocol is adopted not only by CUMULATE but by most of the ADAPT2 tools. It regulates how user and resource identities is transferred from application to application via the following HTTP parameters
- usr - user identifier, usually login (mandatory)
- grp - group identifier (mandatory), just like a user identifier, but for a group of users (class, research team)
- sid - session identifier (optional), usually 5 character string each application makes a choice whether and how to come up with this parameter (e.g. truncate | Apache Tomcat session id to last 5 characters)
- act - id of the resource (mandatory), each application maintains its own vocabulary of resource ids
- sub - if resource is a collection of multiple resources/steps, then a sub-resource id is supplied (optional)
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
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.
- 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>
Protocol for reporting changes in user knowledge
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://adapt2.sis.pitt.edu/cbum/umc?app=<application_id> &usr=<user> &grp=<group> &dom=<learning domain> &con=<concept list> &val=<result list> &sid=<session_id> &svc=<service_parameters>
,where:
- app – mandatory, application id, for a list of valid application ids refer to Parameter Naming Conventions
- usr – mandatory, user whose activity is reported
- grp – mandatory, group, user is member of
- dom – mandatory learning domain (e.g. C programming), from which the reported concepts are coming
- con – mandatory, comma-separated list of concept names
- val – mandatory, comma-separated list (same cardinality as con) of the results of concept application, each from [0, 1]
- sid – mandatory, the id of the session (for tracking purposes), a token of up to 5 characters
- svc – optional, an arbitrary string the application might want to store for later (e.g. capturing context), not parsed by user modeling server
Example request URL:
http://adapt2.sis.pitt.edu/cbum/umc?app=19&usr=joe&grp=class12&dom=sql_concepts&con=Table,MultipleTableSelection,WhereClause&val=-1,0.5,-1&sid=1&svc=5
There is no api support for this protocol yet.
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>
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); }
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, synthesis 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> <user-app-hash>2009-06-11 20:20:05.545</user-app-hash> <user-hash>2009-06-11 20:20:05.545</user-hash> <concepts> ... <concept> <name>add</name> <cog_levels> <cog_level> <name>application</name> <value>0.6266574470377776</value> </cog_level> </cog_levels> </concept> <concept> <name>sub</name> <cog_levels> <cog_level> <name>application</name> <value>0.36388277385950873</value> </cog_level> </cog_levels> </concept> ... </concepts> </report>
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); }
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>
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>