Lightwork

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.3

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.

Currently, the Lightwork web services are installed in a Moodle installation by using the local customisations hook and the web services are implemented using the OKTech framework. See https://docs.moodle.org/20/en/Web_Services:OK_Tech_Web_Services. It is now proposed to add the Lightwork web services to the core Moodle 2.3 release as described in the rest of this document.

Challenges and issues

Lightwork stores marker allocation, rubrics and rubric instance information in its own table structure. This structure must be modified to integrate with and enhance Moodle.

• Lightwork makes the use of a rubric compulsory. This is not the case in Moodle.
• Moodle already has the ability to define and use a rubric which was introduced in Moodle 2.2.
• Moodle defines its rubric in database table structure whereas Lightwork uses XML
• Moodle has no marker allocation capability. Lightwork's marker allocation must be introduced so that it can be used by both Moodle and Lightwork

Design goals

Rubric compatibility between the Moodle rubric and Lightwork

Lightwork supports 2 types of rubrics. I'll refer to these as rubric type 1 and rubric type 2. These rubrics are currently stored as XML and there is the potential to create other rubric types. Moodle has one type of rubric, the advanced grading rubric. This is equivalent to Lightwork's type 1 rubric.

Moodle users should be able to work with the Moodle advanced grading rubric as they do currently. If they then choose to use Lightwork, the rubric could be exported to XML for Lightwork to use as a type 1 rubric. In the same way, a type 1 rubric created in Lightwork could be converted from XML into the equivalent records in the Moodle rubric grading tables.

• The timemodified field could be used to detect changes in the data
• Lightwork's PDF transformation can be used to produce a PDF version of the rubric

To avoid creating an export process between XML and the rubric grading tables, it would be better for Lightwork to store its type 1 rubric using the rubric grading tables in Moodle. These tables are mdl_grading_definitions, mdl_gradingform_rubric_criteria and mdl_gradingform_rubric_levels.

Taking this further, a new grading definition could be created in the mdl_grading_definitions table. This definition would be for the Lightwork type 2 rubric. New grading form tables would be created for this rubric.

Issues:

• The Lightwork type 1 rubric allows weightings to be defined for criteria. The Moodle rubric does not support this.
• All Lightwork rubrics support the use of a bank of frequently used comments. The Moodle rubric does not support this but could be extended to use this feature.
• It would be useful to keep the ability to store rubrics in XML format since this would allow transformation into different document types.
• Lightwork would need to be modified to store rubrics and rubric instances in the mdl_grading* tables

Marker allocation and rubric definitions

Lightwork requires marker allocation and a rubric to be used. This was a deliberate design decision to enforce the use of rubrics. Marker allocation will be introduced as part of the new assignment module and will be compatible with Lightwork's current marking process. The following scenarios will be possible in Moodle 2.3:

Scenario in Moodle	Impact of choosing to use Lightwork
Teacher creates an assignment. They choose to use the new Moodle 2.3 marker allocation process and the rubric grading method	Lightwork marking as usual but using the advanced grading rubric already created in Moodle
Teacher creates an assignment. They choose to use the simple grading method and no marker allocation	Choosing to use Lightwork will create marker allocation. Teachers and markers can use this allocation for grading within Moodle if they choose. If Lightwork uses a type 1 rubric it will be saved using the current rubric grading definition. The teacher can now switch to the rubric grading method to take advantage of the rubric created in Lightwork. If Lightwork uses a type 2 rubric it will be saved in Moodle as a new type 2 rubric definition.

Marking and rubric grading instances

Moodle uses the mdl_grading_instances and the mdl_gradingform_rubric_fillings tables to store the results achieved by the students based on the rubric. When marking a Moodle compatible rubric (Lightwork type 1 rubric) in Lightwork, the results will be stored in the same way.

The new proposed Lightwork and marking allocation database structures

This new database structure needs to support the ability for markers (usually teachers and non-editing teachers) to allocate students to markers for the purpose of grading their work. It will be used by both Lightwork and Moodle. It is proposed to use the existing mdl_grading* tables to store the rubrics. A new grading definition will be defined for the Lightwork type 2 rubric. The Lightwork type 1 rubric will use the existing rubric defintition.

The old Lightwork Database structures

lw_rubric

Each record in this table represents a marking rubric that has been created in the Lightwork client. Each rubric is associated with an activity. It is possible to have multiple rubrics per activity. The rubric data is represented in XML which is stored in the xmltext field.

Field	Type	Allow Null	Info
id	int(10)	false	autoincrementing. Required by Moodle
lwid	int(3)	false	Allows multiple rubrics for an activity. The id field cannot be used since these records may be created offline on the Lightwork client
activity	int(10)	false	The associated activity
activitytype	int(10)	false	The associated activity type
xmltext	text	false	The XML rubric
complete	int(1)	false	This value defaults to false on creation of the record. It is set to true when the teacher has finshed creating the rubric and it is ready for release to the students
deleted	int(1)	false	Defaults to false on creation. Setting to true indicates logical deletion.
timemodified	int(10)	false	The time when record was last updated

lw_marking

Each record in this table represents the allocation of a marker to a student and holds the marking sheet as XML. The marking sheet is based on the associated rubric record.

Field	Type	Allow Null	Info
id	int(10)	false	autoincrementing. Required by Moodle.
marker	int(10)	false	The user doing the marking
student	int(10)	false	The student being marked
xmltext	text	false	The XML marking sheet based on the associated rubric
activity	int(10)	false	The associated activity
activitytype	int(10)	false	The associated activity type
statuscode	char(2)	false	The status of the marking as defined by the records in the lw_marking_status table
rubric	int(3)	false	The associated rubric lwid from lw_rubric
deleted	int(1)	false	Defaults to false on creation. Setting to true indicates logical deletion.
timemodified	int(10)	false	The time when record was last updated

lw_marking_history

Multiple records in this table are associated with a single marking record in lw_marking. They represent the history of the marking process from the assignment of the marker to the student up to the release of the marking to the Moodle grade book.

Field	Type	Allow Null	Info
id	int(10)	false	autoincrementing. Required by Moodle
lwid	int(3)	false	Each marking history belong to a marking is uniquely identified by this field. The id field cannot be used since these records may be created offline on the client
marker	int(10)	false	The user doing the marking
student	int(10)	false	The student being marked
activity	int(10)	false	The associated activity
statuscode	char(2)	false	The status of the marking as defined by the records in the lw_marking_status table
rubric	int(3)	false	The associated rubric lwid from lw_rubric
comment	char(255)	false	A comment about this status change
timemodified	int(10)	false	The time when record was last updated

lw_marking_status

The records in this table represent all possible marking statuses. The stauses currently used are:

1. AL - Allocated
2. MA - In marking
3. MF - Marking Finished
4. RV - In review
5. RD - Reviewed
6. RL - Released
7. ED - Inactive
8. AR - Archived

Field	Type	Allow Null	Info
id	int(10)	false	autoincrementing. Required by Moodle
statuscode	char(2)	false	The marking status code
shortdescription	char(10)	false	A short description of this status
longdescription	char(20)	false	A long description of this status

The new Lightwork web services

These web services use the Moodle web services with the REST protocol. The login and password mechanism in the old web services is being replaced by tokens. Token based authentication is replacing password based authentication in Moodle.

methodname	classname	classpath	parameters	type	description and comments
core_get_moodle_version	core_webservice_external	webservice/externallib.php	None	read	Return the Moodle version number. This is the equivalent of the old getServiceVersion method. This is required to ensure that the Lightwork client is compatible with the Moodle version it is calling. Investigate whether the existing web service core_webservice_get_site_info() could be used instead.
core_course_get_courses_and_assignments	core_course_external	course/externallib.php	Capability	read	Return list of courses and assignments that this user has a particular capability in.
core_course_get_course_participants	core_course_external	course/externallib.php	List of course ids, Flag to specify whether all students are returned or just the ones that have submitted a submissions. List of capabilities to filter the results.	read	Return list of participants to specified courses. This should include students and teachers. User details are returned together with capabilities.
core_assignment_get_assignment_submissions	core_assignment_external	mod/assignment/externallib.php	List of assignment ids. Flag to specify whether to return all submissions (draft and final) or just final submissions.	read	Return assignment submissions for the specified assignments
core_assignment_get_assignment_grading_definitions	core_assignment_external	mod/assignment/externallib.php	List of assignment ids.	read	This is equivalent to the old getMarkingRubrics method. It returns the rubric grading definition details from the mdl_grading_definitions table and the mdl_gradingform* tables

The old Lightwork SOAP OKtech web services

These web services use the OKtech SOAP implementation. They are being replaced by the Moodle web services described in the previous section.

Operation name	Input message	Output message	Comments
login	username, password	the session key	A username and encrypted password is submitted and a session is returned
logout	session key	true or false
getPublicKey	empty	the public key	The web service is called prior to logging in so that the public key can be used with the client's private key to encrypt the password
getServiceVersion	empty	The Lightwork web services version number	Allows the Lightwork client to ensure that it is using a compatible version of the web services
getCourses	the session key	An array of 0 or more course records. An array of 0 or more error messages.	All courses for which the Lightwork user has the Lightwork marking manager or marker capability are returned.
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.

Moodle APIs used by Lightwork in Moodle 2.1

• mod/assignment/lib.php (will be replaced with mod_assign in Moodle 2.3)
• mod/assignment/type/<assignment type>/assignment.class.php (will be replaced with mod_assign in Moodle 2.3)
• mod/resource/locallib.php
• lib/dml/moodle-database.php
• lib/accesslib.php
• lib/grade/
• lib/uploadlib.php
• lib/filebrowser/
• lib/filestorage/