Documentation:WeBWorK/LTI

From UBC Wiki
Jump to: navigation, search

Example Control Flow

LTI Launch Request

A LTI Launch Request is basically LTI's version of a handshake between two applications. The tool that is issuing an LTI Launch Request is called the Tool Consumer while the tool that receives the LTI Launch Request is called the Tool Producer. The Tool Consumer is usually the LMS, in our case, Blackboard Learn. The Tool Producer in this case is Webwork. The Tool Consumer puts information about its user and itself into the launch request. The user information is meant to allow single sign on authentication. The Tool Consumer information is mainly for advertising which LTI features is enabled/supported. The Tool Producer uses that information to pull data from the Tool Consumer.

The launch request is submitted as a HTTP POST request to the launch url of the targetted tool, which for Webwork is just the application url. The following is a list of parameters sent by the Blackboard LTI Building Block for a Webwork launch. These parameters are sent in the POST body as an urlencoded string (exactly like an html form submit).

Core Standard

OAuth Message Signing Parameters

Note that these parameters may either be in the POST body or in the Authorization section of the HTTP header. You can usually trick an OAuth library to do the signature verification for you, but there is a concise guide to the OAuth HMAC calculation process if you need to roll a custom verifier.

oauth_consumer_key => 'lti_secret'
oauth_signature => 'pB0aq142aVslYuTEHH56472a3Aw='
oauth_callback => 'about:blank' # always about:blank since lti doesn't use it
oauth_version => '1.0'
oauth_signature_method => 'HMAC-SHA1' # all lti implementation must support hmac-sha1
oauth_timestamp => '1367278573'
oauth_nonce => '352281230342435'

Required Parameters

lti_version => 'LTI-1p0'
lti_message_type => 'basic-lti-launch-request'
resource_link_id => 'CL.UBC.MATH.101.201.2012W2.13204' # the course ID
lis_person_sourcedid => 'john' # will be the PUID on Connect, though is configurable using the LTI Building Block

Outcomes Service parameters

Used to push grades. Note that this is only avavailable with LTI 1.1 support. We're still using the extension support as it's more fully featured.

lis_outcome_service_url => 'http://137.82.12.118/webapps/ubc-Webwork-BBLEARN/service'

Optional informational parameters

Information about the application that the user is coming from.

tool_consumer_instance_url => 'http://137.82.12.118'
tool_consumer_info_product_family_code => 'learn'
tool_consumer_instance_name => 'UBC'
tool_consumer_instance_description => 'University of British Columbia'
tool_consumer_instance_guid => 'lti_secret'
tool_consumer_info_version => '9.1.110082'

Context information, usually course information.

context_id => 'CL.UBC.MATH.101.201.2012W2.13204'
context_type => 'CourseSection'
context_title => '2012W2-MATH101-201- Integral Calculus with Applications to Physical Sciences and Engineering-Instructors'
context_label => 'CL.UBC.MATH.101.201.2012W2.13204'

Personal information on who is making the launch request

user_id => ''
roles => 'Instructor'
lis_person_contact_email_primary => ''
lis_person_name_family => 'Hsu,ø'
lis_person_name_given => 'John'
lis_person_name_full => 'John Hsu,ø'

Course which is making this request

lis_course_offering_sourcedid => 'CL.UBC.MATH.101.201.2012W2.13204'
lis_course_section_sourcedid => 'CL.UBC.MATH.101.201.2012W2.13204'
launch_presentation_return_url => 'http://137.82.12.118/webapps/ubc-Webwork-BBLEARN/return.jsp?id=webworkdev&course_id=_101_1&course_id=_101_1&lti_page=ctools&'
launch_presentation_document_target => 'frame'
launch_presentation_locale => 'en_GB'
resource_link_title => 'webworkdev'

Unofficial Extensions

Even though these extensions are technically not part of the LTI specs, they're so widely implemented that it's gained de facto recognition, as they're documented on the official site: http://developers.imsglobal.org/extensions.html

Memberships Extension Service parameters

Used to pull class rosters from Connect.

ext_ims_lis_memberships_id => ':_101_1::webworkdev:1367278573'
ext_ims_lis_memberships_url => 'http://137.82.12.118/webapps/ubc-Webwork-BBLEARN/extension'

Outcomes Extension Service parameters

Used to push grades to Connect. A significant limitation is that officially, it's designed to push only 1 grade at a time and the student must initiate the push. A custom workaround was devised so that it's more like membership requests, which allows batch syncing and can push grades at any time.

ext_ims_lis_resultvalue_sourcedids => 'decimal,percentage,ratio,passfail,letteraf,letterafplus,freetext'
ext_ims_lis_basic_outcome_url => 'http://137.82.12.118/webapps/ubc-Webwork-BBLEARN/extension'

Informational

ext_lms => 'learn-9.1.110082'

Custom Parameters

It's a flag for Webwork to perform grade syncing operations.

custom_gradesync => '1'

LTI Membership Extension Request

Like the launch request, a membership request is a HTTP POST request and also requires the OAuth parameters. Besides the OAuth parameters, this request requires 3 other parameters. The HTTP POST request is submitted to the ext_ims_lis_memberships_url parameter given in the launch request. In this example, the url is http://137.82.12.118/webapps/ubc-Webwork-BBLEARN/extension. This extension is documented here.

This is the id used to identify the course and is given by the ext_ims_lis_memberships_id parameter given in the launch request.

id=:_101_1::webworkdev:1367278573

This parameter is required to indicate a membership request.

lti_message_type=basic-lis-readmembershipsforcontext

This parameter is required to indicate an LTI request.

lti_version=LTI-1p0

If successful, you will receive an XML formatted list of users in the course.


<message_response>
  <lti_message_type>basic-lis-readmembershipsforcontext</lti_message_type>
  <statusinfo>
    <codemajor>Success</codemajor>
    <severity>Status</severity>
    <codeminor>fullsuccess</codeminor>
    <description>Roster retrieved</description>
  </statusinfo>
  <memberships>
    <member>
      <user_id></user_id>
      <roles>Instructor</roles>
      <person_sourcedid>john</person_sourcedid>
      <person_contact_email_primary></person_contact_email_primary>
      <person_name_given>John</person_name_given>
      <person_name_family>Hsu,ø</person_name_family>
      <person_name_full>John Hsu,ø</person_name_full>
    </member>
    <member>
      <user_id>0004</user_id>
      <roles>Learner</roles>
      <person_sourcedid>redshirt0004</person_sourcedid>
      <person_contact_email_primary></person_contact_email_primary>
      <person_name_given>shirt0004</person_name_given>
      <person_name_family>red0004</person_name_family>
      <person_name_full>shirt0004 red0004</person_name_full>
      <lis_result_sourcedid>:_101_1::webworkdev:0004</lis_result_sourcedid>
    </member>
    <member>
      <user_id>0001</user_id>
      <roles>Learner</roles>
      <person_sourcedid>redshirt0001</person_sourcedid>
      <person_contact_email_primary></person_contact_email_primary>
      <person_name_given>shirt0001</person_name_given>
      <person_name_family>red0001</person_name_family>
      <person_name_full>shirt0001 red0001</person_name_full>
      <lis_result_sourcedid>:_101_1::webworkdev:0001</lis_result_sourcedid>
    </member>
    <member>
      <user_id>0002</user_id>
      <roles>Learner</roles>
      <person_sourcedid>redshirt0002</person_sourcedid>
      <person_contact_email_primary></person_contact_email_primary>
      <person_name_given>shirt0002</person_name_given>
      <person_name_family>red0002</person_name_family>
      <person_name_full>shirt0002 red0002</person_name_full>
      <lis_result_sourcedid>:_101_1::webworkdev:0002</lis_result_sourcedid>
    </member>
    <member>
      <user_id>0003</user_id>
      <roles>Learner</roles>
      <person_sourcedid>redshirt0003</person_sourcedid>
      <person_contact_email_primary></person_contact_email_primary>
      <person_name_given>shirt0003</person_name_given>
      <person_name_family>red0003</person_name_family>
      <person_name_full>shirt0003 red0003</person_name_full>
      <lis_result_sourcedid>:_101_1::webworkdev:0003</lis_result_sourcedid>
    </member>
  </memberships>
</message_response>

If unsuccessful, you should get an XML formatted error message.


<message_response>
  <lti_message_type>basic-lis-readmembershipsforcontext</lti_message_type>
  <statusinfo>
     <codemajor>Failure</codemajor>
     <severity>Error</severity>
     <codeminor>Invalid signature/codeminor>
  </statusinfo>
</message_response>

LTI Outcomes Extension Request

Like all other LTI requests, this is a HTTP POST request that requires all the OAuth parameters. Besides the OAuth parameters, this request has 5 other parameters. Note that the example shown here has been slightly modified to allow automatic course sync and might only work with the Webwork Building Block we modified for this purpose. The original intended use for this extension was that each and every student has to press a button in order to send their own individual grade back to the LMS. This extension is documented here.

Required to flag this as an Outcomes request.

lti_message_type=basic-lis-updateresult

Required to flag this as a LTI request.

lti_version=LTI-1p0

This is the score value.

result_resultscore_textstring=0/2

This determines how it'll handle the score value. The available options are listed as a comma separated list in the launch request parameter ext_ims_lis_resultvalue_sourcedids.

result_resultvaluesourcedid=ratio

The sourced ID has 5 components: :context id:hash:tool consumer name:student number:assignment name

The components are actually assembled from the lis_result_sourcedid returned with each student in the Membership request. You just append the assignment name to it. This is where our implementation differs from the stock implementation, in stock, you would need to create the grading column in Blackboard for each and every assignment that needs to be synced first, whereas our implementation will create a grading column in Blackboard if it needs to.

sourcedid=:_101_1::webworkdev:0004:blah

If successful, you'll get a XML formatted response saying that the value was set:


<message_response>
  <lti_message_type>basic-lis-updateresult</lti_message_type>
  <statusinfo>
    <codemajor>Success</codemajor>
    <severity>Status</severity>
    <codeminor>fullsuccess</codeminor>
    <description>Grade updated</description>
  </statusinfo>
  <result>
    <sourcedid>:_101_1::webworkdev:0001:blah</sourcedid>
    <personsourcedid>redshirt0001</personsourcedid>
    <date>2013-05-01T21:28:39Z</date>
    <resultscore>
      <resultvaluesourcedid>ratio</resultvaluesourcedid>
      <textstring>2/2</textstring>
    </resultscore>
  </result>
</message_response>

If unsuccessful, you should get a XML error message similar to Membership request's error message.

Installation in Webwork

Additional Package Needed

  • perl-Text-CSV.noarch
  • perl-Net-OAuth.noarch
  • perl-XML-Simple.noarch

LTI

  • Additional files:
lib/WebworkBridge
lib/WeBWorK/Authen/LTI.pm
lib/WeBWorK/Authen/VistaLogin2.pm
lib/WeBWorK/ContentGenerator/WebworkBridgeStatus.pm
  • Modified files:
lib/WeBWorK.pm
conf/global.conf