|Project state||In Development|
- 1 Summary
- 2 Using Lightwork with Moodle for offline marking
- 3 Design issues
- 4 The Lightwork web service
- 5 The Old Lightwork SOAP OKtech web service functions
- 6 Capabilities and permissions
- 7 Administration and configuration
- 8 User Interface - Create assignment, define Marking guide and mark student work according to Marking guide
- 9 User Interface - Marker allocation and management
- 10 Marking guide - Screenshot and Testing
Lightwork is a marking tool for managing and marking student assignments. See http://lightwork.massey.ac.nz/projects/show/fat and http://lightworkmarking.org/. It consists of a client application that was created using the Open source Eclipse Rich Client Platform see http://wiki.eclipse.org/index.php/Rich_Client_Platform and web services for communication with Moodle. Lightwork downloads and manages student submissions so that marking can be done on the client computer. It can be used offline with changes synchronized to Moodle the next time the teacher connects.
The current version of Lightwork (3.x.x) uses the old assignment module. It interacts with Moodle using custom web services which are installed in Moodle by using the local customisations hook and the OKTech framework. See https://docs.moodle.org/20/en/Web_Services:OK_Tech_Web_Services. It also uses additional database tables which are installed as part of the local customisation.
A new version of Lightwork (4.x.x) is under development. This will use the new assignment module and reguire no additional Moodle customisations. To allow this, the following changes have been made to the Moodle core code:
- The Marking Guide grading method has been added (included in Moodle 2.5)
- Marking allocation has been added (included in Moodle 2.6)
- Additional web services have been added (included in Moodle 2.8 and listed later in this page)
Using Lightwork with Moodle for offline marking
The following user stories are designed to help explain how Lightwork is used with Moodle for offline marking:
Creating a Marking Guide and setting it ready for marking
A teacher decides that they would like to use Lightwork's marking guide (introduced to Moodle in 2.3) for an assignment that they have given to their students. The teacher is a busy person who spends a lot of time out of the office without an internet connection and wants to be able to continue developing the Marking Guide in any spare moment that they have. They decide to use Lightwork to do this:
- In their office on their work PC the teacher begins work on the Marking Guide
- The teacher remembers that they will be out of the office for the next few days. There is still lots to do in order to finish the marking guide. They remember that Lightwork allows them to work offline.
- The teacher installs Lightwork on their new laptop. They connect to the internet and synchronize Lightwork with their Moodle instance.
- Within Lightwork they can now all their courses and assignments. They can see their partially completed Marking Guide.
- The next day, the teacher is waiting in their car to meet with a colleague and remembers the unfinished Marking Guide. They open Lightwork in their laptop and continue developing the Marking Guide in Lightwork's interface. They add/modify criteria and frequently used comments to their marking guide. When their colleague arrives they still haven't finished. The nearly completed Marking Guide is stored in Lightwork but cannot be synchronized to Moodle since there is no internet connection.
- After several more offline sessions, the teacher completes the marking guide
- The teacher arrives home at the end of the week. They want the other teachers to review their Marking Guide.
- The teacher connects their laptop to the internet, opens Lightwork and synchronizes it with their Moodle instance.
- The teacher's completed Marking Guide is now synchronized up to Moodle. Since they've been away more students have enrolled on the Moodle course, this new information is synchronized down to Lightwork.
- The teacher phones the other 2 teachers who help to teach the course. The first one only uses Moodle to mark, the second only uses Lightwork. The first teacher views the Marking Guide in Moodle. The second teacher synchronizes Lightwork and views the Marking Guide.
- The next the teachers all get together to discuss the Marking Guide. They agree some changes which they make in Lightwork. They then set their Marking Guide ready for marking and synchronize their changes with Moodle.
- Lightwork requires the use of either the rubric or the marking guide.
- Lightwork requires the use of marker allocation.
The Lightwork web service
These functions make up the Lightwork Moodle web service. They will use the REST protocol. Token based authentication is replacing password based authentication.
|methodname||classname||classpath||parameters||type||description and comments|
|core_webservice_get_site_info||core_webservice_external||webservice/externallib.php||None||read||http://tracker.moodle.org/browse/MDL-34962 This is required to ensure that the Lightwork client is compatible with the Moodle version it is calling. This existing Moodle function returns a build number for each web service function. Currently, for core web services, the function just returns the build number in the main version.php file. This function needs to be modified to return the release number and the version number. The release number is a user friendly number that the client can display and it indicates the Moodle version number for which the current version of the client has been designed to function. When the client detects that the Moodle version has changed, the client will either automatically update itself or it will prompt the user to perform the update to match the Moodle version to which it is connecting.|
|mod_assign_get_assignments||mod_assign_external||mod/assign/externallib.php||courseids (optional), capabilities (optional)||read||http://tracker.moodle.org/browse/MDL-31683 Return list of courses and assignments that this user has a particular capability in.|
|core_enrol_get_enrolled_users_with_capability||core_enrol_external||enrol/externallib.php||List of course ids with the capabilities required, Options.||read||http://tracker.moodle.org/browse/MDL-31859 Return list of participants of courses that have the specified capabilities.|
|mod_assign_get_submissions||mod_assign_external||mod/assign/externallib.php||List of assignment ids (required), status (optional), since (optional), before (optional)||read||http://tracker.moodle.org/browse/MDL-31682 Return assignment submissions for the specified assignments|
|mod_assign_get_grades||mod_assign_external||mod/assign/externallib.php||List of assignment ids (required), since (optional)||read||http://tracker.moodle.org/browse/MDL-31873 Return assignment grades (from the assign_grades table) for the specified assignments|
|core_group_get_groupings||core_group_external||group/externallib.php||List of grouping ids (required), returngroups (optional)||read||http://tracker.moodle.org/browse/MDL-36541 Return groupings and the associated groups when returngroups is true|
|core_group_get_group_members||core_group_external||group/externallib.php||List of group ids (required)||read||Returns the members of the specified groups|
|core_grading_get_definitions||core_grading_external||lib/classes/grading_external.php||List of grading area ids||read||http://tracker.moodle.org/browse/MDL-31681 Returns the details for the 'rubric' grading definitions from the mdl_grading_definitions table and the mdl_gradingform* tables|
|core_grading_save_definitions||core_grading_external||lib/classes/grading_external.php||List of grading areas with definitions||write||http://tracker.moodle.org/browse/MDL-31861 Inserts/updates/deletes grading definitions|
|mod_assign_set_user_flags||mod_assign_external||mod/assign/externallib.php||assignment id and user flags to be set||write||http://tracker.moodle.org/browse/MDL-41738|
The Old Lightwork SOAP OKtech web service functions
These web services use the OKtech SOAP implementation. They are being replaced by the Moodle web service functions described in the previous section.
|Operation name||Input message||Output message||Modifications for migration to Moodle core web services|
|login||username, password||the session key||No longer required. Moodle's token authentication will be used|
|logout||session key||true or false||No longer required. Moodle's token authentication will be used|
|getPublicKey||empty||the public key||No longer required. Moodle's token authentication will be used|
|getServiceVersion||empty||The Lightwork web services version number||We will use the Moodle version number instead. This is returned by calling service core_webservice_get_site_info|
|getCourses||the session key||An array of 0 or more course records. An array of 0 or more error messages.||We will no longer use capabilities. Instead we will use the teacher and non editing teacher roles which will be the marking manager and marker respectively|
|getCourseParticipants||the session key, an array of course ids, allStudents(boolean)||An array of 0 or more course participant records. An array of 0 or more error messages.||when allStudents is true, all course particpants students are returned, otherwise only students that have submitted work are included|
|getTeams||the session key, an array of assignment ids, a list of team ids, allStudents(boolean)||An array of 0 or more team records, an array of 0 or more error messages.||This web service is used when the team assignment type has been installed|
|getSubmissions||the session key, an array of activity ids, allStudents(boolean)||An array of 0 or more records from the assignment_submissions table, an array of 0 or more error messages.||When allStudents is set to true, draft submissions are not included|
|getRubrics||the session key, an array of activity ids, a timemodified value >=0||An array of 0 or more records from the lw_rubric table, an array of 0 or more error messages.||The timemodified parameter can be used to reduce the number of records returned when the client knows they have already received updates for all rubrics at a certain point in time.|
|saveRubrics||the session key, an array of rubric records||An array of saved rubric records, an array of 0 or more error messages.||Updates the lw_rubric table with new and updated rubrics|
|getFeedbackSubmissions||the session key, an activity id, a timemodified value >=0||An array of feedback submission records, an array of 0 or more error messages.||This web service is used when the feedback assignment type has been installed|
|getUserInfo||The session key, a multi-dimensional array with user ids associated with a timemodified value >=0, an assignment id||An array of user_info records, an array of 0 or more error messages.||Returns information from the user_info_data for a category in the user_info_category table|
|getModifiedMarkingCount||The session key, an array of activity ids, the marking type, a timemodified value >=0||The number of records in the lw_marking table modified after timemodified||Used to prevent making queries on the lw_marking table when there are no new records|
|getmarking||The session key, an activity id, the marking type, a timemodified value >=0, allstudents(boolean)||An array of records from the lw_marking table, an array of 0 or more error messages.||Returns records from lw_marking for the specified activity id that have been modified after the specified timemodified value|
|getMarkingHistory||The session key, the marking type, an array of unique marking identifiers||An array of records from the lw_marking_history table, an array of 0 or more error messages.|
|saveMarking||The session key, array of lw_marking records, the marking type, allstudents(boolean)||An array of unique marking identifiers, an array of 0 or more error messages.||Updates the lw_marking and lw_marking_history table with new and updated marking and marking history records|
|releaseMarking||The session key, array of lw_marking records, the marking type||An array of unique marking identifiers, an array of 0 or more error messages.||Releases the marking to the Moodle grade book. Also uploads marking feedback as attachments.|
|releaseTeamMarking||The session key, array of lw_marking records, the marking type||An array of unique marking identifiers, an array of 0 or more error messages.||This web service is used when the team assignment type has been installed|
|uploadAssignmentDocuments||The session key, array of assignment ids associated with a file reference||an array of 0 or more error messages||Uploads file attachments for the specified assignments. The file attachments can be any documents that have been annotated during marking and PDF rubrics for the students|
|downloadAssignmentDocumentsMetaData||The session key, course id, assignment id, includeannotatedfiles||An array of metadata about the files stored for the assignment, an array of 0 or more error messages.||This web service is used by the Lightwork client to decide whether to replace or upload its own local versions of the files|
|repairLightworkData||The session key, an array of assignment ids||An array of unique identifiers for records that were deleted, an array of 0 or more error messages.||Database records such as assignments and users may be deleted or updated in Moodle at any time. This web service can be called by the Lightwork client when it suspects that data has become invalid. The returned results are used to update the Lightwork client's data model. For example, if a teacher unenrolls from a course then they no longer have permissions to view this course and it must be removed from the Lightwork client's local database.|
|getAssignmentDocuments||The session key, course id, assignment id, an array of filenames to be downloaded||An array of file references, an array of 0 or more error messages||Downloads files as attachments which are accessed using the file references|
|getSubmissionReport||The session key, course id, start date, end date||An array of submission report records, an array of 0 or more error messages||Downloads information about all student submissions for a course between a specified time period. This information is used by the Lightwork client to produce a submission report.|
|getSubmissionFiles||The session key, the activity id, an array of submission ids||An array of assignment_submissions table records with file references, an array of 0 or more error messages||An array of records from the assignment_submissions table with references to a zip file attachment containing files submitted by the student|
Capabilities and permissions
- moodle/lightwork:managelightworkmarkers - create and modify rubrics, allocate markers to students, release marks to the gradebook
- moodle/lightwork:marklightworksubmissions - Mark student submissions
Normally, capabilities would be set up as follows:
Non-editing teacher role
Administration and configuration
The change to use the core Lightwork web services will be transparent to Lightwork users. However, the Moodle administrator will need to configure the services as follows:
- Enable Web services in the Site Administration - Advanced features page
- Enable the SOAP protocol in the Site Administration - Plugins - Web services - Manage protocols page
- Add a new custom external service in the Site Administration - Plugins - Web services - External services page
- Name - Lightwork
- Enabled - Checked
- Authorised users only - Unchecked
- Required capability - No required capability
- Select Add Service to add the new Lightwork web service
- Select the Functions link of the new Lightwork web service
- Select Add Functions and add all the functions that are prefixed with lightwork_
Assuming that the correct capabilities have been setup for them as described in the capabilities section, Lightwork users will now be able to connect to Moodle.
User Interface - Create assignment, define Marking guide and mark student work according to Marking guide
Create and update assignment
Advanced grading, Define Marking guide page
The marking manager selects Define Marking guide under Settings-Assignment administration-Advanced grading
Advanced grading page with active grading method Marking guide
The marking manager selects Advanced grading under the Settings-Assignment administration link
Mark student using the Marking guide
The marker selects the student submission from the submissions page and chooses to start marking
Student views their feedback
The marking manager has reviewed and released the marks to the student. The student logs in and views their feedback.
User Interface - Marker allocation and management
Select to use marker allocation in this assignment
Allocate markers to students
The teacher commences allocating markers to students
Review the marking
This assumes that this assignment is being marked using the new "marking guide" advanced grading method
Release the marking
Marking guide - Screenshot and Testing
Screenshots (to come)
Call for testing
Please help us with testing the marking guide functionality.
Link to marking guide code: https://github.com/Lightwork-Marking/moodle-gradingform_guide
A test plan is available from: TestPlan_MarkingGuide
Testing results can be recorded in: Testing_Record_MarkingGuide