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:
- AL - Allocated
- MA - In marking
- MF - Marking Finished
- RV - In review
- RD - Reviewed
- RL - Released
- ED - Inactive
- 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 |
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. |
get_courses_and_assignments | core_course_external | course/externallib.php | List of capabilities to filter the results. | read | Return list of courses and assignments that this user can mark. Consider the best way to make this generic. We are interested in the courses and assignments for which the user has the capabilities of mark or marking management. Lightwork creates these capabilities which are generally assigned only to users with the Teacher or Non-editing Teacher role. |
get_courses_participants | core_course_external | course/externallib.php | 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. |
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 |
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/