LMS-Tutor Integration
Last updated June 11, 2013
CTAT 3.2
This pages collects documentation on the integration of CTAT tutors into a Learning Management System (LMS).
Files
Tutor-LMS Communication
Initial tutor display
To start a problem set, the LMS server needs to be able to execute a command that sends an HTML page with an 'object' tag included. We refer to this command as the 'run problem' command. For our Tutorshop LMS, the object tag for one of our example tutors (Decimal Addition/Birthday, linked above) looks like this:
<object style="visibility: visible;" id="flash-50531-1" data="/tutors/problem_sets/Current/decimal_addition/Flash/DecimalAdditionCS5.swf" name="flash-50531-1" type="application/x-shockwave-flash" height="550.0" width="920.0"> <param name="quality" value="high"> <param name="seamlesstabbing" value="false"> <param name="wmode" value="opaque"> <param name="allowscriptaccess" value="always"> <param name="flashvars" value="session_timeout=1800&tutoring_service_communication=socket&authenticity_token=9RyaHZgEnFTyMFqSvJTin3IoZGK2sdjfueskYnztyxY%3D&remoteSocketURL=ctat5.hcii.cs.cmu.edu&remoteSocketPort=80&reuse_swf=false&target_frame=&problem_state_status=empty&SessionLog=true&Logging=ClientToService&log_service_url=http://pslc-qa.andrew.cmu.edu/log/server&curriculum_service_url=https://preview.pact.cs.cmu.edu/process_student_assignment/50531/1&run_problem_url=https://preview.pact.cs.cmu.edu/run_student_assignment/50531&restore_problem_url=https://preview.pact.cs.cmu.edu/restore_student_assignment/50531/1&expire_logout_url=https://preview.pact.cs.cmu.edu/expire_logout&refresh_session_url=https://preview.pact.cs.cmu.edu/refresh_session&question_file=tutors/problem_sets_dev/Current/decimal_addition/FinalBRDs/birthday.brd&student_interface=/tutors/problem_sets/Current/decimal_addition/Flash/DecimalAdditionCS5.swf&BehaviorRecorderMode=AuthorTimeTutoring&source_id=FLASH_PSEUDO_TUTOR&instrumentation_log=on&show_debug_traces=false&info=%3Cdiv+id%3D%27label%27%3EDecimal+Addition%3A%3C%2Fdiv%3E%3Cdiv+id%3D%27caption%27%3E+Page+1+of+2%3C%2Fdiv%3E&skills=%3Cskills%3E%3Cskill+pKnown%3D%220.25%22+category%3D%22Decimal-Addition-and-Subtraction%22+label%3D%22Choose+operation%22+pLearn%3D%220.2%22+description%3D%22Choose+operation%22+pGuess%3D%220.2%22+pSlip%3D%220.1%22+opportunityCount%3D%220%22+name%3D%22Choose_operation%22%2F%3E%3Cskill+pKnown%3D%220.25%22+category%3D%22Decimal-Addition-and-Subtraction%22+label%3D%22Enter+addends%22+pLearn%3D%220.2%22+description%3D%22Enter+addends%22+pGuess%3D%220.2%22+pSlip%3D%220.1%22+opportunityCount%3D%220%22+name%3D%22Enter_addends%22%2F%3E%3Cskill+pKnown%3D%220.25%22+category%3D%22Decimal-Addition-and-Subtraction%22+label%3D%22Enter+decimal+point%22+pLearn%3D%220.2%22+description%3D%22Enter+decimal+point%22+pGuess%3D%220.2%22+pSlip%3D%220.1%22+opportunityCount%3D%220%22+name%3D%22Enter_decimal_point%22%2F%3E%3Cskill+pKnown%3D%220.25%22+category%3D%22Decimal-Addition-and-Subtraction%22+label%3D%22Sub+column+with+borrow%22+pLearn%3D%220.2%22+description%3D%22Sub+column+with+borrow%22+pGuess%3D%220.2%22+pSlip%3D%220.1%22+opportunityCount%3D%220%22+name%3D%22Sub_column_with_borrow%22%2F%3E%3Cskill+pKnown%3D%220.25%22+category%3D%22Decimal-Addition-and-Subtraction%22+label%3D%22Sub+column+with+no+borrow%22+pLearn%3D%220.2%22+description%3D%22Sub+column+with+no+borrow%22+pGuess%3D%220.2%22+pSlip%3D%220.1%22+opportunityCount%3D%220%22+name%3D%22Sub_column_with_no_borrow%22%2F%3E%3C%2Fskills%3E&user_guid=ts01&session_id=Sa97c8b59cdd83ffaa2b38a75cc258163&dataset_name=Tutorshop Dev&dataset_level_type1=Assignment&dataset_level_name1=Test Assignment&dataset_level_type2=ProblemSet&dataset_level_name2=decimal_addition&problem_name=birthday&problem_context=Birthday&problem_tutorflag=tutor&class_name=Test Sites&school_name=Admin&instructor_name=testsites&study_condition_name1=&study_condition_type1=Condition&"> </object>
The object tag could be generated statically or dynamically, using a JavaScript utility like swfobject.js. For IE the 'type' attribute needs to be replaced with 'classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"'.
The flashvar parameters are described elsewhere. Some LMSs might not need all of them, depending on the configuration. A large part of the flashvars string consists of an escaped XML string of skills, which can be used by the tutor in displaying skill bars and potentially by the LMS for problem selection. When unescaped and formatted, the skills string in the example above looks like this:
<skills> <skill pKnown="0.25" category="Decimal-Addition-and-Subtraction" label="Choose operation" pLearn="0.2" description="Choose operation" pGuess="0.2" pSlip="0.1" opportunityCount="0" name="Choose_operation"/> <skill pKnown="0.25" category="Decimal-Addition-and-Subtraction" label="Enter addends" pLearn="0.2" description="Enter addends" pGuess="0.2" pSlip="0.1" opportunityCount="0" name="Enter_addends"/> <skill pKnown="0.25" category="Decimal-Addition-and-Subtraction" label="Enter decimal point" pLearn="0.2" description="Enter decimal point" pGuess="0.2" pSlip="0.1" opportunityCount="0" name="Enter_decimal_point"/> <skill pKnown="0.25" category="Decimal-Addition-and-Subtraction" label="Sub column with borrow" pLearn="0.2" description="Sub column with borrow" pGuess="0.2" pSlip="0.1" opportunityCount="0" name="Sub_column_with_borrow"/> <skill pKnown="0.25" category="Decimal-Addition-and-Subtraction" label="Sub column with no borrow" pLearn="0.2" description="Sub column with no borrow" pGuess="0.2" pSlip="0.1" opportunityCount="0" name="Sub_column_with_no_borrow"/> </skills>
End-of-problem communication
At the end of a problem, when the student clicks on the 'Done' button, the Flash tutor sends to the LMS server a POST command with the URL specified in the 'curriculum_service_url' flashvar, and with a body containing a number of parameters, similar to this example:
session_id=S5a3e84a6b1bbd40208a702e7e4389e61&authenticity_token=9RyaHZgEnFTyMFqSvJTin3IoZGK2sdjfueskYnztyxY=&school_name=Admin&user_guid=ts00&summary=%3CProblemSummary%20ProblemName%3D%22birthday%22%20CompletionStatus%3D%22complete%22%20Correct%3D%2222%22%20UniqueCorrect%3D%2222%22%20UniqueCorrectUnassisted%3D%2222%22%20Hints%3D%220%22%20UniqueHints%3D%220%22%20HintsOnly%3D%220%22%20Errors%3D%220%22%20UniqueErrors%3D%220%22%20ErrorsOnly%3D%220%22%20UniqueSteps%3D%2222%22%20TimeElapsed%3D%2277450%22%3E%3CSkills%3E%3CSkill%20name%3D%22Choose_operation%22%20category%3D%22Decimal-Addition-and-Subtraction%22%20description%3D%22Choose%20operation%22%20label%3D%22Choose%20operation%22%20opportunityCount%3D%221%22%20pGuess%3D%220.2%22%20pKnown%3D%220.68%22%20pLearn%3D%220.2%22%20pSlip%3D%220.1%22%20%2F%3E%3CSkill%20name%3D%22Enter_addends%22%20category%3D%22Decimal-Addition-and-Subtraction%22%20description%3D%22Enter%20addends%22%20label%3D%22Enter%20addends%22%20opportunityCount%3D%229%22%20pGuess%3D%220.2%22%20pKnown%3D%220.9999995%22%20pLearn%3D%220.2%22%20pSlip%3D%220.1%22%20%2F%3E%3CSkill%20name%3D%22Enter_decimal_point%22%20category%3D%22Decimal-Addition-and-Subtraction%22%20description%3D%22Enter%20decimal%20point%22%20label%3D%22Enter%20decimal%20point%22%20opportunityCount%3D%223%22%20pGuess%3D%220.2%22%20pKnown%3D%220.9856923%22%20pLearn%3D%220.2%22%20pSlip%3D%220.1%22%20%2F%3E%3CSkill%20name%3D%22Sub_column_with_borrow%22%20category%3D%22Decimal-Addition-and-Subtraction%22%20description%3D%22Sub%20column%20with%20borrow%22%20label%3D%22Sub%20column%20with%20borrow%22%20opportunityCount%3D%224%22%20pGuess%3D%220.2%22%20pKnown%3D%220.99742776%22%20pLearn%3D%220.2%22%20pSlip%3D%220.1%22%20%2F%3E%3CSkill%20name%3D%22Sub_column_with_no_borrow%22%20category%3D%22Decimal-Addition-and-Subtraction%22%20description%3D%22Sub%20column%20with%20no%20borrow%22%20label%3D%22Sub%20column%20with%20no%20borrow%22%20opportunityCount%3D%224%22%20pGuess%3D%220.2%22%20pKnown%3D%220.99742776%22%20pLearn%3D%220.2%22%20pSlip%3D%220.1%22%20%2F%3E%3C%2FSkills%3E%3C%2FProblemSummary%3E&problem_state=<messages>...</messages>
The 'session_id', 'authenticity_token', 'school_name', and 'user_guid' have the same values that the tutor received in the flashvars. They might not be needed, depending on LMS configuration. The important values are the problem summary and the problem state. The 'summary' parameter is an escaped XML structure containing the problem summary, which after unescaping and formatting looks like this:
<ProblemSummary ProblemName="birthday" CompletionStatus="complete" Correct="22" UniqueCorrect="22" UniqueCorrectUnassisted="22" Hints="0" UniqueHints="0" HintsOnly="0" Errors="0" UniqueErrors="0" ErrorsOnly="0" UniqueSteps="22" TimeElapsed="77450">
<Skills>
<Skill name="Choose_operation" category="Decimal-Addition-and-Subtraction" description="Choose operation" label="Choose operation" opportunityCount="1" pGuess="0.2" pKnown="0.68" pLearn="0.2" pSlip="0.1" />
<Skill name="Enter_addends" category="Decimal-Addition-and-Subtraction" description="Enter addends" label="Enter addends" opportunityCount="9" pGuess="0.2" pKnown="0.9999995" pLearn="0.2" pSlip="0.1" />
<Skill name="Enter_decimal_point" category="Decimal-Addition-and-Subtraction" description="Enter decimal point" label="Enter decimal point" opportunityCount="3" pGuess="0.2" pKnown="0.9856923" pLearn="0.2" pSlip="0.1" />
<Skill name="Sub_column_with_borrow" category="Decimal-Addition-and-Subtraction" description="Sub column with borrow" label="Sub column with borrow" opportunityCount="4" pGuess="0.2" pKnown="0.99742776" pLearn="0.2" pSlip="0.1" />
<Skill name="Sub_column_with_no_borrow" category="Decimal-Addition-and-Subtraction" description="Sub column with no borrow" label="Sub column with no borrow" opportunityCount="4" pGuess="0.2" pKnown="0.99742776" pLearn="0.2" pSlip="0.1" />
</Skills>
</ProblemSummary>
The meaning of the ProblemSummary attributes and skill elements are described in more detail here. The Skills list has the same format as in the flashvars, but contains values updated after the student interaction with the tutor.
The 'problem_state' parameter is an XML structure containing a number of 'message' elements which describe the current state of the tutor. The LMS doesn't need to know or interpret the structure in any way, it only needs to store it in some place, so it can send it back to the tutor on request.
The LMS only needs to acknowledge the command by sending back an empty response. The the tutor will then send a GET command to the URL from the 'run_problem_url' flashvar, which is a command to request the next tutor, similar to the one that initiated the current tutor. This 'run problem' command also specifies a frame target for running the next tutor, taken from the 'target_frame' flashvar. If the target is empty, the next tutor will be run in the same HTML frame as the current one.
Normal problem-to-problem sequence
Saving/restoring problem state
In the case where a tutor is closed before it is finished (by the student closing its window), it can be asked to save the current state of the problem. The request is made from JavaScript by calling the object tag's 'saveAndQuit' method with no arguments. On such a request the tutor will run the same POST command with the url given by the 'curriculum_service_url' flashvar as in the case when the problem is finished. As mentioned above, this command sends both the problem state and the problem summary to the LMS server. Upon completion of the command, the tutor will call back a JavaScript 'exitAssignment' global method with no arguments, which should perform the actual window closing.
Saving state on student exit before finishing problem
When the server is starting the tutor again on the next session, as part of the process of restoring the initial state, the tutor examines the value of the 'problem_state_status' flashvar received from the LMS server. This value could be 'empty', 'incomplete', or 'complete'. If the value is 'incomplete' or 'complete', the tutor knows that a previous state was saved for this particular problem. It can then request the saved state by sending a GET command with the URL specified by the 'restore_problem_url' flashvar. The LMS's response to this command should be just the value of the 'problem_state' parameter received previously.
Restoring state on student exit before finishing problem
