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. The type 2 rubric allows the teacher to choose a mark for a criterion as opposed to selecting from fixed defined levels. A possibility for a name for the type 2 rubric might be marking guide, see http://moodle.org/mod/forum/discuss.php?d=195738&parent=854867.
Since Moodle has already implemented rubrics by using database tables instead of XML, Lightwork on Moodle will have to change to follow this approach.
Lightwork will need to store its type 1 rubric and rubric instances using the rubric grading tables in Moodle. These tables are:
- mdl_grading_definitions
- mdl_grading_instances
- mdl_gradingform_rubric_criteria
- mdl_gradingform_rubric_fillings
- mdl_gradingform_rubric_levels
In order to implement the type 2 rubrics we could either:
- Create a new gradingform plugin for the type 2 rubric. This might be called gradingform_markingguide
- Modify the existing gradingform_rubric so that it supports the type 2 rubric. The table structure required for the type 2 rubric is very similar and differs only in that mdl_gradingform_rubric_fillings would require an additional field to store the mark and mdl_gradingform_rubric_levels is not required.
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 using the same advanced grading mechanism. |
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. This will require new tables to be designed and implemented
TODO - design the marking management tables
The existing mdl_grading* tables will be used to store the Lightwork rubrics. Depending on the approach taken (see previous section) these tables may either need to be modified or a new plugin created to support the Lightwork type 2 rubric.
The new Moodle 2.3 assignment module
In addition to adding Lightwork's web services into the Moodle core, many of Lightwork's features are being included in the Moodle 2.3 assignment module. This work is being done in conjunction with https://docs.moodle.org/dev/Assignment. The new features are:
- An additional type of rubric that allows markers to specify the mark given for a criterion. This differs from the current rubric where the marker must select from one or more fixed marks. We are currently undecided on the best name for this type of rubric. We are currently calling it a Marking guide.
- Frequently used comments. A bank of Frequently used comments can be defined for a rubric. Markers can select and add these comments when providing feedback based on a rubric.
- Marking management. A marking manager can allocate students to markers. A marking process is used to ensure consistency of marking.
- Team submission. Students work as a team and submit a single team submission.
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 |
core_webservice_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 | http://tracker.moodle.org/browse/MDL-31683 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. It has been noted that there already exists a similar function core_enrol_get_enrolled_users. This needs to be investigated. |
mod_assignment_get_assignment_submissions | mod_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 | http://tracker.moodle.org/browse/MDL-31682 Return assignment submissions for the specified assignments |
core_grade_get_rubric_grading_definitions | core_grade_external | grade/externallib.php | List of grading area ids | read | http://tracker.moodle.org/browse/MDL-31681 This is equivalent to the old getMarkingRubrics method. It returns the details for the 'rubric' grading definitions 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/
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 user selects Define Marking guide under Settings-Assignment administration-Advanced grading
Advanced grading page with active grading method Marking guide
The user selects Advanced grading under the Settings-Assignment administration link