View source for LTI Grade Pass Back (for WeBWorK 2.17 or older)

With the LTIAdvanced interface it is possible for WeBWorK to automatically pass grades back to your Learning Management System (LMS), e.g. Blackboard, Moodle, Canvas, etc...  However because we are using the more widespread, but also more restrictive, version 1.2 of LTI there are some quirks.  The way LTI grade passback works in version 1.2 is when you create the "Assignment" in your LMS that points to WeBWorK that "Assignment" gets a corresponding column in your LMS gradebook.  WeBWorK then returns a percentage grade which is used to assign the student grade in the LMS.  In particular there is exactly one column in the LMS grade book for each link to WeBWorK in the LMS and the '''only''' information passed back from WeBWorK to the LMS is the percentage grade.  Given this restriction there are two modes for the WeBWorK LTI grading interface.

* '''Course Grade Mode''': In this mode you create a single link/assignment in the LMS which points to WeBWorK.  WeBWorK will then return the "cumulative" homework grade as a percentage to the LMS.  In other words the grade in the LMS column is the course homework grade. 

* '''Homework Grade Mode''':  In this mode you create a single link/assignment in the LMS for each problem set in WeBWorK.  WeBWorK will then return the total score for the problem set to the LMS.  In other words you will have multiple columns in the LMS gradebook, one for each link, and they will be filled out with the student scores on individual WeBWorK problem sets.  

The first mode is the easiest to set up, but the second mode is more granular and ends up transferring more data to the LMS gradebook.

= First Time Setup =
If you haven't already you should set up LTI authentication.  See [[LTI-Advanced Authentication]] for details. 

== WeBWorK Setup ==

There are several configuration variables in authen_LTI.conf which need to be set to enable grade passback.  

'''$LTIGradeMode''' -  If this variable is not set then the grade passback feature is turned off.  If it is set to "course" then the Course Grade Mode described above is used.  If it is set to "homework" then the Homework Grade Mode described above is used. 

'''$LTIGradeOnSubmit''' - If this flag is enabled then WeBWorK will attempt to update student grades every time they submit an answer to a problem.  This keeps the student grades current, but can be a drain on your server.  If either the WeBWorK server or the LMS server bogs down it might be a good idea to turn this off. 

'''$LTIMassUpdateInterval''' - Because instructor activities like adding new sets, deleting problems, or marking problems correct can change student grades we periodically update all student grades just to make sure things are current.  This interval controls how often that mass update happens (in seconds).  It is set to 86400 (24 hours) be default and if it is set to -1 this feature will be disabled.   

== LMS Setup ==

In addition to configuring WeBWorK you may also need to enable the grading feature on your LMS.  How this works varies among different LMS.  I will describe how to configure Blackboard, Moodle, and Canvas. 
* '''Blackboard''' - There is a global flag which controls if Tools are allowed to submit grades.  You will need administrator access to change this.
#  In the Administrator Panel go to Building Blocks > LTI Tool Providers > Global Properties
#  Enable the setting to allow any Tool Provider to post grades to the Grade Center.
* '''Moodle''' - There is a flag which controls if Tools are allowed to submit grades.   This can be set for individual courses or site wide. 
#  Go to Site administration > Plugins > Activity modules > LTI > Manage external tool types.
#  Edit the WeBWorK tool and under Privacy enable "Accept grades from the tool".
* '''Canvas''' - Grade passback is always enabled in Canvas, but it is necessary to set the Domain value in the App configuration.
#  Go to Settings > Apps
#  On the line below the Apps tab, click "View Apps Configurations"
#  Find WeBWorK in the list, click on the gear icon on the right, and select "Edit" from the drop-down menu
#  Enter the domain of your WeBWorK server in the appropriate box, and click "Submit".  For example, if the URL for your course is "https://webwork.server.edu/webwork2/TestCourse/", then enter "webwork.server.edu" (without the quotes).

= Adding Graded Links =

You add links to WeBWorK in the LMS the same way you do if you are just using the authentication feature (see [[LTI-Advanced Authentication]]).  In particular you create an "Assignment/Link" and provide the url of the WeBWorK course.  The only additional thing you have to worry about is setting up the grade.  In general you need to make sure grading is enabled for the link and set the total number of points the assignment is worth.  It is recommended that you use 100 points so that the grade looks like a percentage.  However, the grade given to the student will always be a percentage of the total available points so  you can use however many points you want.  Its important to remember that the only information transferred from WeBWorK to the LMS is the percentage grade of the assignment.  In particular things like visibility and due dates are not automatically synchronized.  It is recommended that you do not set due dates in the LMS and allow WeBWorK to control the availability of the problem sets.  I'll describe the specifics for Blackboard, Moodle and Canvas.  

==== Blackboard ====
[[File:blackboard-lti-graded.png|300px]]

You need to make sure "Enable Evaluation" is set to yes.  You can also set the number of points available and the due date of the assignment. 

==== Moodle ====
[[File:moodle-lti-graded.png|300px]]

All you need to do is set the points possible as well as any of the other Moodle specific options. 

==== Canvas ====
[[File:canvas-lti-graded.png|300px]]

All you need to do is set the number of points possible.  Make sure the domain of your server is set in the Canvas tool configuration for WeBWorK.

= Course Grade Mode =

Lets look at an example of Blackboard set up with Course Grade mode.  Here we have a single (graded) link to our WeBWorK course in the Content area.  Students will use this link to access WeBWorK. 

[[File:blackboard-lti-example.png|500px]]

Once in WeBWorK they navigate and finish problem sets in exactly the same way they normally would.  WeBWorK behaves just as it would if there were no LMS at all.  The only difference is when students submit an answer their course grade will be computed and sent to the LMS.  Some things to remember: 
* '''Note''':  In many LMS instructors do not have grades.  In this case you (the instructor) will see the message "Your score was not successfully sent to the LMS".  This is fine, unless its not.  If you suspect that there is a problem enable '''$debug_lti_parameters''' to see more verbose error messages.  
* How the WeBWorK grade is used in the "Total Grade" on the LMS is entirely up to you and how you have set the weights in the LMS.  See the documentation for the LMS for how to set weights on grades.  
* Only make one (graded) link to WeBWorK.  If you make more than one then your gradebook will have multiple columns and WeBWorK will get confused about which one to send the grade back to.  
* Users have to log in to WeBWorK via the LMS at least once for this to work.  The easiest way to guarantee this is to make the LMS create the users.  However, once they have logged in via the LMS once they can log in directly via WeBWorK after that (assuming your authentication system is set up that way).
* You can use different grade modes in different courses by setting the '''$LTIGradeMode''' variable in the '''course.conf''' file.   So you are not locked into using one type of grading for all of your courses.

= Homework Grade Mode = 

This grading mode is more granular in that students get all of their problem set grades, as well as any other LMS grades, all in one place.  The cost is that you need to set up a separate link to each WeBWorK problem set.  For example in this Canvas course we have links to three different WeBWorK assignments.

[[File:moodle-lti-ex-1.png|400px]]

The important thing about these links is that they point directly to their corresponding problem set.  So for example, the link pointing to the Orientation set has the URL

[[File:moodle-lti-ex-2.png|300px]]

 https://webwork.server.edu/webwork2/TestCourse/Orientation

In general the link to set '''<set name>''' should have the following format:
* Default or Just-In-Time Set: '''<nowiki>https://<server address>/webwork2/<course name>/<set name></nowiki>'''
* Gateway: '''<nowiki>https://<server address>/webwork2/<course name>/quiz_mode/<set name></nowiki>'''
* Proctored Gateway: '''<nowiki>https://<server address>/webwork2/<course name>/proctored_quiz_mode/<set name></nowiki>'''
''If the set name is not somewhere in the url for that set on the LMS side then it is incorrect.''  You can get the URL for a particular set by right clicking and using "Copy this link location" on the link to the problem set in the main course page.  Once things are set up students then click on the links to access their homework and complete their assignments as normal.  If things are working then they should see their grades appear in the LMS.  There are a couple of caveats.

* '''Note''':  In many LMS instructors do not have grades.  In this case you (the instructor) will see the message "Your score was not successfully sent to the LMS".  This is fine, unless its not.  If you suspect that there is a problem enable '''$debug_lti_parameters''' to see more verbose error messages.  
* Students have to click on the link corresponding to the set at least once for grading to work.  Once in WeBWorK they can navigate like normal.  However, if they try to navigate to sets which are open, but which they haven't visited via the LMS get get messages like "You must log into this set via your Learning Management System". 
* Homework due dates and problem totals are not synced between WeBWorK and the LMS.  The easiest thing to do is to set all of the homework sets to be open forever in the LMS and let WeBWorK manage access to the homework sets.  You can also set the number of points for each set to 100 in the LMS and the score will be a percentage.  You can also keep the due dates and number of points synchronized, but you will have to do so by hand.  
* Also note that depending on how you weight things in the LMS the contributions of the homework to the total grade in the LMS will be different than the Homework Total on the Grades page in WeBWorK.  (In particular the WeBWorK grade is the total number of points earned over the points available, while, assuming you set the points to 100 for every assignment in the LMS, the LMS grade is the average of all the homework percentages.)  You can turn off displaying the Homework Total in WeBWorK using the Course Configuration menu if this bothers you or your students.  
* You can use different grade modes in different courses by setting the '''$LTIGradeMode''' variable in the '''course.conf''' file.   So you are not locked into using one type of grading for all of your courses.

[[Category:Administrators]]
[[Category:Authentication]]