Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Lightwork

From MoodleDocs

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

Lightwork
Project state In Development
Tracker issue http://tracker.moodle.org/browse/MDL-31409
Discussion http://moodle.org/mod/forum/discuss.php?d=187818
Assignee Lightwork

Moodle 2.8


Summary

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:

  1. In their office on their work PC the teacher begins work on the Marking Guide
  2. 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.
  3. The teacher installs Lightwork on their new laptop. They connect to the internet and synchronize Lightwork with their Moodle instance.
  4. Within Lightwork they can now all their courses and assignments. They can see their partially completed Marking Guide.
  5. 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.
  6. After several more offline sessions, the teacher completes the marking guide
  7. The teacher arrives home at the end of the week. They want the other teachers to review their Marking Guide.
  8. The teacher connects their laptop to the internet, opens Lightwork and synchronizes it with their Moodle instance.
  9. 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.
  10. 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.
  11. 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.

Design issues

  • 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
mod_assign_save_grades mod_assign_external mod/assign/externallib.php write http://tracker.moodle.org/browse/MDL-42425
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_get_gradingform_instances core_grading_external lib/classes/grading_external.php read http://tracker.moodle.org/browse/MDL-31890
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_get_user_flags mod_assign_external mod/assign/externallib.php assignment id read http://tracker.moodle.org/browse/MDL-40548
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
  • webservice:createtoken
  • webservice/soap:use

Normally, capabilities would be set up as follows:

Teacher role

  • moodle/lightwork:managelightworkmarkers
  • moodle/lightwork:marklightworksubmissions
  • webservice:createtoken
  • webservice/soap:use

Non-editing teacher role

  • moodle/lightwork:marklightworksubmissions
  • webservice:createtoken
  • webservice/soap:use

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

Create and update assignment page

Advanced grading, Define Marking guide page

The marking manager selects Define Marking guide under Settings-Assignment administration-Advanced grading

Advanced grading, Define Marking guide page

Advanced grading page with active grading method Marking guide

The marking manager selects Advanced grading under the Settings-Assignment administration link

Advanced grading page with active grading method marking guide

Mark student using the Marking guide

The marker selects the student submission from the submissions page and chooses to start marking

Mark student using the Marking guide

Student views their feedback

The marking manager has reviewed and released the marks to the student. The student logs in and views their feedback.

Student 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

Allocate markers to students

Review the marking

This assumes that this assignment is being marked using the new "marking guide" advanced grading method

Review the marking

Release the marking

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