MoodleDocs - User contributions [en]

Lightwork

2014-06-20T05:40:48Z

Pcharsle: /* Moodle APIs used by Lightwork in Moodle 2.1 */

Lightwork

2014-06-20T05:38:50Z

Pcharsle: /* The Lightwork web service */

Lightwork

2014-06-20T05:30:53Z

Pcharsle: /* The Lightwork web service */

Lightwork

2014-06-20T05:07:18Z

Pcharsle: /* Migration of existing SOAP OKtech web services to Moodle core web services */

Lightwork

2014-06-20T05:04:56Z

Pcharsle: /* The new Lightwork web services */

Lightwork

2014-06-20T05:04:20Z

Pcharsle: /* The new Moodle 2.3 assignment module */

Lightwork

2014-06-20T05:03:37Z

Pcharsle: /* The new proposed Lightwork and marking allocation database structures */

{{Work in progress}}
{{Infobox Project
|name = Lightwork
|state = In Development
|tracker = 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_customisation|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.

== Design issues ==

* Lightwork requires the use of either the rubric or the marking guide.
* Lightwork requires the use of marker allocation.

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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_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
|}

== Migration of existing SOAP OKtech web services to Moodle core web services ==

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

== 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 ===

[[File:UpdateAssignment.png|600px|thumb|center|Create and update assignment page]]

=== Advanced grading, Define Marking guide page ===

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

[[File:UpdateRubric.png|600px|thumb|center|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

[[File:LookAtRubric.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_2.png|600px|thumb|center|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.

[[File:StudentView.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_1.png|600px|thumb|center|Allocate markers to students]]

=== Review the marking ===

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

[[File:ViewSubmittedAssignments_3.png|600px|thumb|center|Review the marking]]

=== Release the marking ===

[[File:ViewSubmittedAssignments_4.png|600px|thumb|center|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: [http://lightwork.massey.ac.nz/documents/show/6 TestPlan_MarkingGuide]

Testing results can be recorded in: [http://lightwork.massey.ac.nz/documents/show/6 Testing_Record_MarkingGuide]

Lightwork

2014-06-20T05:01:55Z

Pcharsle: /* Design goals */

{{Work in progress}}
{{Infobox Project
|name = Lightwork
|state = In Development
|tracker = 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_customisation|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.

== Design issues ==

* Lightwork requires the use of either the rubric or the marking guide.
* Lightwork requires the use of marker allocation.

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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_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
|}

== Migration of existing SOAP OKtech web services to Moodle core web services ==

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

== 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 ===

[[File:UpdateAssignment.png|600px|thumb|center|Create and update assignment page]]

=== Advanced grading, Define Marking guide page ===

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

[[File:UpdateRubric.png|600px|thumb|center|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

[[File:LookAtRubric.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_2.png|600px|thumb|center|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.

[[File:StudentView.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_1.png|600px|thumb|center|Allocate markers to students]]

=== Review the marking ===

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

[[File:ViewSubmittedAssignments_3.png|600px|thumb|center|Review the marking]]

=== Release the marking ===

[[File:ViewSubmittedAssignments_4.png|600px|thumb|center|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: [http://lightwork.massey.ac.nz/documents/show/6 TestPlan_MarkingGuide]

Testing results can be recorded in: [http://lightwork.massey.ac.nz/documents/show/6 Testing_Record_MarkingGuide]

Lightwork

2014-06-20T04:48:06Z

Pcharsle: /* Challenges and issues */

{{Work in progress}}
{{Infobox Project
|name = Lightwork
|state = In Development
|tracker = 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_customisation|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.

== 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:

{| border="1" cellpadding="2" cellspacing="0"
|'''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 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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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_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
|}

== Migration of existing SOAP OKtech web services to Moodle core web services ==

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

== 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 ===

[[File:UpdateAssignment.png|600px|thumb|center|Create and update assignment page]]

=== Advanced grading, Define Marking guide page ===

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

[[File:UpdateRubric.png|600px|thumb|center|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

[[File:LookAtRubric.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_2.png|600px|thumb|center|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.

[[File:StudentView.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_1.png|600px|thumb|center|Allocate markers to students]]

=== Review the marking ===

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

[[File:ViewSubmittedAssignments_3.png|600px|thumb|center|Review the marking]]

=== Release the marking ===

[[File:ViewSubmittedAssignments_4.png|600px|thumb|center|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: [http://lightwork.massey.ac.nz/documents/show/6 TestPlan_MarkingGuide]

Testing results can be recorded in: [http://lightwork.massey.ac.nz/documents/show/6 Testing_Record_MarkingGuide]

Lightwork

2014-06-20T02:42:16Z

Pcharsle:

{{Work in progress}}
{{Infobox Project
|name = Lightwork
|state = In Development
|tracker = 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_customisation|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.

== 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:

{| border="1" cellpadding="2" cellspacing="0"
|'''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 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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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_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
|}

== Migration of existing SOAP OKtech web services to Moodle core web services ==

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

== 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 ===

[[File:UpdateAssignment.png|600px|thumb|center|Create and update assignment page]]

=== Advanced grading, Define Marking guide page ===

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

[[File:UpdateRubric.png|600px|thumb|center|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

[[File:LookAtRubric.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_2.png|600px|thumb|center|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.

[[File:StudentView.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_1.png|600px|thumb|center|Allocate markers to students]]

=== Review the marking ===

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

[[File:ViewSubmittedAssignments_3.png|600px|thumb|center|Review the marking]]

=== Release the marking ===

[[File:ViewSubmittedAssignments_4.png|600px|thumb|center|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: [http://lightwork.massey.ac.nz/documents/show/6 TestPlan_MarkingGuide]

Testing results can be recorded in: [http://lightwork.massey.ac.nz/documents/show/6 Testing_Record_MarkingGuide]

Lightwork

2014-06-20T02:32:24Z

Pcharsle:

{{Work in progress}}
{{Infobox Project
|name = Lightwork
|state = In Development
|tracker = 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_customisation|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 is under development.

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

== 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:

{| border="1" cellpadding="2" cellspacing="0"
|'''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 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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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_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
|}

== Migration of existing SOAP OKtech web services to Moodle core web services ==

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

== 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 ===

[[File:UpdateAssignment.png|600px|thumb|center|Create and update assignment page]]

=== Advanced grading, Define Marking guide page ===

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

[[File:UpdateRubric.png|600px|thumb|center|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

[[File:LookAtRubric.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_2.png|600px|thumb|center|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.

[[File:StudentView.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_1.png|600px|thumb|center|Allocate markers to students]]

=== Review the marking ===

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

[[File:ViewSubmittedAssignments_3.png|600px|thumb|center|Review the marking]]

=== Release the marking ===

[[File:ViewSubmittedAssignments_4.png|600px|thumb|center|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: [http://lightwork.massey.ac.nz/documents/show/6 TestPlan_MarkingGuide]

Testing results can be recorded in: [http://lightwork.massey.ac.nz/documents/show/6 Testing_Record_MarkingGuide]

Web service API functions

2014-06-20T02:18:20Z

Pcharsle: /* Core web service functions */

{{Moodle_2.0}}

{| class = "wikitable"
|+Color meaning
|-
| style="background:#D4FFDF;" | Implemented
|-
| style="background:#ffdead;" | Must be implemented
|-
| style="background:#ffdfcd;" | Suggested
|}

==Web service protocols==

{| class="wikitable sortable"
! Name !! Moodle Ver. !! class="unsortable" |Description !! class="unsortable" | Issue
|-
| style="background:#D4FFDF;" | AMF || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adobe protocol to communicate with Flash/Flex apps ||
|-
| style="background:#D4FFDF;" | REST (returning XML) || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML data accessed through a REST API (not restful) ||
|-
| style="background:#D4FFDF;" | REST (returning JSON) || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | JSON data accessed through a REST API (not restful) || MDL-29242
|-
| style="background:#ffdfcd;" | REST (returning JSONP) || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | Would be very useful for client-side JavaScript || MDL-29913
|-
| style="background:#ffdfcd;" | JSON || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | JSON server receives a JSON encoded params and return JSON encoded values. || MDL-21341
|-
| style="background:#ffdead;" | SOAP|| style="background:#ffdead;" | 2.0 || style="background:#ffdead;" | Very important for interoperating with Java and .Net applications. There was a partial implementation JAVA/.Net in Moodle 2.0, but it does not work for anything but the most trivial functions. It is fully working with PHP clients.|| MDL-20804, MDL-28988, MDL-28989
|-
| style="background:#D4FFDF;" | XMLRPC|| style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML remote-procedure call. ||
|}

==Web service functions==

=== Naming convention ===

We updated (regularised) the naming convention in Moodle 2.2. See MDL-29106 for those details.

All functions should be named as follows:

* wsfunction = fullcomponent_methodname
* fullcomponent = [https://docs.moodle.org/dev/Frankenstyle frankenstyle] (eg core_xxxx or mod_xxx etc)
* methodname = verb_noun(s)
* verb = get|create|delete|update
* noun = moodle objects, usually plural (eg posts, discussions, users, courses etc)

=== Core web service functions ===
{| class="wikitable sortable"
!Area!! Moodle 2.2 name !! Moodle 2.0/2.1 name !! Introduced in !! class="unsortable" |Description !! class="unsortable" | Issue
|-
|user
| style="background:#D4FFDF;" | core_user_create_users() || style="background:#D4FFDF;" | moodle_user_create_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_delete_users() || style="background:#D4FFDF;" | moodle_user_delete_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Delete users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_update_users() || style="background:#D4FFDF;" | moodle_user_update_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Update users ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_id() || style="background:#D4FFDF;" | moodle_user_get_users_by_id() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Get users by id ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_course_user_profiles() || style="background:#D4FFDF;" | moodle_user_get_course_participants_by_id() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get course user profiles by id ||
|-

|cohort
| style="background:#D4FFDF;" | core_cohort_create_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Create cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_update_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Update cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_add_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Add members to cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete members from cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohort members || MDL-29472
|-

|course
| style="background:#D4FFDF;" | core_course_get_courses() || style="background:#D4FFDF;" | moodle_course_get_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Return course details ||
|-
|course
| style="background:#D4FFDF;" | core_course_create_courses() || style="background:#D4FFDF;" | moodle_course_create_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create new courses ||
|-
|group
| style="background:#D4FFDF;" | core_group_create_groups() || style="background:#D4FFDF;" | moodle_group_create_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Creates new groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_groups() || style="background:#D4FFDF;" | moodle_group_get_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group details. ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groups() || style="background:#D4FFDF;" | moodle_group_get_course_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns all groups in specified course ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groups() || style="background:#D4FFDF;" | moodle_group_delete_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes all specified groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_group_members() || style="background:#D4FFDF;" | moodle_group_get_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_add_group_members() || style="background:#D4FFDF;" | moodle_group_add_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adds group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_group_members() || style="background:#D4FFDF;" | moodle_group_delete_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes group members ||
|-
|role
| style="background:#D4FFDF;" | core_role_assign_roles() || style="background:#D4FFDF;" | moodle_role_assign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role assignments ||
|-
|role
| style="background:#D4FFDF;" | core_role_unassign_roles() || style="background:#D4FFDF;" | moodle_role_unassign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role unassignments ||
|-
|enrol
| style="background:#D4FFDF;" | NONE || style="background:#D4FFDF;" | moodle_enrol_get_enrolled_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get some minimal information about the users enrolled in a course (DEPRECATED) ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users() || style="background:#D4FFDF;" | moodle_user_get_users_by_courseid() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get enrolled users by course id ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_users_courses() || style="background:#D4FFDF;" | moodle_enrol_get_users_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get list of course ids that a user is enrolled in (if you are allowed to see that) ||
|-
|enrol/manual
| style="background:#D4FFDF;" | enrol_manual_enrol_users() || style="background:#D4FFDF;" | moodle_enrol_manual_enrol_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual enrol users ||
|-
|webservice
| style="background:#D4FFDF;" | core_webservice_get_site_info() || style="background:#D4FFDF;" | moodle_webservice_get_siteinfo() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Return some site info / user info / list web service functions ||
|-
|message
| style="background:#D4FFDF;" | core_message_send_instant_messages() || style="background:#D4FFDF;" | moodle_message_send_instantmessages() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Send instant messages ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_create_notes() || style="background:#D4FFDF;" | moodle_notes_create_notes() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Create notes ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_delete_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_get_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_update_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update Notes || MDL-30072
|-
|files
| style="background:#D4FFDF;" | core_files_get_files() || style="background:#D4FFDF;" | moodle_file_get_files() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | browse moodle files ||
|-
|files
| style="background:#D4FFDF;" | core_files_upload() || style="background:#D4FFDF;" | moodle_file_upload() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | upload a file to moodle (DEPRECATED) ||
|-
|course
| style="background:#D4FFDF;" | core_course_get_contents() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | get course content (modules + web service file urls) || MDL-28646
|-
|course
| style="background:#D4FFDF;" | core_course_delete_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete courses || MDL-13130
|-
|course
| style="background:#D4FFDF;" | core_course_duplicate_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | duplicate a course || MDL-32233
|-
|course
| style="background:#D4FFDF;" | core_course_get_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_update_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_create_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_delete_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete categories || MDL-32941
|-
|group
| style="background:#D4FFDF;" | core_group_create_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_update_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_assign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | assign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_unassign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | unassign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get all groupings in specified course || MDL-32662
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_field() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve users information for a specified unique field - If you want to do a user search, use core_user_get_users() || MDL-35543
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users_with_capability() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | For each course and capability specified, return a list of the users that are enrolled in the course and have that capability || MDL-31859
|-
|course
| style="background:#D4FFDF;" | core_course_import_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Import course data from a course into another course. Does not include any user data. || MDL-32919
|-
|message
| style="background:#D4FFDF;" | core_message_create_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Add contacts to the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_delete_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Remove contacts from the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_block_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Block contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_unblock_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Unblock contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_get_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_search_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search for contacts || MDL-30070
|-
|external
| style="background:#D4FFDF;" | core_get_string() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return a translated string - similar to core get_string() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_component_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return all raw strings (with {$a->xxx}) for a specific component - similar to core get_component_strings() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return some translated strings - like several core get_string() calls || MDL-35997
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_delete_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete calendar events || MDL-37077
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_get_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Get calendar events || MDL-37100
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_create_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Create calendar events || MDL-37101
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_grades() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns grades from the assignment || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_assignments() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns the courses and assignments for the users capability || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns the submissions for assignments || MDL-31682
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_user_flags || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the user_flags for assignments || MDL-40548
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_set_user_flags || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Sets the specified user_flags for an assignment || MDL-41738
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_user_mappings || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the user_mappings for assignments || MDL-40548
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_revert_submissions_to_draft || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Reverts the list of submissions to draft status || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_lock_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Prevent students from making changes to a list of submissions || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_unlock_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Allow students to make changes to a list of submissions || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_save_submission || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Update the current students submission || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_submit_for_grading || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Submit the current students assignment for grading || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_save_grade || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Save a grade update for a single student. || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_save_grades || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.7 || style="background:#D4FFDF;" | Save grade updates for one or more students. || MDL-42425
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_save_user_extensions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Save a list of assignment extensions || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_reveal_identities || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Reveal the identities for a blind marking assignment || MDL-37148
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forums_by_courses || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum instances in a provided set of courses, if no courses are provided then all the forum instances the user has access to will be returned. || MDL-37247
|-
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forum_discussions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum discussions in a provided set of forums. || MDL-30102
|-
|course
| style="background:#D4FFDF;" | core_course_update_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update courses. || MDL-30062
|-
|user
| style="background:#D4FFDF;" | core_user_get_users() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search users. - If you want to get multiple users for one specific field, use core_user_get_users_by_field(), it's designed for this purpose and it should be faster. || MDL-29938
|-
|grade
| style="background:#D4FFDF;" | core_grade_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned. Will be deprecated and replaced by core_grading_get_definitions in 2.6|| MDL-31681
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned.|| MDL-31890
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_gradingform_instances() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the instances and fillings for the requested definition id. An optional since parameter allows the number of records returned to be reduced so that only those with a timemodified value >= since are returned|| MDL-31890
|-
|grading
| style="background:#D4FFDF;" | core_grading_save_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.8 || style="background:#D4FFDF;" |Accepts an array of areas as a parameter. The areas contain grading definitions with criteria for inserting and updating|| MDL-31861
|-
|}
This is the list of the integrated core functions. To see the roadmap, see to the tracker issue in the section bellow.

=== API Roadmap===
Tracker issue: MDL-29934

= See also =
* [[Web services API Changes]]
* [[How to contribute a web service function to core]]
* [[Web services|Web services developer documentation]]
* [[:en:Web services|Web services user documentation]]

[[Category:Web Services]]
[[Category:API]]

Web service API functions

2014-06-20T02:13:19Z

Pcharsle: /* Core web service functions */

{{Moodle_2.0}}

{| class = "wikitable"
|+Color meaning
|-
| style="background:#D4FFDF;" | Implemented
|-
| style="background:#ffdead;" | Must be implemented
|-
| style="background:#ffdfcd;" | Suggested
|}

==Web service protocols==

{| class="wikitable sortable"
! Name !! Moodle Ver. !! class="unsortable" |Description !! class="unsortable" | Issue
|-
| style="background:#D4FFDF;" | AMF || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adobe protocol to communicate with Flash/Flex apps ||
|-
| style="background:#D4FFDF;" | REST (returning XML) || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML data accessed through a REST API (not restful) ||
|-
| style="background:#D4FFDF;" | REST (returning JSON) || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | JSON data accessed through a REST API (not restful) || MDL-29242
|-
| style="background:#ffdfcd;" | REST (returning JSONP) || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | Would be very useful for client-side JavaScript || MDL-29913
|-
| style="background:#ffdfcd;" | JSON || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | JSON server receives a JSON encoded params and return JSON encoded values. || MDL-21341
|-
| style="background:#ffdead;" | SOAP|| style="background:#ffdead;" | 2.0 || style="background:#ffdead;" | Very important for interoperating with Java and .Net applications. There was a partial implementation JAVA/.Net in Moodle 2.0, but it does not work for anything but the most trivial functions. It is fully working with PHP clients.|| MDL-20804, MDL-28988, MDL-28989
|-
| style="background:#D4FFDF;" | XMLRPC|| style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML remote-procedure call. ||
|}

==Web service functions==

=== Naming convention ===

We updated (regularised) the naming convention in Moodle 2.2. See MDL-29106 for those details.

All functions should be named as follows:

* wsfunction = fullcomponent_methodname
* fullcomponent = [https://docs.moodle.org/dev/Frankenstyle frankenstyle] (eg core_xxxx or mod_xxx etc)
* methodname = verb_noun(s)
* verb = get|create|delete|update
* noun = moodle objects, usually plural (eg posts, discussions, users, courses etc)

=== Core web service functions ===
{| class="wikitable sortable"
!Area!! Moodle 2.2 name !! Moodle 2.0/2.1 name !! Introduced in !! class="unsortable" |Description !! class="unsortable" | Issue
|-
|user
| style="background:#D4FFDF;" | core_user_create_users() || style="background:#D4FFDF;" | moodle_user_create_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_delete_users() || style="background:#D4FFDF;" | moodle_user_delete_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Delete users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_update_users() || style="background:#D4FFDF;" | moodle_user_update_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Update users ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_id() || style="background:#D4FFDF;" | moodle_user_get_users_by_id() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Get users by id ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_course_user_profiles() || style="background:#D4FFDF;" | moodle_user_get_course_participants_by_id() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get course user profiles by id ||
|-

|cohort
| style="background:#D4FFDF;" | core_cohort_create_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Create cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_update_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Update cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_add_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Add members to cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete members from cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohort members || MDL-29472
|-

|course
| style="background:#D4FFDF;" | core_course_get_courses() || style="background:#D4FFDF;" | moodle_course_get_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Return course details ||
|-
|course
| style="background:#D4FFDF;" | core_course_create_courses() || style="background:#D4FFDF;" | moodle_course_create_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create new courses ||
|-
|group
| style="background:#D4FFDF;" | core_group_create_groups() || style="background:#D4FFDF;" | moodle_group_create_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Creates new groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_groups() || style="background:#D4FFDF;" | moodle_group_get_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group details. ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groups() || style="background:#D4FFDF;" | moodle_group_get_course_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns all groups in specified course ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groups() || style="background:#D4FFDF;" | moodle_group_delete_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes all specified groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_group_members() || style="background:#D4FFDF;" | moodle_group_get_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_add_group_members() || style="background:#D4FFDF;" | moodle_group_add_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adds group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_group_members() || style="background:#D4FFDF;" | moodle_group_delete_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes group members ||
|-
|role
| style="background:#D4FFDF;" | core_role_assign_roles() || style="background:#D4FFDF;" | moodle_role_assign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role assignments ||
|-
|role
| style="background:#D4FFDF;" | core_role_unassign_roles() || style="background:#D4FFDF;" | moodle_role_unassign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role unassignments ||
|-
|enrol
| style="background:#D4FFDF;" | NONE || style="background:#D4FFDF;" | moodle_enrol_get_enrolled_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get some minimal information about the users enrolled in a course (DEPRECATED) ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users() || style="background:#D4FFDF;" | moodle_user_get_users_by_courseid() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get enrolled users by course id ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_users_courses() || style="background:#D4FFDF;" | moodle_enrol_get_users_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get list of course ids that a user is enrolled in (if you are allowed to see that) ||
|-
|enrol/manual
| style="background:#D4FFDF;" | enrol_manual_enrol_users() || style="background:#D4FFDF;" | moodle_enrol_manual_enrol_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual enrol users ||
|-
|webservice
| style="background:#D4FFDF;" | core_webservice_get_site_info() || style="background:#D4FFDF;" | moodle_webservice_get_siteinfo() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Return some site info / user info / list web service functions ||
|-
|message
| style="background:#D4FFDF;" | core_message_send_instant_messages() || style="background:#D4FFDF;" | moodle_message_send_instantmessages() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Send instant messages ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_create_notes() || style="background:#D4FFDF;" | moodle_notes_create_notes() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Create notes ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_delete_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_get_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_update_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update Notes || MDL-30072
|-
|files
| style="background:#D4FFDF;" | core_files_get_files() || style="background:#D4FFDF;" | moodle_file_get_files() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | browse moodle files ||
|-
|files
| style="background:#D4FFDF;" | core_files_upload() || style="background:#D4FFDF;" | moodle_file_upload() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | upload a file to moodle (DEPRECATED) ||
|-
|course
| style="background:#D4FFDF;" | core_course_get_contents() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | get course content (modules + web service file urls) || MDL-28646
|-
|course
| style="background:#D4FFDF;" | core_course_delete_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete courses || MDL-13130
|-
|course
| style="background:#D4FFDF;" | core_course_duplicate_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | duplicate a course || MDL-32233
|-
|course
| style="background:#D4FFDF;" | core_course_get_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_update_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_create_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_delete_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete categories || MDL-32941
|-
|group
| style="background:#D4FFDF;" | core_group_create_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_update_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_assign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | assign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_unassign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | unassign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get all groupings in specified course || MDL-32662
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_field() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve users information for a specified unique field - If you want to do a user search, use core_user_get_users() || MDL-35543
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users_with_capability() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | For each course and capability specified, return a list of the users that are enrolled in the course and have that capability || MDL-31859
|-
|course
| style="background:#D4FFDF;" | core_course_import_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Import course data from a course into another course. Does not include any user data. || MDL-32919
|-
|message
| style="background:#D4FFDF;" | core_message_create_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Add contacts to the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_delete_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Remove contacts from the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_block_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Block contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_unblock_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Unblock contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_get_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_search_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search for contacts || MDL-30070
|-
|external
| style="background:#D4FFDF;" | core_get_string() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return a translated string - similar to core get_string() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_component_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return all raw strings (with {$a->xxx}) for a specific component - similar to core get_component_strings() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return some translated strings - like several core get_string() calls || MDL-35997
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_delete_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete calendar events || MDL-37077
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_get_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Get calendar events || MDL-37100
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_create_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Create calendar events || MDL-37101
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_grades() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns grades from the assignment || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_assignments() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns the courses and assignments for the users capability || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns the submissions for assignments || MDL-31682
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_user_flags || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the user_flags for assignments || MDL-40548
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_user_mappings || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the user_mappings for assignments || MDL-40548
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_revert_submissions_to_draft || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Reverts the list of submissions to draft status || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_lock_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Prevent students from making changes to a list of submissions || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_unlock_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Allow students to make changes to a list of submissions || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_save_submission || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Update the current students submission || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_submit_for_grading || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Submit the current students assignment for grading || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_save_grade || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Save a grade update for a single student. || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_save_grades || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.7 || style="background:#D4FFDF;" | Save grade updates for one or more students. || MDL-42425
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_save_user_extensions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Save a list of assignment extensions || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_reveal_identities || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Reveal the identities for a blind marking assignment || MDL-37148
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forums_by_courses || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum instances in a provided set of courses, if no courses are provided then all the forum instances the user has access to will be returned. || MDL-37247
|-
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forum_discussions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum discussions in a provided set of forums. || MDL-30102
|-
|course
| style="background:#D4FFDF;" | core_course_update_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update courses. || MDL-30062
|-
|user
| style="background:#D4FFDF;" | core_user_get_users() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search users. - If you want to get multiple users for one specific field, use core_user_get_users_by_field(), it's designed for this purpose and it should be faster. || MDL-29938
|-
|grade
| style="background:#D4FFDF;" | core_grade_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned. Will be deprecated and replaced by core_grading_get_definitions in 2.6|| MDL-31681
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned.|| MDL-31890
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_gradingform_instances() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the instances and fillings for the requested definition id. An optional since parameter allows the number of records returned to be reduced so that only those with a timemodified value >= since are returned|| MDL-31890
|-
|grading
| style="background:#D4FFDF;" | core_grading_save_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.8 || style="background:#D4FFDF;" |Accepts an array of areas as a parameter. The areas contain grading definitions with criteria for inserting and updating|| MDL-31861
|-
|}
This is the list of the integrated core functions. To see the roadmap, see to the tracker issue in the section bellow.

=== API Roadmap===
Tracker issue: MDL-29934

= See also =
* [[Web services API Changes]]
* [[How to contribute a web service function to core]]
* [[Web services|Web services developer documentation]]
* [[:en:Web services|Web services user documentation]]

[[Category:Web Services]]
[[Category:API]]

Web service API functions

2014-06-20T02:07:27Z

Pcharsle: /* Core web service functions */

{{Moodle_2.0}}

{| class = "wikitable"
|+Color meaning
|-
| style="background:#D4FFDF;" | Implemented
|-
| style="background:#ffdead;" | Must be implemented
|-
| style="background:#ffdfcd;" | Suggested
|}

==Web service protocols==

{| class="wikitable sortable"
! Name !! Moodle Ver. !! class="unsortable" |Description !! class="unsortable" | Issue
|-
| style="background:#D4FFDF;" | AMF || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adobe protocol to communicate with Flash/Flex apps ||
|-
| style="background:#D4FFDF;" | REST (returning XML) || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML data accessed through a REST API (not restful) ||
|-
| style="background:#D4FFDF;" | REST (returning JSON) || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | JSON data accessed through a REST API (not restful) || MDL-29242
|-
| style="background:#ffdfcd;" | REST (returning JSONP) || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | Would be very useful for client-side JavaScript || MDL-29913
|-
| style="background:#ffdfcd;" | JSON || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | JSON server receives a JSON encoded params and return JSON encoded values. || MDL-21341
|-
| style="background:#ffdead;" | SOAP|| style="background:#ffdead;" | 2.0 || style="background:#ffdead;" | Very important for interoperating with Java and .Net applications. There was a partial implementation JAVA/.Net in Moodle 2.0, but it does not work for anything but the most trivial functions. It is fully working with PHP clients.|| MDL-20804, MDL-28988, MDL-28989
|-
| style="background:#D4FFDF;" | XMLRPC|| style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML remote-procedure call. ||
|}

==Web service functions==

=== Naming convention ===

We updated (regularised) the naming convention in Moodle 2.2. See MDL-29106 for those details.

All functions should be named as follows:

* wsfunction = fullcomponent_methodname
* fullcomponent = [https://docs.moodle.org/dev/Frankenstyle frankenstyle] (eg core_xxxx or mod_xxx etc)
* methodname = verb_noun(s)
* verb = get|create|delete|update
* noun = moodle objects, usually plural (eg posts, discussions, users, courses etc)

=== Core web service functions ===
{| class="wikitable sortable"
!Area!! Moodle 2.2 name !! Moodle 2.0/2.1 name !! Introduced in !! class="unsortable" |Description !! class="unsortable" | Issue
|-
|user
| style="background:#D4FFDF;" | core_user_create_users() || style="background:#D4FFDF;" | moodle_user_create_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_delete_users() || style="background:#D4FFDF;" | moodle_user_delete_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Delete users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_update_users() || style="background:#D4FFDF;" | moodle_user_update_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Update users ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_id() || style="background:#D4FFDF;" | moodle_user_get_users_by_id() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Get users by id ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_course_user_profiles() || style="background:#D4FFDF;" | moodle_user_get_course_participants_by_id() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get course user profiles by id ||
|-

|cohort
| style="background:#D4FFDF;" | core_cohort_create_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Create cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_update_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Update cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_add_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Add members to cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete members from cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohort members || MDL-29472
|-

|course
| style="background:#D4FFDF;" | core_course_get_courses() || style="background:#D4FFDF;" | moodle_course_get_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Return course details ||
|-
|course
| style="background:#D4FFDF;" | core_course_create_courses() || style="background:#D4FFDF;" | moodle_course_create_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create new courses ||
|-
|group
| style="background:#D4FFDF;" | core_group_create_groups() || style="background:#D4FFDF;" | moodle_group_create_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Creates new groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_groups() || style="background:#D4FFDF;" | moodle_group_get_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group details. ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groups() || style="background:#D4FFDF;" | moodle_group_get_course_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns all groups in specified course ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groups() || style="background:#D4FFDF;" | moodle_group_delete_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes all specified groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_group_members() || style="background:#D4FFDF;" | moodle_group_get_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_add_group_members() || style="background:#D4FFDF;" | moodle_group_add_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adds group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_group_members() || style="background:#D4FFDF;" | moodle_group_delete_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes group members ||
|-
|role
| style="background:#D4FFDF;" | core_role_assign_roles() || style="background:#D4FFDF;" | moodle_role_assign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role assignments ||
|-
|role
| style="background:#D4FFDF;" | core_role_unassign_roles() || style="background:#D4FFDF;" | moodle_role_unassign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role unassignments ||
|-
|enrol
| style="background:#D4FFDF;" | NONE || style="background:#D4FFDF;" | moodle_enrol_get_enrolled_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get some minimal information about the users enrolled in a course (DEPRECATED) ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users() || style="background:#D4FFDF;" | moodle_user_get_users_by_courseid() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get enrolled users by course id ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_users_courses() || style="background:#D4FFDF;" | moodle_enrol_get_users_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get list of course ids that a user is enrolled in (if you are allowed to see that) ||
|-
|enrol/manual
| style="background:#D4FFDF;" | enrol_manual_enrol_users() || style="background:#D4FFDF;" | moodle_enrol_manual_enrol_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual enrol users ||
|-
|webservice
| style="background:#D4FFDF;" | core_webservice_get_site_info() || style="background:#D4FFDF;" | moodle_webservice_get_siteinfo() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Return some site info / user info / list web service functions ||
|-
|message
| style="background:#D4FFDF;" | core_message_send_instant_messages() || style="background:#D4FFDF;" | moodle_message_send_instantmessages() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Send instant messages ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_create_notes() || style="background:#D4FFDF;" | moodle_notes_create_notes() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Create notes ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_delete_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_get_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_update_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update Notes || MDL-30072
|-
|files
| style="background:#D4FFDF;" | core_files_get_files() || style="background:#D4FFDF;" | moodle_file_get_files() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | browse moodle files ||
|-
|files
| style="background:#D4FFDF;" | core_files_upload() || style="background:#D4FFDF;" | moodle_file_upload() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | upload a file to moodle (DEPRECATED) ||
|-
|course
| style="background:#D4FFDF;" | core_course_get_contents() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | get course content (modules + web service file urls) || MDL-28646
|-
|course
| style="background:#D4FFDF;" | core_course_delete_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete courses || MDL-13130
|-
|course
| style="background:#D4FFDF;" | core_course_duplicate_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | duplicate a course || MDL-32233
|-
|course
| style="background:#D4FFDF;" | core_course_get_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_update_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_create_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_delete_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete categories || MDL-32941
|-
|group
| style="background:#D4FFDF;" | core_group_create_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_update_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_assign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | assign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_unassign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | unassign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get all groupings in specified course || MDL-32662
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_field() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve users information for a specified unique field - If you want to do a user search, use core_user_get_users() || MDL-35543
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users_with_capability() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | For each course and capability specified, return a list of the users that are enrolled in the course and have that capability || MDL-31859
|-
|course
| style="background:#D4FFDF;" | core_course_import_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Import course data from a course into another course. Does not include any user data. || MDL-32919
|-
|message
| style="background:#D4FFDF;" | core_message_create_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Add contacts to the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_delete_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Remove contacts from the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_block_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Block contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_unblock_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Unblock contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_get_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_search_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search for contacts || MDL-30070
|-
|external
| style="background:#D4FFDF;" | core_get_string() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return a translated string - similar to core get_string() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_component_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return all raw strings (with {$a->xxx}) for a specific component - similar to core get_component_strings() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return some translated strings - like several core get_string() calls || MDL-35997
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_delete_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete calendar events || MDL-37077
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_get_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Get calendar events || MDL-37100
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_create_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Create calendar events || MDL-37101
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_grades() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns grades from the assignment || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_assignments() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns the courses and assignments for the users capability || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns the submissions for assignments || MDL-31682
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_user_flags || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the user_flags for assignments || MDL-40548
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_user_mappings || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the user_mappings for assignments || MDL-40548
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_revert_submissions_to_draft || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Reverts the list of submissions to draft status || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_lock_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Prevent students from making changes to a list of submissions || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_unlock_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Allow students to make changes to a list of submissions || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_save_submission || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Update the current students submission || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_submit_for_grading || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Submit the current students assignment for grading || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_save_grade || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Save a grade update for a single student. || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_save_user_extensions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Save a list of assignment extensions || MDL-37148
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_reveal_identities || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Reveal the identities for a blind marking assignment || MDL-37148
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forums_by_courses || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum instances in a provided set of courses, if no courses are provided then all the forum instances the user has access to will be returned. || MDL-37247
|-
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forum_discussions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum discussions in a provided set of forums. || MDL-30102
|-
|course
| style="background:#D4FFDF;" | core_course_update_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update courses. || MDL-30062
|-
|user
| style="background:#D4FFDF;" | core_user_get_users() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search users. - If you want to get multiple users for one specific field, use core_user_get_users_by_field(), it's designed for this purpose and it should be faster. || MDL-29938
|-
|grade
| style="background:#D4FFDF;" | core_grade_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned. Will be deprecated and replaced by core_grading_get_definitions in 2.6|| MDL-31681
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned.|| MDL-31890
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_gradingform_instances() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the instances and fillings for the requested definition id. An optional since parameter allows the number of records returned to be reduced so that only those with a timemodified value >= since are returned|| MDL-31890
|-
|grading
| style="background:#D4FFDF;" | core_grading_save_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.8 || style="background:#D4FFDF;" |Accepts an array of areas as a parameter. The areas contain grading definitions with criteria for inserting and updating|| MDL-31861
|-
|}
This is the list of the integrated core functions. To see the roadmap, see to the tracker issue in the section bellow.

=== API Roadmap===
Tracker issue: MDL-29934

= See also =
* [[Web services API Changes]]
* [[How to contribute a web service function to core]]
* [[Web services|Web services developer documentation]]
* [[:en:Web services|Web services user documentation]]

[[Category:Web Services]]
[[Category:API]]

Web service API functions

2013-09-11T02:53:38Z

Pcharsle: /* Core web service functions */

{{Moodle_2.0}}

{| class = "wikitable"
|+Color meaning
|-
| style="background:#D4FFDF;" | Implemented
|-
| style="background:#ffdead;" | Must be implemented
|-
| style="background:#ffdfcd;" | Suggested
|}

==Web service protocols==

{| class="wikitable sortable"
! Name !! Moodle Ver. !! class="unsortable" |Description !! class="unsortable" | Issue
|-
| style="background:#D4FFDF;" | AMF || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adobe protocol to communicate with Flash/Flex apps ||
|-
| style="background:#D4FFDF;" | REST (returning XML) || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML data accessed through a REST API (not restful) ||
|-
| style="background:#D4FFDF;" | REST (returning JSON) || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | JSON data accessed through a REST API (not restful) || MDL-29242
|-
| style="background:#ffdfcd;" | REST (returning JSONP) || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | Would be very useful for client-side JavaScript || MDL-29913
|-
| style="background:#ffdfcd;" | JSON || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | JSON server receives a JSON encoded params and return JSON encoded values. || MDL-21341
|-
| style="background:#ffdead;" | SOAP|| style="background:#ffdead;" | 2.0 || style="background:#ffdead;" | Very important for interoperating with Java and .Net applications. There was a partial implementation JAVA/.Net in Moodle 2.0, but it does not work for anything but the most trivial functions. It is fully working with PHP clients.|| MDL-20804, MDL-28988, MDL-28989
|-
| style="background:#D4FFDF;" | XMLRPC|| style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML remote-procedure call. ||
|}

==Web service functions==

=== Naming convention ===

We updated (regularised) the naming convention in Moodle 2.2. See MDL-29106 for those details.

All functions should be named as follows:

* wsfunction = fullcomponent_methodname
* fullcomponent = [https://docs.moodle.org/dev/Frankenstyle frankenstyle] (eg core_xxxx or mod_xxx etc)
* methodname = verb_noun(s)
* verb = get|create|delete|update
* noun = moodle objects, usually plural (eg posts, discussions, users, courses etc)

=== Core web service functions ===
{| class="wikitable sortable"
!Area!! Moodle 2.2 name !! Moodle 2.0/2.1 name !! Introduced in !! class="unsortable" |Description !! class="unsortable" | Issue
|-
|user
| style="background:#D4FFDF;" | core_user_create_users() || style="background:#D4FFDF;" | moodle_user_create_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_delete_users() || style="background:#D4FFDF;" | moodle_user_delete_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Delete users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_update_users() || style="background:#D4FFDF;" | moodle_user_update_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Update users ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_id() || style="background:#D4FFDF;" | moodle_user_get_users_by_id() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Get users by id ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_course_user_profiles() || style="background:#D4FFDF;" | moodle_user_get_course_participants_by_id() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get course user profiles by id ||
|-

|cohort
| style="background:#D4FFDF;" | core_cohort_create_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Create cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_update_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Update cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_add_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Add members to cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete members from cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohort members || MDL-29472
|-

|course
| style="background:#D4FFDF;" | core_course_get_courses() || style="background:#D4FFDF;" | moodle_course_get_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Return course details ||
|-
|course
| style="background:#D4FFDF;" | core_course_create_courses() || style="background:#D4FFDF;" | moodle_course_create_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create new courses ||
|-
|group
| style="background:#D4FFDF;" | core_group_create_groups() || style="background:#D4FFDF;" | moodle_group_create_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Creates new groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_groups() || style="background:#D4FFDF;" | moodle_group_get_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group details. ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groups() || style="background:#D4FFDF;" | moodle_group_get_course_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns all groups in specified course ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groups() || style="background:#D4FFDF;" | moodle_group_delete_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes all specified groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_group_members() || style="background:#D4FFDF;" | moodle_group_get_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_add_group_members() || style="background:#D4FFDF;" | moodle_group_add_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adds group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_group_members() || style="background:#D4FFDF;" | moodle_group_delete_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes group members ||
|-
|role
| style="background:#D4FFDF;" | core_role_assign_roles() || style="background:#D4FFDF;" | moodle_role_assign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role assignments ||
|-
|role
| style="background:#D4FFDF;" | core_role_unassign_roles() || style="background:#D4FFDF;" | moodle_role_unassign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role unassignments ||
|-
|enrol
| style="background:#D4FFDF;" | NONE || style="background:#D4FFDF;" | moodle_enrol_get_enrolled_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get some minimal information about the users enrolled in a course (DEPRECATED) ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users() || style="background:#D4FFDF;" | moodle_user_get_users_by_courseid() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get enrolled users by course id ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_users_courses() || style="background:#D4FFDF;" | moodle_enrol_get_users_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get list of course ids that a user is enrolled in (if you are allowed to see that) ||
|-
|enrol/manual
| style="background:#D4FFDF;" | enrol_manual_enrol_users() || style="background:#D4FFDF;" | moodle_enrol_manual_enrol_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual enrol users ||
|-
|webservice
| style="background:#D4FFDF;" | core_webservice_get_site_info() || style="background:#D4FFDF;" | moodle_webservice_get_siteinfo() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Return some site info / user info / list web service functions ||
|-
|message
| style="background:#D4FFDF;" | core_message_send_instant_messages() || style="background:#D4FFDF;" | moodle_message_send_instantmessages() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Send instant messages ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_create_notes() || style="background:#D4FFDF;" | moodle_notes_create_notes() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Create notes ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_delete_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_get_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_update_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update Notes || MDL-30072
|-
|files
| style="background:#D4FFDF;" | core_files_get_files() || style="background:#D4FFDF;" | moodle_file_get_files() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | browse moodle files ||
|-
|files
| style="background:#D4FFDF;" | core_files_upload() || style="background:#D4FFDF;" | moodle_file_upload() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | upload a file to moodle (DEPRECATED) ||
|-
|course
| style="background:#D4FFDF;" | core_course_get_contents() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | get course content (modules + web service file urls) || MDL-28646
|-
|course
| style="background:#D4FFDF;" | core_course_delete_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete courses || MDL-13130
|-
|course
| style="background:#D4FFDF;" | core_course_duplicate_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | duplicate a course || MDL-32233
|-
|course
| style="background:#D4FFDF;" | core_course_get_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_update_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_create_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_delete_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete categories || MDL-32941
|-
|group
| style="background:#D4FFDF;" | core_group_create_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_update_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_assign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | assign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_unassign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | unassign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get all groupings in specified course || MDL-32662
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_field() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve users information for a specified unique field - If you want to do a user search, use core_user_get_users() || MDL-35543
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users_with_capability() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | For each course and capability specified, return a list of the users that are enrolled in the course and have that capability || MDL-31859
|-
|course
| style="background:#D4FFDF;" | core_course_import_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Import course data from a course into another course. Does not include any user data. || MDL-32919
|-
|message
| style="background:#D4FFDF;" | core_message_create_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Add contacts to the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_delete_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Remove contacts from the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_block_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Block contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_unblock_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Unblock contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_get_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_search_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search for contacts || MDL-30070
|-
|external
| style="background:#D4FFDF;" | core_get_string() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return a translated string - similar to core get_string() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_component_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return all raw strings (with {$a->xxx}) for a specific component - similar to core get_component_strings() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return some translated strings - like several core get_string() calls || MDL-35997
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_delete_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete calendar events || MDL-37077
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_get_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Get calendar events || MDL-37100
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_create_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Create calendar events || MDL-37101
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_grades() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns grades from the assignment || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_assignments() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns the courses and assignments for the users capability || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns the submissions for assignments || MDL-31682
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_user_flags || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the user_flags for assignments || MDL-40548
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_user_mappings || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the user_mappings for assignments || MDL-40548
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forums_by_courses || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum instances in a provided set of courses, if no courses are provided then all the forum instances the user has access to will be returned. || MDL-37247
|-
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forum_discussions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum discussions in a provided set of forums. || MDL-30102
|-
|course
| style="background:#D4FFDF;" | core_course_update_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update courses. || MDL-30062
|-
|user
| style="background:#D4FFDF;" | core_user_get_users() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search users. - If you want to get multiple users for one specific field, use core_user_get_users_by_field(), it's designed for this purpose and it should be faster. || MDL-29938
|-
|grade
| style="background:#D4FFDF;" | core_grade_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned. Will be deprecated and replaced by core_grading_get_definitions in 2.6|| MDL-31681
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned.|| MDL-31890
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_gradingform_instances() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the instances and fillings for the requested definition id. An optional since parameter allows the number of records returned to be reduced so that only those with a timemodified value >= since are returned|| MDL-31890
|-

|}
This is the list of the integrated core functions. To see the roadmap, see to the tracker issue in the section bellow.

=== API Roadmap===
Tracker issue: MDL-29934

= See also =
* [[Web services API Changes]]
* [[How to contribute a web service function to core]]
* [[Web services|Web services developer documentation]]
* [[:en:Web services|Web services user documentation]]

[[Category:Web Services]]
[[Category:API]]

Web service API functions

2013-09-11T02:46:41Z

Pcharsle: /* Core web service functions */

{{Moodle_2.0}}

{| class = "wikitable"
|+Color meaning
|-
| style="background:#D4FFDF;" | Implemented
|-
| style="background:#ffdead;" | Must be implemented
|-
| style="background:#ffdfcd;" | Suggested
|}

==Web service protocols==

{| class="wikitable sortable"
! Name !! Moodle Ver. !! class="unsortable" |Description !! class="unsortable" | Issue
|-
| style="background:#D4FFDF;" | AMF || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adobe protocol to communicate with Flash/Flex apps ||
|-
| style="background:#D4FFDF;" | REST (returning XML) || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML data accessed through a REST API (not restful) ||
|-
| style="background:#D4FFDF;" | REST (returning JSON) || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | JSON data accessed through a REST API (not restful) || MDL-29242
|-
| style="background:#ffdfcd;" | REST (returning JSONP) || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | Would be very useful for client-side JavaScript || MDL-29913
|-
| style="background:#ffdfcd;" | JSON || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | JSON server receives a JSON encoded params and return JSON encoded values. || MDL-21341
|-
| style="background:#ffdead;" | SOAP|| style="background:#ffdead;" | 2.0 || style="background:#ffdead;" | Very important for interoperating with Java and .Net applications. There was a partial implementation JAVA/.Net in Moodle 2.0, but it does not work for anything but the most trivial functions. It is fully working with PHP clients.|| MDL-20804, MDL-28988, MDL-28989
|-
| style="background:#D4FFDF;" | XMLRPC|| style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML remote-procedure call. ||
|}

==Web service functions==

=== Naming convention ===

We updated (regularised) the naming convention in Moodle 2.2. See MDL-29106 for those details.

All functions should be named as follows:

* wsfunction = fullcomponent_methodname
* fullcomponent = [https://docs.moodle.org/dev/Frankenstyle frankenstyle] (eg core_xxxx or mod_xxx etc)
* methodname = verb_noun(s)
* verb = get|create|delete|update
* noun = moodle objects, usually plural (eg posts, discussions, users, courses etc)

=== Core web service functions ===
{| class="wikitable sortable"
!Area!! Moodle 2.2 name !! Moodle 2.0/2.1 name !! Introduced in !! class="unsortable" |Description !! class="unsortable" | Issue
|-
|user
| style="background:#D4FFDF;" | core_user_create_users() || style="background:#D4FFDF;" | moodle_user_create_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_delete_users() || style="background:#D4FFDF;" | moodle_user_delete_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Delete users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_update_users() || style="background:#D4FFDF;" | moodle_user_update_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Update users ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_id() || style="background:#D4FFDF;" | moodle_user_get_users_by_id() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Get users by id ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_course_user_profiles() || style="background:#D4FFDF;" | moodle_user_get_course_participants_by_id() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get course user profiles by id ||
|-

|cohort
| style="background:#D4FFDF;" | core_cohort_create_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Create cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_update_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Update cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_add_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Add members to cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete members from cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohort members || MDL-29472
|-

|course
| style="background:#D4FFDF;" | core_course_get_courses() || style="background:#D4FFDF;" | moodle_course_get_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Return course details ||
|-
|course
| style="background:#D4FFDF;" | core_course_create_courses() || style="background:#D4FFDF;" | moodle_course_create_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create new courses ||
|-
|group
| style="background:#D4FFDF;" | core_group_create_groups() || style="background:#D4FFDF;" | moodle_group_create_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Creates new groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_groups() || style="background:#D4FFDF;" | moodle_group_get_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group details. ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groups() || style="background:#D4FFDF;" | moodle_group_get_course_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns all groups in specified course ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groups() || style="background:#D4FFDF;" | moodle_group_delete_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes all specified groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_group_members() || style="background:#D4FFDF;" | moodle_group_get_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_add_group_members() || style="background:#D4FFDF;" | moodle_group_add_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adds group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_group_members() || style="background:#D4FFDF;" | moodle_group_delete_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes group members ||
|-
|role
| style="background:#D4FFDF;" | core_role_assign_roles() || style="background:#D4FFDF;" | moodle_role_assign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role assignments ||
|-
|role
| style="background:#D4FFDF;" | core_role_unassign_roles() || style="background:#D4FFDF;" | moodle_role_unassign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role unassignments ||
|-
|enrol
| style="background:#D4FFDF;" | NONE || style="background:#D4FFDF;" | moodle_enrol_get_enrolled_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get some minimal information about the users enrolled in a course (DEPRECATED) ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users() || style="background:#D4FFDF;" | moodle_user_get_users_by_courseid() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get enrolled users by course id ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_users_courses() || style="background:#D4FFDF;" | moodle_enrol_get_users_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get list of course ids that a user is enrolled in (if you are allowed to see that) ||
|-
|enrol/manual
| style="background:#D4FFDF;" | enrol_manual_enrol_users() || style="background:#D4FFDF;" | moodle_enrol_manual_enrol_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual enrol users ||
|-
|webservice
| style="background:#D4FFDF;" | core_webservice_get_site_info() || style="background:#D4FFDF;" | moodle_webservice_get_siteinfo() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Return some site info / user info / list web service functions ||
|-
|message
| style="background:#D4FFDF;" | core_message_send_instant_messages() || style="background:#D4FFDF;" | moodle_message_send_instantmessages() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Send instant messages ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_create_notes() || style="background:#D4FFDF;" | moodle_notes_create_notes() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Create notes ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_delete_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_get_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_update_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update Notes || MDL-30072
|-
|files
| style="background:#D4FFDF;" | core_files_get_files() || style="background:#D4FFDF;" | moodle_file_get_files() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | browse moodle files ||
|-
|files
| style="background:#D4FFDF;" | core_files_upload() || style="background:#D4FFDF;" | moodle_file_upload() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | upload a file to moodle (DEPRECATED) ||
|-
|course
| style="background:#D4FFDF;" | core_course_get_contents() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | get course content (modules + web service file urls) || MDL-28646
|-
|course
| style="background:#D4FFDF;" | core_course_delete_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete courses || MDL-13130
|-
|course
| style="background:#D4FFDF;" | core_course_duplicate_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | duplicate a course || MDL-32233
|-
|course
| style="background:#D4FFDF;" | core_course_get_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_update_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_create_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_delete_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete categories || MDL-32941
|-
|group
| style="background:#D4FFDF;" | core_group_create_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_update_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_assign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | assign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_unassign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | unassign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get all groupings in specified course || MDL-32662
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_field() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve users information for a specified unique field - If you want to do a user search, use core_user_get_users() || MDL-35543
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users_with_capability() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | For each course and capability specified, return a list of the users that are enrolled in the course and have that capability || MDL-31859
|-
|course
| style="background:#D4FFDF;" | core_course_import_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Import course data from a course into another course. Does not include any user data. || MDL-32919
|-
|message
| style="background:#D4FFDF;" | core_message_create_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Add contacts to the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_delete_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Remove contacts from the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_block_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Block contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_unblock_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Unblock contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_get_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_search_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search for contacts || MDL-30070
|-
|external
| style="background:#D4FFDF;" | core_get_string() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return a translated string - similar to core get_string() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_component_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return all raw strings (with {$a->xxx}) for a specific component - similar to core get_component_strings() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return some translated strings - like several core get_string() calls || MDL-35997
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_delete_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete calendar events || MDL-37077
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_get_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Get calendar events || MDL-37100
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_create_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Create calendar events || MDL-37101
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_grades() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns grades from the assignment || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_assignments() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns the courses and assignments for the users capability || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns the submissions for assignments || MDL-31682
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forums_by_courses || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum instances in a provided set of courses, if no courses are provided then all the forum instances the user has access to will be returned. || MDL-37247
|-
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forum_discussions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum discussions in a provided set of forums. || MDL-30102
|-
|course
| style="background:#D4FFDF;" | core_course_update_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update courses. || MDL-30062
|-
|user
| style="background:#D4FFDF;" | core_user_get_users() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search users. - If you want to get multiple users for one specific field, use core_user_get_users_by_field(), it's designed for this purpose and it should be faster. || MDL-29938
|-
|grade
| style="background:#D4FFDF;" | core_grade_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned.|| MDL-31681
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned.|| MDL-31890
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_gradingform_instances() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the instances and fillings for the requested definition id. An optional since parameter allows the number of records returned to be reduced so that only those with a timemodified value >= since are returned|| MDL-31890
|-

|}
This is the list of the integrated core functions. To see the roadmap, see to the tracker issue in the section bellow.

=== API Roadmap===
Tracker issue: MDL-29934

= See also =
* [[Web services API Changes]]
* [[How to contribute a web service function to core]]
* [[Web services|Web services developer documentation]]
* [[:en:Web services|Web services user documentation]]

[[Category:Web Services]]
[[Category:API]]

Web service API functions

2013-09-11T02:42:30Z

Pcharsle: /* Core web service functions */

{{Moodle_2.0}}

{| class = "wikitable"
|+Color meaning
|-
| style="background:#D4FFDF;" | Implemented
|-
| style="background:#ffdead;" | Must be implemented
|-
| style="background:#ffdfcd;" | Suggested
|}

==Web service protocols==

{| class="wikitable sortable"
! Name !! Moodle Ver. !! class="unsortable" |Description !! class="unsortable" | Issue
|-
| style="background:#D4FFDF;" | AMF || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adobe protocol to communicate with Flash/Flex apps ||
|-
| style="background:#D4FFDF;" | REST (returning XML) || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML data accessed through a REST API (not restful) ||
|-
| style="background:#D4FFDF;" | REST (returning JSON) || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | JSON data accessed through a REST API (not restful) || MDL-29242
|-
| style="background:#ffdfcd;" | REST (returning JSONP) || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | Would be very useful for client-side JavaScript || MDL-29913
|-
| style="background:#ffdfcd;" | JSON || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | JSON server receives a JSON encoded params and return JSON encoded values. || MDL-21341
|-
| style="background:#ffdead;" | SOAP|| style="background:#ffdead;" | 2.0 || style="background:#ffdead;" | Very important for interoperating with Java and .Net applications. There was a partial implementation JAVA/.Net in Moodle 2.0, but it does not work for anything but the most trivial functions. It is fully working with PHP clients.|| MDL-20804, MDL-28988, MDL-28989
|-
| style="background:#D4FFDF;" | XMLRPC|| style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML remote-procedure call. ||
|}

==Web service functions==

=== Naming convention ===

We updated (regularised) the naming convention in Moodle 2.2. See MDL-29106 for those details.

All functions should be named as follows:

* wsfunction = fullcomponent_methodname
* fullcomponent = [https://docs.moodle.org/dev/Frankenstyle frankenstyle] (eg core_xxxx or mod_xxx etc)
* methodname = verb_noun(s)
* verb = get|create|delete|update
* noun = moodle objects, usually plural (eg posts, discussions, users, courses etc)

=== Core web service functions ===
{| class="wikitable sortable"
!Area!! Moodle 2.2 name !! Moodle 2.0/2.1 name !! Introduced in !! class="unsortable" |Description !! class="unsortable" | Issue
|-
|user
| style="background:#D4FFDF;" | core_user_create_users() || style="background:#D4FFDF;" | moodle_user_create_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_delete_users() || style="background:#D4FFDF;" | moodle_user_delete_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Delete users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_update_users() || style="background:#D4FFDF;" | moodle_user_update_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Update users ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_id() || style="background:#D4FFDF;" | moodle_user_get_users_by_id() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Get users by id ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_course_user_profiles() || style="background:#D4FFDF;" | moodle_user_get_course_participants_by_id() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get course user profiles by id ||
|-

|cohort
| style="background:#D4FFDF;" | core_cohort_create_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Create cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_update_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Update cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_add_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Add members to cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete members from cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohort members || MDL-29472
|-

|course
| style="background:#D4FFDF;" | core_course_get_courses() || style="background:#D4FFDF;" | moodle_course_get_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Return course details ||
|-
|course
| style="background:#D4FFDF;" | core_course_create_courses() || style="background:#D4FFDF;" | moodle_course_create_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create new courses ||
|-
|group
| style="background:#D4FFDF;" | core_group_create_groups() || style="background:#D4FFDF;" | moodle_group_create_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Creates new groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_groups() || style="background:#D4FFDF;" | moodle_group_get_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group details. ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groups() || style="background:#D4FFDF;" | moodle_group_get_course_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns all groups in specified course ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groups() || style="background:#D4FFDF;" | moodle_group_delete_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes all specified groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_group_members() || style="background:#D4FFDF;" | moodle_group_get_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_add_group_members() || style="background:#D4FFDF;" | moodle_group_add_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adds group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_group_members() || style="background:#D4FFDF;" | moodle_group_delete_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes group members ||
|-
|role
| style="background:#D4FFDF;" | core_role_assign_roles() || style="background:#D4FFDF;" | moodle_role_assign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role assignments ||
|-
|role
| style="background:#D4FFDF;" | core_role_unassign_roles() || style="background:#D4FFDF;" | moodle_role_unassign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role unassignments ||
|-
|enrol
| style="background:#D4FFDF;" | NONE || style="background:#D4FFDF;" | moodle_enrol_get_enrolled_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get some minimal information about the users enrolled in a course (DEPRECATED) ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users() || style="background:#D4FFDF;" | moodle_user_get_users_by_courseid() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get enrolled users by course id ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_users_courses() || style="background:#D4FFDF;" | moodle_enrol_get_users_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get list of course ids that a user is enrolled in (if you are allowed to see that) ||
|-
|enrol/manual
| style="background:#D4FFDF;" | enrol_manual_enrol_users() || style="background:#D4FFDF;" | moodle_enrol_manual_enrol_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual enrol users ||
|-
|webservice
| style="background:#D4FFDF;" | core_webservice_get_site_info() || style="background:#D4FFDF;" | moodle_webservice_get_siteinfo() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Return some site info / user info / list web service functions ||
|-
|message
| style="background:#D4FFDF;" | core_message_send_instant_messages() || style="background:#D4FFDF;" | moodle_message_send_instantmessages() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Send instant messages ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_create_notes() || style="background:#D4FFDF;" | moodle_notes_create_notes() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Create notes ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_delete_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_get_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_update_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update Notes || MDL-30072
|-
|files
| style="background:#D4FFDF;" | core_files_get_files() || style="background:#D4FFDF;" | moodle_file_get_files() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | browse moodle files ||
|-
|files
| style="background:#D4FFDF;" | core_files_upload() || style="background:#D4FFDF;" | moodle_file_upload() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | upload a file to moodle (DEPRECATED) ||
|-
|course
| style="background:#D4FFDF;" | core_course_get_contents() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | get course content (modules + web service file urls) || MDL-28646
|-
|course
| style="background:#D4FFDF;" | core_course_delete_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete courses || MDL-13130
|-
|course
| style="background:#D4FFDF;" | core_course_duplicate_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | duplicate a course || MDL-32233
|-
|course
| style="background:#D4FFDF;" | core_course_get_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_update_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_create_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_delete_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete categories || MDL-32941
|-
|group
| style="background:#D4FFDF;" | core_group_create_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_update_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_assign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | assign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_unassign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | unassign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get all groupings in specified course || MDL-32662
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_field() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve users information for a specified unique field - If you want to do a user search, use core_user_get_users() || MDL-35543
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users_with_capability() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | For each course and capability specified, return a list of the users that are enrolled in the course and have that capability || MDL-31859
|-
|course
| style="background:#D4FFDF;" | core_course_import_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Import course data from a course into another course. Does not include any user data. || MDL-32919
|-
|message
| style="background:#D4FFDF;" | core_message_create_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Add contacts to the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_delete_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Remove contacts from the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_block_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Block contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_unblock_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Unblock contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_get_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_search_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search for contacts || MDL-30070
|-
|external
| style="background:#D4FFDF;" | core_get_string() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return a translated string - similar to core get_string() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_component_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return all raw strings (with {$a->xxx}) for a specific component - similar to core get_component_strings() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return some translated strings - like several core get_string() calls || MDL-35997
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_delete_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete calendar events || MDL-37077
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_get_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Get calendar events || MDL-37100
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_create_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Create calendar events || MDL-37101
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_grades() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns grades from the assignment || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_assignments() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns the courses and assignments for the users capability || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns the submissions for assignments || MDL-31682
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forums_by_courses || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum instances in a provided set of courses, if no courses are provided then all the forum instances the user has access to will be returned. || MDL-37247
|-
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forum_discussions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum discussions in a provided set of forums. || MDL-30102
|-
|course
| style="background:#D4FFDF;" | core_course_update_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update courses. || MDL-30062
|-
|user
| style="background:#D4FFDF;" | core_user_get_users() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search users. - If you want to get multiple users for one specific field, use core_user_get_users_by_field(), it's designed for this purpose and it should be faster. || MDL-29938
|-
|grade
| style="background:#D4FFDF;" | core_grade_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned.|| MDL-31681
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned.|| MDL-31682
|-
|grading
| style="background:#D4FFDF;" | core_grading_get_gradingform_instances() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.6 || style="background:#D4FFDF;" | Returns the instances and fillings for the requested definition id. An optional since parameter allows the number of records returned to be reduced so that only those with a timemodified value >= since are returned|| MDL-31682
|-

|}
This is the list of the integrated core functions. To see the roadmap, see to the tracker issue in the section bellow.

=== API Roadmap===
Tracker issue: MDL-29934

= See also =
* [[Web services API Changes]]
* [[How to contribute a web service function to core]]
* [[Web services|Web services developer documentation]]
* [[:en:Web services|Web services user documentation]]

[[Category:Web Services]]
[[Category:API]]

Web service API functions

2013-03-27T04:10:33Z

Pcharsle: /* Core web service functions */

{{Moodle_2.0}}

{| class = "wikitable"
|+Color meaning
|-
| style="background:#D4FFDF;" | Implemented
|-
| style="background:#ffdead;" | Must be implemented
|-
| style="background:#ffdfcd;" | Suggested
|}

==Web service protocols==

{| class="wikitable sortable"
! Name !! Moodle Ver. !! class="unsortable" |Description !! class="unsortable" | Issue
|-
| style="background:#D4FFDF;" | AMF || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adobe protocol to communicate with Flash/Flex apps ||
|-
| style="background:#D4FFDF;" | REST (returning XML) || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML data accessed through a REST API (not restful) ||
|-
| style="background:#D4FFDF;" | REST (returning JSON) || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | JSON data accessed through a REST API (not restful) || MDL-29242
|-
| style="background:#ffdfcd;" | REST (returning JSONP) || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | Would be very useful for client-side JavaScript || MDL-29913
|-
| style="background:#ffdfcd;" | JSON || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | JSON server receives a JSON encoded params and return JSON encoded values. || MDL-21341
|-
| style="background:#ffdead;" | SOAP|| style="background:#ffdead;" | 2.0 || style="background:#ffdead;" | Very important for interoperating with Java and .Net applications. There was a partial implementation JAVA/.Net in Moodle 2.0, but it does not work for anything but the most trivial functions. It is fully working with PHP clients.|| MDL-20804, MDL-28988, MDL-28989
|-
| style="background:#D4FFDF;" | XMLRPC|| style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML remote-procedure call. ||
|}

==Web service functions==

=== Naming convention ===

We updated (regularised) the naming convention in Moodle 2.2. See MDL-29106 for those details.

All functions should be named as follows:

* wsfunction = fullcomponent_methodname
* fullcomponent = [https://docs.moodle.org/dev/Frankenstyle frankenstyle] (eg core_xxxx or mod_xxx etc)
* methodname = verb_noun(s)
* verb = get|create|delete|update
* noun = moodle objects, usually plural (eg posts, discussions, users, courses etc)

=== Core web service functions ===
{| class="wikitable sortable"
!Area!! Moodle 2.2 name !! Moodle 2.0/2.1 name !! Introduced in !! class="unsortable" |Description !! class="unsortable" | Issue
|-
|user
| style="background:#D4FFDF;" | core_user_create_users() || style="background:#D4FFDF;" | moodle_user_create_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_delete_users() || style="background:#D4FFDF;" | moodle_user_delete_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Delete users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_update_users() || style="background:#D4FFDF;" | moodle_user_update_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Update users ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_id() || style="background:#D4FFDF;" | moodle_user_get_users_by_id() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Get users by id ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_course_user_profiles() || style="background:#D4FFDF;" | moodle_user_get_course_participants_by_id() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get course user profiles by id ||
|-

|cohort
| style="background:#D4FFDF;" | core_cohort_create_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Create cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_update_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Update cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_add_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Add members to cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete members from cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohort members || MDL-29472
|-

|course
| style="background:#D4FFDF;" | core_course_get_courses() || style="background:#D4FFDF;" | moodle_course_get_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Return course details ||
|-
|course
| style="background:#D4FFDF;" | core_course_create_courses() || style="background:#D4FFDF;" | moodle_course_create_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create new courses ||
|-
|group
| style="background:#D4FFDF;" | core_group_create_groups() || style="background:#D4FFDF;" | moodle_group_create_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Creates new groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_groups() || style="background:#D4FFDF;" | moodle_group_get_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group details. ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groups() || style="background:#D4FFDF;" | moodle_group_get_course_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns all groups in specified course ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groups() || style="background:#D4FFDF;" | moodle_group_delete_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes all specified groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_group_members() || style="background:#D4FFDF;" | moodle_group_get_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_add_group_members() || style="background:#D4FFDF;" | moodle_group_add_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adds group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_group_members() || style="background:#D4FFDF;" | moodle_group_delete_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes group members ||
|-
|role
| style="background:#D4FFDF;" | core_role_assign_roles() || style="background:#D4FFDF;" | moodle_role_assign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role assignments ||
|-
|role
| style="background:#D4FFDF;" | core_role_unassign_roles() || style="background:#D4FFDF;" | moodle_role_unassign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role unassignments ||
|-
|enrol
| style="background:#D4FFDF;" | NONE || style="background:#D4FFDF;" | moodle_enrol_get_enrolled_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get some minimal information about the users enrolled in a course (DEPRECATED) ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users() || style="background:#D4FFDF;" | moodle_user_get_users_by_courseid() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get enrolled users by course id ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_users_courses() || style="background:#D4FFDF;" | moodle_enrol_get_users_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get list of course ids that a user is enrolled in (if you are allowed to see that) ||
|-
|enrol/manual
| style="background:#D4FFDF;" | enrol_manual_enrol_users() || style="background:#D4FFDF;" | moodle_enrol_manual_enrol_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual enrol users ||
|-
|webservice
| style="background:#D4FFDF;" | core_webservice_get_site_info() || style="background:#D4FFDF;" | moodle_webservice_get_siteinfo() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Return some site info / user info / list web service functions ||
|-
|message
| style="background:#D4FFDF;" | core_message_send_instant_messages() || style="background:#D4FFDF;" | moodle_message_send_instantmessages() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Send instant messages ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_create_notes() || style="background:#D4FFDF;" | moodle_notes_create_notes() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Create notes ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_delete_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_get_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_update_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update Notes || MDL-30072
|-
|files
| style="background:#D4FFDF;" | core_files_get_files() || style="background:#D4FFDF;" | moodle_file_get_files() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | browse moodle files ||
|-
|files
| style="background:#D4FFDF;" | core_files_upload() || style="background:#D4FFDF;" | moodle_file_upload() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | upload a file to moodle (DEPRECATED) ||
|-
|course
| style="background:#D4FFDF;" | core_course_get_contents() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | get course content (modules + web service file urls) || MDL-28646
|-
|course
| style="background:#D4FFDF;" | core_course_delete_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete courses || MDL-13130
|-
|course
| style="background:#D4FFDF;" | core_course_duplicate_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | duplicate a course || MDL-32233
|-
|course
| style="background:#D4FFDF;" | core_course_get_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_update_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_create_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_delete_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete categories || MDL-32941
|-
|group
| style="background:#D4FFDF;" | core_group_create_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_update_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_assign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | assign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_unassign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | unassign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get all groupings in specified course || MDL-32662
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_field() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve users information for a specified unique field - If you want to do a user search, use core_user_get_users() || MDL-35543
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users_with_capability() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | For each course and capability specified, return a list of the users that are enrolled in the course and have that capability || MDL-31859
|-
|course
| style="background:#D4FFDF;" | core_course_import_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Import course data from a course into another course. Does not include any user data. || MDL-32919
|-
|message
| style="background:#D4FFDF;" | core_message_create_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Add contacts to the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_delete_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Remove contacts from the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_block_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Block contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_unblock_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Unblock contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_get_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_search_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search for contacts || MDL-30070
|-
|external
| style="background:#D4FFDF;" | core_get_string() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return a translated string - similar to core get_string() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_component_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return all raw strings (with {$a->xxx}) for a specific component - similar to core get_component_strings() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return some translated strings - like several core get_string() calls || MDL-35997
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_delete_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete calendar events || MDL-37077
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_get_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Get calendar events || MDL-37100
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_create_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Create calendar events || MDL-37101
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_grades() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns grades from the assignment || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_assignments() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns the courses and assignments for the users capability || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns the submissions for assignments || MDL-31682
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forums_by_courses || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum instances in a provided set of courses, if no courses are provided then all the forum instances the user has access to will be returned. || MDL-37247
|-
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forum_discussions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum discussions in a provided set of forums. || MDL-30102
|-
|course
| style="background:#D4FFDF;" | core_course_update_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update courses. || MDL-30062
|-
|user
| style="background:#D4FFDF;" | core_user_get_users() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search users. - If you want to get multiple users for one specific field, use core_user_get_users_by_field(), it's designed for this purpose and it should be faster. || MDL-29938
|-
|grade
| style="background:#D4FFDF;" | core_grade_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. An optionall activeonly parameter can be provided so that only the active grading method is returned.|| MDL-31681
|-

|}
This is the list of the integrated core functions. To see the roadmap, see to the tracker issue in the section bellow.

=== API Roadmap===
Tracker issue: MDL-29934

= See also =
* [[Web services API Changes]]
* [[How to contribute a web service function to core]]
* [[Web services|Web services developer documentation]]
* [[:en:Web services|Web services user documentation]]

[[Category:Web Services]]
[[Category:API]]

Web service API functions

2013-03-27T03:52:18Z

Pcharsle: /* Core web service functions */

{{Moodle_2.0}}

{| class = "wikitable"
|+Color meaning
|-
| style="background:#D4FFDF;" | Implemented
|-
| style="background:#ffdead;" | Must be implemented
|-
| style="background:#ffdfcd;" | Suggested
|}

==Web service protocols==

{| class="wikitable sortable"
! Name !! Moodle Ver. !! class="unsortable" |Description !! class="unsortable" | Issue
|-
| style="background:#D4FFDF;" | AMF || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adobe protocol to communicate with Flash/Flex apps ||
|-
| style="background:#D4FFDF;" | REST (returning XML) || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML data accessed through a REST API (not restful) ||
|-
| style="background:#D4FFDF;" | REST (returning JSON) || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | JSON data accessed through a REST API (not restful) || MDL-29242
|-
| style="background:#ffdfcd;" | REST (returning JSONP) || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | Would be very useful for client-side JavaScript || MDL-29913
|-
| style="background:#ffdfcd;" | JSON || style="background:#ffdfcd;" | 2.X || style="background:#ffdfcd;" | JSON server receives a JSON encoded params and return JSON encoded values. || MDL-21341
|-
| style="background:#ffdead;" | SOAP|| style="background:#ffdead;" | 2.0 || style="background:#ffdead;" | Very important for interoperating with Java and .Net applications. There was a partial implementation JAVA/.Net in Moodle 2.0, but it does not work for anything but the most trivial functions. It is fully working with PHP clients.|| MDL-20804, MDL-28988, MDL-28989
|-
| style="background:#D4FFDF;" | XMLRPC|| style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | XML remote-procedure call. ||
|}

==Web service functions==

=== Naming convention ===

We updated (regularised) the naming convention in Moodle 2.2. See MDL-29106 for those details.

All functions should be named as follows:

* wsfunction = fullcomponent_methodname
* fullcomponent = [https://docs.moodle.org/dev/Frankenstyle frankenstyle] (eg core_xxxx or mod_xxx etc)
* methodname = verb_noun(s)
* verb = get|create|delete|update
* noun = moodle objects, usually plural (eg posts, discussions, users, courses etc)

=== Core web service functions ===
{| class="wikitable sortable"
!Area!! Moodle 2.2 name !! Moodle 2.0/2.1 name !! Introduced in !! class="unsortable" |Description !! class="unsortable" | Issue
|-
|user
| style="background:#D4FFDF;" | core_user_create_users() || style="background:#D4FFDF;" | moodle_user_create_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_delete_users() || style="background:#D4FFDF;" | moodle_user_delete_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Delete users - admin function ||
|-
|user
| style="background:#D4FFDF;" | core_user_update_users() || style="background:#D4FFDF;" | moodle_user_update_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Update users ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_id() || style="background:#D4FFDF;" | moodle_user_get_users_by_id() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Get users by id ||
|-
|user
| style="background:#D4FFDF;" | core_user_get_course_user_profiles() || style="background:#D4FFDF;" | moodle_user_get_course_participants_by_id() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get course user profiles by id ||
|-

|cohort
| style="background:#D4FFDF;" | core_cohort_create_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Create cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_update_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Update cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohorts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohorts || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_add_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Add members to cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_delete_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Delete members from cohort || MDL-29472
|-
|cohort
| style="background:#D4FFDF;" | core_cohort_get_cohort_members() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" |Get cohort members || MDL-29472
|-

|course
| style="background:#D4FFDF;" | core_course_get_courses() || style="background:#D4FFDF;" | moodle_course_get_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Return course details ||
|-
|course
| style="background:#D4FFDF;" | core_course_create_courses() || style="background:#D4FFDF;" | moodle_course_create_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Create new courses ||
|-
|group
| style="background:#D4FFDF;" | core_group_create_groups() || style="background:#D4FFDF;" | moodle_group_create_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Creates new groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_groups() || style="background:#D4FFDF;" | moodle_group_get_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group details. ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groups() || style="background:#D4FFDF;" | moodle_group_get_course_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns all groups in specified course ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groups() || style="background:#D4FFDF;" | moodle_group_delete_groups() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes all specified groups ||
|-
|group
| style="background:#D4FFDF;" | core_group_get_group_members() || style="background:#D4FFDF;" | moodle_group_get_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Returns group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_add_group_members() || style="background:#D4FFDF;" | moodle_group_add_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Adds group members ||
|-
|group
| style="background:#D4FFDF;" | core_group_delete_group_members() || style="background:#D4FFDF;" | moodle_group_delete_groupmembers() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Deletes group members ||
|-
|role
| style="background:#D4FFDF;" | core_role_assign_roles() || style="background:#D4FFDF;" | moodle_role_assign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role assignments ||
|-
|role
| style="background:#D4FFDF;" | core_role_unassign_roles() || style="background:#D4FFDF;" | moodle_role_unassign() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual role unassignments ||
|-
|enrol
| style="background:#D4FFDF;" | NONE || style="background:#D4FFDF;" | moodle_enrol_get_enrolled_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get some minimal information about the users enrolled in a course (DEPRECATED) ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users() || style="background:#D4FFDF;" | moodle_user_get_users_by_courseid() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Get enrolled users by course id ||
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_users_courses() || style="background:#D4FFDF;" | moodle_enrol_get_users_courses() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | get list of course ids that a user is enrolled in (if you are allowed to see that) ||
|-
|enrol/manual
| style="background:#D4FFDF;" | enrol_manual_enrol_users() || style="background:#D4FFDF;" | moodle_enrol_manual_enrol_users() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | Manual enrol users ||
|-
|webservice
| style="background:#D4FFDF;" | core_webservice_get_site_info() || style="background:#D4FFDF;" | moodle_webservice_get_siteinfo() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Return some site info / user info / list web service functions ||
|-
|message
| style="background:#D4FFDF;" | core_message_send_instant_messages() || style="background:#D4FFDF;" | moodle_message_send_instantmessages() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Send instant messages ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_create_notes() || style="background:#D4FFDF;" | moodle_notes_create_notes() || style="background:#D4FFDF;" | 2.1 || style="background:#D4FFDF;" | Create notes ||
|-
|notes
| style="background:#D4FFDF;" | core_notes_delete_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_get_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve Notes || MDL-30072
|-
|notes
| style="background:#D4FFDF;" | core_notes_update_notes() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update Notes || MDL-30072
|-
|files
| style="background:#D4FFDF;" | core_files_get_files() || style="background:#D4FFDF;" | moodle_file_get_files() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | browse moodle files ||
|-
|files
| style="background:#D4FFDF;" | core_files_upload() || style="background:#D4FFDF;" | moodle_file_upload() || style="background:#D4FFDF;" | 2.0 || style="background:#D4FFDF;" | upload a file to moodle (DEPRECATED) ||
|-
|course
| style="background:#D4FFDF;" | core_course_get_contents() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.2 || style="background:#D4FFDF;" | get course content (modules + web service file urls) || MDL-28646
|-
|course
| style="background:#D4FFDF;" | core_course_delete_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete courses || MDL-13130
|-
|course
| style="background:#D4FFDF;" | core_course_duplicate_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | duplicate a course || MDL-32233
|-
|course
| style="background:#D4FFDF;" | core_course_get_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_update_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_create_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create categories || MDL-32941
|-
|course
| style="background:#D4FFDF;" | core_course_delete_categories() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete categories || MDL-32941
|-
|group
| style="background:#D4FFDF;" | core_group_create_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | create groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_update_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | update groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_delete_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | delete groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_assign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | assign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_unassign_grouping() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | unassign groups from groupings || MDL-32662
|-
|group
| style="background:#D4FFDF;" | core_group_get_course_groupings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.3 || style="background:#D4FFDF;" | get all groupings in specified course || MDL-32662
|-
|user
| style="background:#D4FFDF;" | core_user_get_users_by_field() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve users information for a specified unique field - If you want to do a user search, use core_user_get_users() || MDL-35543
|-
|enrol
| style="background:#D4FFDF;" | core_enrol_get_enrolled_users_with_capability() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | For each course and capability specified, return a list of the users that are enrolled in the course and have that capability || MDL-31859
|-
|course
| style="background:#D4FFDF;" | core_course_import_course() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Import course data from a course into another course. Does not include any user data. || MDL-32919
|-
|message
| style="background:#D4FFDF;" | core_message_create_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Add contacts to the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_delete_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Remove contacts from the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_block_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Block contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_unblock_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Unblock contacts || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_get_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Retrieve the contact list || MDL-30070
|-
|message
| style="background:#D4FFDF;" | core_message_search_contacts() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search for contacts || MDL-30070
|-
|external
| style="background:#D4FFDF;" | core_get_string() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return a translated string - similar to core get_string() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_component_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return all raw strings (with {$a->xxx}) for a specific component - similar to core get_component_strings() call || MDL-35997
|-
|external
| style="background:#D4FFDF;" | core_get_strings() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Return some translated strings - like several core get_string() calls || MDL-35997
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_delete_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Delete calendar events || MDL-37077
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_get_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Get calendar events || MDL-37100
|-
|calendar
| style="background:#D4FFDF;" | core_calendar_create_calendar_events() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Create calendar events || MDL-37101
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_grades() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns grades from the assignment || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_assignments() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.4 || style="background:#D4FFDF;" | Returns the courses and assignments for the users capability || MDL-31873
|-
|mod_assign
| style="background:#D4FFDF;" | mod_assign_get_submissions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns the submissions for assignments || MDL-31682
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forums_by_courses || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum instances in a provided set of courses, if no courses are provided then all the forum instances the user has access to will be returned. || MDL-37247
|-
|-
|mod_forum
| style="background:#D4FFDF;" | mod_forum_get_forum_discussions || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns a list of forum discussions in a provided set of forums. || MDL-30102
|-
|course
| style="background:#D4FFDF;" | core_course_update_courses() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Update courses. || MDL-30062
|-
|user
| style="background:#D4FFDF;" | core_user_get_users() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Search users. - If you want to get multiple users for one specific field, use core_user_get_users_by_field(), it's designed for this purpose and it should be faster. || MDL-29938
|-
|grade
| style="background:#D4FFDF;" | core_grade_get_definitions() || style="background:#D4FFDF;" | || style="background:#D4FFDF;" | 2.5 || style="background:#D4FFDF;" | Returns grading definitions for the course module ids and areaname provided as parameters. || MDL-31681
|-

|}
This is the list of the integrated core functions. To see the roadmap, see to the tracker issue in the section bellow.

=== API Roadmap===
Tracker issue: MDL-29934

= See also =
* [[Web services API Changes]]
* [[How to contribute a web service function to core]]
* [[Web services|Web services developer documentation]]
* [[:en:Web services|Web services user documentation]]

[[Category:Web Services]]
[[Category:API]]

Lightwork

2013-01-22T01:48:05Z

Pcharsle: /* The new Lightwork web services */

{{Work in progress}}
{{Infobox Project
|name = Lightwork
|state = In Development
|tracker = http://tracker.moodle.org/browse/MDL-31409
|discussion = http://moodle.org/mod/forum/discuss.php?d=187818
|assignee = Lightwork
}}
{{Moodle 2.4}}

== 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_customisation|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.4 release as described in the rest of this document.

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

== 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:

{| border="1" cellpadding="2" cellspacing="0"
|'''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 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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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_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
|}

== Migration of existing SOAP OKtech web services to Moodle core web services ==

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

== 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 ===

[[File:UpdateAssignment.png|600px|thumb|center|Create and update assignment page]]

=== Advanced grading, Define Marking guide page ===

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

[[File:UpdateRubric.png|600px|thumb|center|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

[[File:LookAtRubric.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_2.png|600px|thumb|center|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.

[[File:StudentView.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_1.png|600px|thumb|center|Allocate markers to students]]

=== Review the marking ===

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

[[File:ViewSubmittedAssignments_3.png|600px|thumb|center|Review the marking]]

=== Release the marking ===

[[File:ViewSubmittedAssignments_4.png|600px|thumb|center|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: [http://lightwork.massey.ac.nz/documents/show/6 TestPlan_MarkingGuide]

Testing results can be recorded in: [http://lightwork.massey.ac.nz/documents/show/6 Testing_Record_MarkingGuide]

Lightwork

2013-01-22T01:45:54Z

Pcharsle: /* The new Lightwork web services */

{{Work in progress}}
{{Infobox Project
|name = Lightwork
|state = In Development
|tracker = http://tracker.moodle.org/browse/MDL-31409
|discussion = http://moodle.org/mod/forum/discuss.php?d=187818
|assignee = Lightwork
}}
{{Moodle 2.4}}

== 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_customisation|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.4 release as described in the rest of this document.

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

== 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:

{| border="1" cellpadding="2" cellspacing="0"
|'''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 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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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_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
|}

== Migration of existing SOAP OKtech web services to Moodle core web services ==

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

== 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 ===

[[File:UpdateAssignment.png|600px|thumb|center|Create and update assignment page]]

=== Advanced grading, Define Marking guide page ===

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

[[File:UpdateRubric.png|600px|thumb|center|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

[[File:LookAtRubric.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_2.png|600px|thumb|center|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.

[[File:StudentView.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_1.png|600px|thumb|center|Allocate markers to students]]

=== Review the marking ===

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

[[File:ViewSubmittedAssignments_3.png|600px|thumb|center|Review the marking]]

=== Release the marking ===

[[File:ViewSubmittedAssignments_4.png|600px|thumb|center|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: [http://lightwork.massey.ac.nz/documents/show/6 TestPlan_MarkingGuide]

Testing results can be recorded in: [http://lightwork.massey.ac.nz/documents/show/6 Testing_Record_MarkingGuide]

Lightwork

2013-01-22T01:42:12Z

Pcharsle: /* The new Lightwork web services */

{{Work in progress}}
{{Infobox Project
|name = Lightwork
|state = In Development
|tracker = http://tracker.moodle.org/browse/MDL-31409
|discussion = http://moodle.org/mod/forum/discuss.php?d=187818
|assignee = Lightwork
}}
{{Moodle 2.4}}

== 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_customisation|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.4 release as described in the rest of this document.

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

== 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:

{| border="1" cellpadding="2" cellspacing="0"
|'''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 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.

{| border="1" cellpadding="2" cellspacing="0"
|'''methodname'''
|'''classname'''
|'''classpath'''
|'''parameters'''
|'''type'''
|'''description and comments'''

|-
|'''core_webservice_get_site_info'''
|core_webservice_external
|webservice/externallib.php
|None
|read
|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_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
|}

== Migration of existing SOAP OKtech web services to Moodle core web services ==

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

== 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 ===

[[File:UpdateAssignment.png|600px|thumb|center|Create and update assignment page]]

=== Advanced grading, Define Marking guide page ===

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

[[File:UpdateRubric.png|600px|thumb|center|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

[[File:LookAtRubric.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_2.png|600px|thumb|center|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.

[[File:StudentView.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_1.png|600px|thumb|center|Allocate markers to students]]

=== Review the marking ===

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

[[File:ViewSubmittedAssignments_3.png|600px|thumb|center|Review the marking]]

=== Release the marking ===

[[File:ViewSubmittedAssignments_4.png|600px|thumb|center|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: [http://lightwork.massey.ac.nz/documents/show/6 TestPlan_MarkingGuide]

Testing results can be recorded in: [http://lightwork.massey.ac.nz/documents/show/6 Testing_Record_MarkingGuide]

Lightwork

2013-01-22T01:32:15Z

Pcharsle:

{{Work in progress}}
{{Infobox Project
|name = Lightwork
|state = In Development
|tracker = http://tracker.moodle.org/browse/MDL-31409
|discussion = http://moodle.org/mod/forum/discuss.php?d=187818
|assignee = Lightwork
}}
{{Moodle 2.4}}

== 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_customisation|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.4 release as described in the rest of this document.

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

== 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:

{| border="1" cellpadding="2" cellspacing="0"
|'''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 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.

{| border="1" cellpadding="2" cellspacing="0"
|'''methodname'''
|'''classname'''
|'''classpath'''
|'''parameters'''
|'''type'''
|'''description and comments'''

|-
|'''core_webservice_get_site_info'''
|core_webservice_external
|webservice/externallib.php
|None
|read
|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_users_get_users_with_capability'''
|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
|http://tracker.moodle.org/browse/MDL-31859 Return list of participants to specified courses. This should include students and teachers. User details are returned together with 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_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
|}

== Migration of existing SOAP OKtech web services to Moodle core web services ==

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

== 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 ===

[[File:UpdateAssignment.png|600px|thumb|center|Create and update assignment page]]

=== Advanced grading, Define Marking guide page ===

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

[[File:UpdateRubric.png|600px|thumb|center|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

[[File:LookAtRubric.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_2.png|600px|thumb|center|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.

[[File:StudentView.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_1.png|600px|thumb|center|Allocate markers to students]]

=== Review the marking ===

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

[[File:ViewSubmittedAssignments_3.png|600px|thumb|center|Review the marking]]

=== Release the marking ===

[[File:ViewSubmittedAssignments_4.png|600px|thumb|center|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: [http://lightwork.massey.ac.nz/documents/show/6 TestPlan_MarkingGuide]

Testing results can be recorded in: [http://lightwork.massey.ac.nz/documents/show/6 Testing_Record_MarkingGuide]

Talk:External services description

2012-09-17T00:29:40Z

Pcharsle: /* Description of proposed changes */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

====Overview====

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading, named something like '''mod_assign_movesubmissionfilestoalocationfordownloading(assignid)'''
# Download the file using webservices/pluginfile.php

This 2 step process is cumbersome for clients who want a web service to consist solely of web service functions without the need to call additional php code (webservices/pluginfile.php) outside of the framework.

The changes that we propose will allow the above 2 step process to be replaced by a single web service function call that efficiently returns a file (i.e. NOT encoding in the XML but using http streaming like pluginfile.php). So, the 2 step process described above would be replaced by a single web service function:

# '''mod_assign_getsubmissionfiles(assignid)'''

====Description of proposed changes====

We have created modifications to the Moodle web services by adding a new external type called external_file to allow direct file download. Our changes can be accessed from http://tracker.moodle.org/browse/MDL-32336. Our changes modify the web services servers and complement the existing web services so that the list of return data types available to developers will be:

# external_value
# external_single_structure
# external_multiple_structure
# '''external_file'''

In MDL-32336 we have made our changes to the REST server. In the case of the other protocols we have the option to use either the same implementation or an implementation that is specific to the protocol. For instance, in the case of SOAP we could implement the file download using SOAP with attachments (http://www.w3.org/TR/SOAP-attachments). The simplest option, and our preference, is to use the same implementation for all servers.

The following code snippet shows the new proposed class '''external_file''' that is added to lib/externallib.php:

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet describes a simple web service function which downloads a file using external_file type.

<code php>
class mod_assign_external extends external_api {

public static function getsubmissionfiles_parameters() {
return new external_function_parameters(
array('assignid' => new external_value(PARAM_INT, 'id of assignment for which submission files will be downloaded')));
}

public static function getsubmissionfiles($assignid) {

// perform application logic, get files and package them in zipfilename

$result = array();
$result['filename'] = $zipfilename;
$result['path'] = '/somepath' . $zipfilename;
$result['tempfile'] = true;

return $result;
}

public static function getsubmissionfiles_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-16T23:40:33Z

Pcharsle: /* Description of proposed changes */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

====Overview====

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading, named something like '''mod_assign_movesubmissionfilestoalocationfordownloading(assignid)'''
# Download the file using webservices/pluginfile.php

This 2 step process is cumbersome for clients who want a web service to consist solely of web service functions without the need to call additional php code (webservices/pluginfile.php) outside of the framework.

The changes that we propose will allow the above 2 step process to be replaced by a single web service function call that efficiently returns a file (i.e. NOT encoding in the XML but using http streaming like pluginfile.php). So, the 2 step process described above would be replaced by a single web service function:

# '''mod_assign_getsubmissionfiles(assignid)'''

====Description of proposed changes====

We have created modifications to the Moodle web services by adding a new external type called external_file to allow direct file download. Our changes can be accessed from http://tracker.moodle.org/browse/MDL-32336. Our changes modify the web services servers and complement the existing web services so that the list of return data types available to developers will be:

# external_value
# external_single_structure
# external_multiple_structure
# '''external_file'''

In MDL-32336 we have made our changes to the REST server. In the case of the other protocols we have the option to use either the same implementation or an implementation that is specific to the protocol. For instance, in the case of SOAP we could implement the file download using SOAP with attachments (http://www.w3.org/TR/SOAP-attachments).

The following code snippet shows the new proposed class '''external_file''' that is added to lib/externallib.php:

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet describes a simple web service function which downloads a file using external_file type.

<code php>
class mod_assign_external extends external_api {

public static function getsubmissionfiles_parameters() {
return new external_function_parameters(
array('assignid' => new external_value(PARAM_INT, 'id of assignment for which submission files will be downloaded')));
}

public static function getsubmissionfiles($assignid) {

// perform application logic, get files and package them in zipfilename

$result = array();
$result['filename'] = $zipfilename;
$result['path'] = '/somepath' . $zipfilename;
$result['tempfile'] = true;

return $result;
}

public static function getsubmissionfiles_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-16T23:40:00Z

Pcharsle: /* Overview */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

====Overview====

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading, named something like '''mod_assign_movesubmissionfilestoalocationfordownloading(assignid)'''
# Download the file using webservices/pluginfile.php

This 2 step process is cumbersome for clients who want a web service to consist solely of web service functions without the need to call additional php code (webservices/pluginfile.php) outside of the framework.

The changes that we propose will allow the above 2 step process to be replaced by a single web service function call that efficiently returns a file (i.e. NOT encoding in the XML but using http streaming like pluginfile.php). So, the 2 step process described above would be replaced by a single web service function:

# '''mod_assign_getsubmissionfiles(assignid)'''

====Description of proposed changes====

We have created modifications to the Moodle web services by adding a new external type called external_file to allow direct file download. Our changes can be accessed from http://tracker.moodle.org/browse/MDL-32336. Our changes modify the web services servers and complement the existing web services so that the list of return data types available to developers will be:

# external_value
# external_single_structure
# external_multiple_structure
# '''external_file'''

The following code snippet shows the new proposed class '''external_file''' that is added to lib/externallib.php:

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet describes a simple web service function which downloads a file using external_file type.

<code php>
class mod_assign_external extends external_api {

public static function getsubmissionfiles_parameters() {
return new external_function_parameters(
array('assignid' => new external_value(PARAM_INT, 'id of assignment for which submission files will be downloaded')));
}

public static function getsubmissionfiles($assignid) {

// perform application logic, get files and package them in zipfilename

$result = array();
$result['filename'] = $zipfilename;
$result['path'] = '/somepath' . $zipfilename;
$result['tempfile'] = true;

return $result;
}

public static function getsubmissionfiles_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-16T23:38:00Z

Pcharsle: /* Overview */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

====Overview====

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading, named something like '''mod_assign_movesubmissionfilestoalocationfordownloading(assignid)'''
# Download the file using webservices/pluginfile.php

This 2 step process is cumbersome for clients who want a web service to consist solely of web service functions without the need to call additional php code (webservices/pluginfile.php) outside of the framework.

The changes that we propose will allow the above 2 step process to be replaced by a single web service function call that efficiently returns a file (i.e. NOT encoding in the XML but using http streaming like pluginfile.php). So, the 2 step process described above would be replaced by a single web service function:

# '''mod_assign_getsubmissionfiles(assignid)'''

In MDL-32336 we have made our changes to the REST server. In the case of the other protocols we have the option to use either the same implementation or an implementation that is specific to the protocol. For instance, in the case of SOAP we could implement the file download using SOAP with attachments (http://www.w3.org/TR/SOAP-attachments).

====Description of proposed changes====

We have created modifications to the Moodle web services by adding a new external type called external_file to allow direct file download. Our changes can be accessed from http://tracker.moodle.org/browse/MDL-32336. Our changes modify the web services servers and complement the existing web services so that the list of return data types available to developers will be:

# external_value
# external_single_structure
# external_multiple_structure
# '''external_file'''

The following code snippet shows the new proposed class '''external_file''' that is added to lib/externallib.php:

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet describes a simple web service function which downloads a file using external_file type.

<code php>
class mod_assign_external extends external_api {

public static function getsubmissionfiles_parameters() {
return new external_function_parameters(
array('assignid' => new external_value(PARAM_INT, 'id of assignment for which submission files will be downloaded')));
}

public static function getsubmissionfiles($assignid) {

// perform application logic, get files and package them in zipfilename

$result = array();
$result['filename'] = $zipfilename;
$result['path'] = '/somepath' . $zipfilename;
$result['tempfile'] = true;

return $result;
}

public static function getsubmissionfiles_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T23:37:31Z

Pcharsle: /* Description of proposed changes */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

====Overview====

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading, named something like '''mod_assign_movesubmissionfilestoalocationfordownloading(assignid)'''
# Download the file using webservices/pluginfile.php

This 2 step process is cumbersome for clients who want a web service to consist solely of web service functions without the need to call additional php code (webservices/pluginfile.php) outside of the framework.

The changes that we propose will allow the above 2 step process to be replaced by a single web service function call that efficiently returns a file (i.e. NOT encoding in the XML but using http streaming like pluginfile.php). So, the 2 step process described above would be replaced by a single web service function:

# '''mod_assign_getsubmissionfiles(assignid)'''

====Description of proposed changes====

We have created modifications to the Moodle web services by adding a new external type called external_file to allow direct file download. Our changes can be accessed from http://tracker.moodle.org/browse/MDL-32336. Our changes modify the web services servers and complement the existing web services so that the list of return data types available to developers will be:

# external_value
# external_single_structure
# external_multiple_structure
# '''external_file'''

The following code snippet shows the new proposed class '''external_file''' that is added to lib/externallib.php:

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet describes a simple web service function which downloads a file using external_file type.

<code php>
class mod_assign_external extends external_api {

public static function getsubmissionfiles_parameters() {
return new external_function_parameters(
array('assignid' => new external_value(PARAM_INT, 'id of assignment for which submission files will be downloaded')));
}

public static function getsubmissionfiles($assignid) {

// perform application logic, get files and package them in zipfilename

$result = array();
$result['filename'] = $zipfilename;
$result['path'] = '/somepath' . $zipfilename;
$result['tempfile'] = true;

return $result;
}

public static function getsubmissionfiles_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T23:36:26Z

Pcharsle: /* Overview */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

====Overview====

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading, named something like '''mod_assign_movesubmissionfilestoalocationfordownloading(assignid)'''
# Download the file using webservices/pluginfile.php

This 2 step process is cumbersome for clients who want a web service to consist solely of web service functions without the need to call additional php code (webservices/pluginfile.php) outside of the framework.

The changes that we propose will allow the above 2 step process to be replaced by a single web service function call that efficiently returns a file (i.e. NOT encoding in the XML but using http streaming like pluginfile.php). So, the 2 step process described above would be replaced by a single web service function:

# '''mod_assign_getsubmissionfiles(assignid)'''

==Description of proposed changes==

We have created modifications to the Moodle web services by adding a new external type called external_file to allow direct file download. Our changes can be accessed from http://tracker.moodle.org/browse/MDL-32336. Our changes modify the web services servers and complement the existing web services so that the list of return data types available to developers will be:

# external_value
# external_single_structure
# external_multiple_structure
# '''external_file'''

The following code snippet shows the new proposed class '''external_file''' that is added to lib/externallib.php:

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet describes a simple web service function which downloads a file using external_file type.

<code php>
class mod_assign_external extends external_api {

public static function getsubmissionfiles_parameters() {
return new external_function_parameters(
array('assignid' => new external_value(PARAM_INT, 'id of assignment for which submission files will be downloaded')));
}

public static function getsubmissionfiles($assignid) {

// perform application logic, get files and package them in zipfilename

$result = array();
$result['filename'] = $zipfilename;
$result['path'] = '/somepath' . $zipfilename;
$result['tempfile'] = true;

return $result;
}

public static function getsubmissionfiles_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T23:29:55Z

Pcharsle: /* Description of proposed changes */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

==Overview==

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading, named something like '''mod_assign_movesubmissionfilestoalocationfordownloading(assignid)'''
# Download the file using webservices/pluginfile.php

This 2 step process is cumbersome for clients who want a web service to consist solely of web service functions without the need to call additional php code (webservices/pluginfile.php) outside of the framework.

The changes that we propose will allow the above 2 step process to be replaced by a single web service function call that efficiently returns a file (i.e. NOT encoding in the XML but using http streaming like pluginfile.php). So, the 2 step process described above would be replaced by a single web service function:

# '''mod_assign_getsubmissionfiles(assignid)'''

==Description of proposed changes==

We have created modifications to the Moodle web services by adding a new external type called external_file to allow direct file download. Our changes can be accessed from http://tracker.moodle.org/browse/MDL-32336. Our changes modify the web services servers and complement the existing web services so that the list of return data types available to developers will be:

# external_value
# external_single_structure
# external_multiple_structure
# '''external_file'''

The following code snippet shows the new proposed class '''external_file''' that is added to lib/externallib.php:

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet describes a simple web service function which downloads a file using external_file type.

<code php>
class mod_assign_external extends external_api {

public static function getsubmissionfiles_parameters() {
return new external_function_parameters(
array('assignid' => new external_value(PARAM_INT, 'id of assignment for which submission files will be downloaded')));
}

public static function getsubmissionfiles($assignid) {

// perform application logic, get files and package them in zipfilename

$result = array();
$result['filename'] = $zipfilename;
$result['path'] = '/somepath' . $zipfilename;
$result['tempfile'] = true;

return $result;
}

public static function getsubmissionfiles_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T23:20:33Z

Pcharsle: /* Description of proposed changes */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

==Overview==

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading, named something like '''mod_assign_movesubmissionfilestoalocationfordownloading(assignid)'''
# Download the file using webservices/pluginfile.php

This 2 step process is cumbersome for clients who want a web service to consist solely of web service functions without the need to call additional php code (webservices/pluginfile.php) outside of the framework.

The changes that we propose will allow the above 2 step process to be replaced by a single web service function call that efficiently returns a file (i.e. NOT encoding in the XML but using http streaming like pluginfile.php). So, the 2 step process described above would be replaced by a single web service function:

# '''mod_assign_getsubmissionfiles(assignid)'''

==Description of proposed changes==

We have created modifications to the Moodle web services by adding a new external type called external_file to allow direct file download. Our changes can be accessed from http://tracker.moodle.org/browse/MDL-32336. Our changes modify the web services servers and complement the existing web services so that the list of return data types available to developers will be:

# external_value
# external_single_structure
# external_multiple_structure
# '''external_file'''

The following code snippet shows the new proposed class '''external_file''' that is added to lib/externallib.php:

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet describes a simple web service function which downloads a file using external_file type.

<code php>
class mod_assign_get_external extends external_api {

public static function download_file_parameters() {
return new external_function_parameters(
array('filename' => new external_value(PARAM_TEXT, 'name of file to be downloaded')));
}

public static function download_file($filename) {
$result = array();
$result['filename'] = $filename;
$result['path'] = '/moodle/moodledata' . $filename;
$result['tempfile'] = true;

return $result;
}

public static function download_file_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T23:11:30Z

Pcharsle: /* Integrate file download into the Moodle web services framework */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

==Overview==

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading, named something like '''mod_assign_movesubmissionfilestoalocationfordownloading(assignid)'''
# Download the file using webservices/pluginfile.php

This 2 step process is cumbersome for clients who want a web service to consist solely of web service functions without the need to call additional php code (webservices/pluginfile.php) outside of the framework.

The changes that we propose will allow the above 2 step process to be replaced by a single web service function call that efficiently returns a file (i.e. NOT encoding in the XML but using http streaming like pluginfile.php). So, the 2 step process described above would be replaced by a single web service function:

# '''mod_assign_getsubmissionfiles(assignid)'''

==Description of proposed changes==

We have created modifications to the Moodle web services by adding a new external type called external_file to allow direct file download. Our changes can be accessed from http://tracker.moodle.org/browse/MDL-32336. Our changes modify the web services servers and complement the existing web services so that the list of return data types available to developers will be:

# external_value
# external_single_structure
# external_multiple_structure
# '''external_file'''

The following code snippet describes how the new proposed external_file could be used:

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, preferably from moodledata/temp/something; or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection after ''Externallib.php example'':

''external_file examples:'' 
This example shows how to develop web service function which send file for download using external_file type.

<code php>
class local_wsfile_external extends external_api {

public static function download_file_parameters() {
return new external_function_parameters(
array('filename' => new external_value(PARAM_TEXT, 'name of file to be downloaded')));
}

public static function download_file($filename) {
$result = array();
$result['filename'] = $filename;
$result['path'] = '/moodle/moodledata' . $filename;
$result['tempfile'] = true;

return $result;
}

public static function download_file_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T22:07:22Z

Pcharsle: /* Integrate file download into the Moodle web services framework */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading, named something like '''mod_assign_movesubmissionfilestoalocationfordownloading(assignid)'''
# Download the file using webservices/pluginfile.php

This 2 step process is cumbersome for clients who want a web service to consist solely of web service functions without the need to call additional php code (webservices/pluginfile.php) outside of the framework.

The changes that we propose will allow the above 2 step process to be replaced by a single web service function call that efficiently returns a file (i.e. NOT encoding in the XML but using http streaming like pluginfile.php). So, the 2 step process described above would be replaced by a single web service function:

# '''mod_assign_getsubmissionfiles(assignid)'''

Adding new external type to allow direct file download web service
As proposed in http://tracker.moodle.org/browse/MDL-32336 to add a new type called external_file to allow direct file download web service.
The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection under ''base description classes'':

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, preferably from moodledata/temp/something; or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection after ''Externallib.php example'':

''external_file examples:'' 
This example shows how to develop web service function which send file for download using external_file type.

<code php>
class local_wsfile_external extends external_api {

public static function download_file_parameters() {
return new external_function_parameters(
array('filename' => new external_value(PARAM_TEXT, 'name of file to be downloaded')));
}

public static function download_file($filename) {
$result = array();
$result['filename'] = $filename;
$result['path'] = '/moodle/moodledata' . $filename;
$result['tempfile'] = true;

return $result;
}

public static function download_file_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T21:41:01Z

Pcharsle: /* Integrate file download into the Moodle web services framework */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading, named something like mod_assign_movesubmissionfilestoalocationfordownloading()
# Download the file using webservices/pluginfile.php

Adding new external type to allow direct file download web service
As proposed in http://tracker.moodle.org/browse/MDL-32336 to add a new type called external_file to allow direct file download web service.
The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection under ''base description classes'':

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, preferably from moodledata/temp/something; or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection after ''Externallib.php example'':

''external_file examples:'' 
This example shows how to develop web service function which send file for download using external_file type.

<code php>
class local_wsfile_external extends external_api {

public static function download_file_parameters() {
return new external_function_parameters(
array('filename' => new external_value(PARAM_TEXT, 'name of file to be downloaded')));
}

public static function download_file($filename) {
$result = array();
$result['filename'] = $filename;
$result['path'] = '/moodle/moodledata' . $filename;
$result['tempfile'] = true;

return $result;
}

public static function download_file_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T21:37:55Z

Pcharsle: /* Adding new external type to allow direct file download web service */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Integrate file download into the Moodle web services framework===

Currently (Moodle 2.3) web service client developers cannot download files without having to create extra code outside of the web services framework. For example, in order to develop a web service function that downloads student submission files for an assignment they have to:

# Create a web service function that performs the business logic and puts the files in a location for downloading
# Download the file using webservices/pluginfile.php

Adding new external type to allow direct file download web service
As proposed in http://tracker.moodle.org/browse/MDL-32336 to add a new type called external_file to allow direct file download web service.
The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection under ''base description classes'':

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, preferably from moodledata/temp/something; or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection after ''Externallib.php example'':

''external_file examples:'' 
This example shows how to develop web service function which send file for download using external_file type.

<code php>
class local_wsfile_external extends external_api {

public static function download_file_parameters() {
return new external_function_parameters(
array('filename' => new external_value(PARAM_TEXT, 'name of file to be downloaded')));
}

public static function download_file($filename) {
$result = array();
$result['filename'] = $filename;
$result['path'] = '/moodle/moodledata' . $filename;
$result['tempfile'] = true;

return $result;
}

public static function download_file_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T21:22:46Z

Pcharsle: /* Adding new external type to allow direct file download web service */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Adding new external type to allow direct file download web service===

As proposed in http://tracker.moodle.org/browse/MDL-32336 to add a new type called external_file to allow direct file download web service.
The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection under ''base description classes'':

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, preferably from moodledata/temp/something; or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection after ''Externallib.php example'':

''external_file examples:'' 
This example shows how to develop web service function which send file for download using external_file type.

<code php>
class local_wsfile_external extends external_api {

public static function download_file_parameters() {
return new external_function_parameters(
array('filename' => new external_value(PARAM_TEXT, 'name of file to be downloaded')));
}

public static function download_file($filename) {
$result = array();
$result['filename'] = $filename;
$result['path'] = '/moodle/moodledata' . $filename;
$result['tempfile'] = true;

return $result;
}

public static function download_file_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T21:17:18Z

Pcharsle: /* Adding new external type to allow direct file download web service */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Adding new external type to allow direct file download web service===

As proposed in [http://tracker.moodle.org/browse/MDL-32336 MDL-32336] to add a new type called external_file to allow direct file download web service.
The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection under ''base description classes'':

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, preferably from moodledata/temp/something; or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection after ''Externallib.php example'':

''external_file examples:'' 
This example shows how to develop web service function which send file for download using external_file type.

<code php>
class local_wsfile_external extends external_api {

public static function download_file_parameters() {
return new external_function_parameters(
array('filename' => new external_value(PARAM_TEXT, 'name of file to be downloaded')));
}

public static function download_file($filename) {
$result = array();
$result['filename'] = $filename;
$result['path'] = '/moodle/moodledata' . $filename;
$result['tempfile'] = true;

return $result;
}

public static function download_file_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T21:16:34Z

Pcharsle: /* Adding new external type to allow direct file download web service */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Adding new external type to allow direct file download web service===

As proposed in [http://tracker.moodle.org/browse/MDL-32336] to add a new type called external_file to allow direct file download web service.
The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection under ''base description classes'':

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, preferably from moodledata/temp/something; or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection after ''Externallib.php example'':

''external_file examples:'' 
This example shows how to develop web service function which send file for download using external_file type.

<code php>
class local_wsfile_external extends external_api {

public static function download_file_parameters() {
return new external_function_parameters(
array('filename' => new external_value(PARAM_TEXT, 'name of file to be downloaded')));
}

public static function download_file($filename) {
$result = array();
$result['filename'] = $filename;
$result['path'] = '/moodle/moodledata' . $filename;
$result['tempfile'] = true;

return $result;
}

public static function download_file_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T21:15:09Z

Pcharsle: /* Adding new external type to allow direct file download web service */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Adding new external type to allow direct file download web service===

As proposed in "MDL-32336":http://www.example.com link title]http://tracker.moodle.org/browse/MDL-32336 to add a new type called external_file to allow direct file download web service.
The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection under ''base description classes'':

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, preferably from moodledata/temp/something; or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection after ''Externallib.php example'':

''external_file examples:'' 
This example shows how to develop web service function which send file for download using external_file type.

<code php>
class local_wsfile_external extends external_api {

public static function download_file_parameters() {
return new external_function_parameters(
array('filename' => new external_value(PARAM_TEXT, 'name of file to be downloaded')));
}

public static function download_file($filename) {
$result = array();
$result['filename'] = $filename;
$result['path'] = '/moodle/moodledata' . $filename;
$result['tempfile'] = true;

return $result;
}

public static function download_file_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T21:13:38Z

Pcharsle: /* Adding new external type to allow direct file download web service */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Adding new external type to allow direct file download web service===

As proposed in [[http://tracker.moodle.org/browse/MDL-32336|MDL-32336]] to add a new type called external_file to allow direct file download web service.
The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection under ''base description classes'':

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, preferably from moodledata/temp/something; or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection after ''Externallib.php example'':

''external_file examples:'' 
This example shows how to develop web service function which send file for download using external_file type.

<code php>
class local_wsfile_external extends external_api {

public static function download_file_parameters() {
return new external_function_parameters(
array('filename' => new external_value(PARAM_TEXT, 'name of file to be downloaded')));
}

public static function download_file($filename) {
$result = array();
$result['filename'] = $filename;
$result['path'] = '/moodle/moodledata' . $filename;
$result['tempfile'] = true;

return $result;
}

public static function download_file_returns() {
return new external_file();
}
}
</code>

Talk:External services description

2012-09-13T21:13:06Z

Pcharsle: /* Adding new external type to allow direct file download web service */

=== About the different alternatives describing the available WS, by Eloy ===

Hi, after reading the different alternatives, I'm inclined to implement something like the 3rd one. Having our custom structures to define the interface to the available web services seems really better than using "free-form" structures like "raw" arrays and objects or using harcoded keywords like "multiple" and so on. It has various advantages and doesn't hurt simplicity when defining the parameters:
* Better PHP structures <--> XML mapping
* Extensibility:
** custom/reusable validation methods.
** built-in XML writing
** enforce some sort of common response functionality (see my concerns about returned content below).

Anyway, I've some (small) concerns about the example code used in the 3rd alternative, so I'm writing here how it should look like ideally IMO (rationale about changes is after the code):

<code php>
class moodle_group_external extends external_api {
public static function add_member_parameters() {
return new external_single_structure(
'member', array(
new external_param('groupid', PARAM_INT, 'some group id'),
new external_param('userid', PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_prameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() { // Some concerns here. See below.
return null;
}

public static function add_members_parameters() {
return new external_multiple_structure(
'membership', self::add_member_parameters()
);
}
public static function add_members(array $membership) {
foreach($membership as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() { // BIG concerns here. See below.
return null;
}

public static function get_groups_parameters() {
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('groupid', PARAM_INT, 'some group id')
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_prameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'groups', new external_single_structure(
'group', array(
new external_param('id', PARAM_INT, 'some group id'),
new external_param('name', PARAM_TEXT, 'multilang compatible name, course unique'),
new external_param('description', PARAM_RAW, 'just some text'),
new external_param('enrolmentkey', PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_prameters(self::create_users_parameters(), array('users'=>$users));

foreach ($users as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() { // BIG concerns here. See below.
return new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('userid', PARAM_INT, 'id of the created user'))
)
);
}
}
</code>

====Changes from original code are:====

* Small change in structure names. ''external_bulk_array'' renamed to ''external_multiple_structure'' and ''external_assoc_array'' to ''external_single_structure'' (note that ''structure'' can be changed to anything else). The important bits are the ''single/multiple'' ones vs. the ''assoc/bulk''. Clear IMO.
* Moved the "name" of the single structure and param classes to the constructor (no need for associative arrays). Clear syntax.
* Small change in ''external_multiple_structure'' to add the missing "name" to its constructor. Matching previous point.
* The xxxx_parameters() function will return directly one ''single'' or ''multiple'' structure, saving one nesting level from original code.
* Reuse as much as possible:
** The ''moodle_group_external'' is a clear example. Once we have the ''single'' service implemented (add_member), it's pretty easy to build its ''multiple'' alternative. Just reuse the single parameters definition and the single ''executor''. IMO we should '''always''' enforce the single/multiple duality.
** Also, although there isn't an example, I think we could have some "habitual" structures predefined somewhere, see for example, the ''preference'' or the ''customfield'' single structures (or the whole ''preferences'' or ''customfields'' multiple ones if you prefer). They are basically the same (name/value pairs). It could be useful to have one predefined "name_value" structure somewhere and use it where necessary (user preferences, user custom fields, various config options...).

====Concerns about return functions:====

In the example above we have a good example. There are some xxxx_return() functions returning NULLs, others returning multiple structures (and also is possible to return single structures or numbers or whatever).

IMO returned structures should be, always, encapsulated into something constant, call it 'external_response'. Then, within that, we can return some '''constant information''' (bool result, string error, whatever...) and some '''dynamic information''' (single/multiple structures).

Also, while it's really simple to return results for single structures (for example the ''add_member()'' above will return one simple result ), it's more complex to do so for multiple structures. For example, the ''add_members()'' above must return one different result for each groupid-userid added. Imagine you create one client sending 4 pairs (within a multiple structure well formed WS request).

And '''only one of them is added successfully''', other fails because the userid is incorrect, another fails because it already exists and the 4th fails because the user cannot handle that group, or because the user isn't enrolled in the course the group belongs to or... whatever. How will the '''return information be formatted''' to inform about all those heterogeneous situations? How will the client know the exact status of each pair sent in the multiple request?

Should we introduce one mandatory "key" parameter in all the occurrences within one multiple request, in order to get the response properly identified by those keys? Or will the multiple request be rejected as a whole (I think this isn't possible).

Note I don't know if that has been resolved in other places of the WS documentation but I haven't been able to find it, hence the warn. ;-)

So, summarising, '''I like the 3rd alternative''' with the changes specified above (in order to make it more readable/simple, basically). And I think the "response" (return) part is '''at least as important as''' the "request" (parameters) part, and it still needs more work/definition/polishing. Shouldn't be difficult to achieve that.

Hope this helps, ciao --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:24, 18 September 2009 (UTC)

Offtopic: I hate the "external" keyword everywhere. :-D :-P

'''Note:''' The second revision to this alternative (adding new "name" parameter to all the classes vs old associative arrays) has been discussed/agreed with Petr. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 20:39, 19 September 2009 (UTC)
----

I think the flexible return values are problematic - I personally prefer exception when anything goes wrong, getting complex result requires extra post processing of results. So my -1 here. [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
:But "client" must know what has been processed and what not. What if something breaks in the 4th element of a multiple request? How is the client informed about the 3 first elements already being processed and the rest not? [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 09:10, 18 September 2009 (UTC)
::Right, the methods working with bulk data should do that, I am just not sure single methods should return complex structures, also we could send this extra information through exception - the bulk methods should call simple ones and could return exception containing the original exception + progress info [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 20:32, 19 September 2009 (UTC)
::: I agree with that (the bulk function will catch exception of the single function, and keep going to process the rest) [[User:Jerome Mouneyrac (jmouneyrac)|Jerome Mouneyrac (jmouneyrac)]] 12:23, 21 September 2009 (Perth)
::: Agree too, that is part of code reusability (throwing exception with useful info in single/multiple methods and catching it at higher level to provide WS response. Anyway my concerns are about to have a well-defined response, able to support responses both to single and multiple requests. Right now, it's undefined. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 07:51, 21 September 2009 (UTC)
:::: the parameter syntax allows us to describe both simple and complex return types, for any kind of problems we would use exceptions - in fact we could define add 3rd description function which describes some basic exceptions - I do not like the idea of using normal return when something goes wrong

====Validate_parameters requires that we define a way to match parameters with the description====

Edit: I consider that external functions are normal php functions. So they can accept anything as parameters (very complex param like array of object containing array of object), and they can have several parameters.

I'm writing the validate_parameters function. There is a thing we didn't define into the description specs. 
In order to validate parameters, we need to be able to match the parameters to the description 
I guess we'll match the parameters like that : 
''description => parameter type'' 
external_multiple_structure => a non associative array 
external_single_structure => an object 
 
Moreover I think funtion_name_parameters() should return a array of external_xxxx_structure. So we can support functions with more than one parameter like function_name($param1, $param2, $param3). The validation call will be $params = self::validate_prameters(self::function_name_description(), array($param1, $param2, $param3));

:oh no - we can use multiple params of PHP function, the mapping is simple, you just need to solve the order of params in PHP to names in description - my proposal was solving exactly that [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 15:37, 24 September 2009 (UTC)

<code php>

///example for a function with one param only

public static function create_users_parameters() {
return array (
new external_multiple_structure(
'users', new external_single_structure(
'user', array(
new external_param('username', PARAM_USERNAME, 'Username policy is defined in Moodle security config'),
new external_param('password', PARAM_RAW, 'Moodle passwords can consist of any character'),
new external_param('firstname', PARAM_NOTAGS, 'The first name(s) of the user'),
new external_param('lastname', PARAM_NOTAGS, 'The family name of the user'),
new external_param('email', PARAM_EMAIL, 'A valid and unique email address'),
new external_param('auth', PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc', false),
new external_param('confirmed', PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
new external_param('idnumber', PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
new external_param('emailstop', PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
new external_param('lang', PARAM_LANG, 'Language code such as "en_utf8", must exist on server', false),
new external_param('theme', PARAM_THEME, 'Theme name such as "standard", must exist on server', false),
new external_param('timezone', PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
new external_param('mailformat', PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
new external_param('description', PARAM_TEXT, 'User profile description, as HTML', false),
new external_param('city', PARAM_NOTAGS, 'Home city of the user', false),
new external_param('country', PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
new external_multiple_structure(
'preferences', new external_single_structure(
'preference', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the preference'),
new external_param('value', PARAM_RAW, 'The value of the preference')
)
), 'User preferences', false),
new external_multiple_structure(
'customfields', new external_single_structure(
'customfield', array(
new external_param('type', PARAM_ALPHANUMEXT, 'The name of the custom field'),
new external_param('value', PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', false)
)
)
)
///if the function had a second param we would add it here
/// , new external_multiple_structure(...)
);
}

public static function create_users(array $users) {
...
$params = self::validate_prameters(self::create_users_parameters(), array($users));
/// if the function had a second param we would have wrote
/// public static function create_users(array $users, array $second_param) {
/// $params = self::validate_prameters(self::create_users_parameters(), array($users, $second_param));

</code>

===Adding new external type to allow direct file download web service===

As proposed in [http://tracker.moodle.org/browse/MDL-32336|MDL-32336] to add a new type called external_file to allow direct file download web service.
The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection under ''base description classes'':

<code php>
/**
* File description class. Which indicates the response will return a file for download.
* Implementation that is using external_file is expected to return an associative-array/hashmap
* which contains the file to be downloaded.
*
* The file download process is handled using send_file() and send_temp_file() from lib/filelib.php.
* The properties of the associative-array/hashmap expected are:
* - filename - string - proposed file name when saving file
* - path - string - path to file, preferably from moodledata/temp/something; or content of file itself
* - tempfile - boolean - will use send_temp_file() if true, otherwise use send_file()
*/
class external_file extends external_description {
public function __construct($desc='', $required=VALUE_REQUIRED, $default=null) {
parent::__construct($desc, $required, $default);
}
}
</code>

The following snippet is proposed to be added to the wiki page's '''externallib.php''' subsection after ''Externallib.php example'':

''external_file examples:'' 
This example shows how to develop web service function which send file for download using external_file type.

<code php>
class local_wsfile_external extends external_api {

public static function download_file_parameters() {
return new external_function_parameters(
array('filename' => new external_value(PARAM_TEXT, 'name of file to be downloaded')));
}

public static function download_file($filename) {
$result = array();
$result['filename'] = $filename;
$result['path'] = '/moodle/moodledata' . $filename;
$result['tempfile'] = true;

return $result;
}

public static function download_file_returns() {
return new external_file();
}
}
</code>

Assignment Advanced Marking

2012-08-22T05:50:24Z

Pcharsle: /* Support the marking process */

This is a proposal for additional marking features in the Assignment module.

References: https://docs.moodle.org/dev/Lightwork#User_Interface_-_Marker_allocation_and_management

Tracker Issue: http://tracker.moodle.org/browse/MDL-34902

= Goals, rationale and fundamentals =

The main goals of this change are to:

* Control the distribution
* Support the marking process
* Control the release of marking to students

== Control the distribution ==

This is relevant in the context of large courses where groups/groupings are used to divide the students into groups and to associate dedicated staff with these groups. In terms of assignment marking the idea is that staff associated with groups are responsible for the marking of students in their groups and fulfil such marking independently from the marking of other groups.

An example would be: A course with 300 students is divided into 3 groups of students (based on different delivery locations, modes, tutorial groups, or other criteria). Two or more staff are associated with each group (one teacher and several teaching assistants). The same assignment is setup for the whole course. The staff associated with each group of students are responsible for marking their groups.

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) staff associated with a group should only see the students belonging to this group. It is not recorded which staff member is marking which students.
The staff member in charge of the overall course might have a setting, which allows to see assignment marking for all students (of all groups).

This functionality is primarily of interest to the EAM project.

== Support the marking process ==

The focus here is on assisting with the marking process, typically in situations where multiple teachers and/or teaching assistants form a marking team. The idea is to allow each individual marker to have an overview of marking assigned to them and of the status this marking is in. The teacher in charge of the assignment wants to be able to see how marking is progressing and what quality the marking is (per marker and across markers).

To achieve this focus two aspects need to be introduced:
* Marker allocations;
* Marking statuses.

With marker allocations, it is recorded which marker (teacher or teaching assistant) is marking which student. Only the marker allocated can mark a student. The teacher in charge of the assignment decides the marker allocation (the teacher selects all staff involved in marking and then distributes marking manually, randomly, or even based on groups). As the marking progresses, allocations can be changed (e.g., when a marker becomes unavailable).

GW - my concern with the paragraph above is that it implies that the processes of allocating manually, randomly or by groups will all operate identically. It is my understanding that the spec below is suggesting that manual allocation happens within the assignment grading table, whereas random allocation will effectively occur via the use of groups and will take advantage of the random allocation mechanisms already built into the group manager in Moodle. Likewise allocating by groups will take advantage of the same existing Moodle functionality. It was my impression that changing allocations during the marking process if groups (including random groups) are used, will require changes to the group membership. This may be a minor point, but I think it is worth highlighting.

EH - Grette, putting implementation issues aside, do you agree with the functionality proposed and importantly, with the fundamental difference to what I have called 'distribution of marking'? If we can agree on the fundamentals first we can then see how the implementation will work. What is currently described below (e.g., with the screenshots) suffers, in my opinion, from confusion about what we want to achieve.

GW - I guess I am finding it difficult to see what the difference between allocation and distribution is in reference to identifying which marker will mark which students work. I am unsure what the implications of highlighting the difference will be.

The following marking statuses are suggested:
* Allocated (the marker has not yet started)
* In marking (the marker has started but not yet finished)
* Marking completed (the marker has finished but might need to go back for checking/corrections)
* In review (the marking is now with the teacher in charge for quality checking)
* Ready for release (the teacher in charge is satisfied with the marking but wait before giving students access to the marking)
* Released (students have access to the marking.

The marking statuses are for use by staff. The marking statuses are not visible to students.
The default setting will be that students can see who has marked them (but this can be changed).
Marking can be taken from one status to the next on individual student basis, yet there are also bulk transitions (e.g., to release of ‘ready’ marking). Marking can be taken back into a previous status (e.g., from in review back to in marking if more work is required).

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) it is displayed who is marking which student (and only the staff assigned can edit the marking).

The functionality related to the marking process has its origins in Lightwork and is primarily of interest to the Lightwork online project.

GW - EAM are also interested in manual allocation of marking as an addition to using groups.

EH: Are you talking about manual distribution of subsets of students to individual markers/several markers (with processes like I have described in the first point about 'Distribution', or, are you talking about supporting the marking process?
GW - see my comment above about not being clear on the reason for the distinction between allocation and distribution.

PC: I believe a simplified set of statuses would be good when there is only a single marker:

Multiple markers - "Allocated"->"In Marking"->"Marking Completed"->"In Review"->"Ready for Release"->"Released"

Single marker - "In Marking"->"In Review"->"Released"

== Control the release of marking to students ==

A problem with the current Moodle assignment module (2.3) is that students can immediately see their marking results (if the teacher does not take extra steps for hiding the assignment from student view and hiding the grade book entry). This is not good, as it does not allow the teacher to make changes (e.g., as required to deal with marker drift or for checking across multiple markers).

The suggestion is to add a release control to the assignment module. This will have three possibilities, visible in the assignment marking overview screen (mod/assign/view.php?id=3&action=grading):
* Nothing shown (no-one has yet saved any marking for a student)
* Not released (someone has saved marking, but this marking is not yet visible to the student)
* Released (marking is visible to the student)

The sole focus here is on if the student can see the marking or not. This is not about trying to manage the marking process.

This functionality is already included in supporting the marking process as proposed by the Lightwork Online project. The EAM project is interested in this functionality as well.

PC: A concern that I have with adding a release control to the assignment module is that teachers already have a form of release control (hiding the grade book entry). It might be simpler if we could use this existing mechanism instead of adding a second release control that may confuse teachers.

GW - my sense is that using the hide/show controls for the gradebook entry requires teachers to move to a different part of Moodle in order to ensure that students do not receive their grades/feedback immediately. A function that sits within the assignment module itself will be more visible and hopefully therefore more usable. We should definitely not build something however that prevents teachers from using the 'hide/show gradebook entry' method.

EH: I think that the additional functionality would be well placed. Hiding marking from students needs to occur in two places: in the gradebook and in the assignment activity. Hiding the gragebook entry is fairly easy for the teacher (but, as Grette points out, it is in a different place in Moodle). Hiding the assignment activity has unwelcome side effects. As I understand it, the teacher needs to hide the assignment from student view so students cannot see marks and feedback. But, for example, this means that students cannot make late submissions (as they cannot see the assignment ...).

PC: Just to be clear, what I was talking about was using the proposed release control in the assignment settings to hide the grade book entries (not expecting teachers to move to a different part of Moodle). In other words, when an assignment is created with release control, it would be automatically set to 'hidden' in the grade book.

== How do these functionalities combine for the user and in implementation? ==

The functionalities would result in three settings to the Assignment update page (course/modedit.php?update=3&return=1).

* Control release of marking to students (Yes/No)
* Set distribution of marking (Yes/No; with Yes offering selection of groups/groupings)
* Manage marking process (Yes/No; with Yes offering allocation algorithms/manual allocation)

Controlling the release of marking to students is not in conflict with setting the distribution of marking, and is already included in managing the marking process.

Fundamentally there is no conflict between setting the distribution of marking and managing the marking process (in fact, it would be welcome as a ‘group’ will likely contain a large number of students and possibly several markers, making it very useful to be able to manage their marking). Yet, an initial implementation might keep things more simple and make these setting mutually exclusive.

The distribution of marking will build on already existing groups and groupings. No further database tables should be necessary to capture this information. Any changes to groups would be reflected during the marking process.

Capturing the marking allocations will require new database tables. If one allows building the allocation on groups, this will mean that the initial setting for the allocations is taken from the groups, but that any changes to groups will not be automatically reflected in marker allocations (but can be done manually, like any changes to allocations).
GW - this would be highly problematic for groups that get their membership from Student Information Systems.

= Overview =

''(The following sections currently do not match what is proposed under Goals above.)''

== Settings added to the mod_assign settings page ==

Release grades immediately (Checkbox, default to on - this is the current behaviour)

[Help text] When enabled, grades will be visible to students as soon as they have been entered by a grader (If the grade column is visible in the gradebook). When disabled, any grades that are entered will be only visible to graders until they are approved for release.

Allocate markers to students (Select list of options, "None - all markers can mark all students", "Manually allocated - markers are manually allocated students to mark", "Groups - Markers can mark students in their own group")

When the grouping method is chosen above, an additional setting should be enabled to allow a grouping to be specified for the marker allocations.

Grouping for marker allocations (Select from the available groupings - or None for all groups)

GW - we currently create marking groups using the groups interface and then set assignment up using "Separate groups" so that markers can filter the list of assignments. One of the issues we have come up against is unenrolled (suspended) students still appearing in the groups interface. We have a proposal for better management of suspended users. We have identified 23 (possibly 25) areas where suspended users are currently an issue. Where possible, we’d like an option to toggle between hiding and showing suspended users, with the default option being hidden. We are looking to resource a change that will be all encompassing and a complete fix that can be contributed back to the Moodle community. Initially we will build for 2.1.6, but will then review for 2.3 towards the end of the year.

PC - I believe the assignment settings should be simplified or teachers will find it confusing. I would like to see the "Release grades immediately" and "Allocate markers to students" replaced with a single drop down of standard options:

* Simple marking" (the default settings - grades are released immediately)
* Advanced marking - single marker" (Grades are released when status changed to 'Released')
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released')

Note that when choosing "Advanced marking - multiple markers" the teacher would be able choose whether or not to use a Grouping for allocating
markers. If we are going to allow other combinations of "Release grades immediately" and "Allocate markers to students" then we could have an additional menu item to allow teachers to choose their own combination.

EH: Paul, with "Advanced marking - single marker", do you see that an automated marking allocation is made to one person (who has to have the capability to release grades), therefore enforcing that only this person can mark? I think this is a quite different approach to what Damyon is proposing, which basically says 'use marking statuses but do not record/control who is marking'. If I understand correctly what Paul is proposing, this means that one can use marking statuses only if one controls marker allocation. This might be a better solution, as it cuts out variety, simplifying things for the development and the user. We could add a fourth option for using marking statuses without marker allocation, this might give the following options:

* Simple marking" (the default settings - grades are released immediately, marker allocations are not recorded)
* Advanced marking - no marker allocations" ((Grades are released when status changed to 'Released'. No control who is marking)
* Advanced marking - single marker" (Grades are released when status changed to 'Released'. Only single marker specified can mark and release)
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released'. Multiple markers work together)

GW - I think my preference is for three settings:
Release grades immediately
Allocate markers to students

and the third
Grouping for marker allocations (to appear only if group allocation is selected)

I think it may end up being clearer, rather than trying to explain in help text what Simple marking and the Advanced marking options are.

PC - My concern is that being able to choose a combination of settings in this way does not make it clear to the teacher what they will end up with at the end. For instance, a teacher who wants to take advantage of the advanced marking process should not have to work out that they have to select "Release grades immediately - No" in order to do this. Also, see my comment earlier about the use of the "hiding" facility in the grade book to control the release.

== Changes to grading/grading interface ==

=== Marking release ===

If "Release grades immediately" is not enabled, an additional status should be added to the grading status column "Draft/Ready for release/Released". Use background colors as well to visually distinguish the statuses (Blue - draft, Fushia - Ready for Review, Yellow - Ready for Release, Green - Released).

Anyone with mod/assign:grade capability would be able to move the status from "Draft" to "Ready for Review" via the drop down menu on each submission, or via the batch operations form.

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" to "Ready for Release".

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" or "Ready for Release" to "Released". At this point the grade is pushed to the gradebook and made visible to the student.

=== Marker allocations ===

If "Allocate markers to students" is set to "Manually allocated", and the current user has "mod/assign:allocatemarkers" capability, the list of markers allocated to each student needs to be shown in a new column in the grading interface.

Multiple markers should be able to be allocated to a single student. (GW - future dev? Implies the need for markers to be able to lock assignments while they are marking them). If the current user has mod/assign:allocategraders permission, a red X next to each markers will allow immediately removing this marker (Ajax if possible - don't refresh the full page)
An option should be added to the menu for each submission and the batch operations menu which takes you to a separate page where you can choose from the users with mod/assign:grade permission to allocate to a student (or multiple students).

Any student with no markers allocated should have "No markers" in this column and the column background should be shown in a different colour (Red?) to indicate that no-one has been assigned to mark this submission. If the current user has "mod/assign:allocatemarkers" and "mod/assign:grade" capability, there should be an entry in the menu for this submissions for "Assign to me" (preferably AJAX - do not refresh entire page).

If the a submissions has not been allocated to the current user, the option to grade that submission is removed.

If the current user does not have "mod/assign:allocatemarkers" capability, the list of submissions will be limited to only show the submissions where the current user has been allocated as a marker.

PC - How will you be handling marker allocation in the database when "Grouping for allocating markers" isn't selected? Answer from our last meeting : marker allocation tables will be used

== Use Cases ==

=== Teacher is creating an assignment with a small number of students and they do not wish to use advanced marking ===
* Create an assignment and leave the new settings at their defaults
** Release grades immediately: "checked"
** Allocate markers to students: "None"
=== Teacher is creating an assignment with a small number of students and they wish to mark all submissions, then re-mark several submissions to check for "grading drift" before release ===
(I am defining this as the perception of quality changing over time as the marker marks each assignment in turn - can't find a good reference right now)
EH: This is called 'marker drift'. you'll find a brief description in http://etools.massey.ac.nz/documents/LitReview101006.pdf (p. 19 bottom), as well as references to further literature.
* Teacher has "mod/assign:create", "mod/assign:grade" and "mod/assign:releasegrades" capabilities
* Create an assignment and de-select Release grades immediately
** Release grades immediately: "not checked"
** Allocate markers to students: "None"
* Teacher marks each submission individually. Grades are "Draft" and not released to gradebook or students
GW - I think I know why this status is "Draft", but I think it might get confused with the submission status in the interface. I think we can come up with a better term..not that I have thought of one yet.

PC - How about "Provisional"?
* Teacher re-marks a random sample of submissions
* Teacher releases all the grades via the batch operations form

EH: The seems to be our 'In marking'

GW - what about "Ready to mark" - this might be more consistent with the other statuses "Ready for review" and "Ready for release". Is there any relationship between this status and the submission status...ie. if the submission status is "Draft" should the marking status be "Not ready to mark", which changes to "Ready to mark" when the submission status is "submitted"?

'Not marked' 'In Marking' (?) 'Ready for review' 'Ready for release' ' Released'

EH:

I think we should point out as the main reason for the stepped release of grades via the transition from 'Ready for release' to 'Released' as
* The teacher wants to release marking to all students at the same time.

Marker drift or any other checking done by one person on their own marking is important. Yes, in this use case the teacher can use the statuses proposed for that, yet the need for this type of checking applies to all markers (teachers and teaching assistants). This is why we have proposed the statuses of 'In marking' and 'Marking finished', before the marking is being passed on the the teacher for further quality review (e.g., to check across markers).

PC: I believe the following statuses would be good:

Multiple markers - "Allocated"->"In Marking"->"Marking Completed"->"In Review"->"Ready for Release"->"Released"

Single marker - "In Marking"->"In Review"->"Released"

PS: The descriptions here focus on the release of grades - this portraits a very summative viewpoint; it does not acknowledge the importance of feedback (as in the comments hopefully written to guide the students). This is why I tend to talk about marking and marking results.

=== Multiple Teachers are marking submissions for the same assignment and they want to know who is marking which assignment ===
* Assignment has been created and there are multiple markers with "mod:assign/grade and mod:assign/allocatemarker" capabilities
* Each marker selects "Assign to me" for the submissions they wish to mark.
* Each marker then provides grades and feedback which is released immediately to students
* The markers can see which students have been allocated a marker and will not end up marking the same student

=== A teacher has assistants helping them mark and wants to review all marks before they are released 1===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Manually
* The teacher allocates a set of students to each of the Teaching Assistants
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students

EH: It would be nice to have an option on the settings page where the teacher can set if the Teaching Assistants can see the marking done by other markers (not just the grade). Is the current proposal that a Teaching Assistant would see the entries for students not allocated to them (that means that can see the grade given by another Teaching Assistant)? There would have to be a 'read-only' grading option, allowing the Teaching Assistant to view marking done by others but not change it.
DW: No the current proposal is that they would not see any students not allocated to them.

* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"

EH: Here it would be nice if the Teaching Assistant could pass on a message to the Teacher together with the status change.

* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary

EH: How will the screenshot look? Will the Teacher have access to the grading interface even if the Teacher is not allocated to mark (the Teacher will have to look at the marking details, not just at the grade)?
DW: yes they would see the grading interface
If the Teacher changes feedback or grade, will this mean an automated re-allocation to the Teacher as marker?
DW: The teacher would not be able to provide grades or feedback unless they were the allocated marker
Will the student see who has marked them (there probably should be a setting allowing the Teacher to decide)?
DW: This is a big change - it would currently show them the last person to mark them.
We also need to options here to return the marking to the Teaching Assistant (ideally with comments, explaining why) and to allocate another marker (who then will continue with the marking already started - maybe this is already covered).
DW: This is quite an advanced workflow - we need to make sure we are not adding too much complexity (it is not prevented by this interface - it just does not include any statuses for it - ie "Needs allocation to another marker for a second round of marking")

EH: This description skips the step of the Teacher taking assignments into 'Ready for release' after successful quality checking.

* The teacher changes the status of the grades to 'Released' when they are satisfied with the grading quality.

EH: I think this should read: The Teacher changes the status from 'Ready for review' to 'Ready for Release' when they are satisfied with the grading quality.

Then the next step is: The Teacher changes the status from 'Ready for Release' to 'Released' when they want to release marking to students.

DW: I have added the "ready for release" status - but this will require good help explaining the difference between the statuses to teachers. A visual flow chart of the statuses would help.

GW - I think that the Teacher should have the option to skip the "Ready for Release" status and take the assignment from "Ready for review" straight to "Released". If statuses can be skipped..ie. as long as we don't force users through every status, then i don't think it will be a problem to have the five statuses as proposed above:
'Not marked'
'In marking/Being marked'
'Ready for review'
'Ready for release'
'Released'

PC - I don't agree with skipping the "Ready for Release" status since it is an important part of the review process. However, it is possible to make the switching between statuses fast and efficient by having bulk options such as "Release all" that automatically selects marking with one status and moves it to the next.

Where it would be appropriate to reduce the number of statuses (but possibly not in our first Moodle 2.4 release) is when there is only a
single marker. So, I think we need the following:

Multiple markers - "Allocated"->"In Marking"->"Marking Completed"->"In Review"->"Ready for Release"->"Released"

Single marker - "In Marking"->"In Review"->"Released"

=== A teacher has assistants helping them mark and wants to review all marks before they are released 2 ===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* There are groups containing teaching assistants and sets of students contained in a grouping.
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Groups
** Grouping for marker allocation : "Name of Grouping"
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students
* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"
* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary
* The teacher changes the status of the grades to "Released" when they are satisfied with the grading quality.

If there are multiple markers added to a group then all markers will be able to mark assignments in that group.

GW - If there are no markers in a group, then there is the potential that student assignments would get missed....there is no visual queue that students are unallocated. In addition - our SIS-created groups systematically check for the addition of members who are not in the group in the SIS. Any staff therefore who are added to the groups in Moodle will be removed from the group on the next update...unless we changed our integration script to retain users in SIS-created groups as long as they were not students??

=== Multiple markers which to separately mark the same set of students and then a moderator either takes an average or chooses one of the marks to be released ===
Not supported by this proposal

=== Multiple markers mark one student in sequence ===

EH: This is about two or more markers marking student work, e.g., marker 1 marks parts 1 and 2, marker 2 marks parts 3 and 4 of an assignment. This could be done with a different form of allocation: marker1 picks a student and then marks their part; the interface shows that marker 1 has done their part, marker2 can now allocate themselves and continue the marking. Once all markers involved (as setup initially, here markers 1 and 2 need to mark) have done their parts the status changes to 'ready for review'.

This is not part of the current proposal.

=== Separate release of grades and feedback ===

EH: It would be nice to be able to release feedback (for formative purposes) first and marks/grades later (with a time delay or triggered by the Teacher, or, more sophisticated, dependent on the student doing something).

This is not part of the current proposal.

DW: I think it should be - but I don't what to make it complicated. I think that either the feedback is visible to the student during the entire marking process and they get the grade at the end - or they see nothing and they get the grades + feedback at the end (we could add those 2 options to the settings page). Note: The submission comments are visible to staff and students for the entire duration and provide 2 way comments between students and staff.

GW: The potential issue with this is that feedback might change during the marking process. Is a student-triggered process (ie. viewing the feedback) to release grades "complicated"?

EH: I am with Grette there - feedback should only be visible to students when marking is considered as finished (otherwise we would be back to the current deficiencies in Moodle)

== User Interface ==
=== Assignment settings screen ===
[[File:assign-advgrading-settings.png| Assignment settings screen]]
=== Submission menu in grading table ===
[[File:assign-advgrading-gradingmenu.png| Submission grading menu]]
=== Batch operations menu ===
[[File:assign-advgrading-gradingbatchmenu.png| Grading batch operations menu]]

GW: Will there be an option for the Teacher with "mod/assign:releasegrades" capability to take all assignments that are in "Ready for Review" to either "Ready for Release" or "Release" without having to individually select them?

GW - will there be a batch operation for "Assign to me?"

=== Marker allocation ===
Notes: The current user is "Grader Gary" so the grade option has disappeared for all submissions that this user is not assigned to mark. The current user also has permission to assign graders so they see additional options in the submission menu.

[[File:assign-advgrading-marker-allocation.png| Marker allocation]]

== Database Changes ==

Assignment Advanced Marking

2012-08-22T05:33:02Z

Pcharsle: /* Control the release of marking to students */

This is a proposal for additional marking features in the Assignment module.

References: https://docs.moodle.org/dev/Lightwork#User_Interface_-_Marker_allocation_and_management

Tracker Issue: http://tracker.moodle.org/browse/MDL-34902

= Goals, rationale and fundamentals =

The main goals of this change are to:

* Control the distribution
* Support the marking process
* Control the release of marking to students

== Control the distribution ==

This is relevant in the context of large courses where groups/groupings are used to divide the students into groups and to associate dedicated staff with these groups. In terms of assignment marking the idea is that staff associated with groups are responsible for the marking of students in their groups and fulfil such marking independently from the marking of other groups.

An example would be: A course with 300 students is divided into 3 groups of students (based on different delivery locations, modes, tutorial groups, or other criteria). Two or more staff are associated with each group (one teacher and several teaching assistants). The same assignment is setup for the whole course. The staff associated with each group of students are responsible for marking their groups.

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) staff associated with a group should only see the students belonging to this group. It is not recorded which staff member is marking which students.
The staff member in charge of the overall course might have a setting, which allows to see assignment marking for all students (of all groups).

This functionality is primarily of interest to the EAM project.

== Support the marking process ==

The focus here is on assisting with the marking process, typically in situations where multiple teachers and/or teaching assistants form a marking team. The idea is to allow each individual marker to have an overview of marking assigned to them and of the status this marking is in. The teacher in charge of the assignment wants to be able to see how marking is progressing and what quality the marking is (per marker and across markers).

To achieve this focus two aspects need to be introduced:
* Marker allocations;
* Marking statuses.

With marker allocations, it is recorded which marker (teacher or teaching assistant) is marking which student. Only the marker allocated can mark a student. The teacher in charge of the assignment decides the marker allocation (the teacher selects all staff involved in marking and then distributes marking manually, randomly, or even based on groups). As the marking progresses, allocations can be changed (e.g., when a marker becomes unavailable).

GW - my concern with the paragraph above is that it implies that the processes of allocating manually, randomly or by groups will all operate identically. It is my understanding that the spec below is suggesting that manual allocation happens within the assignment grading table, whereas random allocation will effectively occur via the use of groups and will take advantage of the random allocation mechanisms already built into the group manager in Moodle. Likewise allocating by groups will take advantage of the same existing Moodle functionality. It was my impression that changing allocations during the marking process if groups (including random groups) are used, will require changes to the group membership. This may be a minor point, but I think it is worth highlighting.

EH - Grette, putting implementation issues aside, do you agree with the functionality proposed and importantly, with the fundamental difference to what I have called 'distribution of marking'? If we can agree on the fundamentals first we can then see how the implementation will work. What is currently described below (e.g., with the screenshots) suffers, in my opinion, from confusion about what we want to achieve.

GW - I guess I am finding it difficult to see what the difference between allocation and distribution is in reference to identifying which marker will mark which students work. I am unsure what the implications of highlighting the difference will be.

The following marking statuses are suggested:
* Allocated (the marker has not yet started)
* In marking (the marker has started but not yet finished)
* Marking completed (the marker has finished but might need to go back for checking/corrections)
* In review (the marking is now with the teacher in charge for quality checking)
* Ready for release (the teacher in charge is satisfied with the marking but wait before giving students access to the marking)
* Released (students have access to the marking.

The marking statuses are for use by staff. The marking statuses are not visible to students.
The default setting will be that students can see who has marked them (but this can be changed).
Marking can be taken from one status to the next on individual student basis, yet there are also bulk transitions (e.g., to release of ‘ready’ marking). Marking can be taken back into a previous status (e.g., from in review back to in marking if more work is required).

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) it is displayed who is marking which student (and only the staff assigned can edit the marking).

The functionality related to the marking process has its origins in Lightwork and is primarily of interest to the Lightwork online project.

GW - EAM are also interested in manual allocation of marking as an addition to using groups.

EH: Are you talking about manual distribution of subsets of students to individual markers/several markers (with processes like I have described in the first point about 'Distribution', or, are you talking about supporting the marking process?
GW - see my comment above about not being clear on the reason for the distinction between allocation and distribution.

== Control the release of marking to students ==

A problem with the current Moodle assignment module (2.3) is that students can immediately see their marking results (if the teacher does not take extra steps for hiding the assignment from student view and hiding the grade book entry). This is not good, as it does not allow the teacher to make changes (e.g., as required to deal with marker drift or for checking across multiple markers).

The suggestion is to add a release control to the assignment module. This will have three possibilities, visible in the assignment marking overview screen (mod/assign/view.php?id=3&action=grading):
* Nothing shown (no-one has yet saved any marking for a student)
* Not released (someone has saved marking, but this marking is not yet visible to the student)
* Released (marking is visible to the student)

The sole focus here is on if the student can see the marking or not. This is not about trying to manage the marking process.

This functionality is already included in supporting the marking process as proposed by the Lightwork Online project. The EAM project is interested in this functionality as well.

PC: A concern that I have with adding a release control to the assignment module is that teachers already have a form of release control (hiding the grade book entry). It might be simpler if we could use this existing mechanism instead of adding a second release control that may confuse teachers.

GW - my sense is that using the hide/show controls for the gradebook entry requires teachers to move to a different part of Moodle in order to ensure that students do not receive their grades/feedback immediately. A function that sits within the assignment module itself will be more visible and hopefully therefore more usable. We should definitely not build something however that prevents teachers from using the 'hide/show gradebook entry' method.

EH: I think that the additional functionality would be well placed. Hiding marking from students needs to occur in two places: in the gradebook and in the assignment activity. Hiding the gragebook entry is fairly easy for the teacher (but, as Grette points out, it is in a different place in Moodle). Hiding the assignment activity has unwelcome side effects. As I understand it, the teacher needs to hide the assignment from student view so students cannot see marks and feedback. But, for example, this means that students cannot make late submissions (as they cannot see the assignment ...).

PC: Just to be clear, what I was talking about was using the proposed release control in the assignment settings to hide the grade book entries (not expecting teachers to move to a different part of Moodle). In other words, when an assignment is created with release control, it would be automatically set to 'hidden' in the grade book.

== How do these functionalities combine for the user and in implementation? ==

The functionalities would result in three settings to the Assignment update page (course/modedit.php?update=3&return=1).

* Control release of marking to students (Yes/No)
* Set distribution of marking (Yes/No; with Yes offering selection of groups/groupings)
* Manage marking process (Yes/No; with Yes offering allocation algorithms/manual allocation)

Controlling the release of marking to students is not in conflict with setting the distribution of marking, and is already included in managing the marking process.

Fundamentally there is no conflict between setting the distribution of marking and managing the marking process (in fact, it would be welcome as a ‘group’ will likely contain a large number of students and possibly several markers, making it very useful to be able to manage their marking). Yet, an initial implementation might keep things more simple and make these setting mutually exclusive.

The distribution of marking will build on already existing groups and groupings. No further database tables should be necessary to capture this information. Any changes to groups would be reflected during the marking process.

Capturing the marking allocations will require new database tables. If one allows building the allocation on groups, this will mean that the initial setting for the allocations is taken from the groups, but that any changes to groups will not be automatically reflected in marker allocations (but can be done manually, like any changes to allocations).
GW - this would be highly problematic for groups that get their membership from Student Information Systems.

= Overview =

''(The following sections currently do not match what is proposed under Goals above.)''

== Settings added to the mod_assign settings page ==

Release grades immediately (Checkbox, default to on - this is the current behaviour)

[Help text] When enabled, grades will be visible to students as soon as they have been entered by a grader (If the grade column is visible in the gradebook). When disabled, any grades that are entered will be only visible to graders until they are approved for release.

Allocate markers to students (Select list of options, "None - all markers can mark all students", "Manually allocated - markers are manually allocated students to mark", "Groups - Markers can mark students in their own group")

When the grouping method is chosen above, an additional setting should be enabled to allow a grouping to be specified for the marker allocations.

Grouping for marker allocations (Select from the available groupings - or None for all groups)

GW - we currently create marking groups using the groups interface and then set assignment up using "Separate groups" so that markers can filter the list of assignments. One of the issues we have come up against is unenrolled (suspended) students still appearing in the groups interface. We have a proposal for better management of suspended users. We have identified 23 (possibly 25) areas where suspended users are currently an issue. Where possible, we’d like an option to toggle between hiding and showing suspended users, with the default option being hidden. We are looking to resource a change that will be all encompassing and a complete fix that can be contributed back to the Moodle community. Initially we will build for 2.1.6, but will then review for 2.3 towards the end of the year.

PC - I believe the assignment settings should be simplified or teachers will find it confusing. I would like to see the "Release grades immediately" and "Allocate markers to students" replaced with a single drop down of standard options:

* Simple marking" (the default settings - grades are released immediately)
* Advanced marking - single marker" (Grades are released when status changed to 'Released')
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released')

Note that when choosing "Advanced marking - multiple markers" the teacher would be able choose whether or not to use a Grouping for allocating
markers. If we are going to allow other combinations of "Release grades immediately" and "Allocate markers to students" then we could have an additional menu item to allow teachers to choose their own combination.

EH: Paul, with "Advanced marking - single marker", do you see that an automated marking allocation is made to one person (who has to have the capability to release grades), therefore enforcing that only this person can mark? I think this is a quite different approach to what Damyon is proposing, which basically says 'use marking statuses but do not record/control who is marking'. If I understand correctly what Paul is proposing, this means that one can use marking statuses only if one controls marker allocation. This might be a better solution, as it cuts out variety, simplifying things for the development and the user. We could add a fourth option for using marking statuses without marker allocation, this might give the following options:

* Simple marking" (the default settings - grades are released immediately, marker allocations are not recorded)
* Advanced marking - no marker allocations" ((Grades are released when status changed to 'Released'. No control who is marking)
* Advanced marking - single marker" (Grades are released when status changed to 'Released'. Only single marker specified can mark and release)
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released'. Multiple markers work together)

GW - I think my preference is for three settings:
Release grades immediately
Allocate markers to students

and the third
Grouping for marker allocations (to appear only if group allocation is selected)

I think it may end up being clearer, rather than trying to explain in help text what Simple marking and the Advanced marking options are.

PC - My concern is that being able to choose a combination of settings in this way does not make it clear to the teacher what they will end up with at the end. For instance, a teacher who wants to take advantage of the advanced marking process should not have to work out that they have to select "Release grades immediately - No" in order to do this. Also, see my comment earlier about the use of the "hiding" facility in the grade book to control the release.

== Changes to grading/grading interface ==

=== Marking release ===

If "Release grades immediately" is not enabled, an additional status should be added to the grading status column "Draft/Ready for release/Released". Use background colors as well to visually distinguish the statuses (Blue - draft, Fushia - Ready for Review, Yellow - Ready for Release, Green - Released).

Anyone with mod/assign:grade capability would be able to move the status from "Draft" to "Ready for Review" via the drop down menu on each submission, or via the batch operations form.

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" to "Ready for Release".

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" or "Ready for Release" to "Released". At this point the grade is pushed to the gradebook and made visible to the student.

=== Marker allocations ===

If "Allocate markers to students" is set to "Manually allocated", and the current user has "mod/assign:allocatemarkers" capability, the list of markers allocated to each student needs to be shown in a new column in the grading interface.

Multiple markers should be able to be allocated to a single student. (GW - future dev? Implies the need for markers to be able to lock assignments while they are marking them). If the current user has mod/assign:allocategraders permission, a red X next to each markers will allow immediately removing this marker (Ajax if possible - don't refresh the full page)
An option should be added to the menu for each submission and the batch operations menu which takes you to a separate page where you can choose from the users with mod/assign:grade permission to allocate to a student (or multiple students).

Any student with no markers allocated should have "No markers" in this column and the column background should be shown in a different colour (Red?) to indicate that no-one has been assigned to mark this submission. If the current user has "mod/assign:allocatemarkers" and "mod/assign:grade" capability, there should be an entry in the menu for this submissions for "Assign to me" (preferably AJAX - do not refresh entire page).

If the a submissions has not been allocated to the current user, the option to grade that submission is removed.

If the current user does not have "mod/assign:allocatemarkers" capability, the list of submissions will be limited to only show the submissions where the current user has been allocated as a marker.

PC - How will you be handling marker allocation in the database when "Grouping for allocating markers" isn't selected? Answer from our last meeting : marker allocation tables will be used

== Use Cases ==

=== Teacher is creating an assignment with a small number of students and they do not wish to use advanced marking ===
* Create an assignment and leave the new settings at their defaults
** Release grades immediately: "checked"
** Allocate markers to students: "None"
=== Teacher is creating an assignment with a small number of students and they wish to mark all submissions, then re-mark several submissions to check for "grading drift" before release ===
(I am defining this as the perception of quality changing over time as the marker marks each assignment in turn - can't find a good reference right now)
EH: This is called 'marker drift'. you'll find a brief description in http://etools.massey.ac.nz/documents/LitReview101006.pdf (p. 19 bottom), as well as references to further literature.
* Teacher has "mod/assign:create", "mod/assign:grade" and "mod/assign:releasegrades" capabilities
* Create an assignment and de-select Release grades immediately
** Release grades immediately: "not checked"
** Allocate markers to students: "None"
* Teacher marks each submission individually. Grades are "Draft" and not released to gradebook or students
GW - I think I know why this status is "Draft", but I think it might get confused with the submission status in the interface. I think we can come up with a better term..not that I have thought of one yet.

PC - How about "Provisional"?
* Teacher re-marks a random sample of submissions
* Teacher releases all the grades via the batch operations form

EH: The seems to be our 'In marking'

GW - what about "Ready to mark" - this might be more consistent with the other statuses "Ready for review" and "Ready for release". Is there any relationship between this status and the submission status...ie. if the submission status is "Draft" should the marking status be "Not ready to mark", which changes to "Ready to mark" when the submission status is "submitted"?

'Not marked' 'In Marking' (?) 'Ready for review' 'Ready for release' ' Released'

EH:

I think we should point out as the main reason for the stepped release of grades via the transition from 'Ready for release' to 'Released' as
* The teacher wants to release marking to all students at the same time.

Marker drift or any other checking done by one person on their own marking is important. Yes, in this use case the teacher can use the statuses proposed for that, yet the need for this type of checking applies to all markers (teachers and teaching assistants). This is why we have proposed the statuses of 'In marking' and 'Marking finished', before the marking is being passed on the the teacher for further quality review (e.g., to check across markers).

PC: I believe the following statuses would be good:

Multiple markers - "Allocated"->"In Marking"->"Marking Completed"->"In Review"->"Ready for Release"->"Released"

Single marker - "In Marking"->"In Review"->"Released"

PS: The descriptions here focus on the release of grades - this portraits a very summative viewpoint; it does not acknowledge the importance of feedback (as in the comments hopefully written to guide the students). This is why I tend to talk about marking and marking results.

=== Multiple Teachers are marking submissions for the same assignment and they want to know who is marking which assignment ===
* Assignment has been created and there are multiple markers with "mod:assign/grade and mod:assign/allocatemarker" capabilities
* Each marker selects "Assign to me" for the submissions they wish to mark.
* Each marker then provides grades and feedback which is released immediately to students
* The markers can see which students have been allocated a marker and will not end up marking the same student

=== A teacher has assistants helping them mark and wants to review all marks before they are released 1===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Manually
* The teacher allocates a set of students to each of the Teaching Assistants
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students

EH: It would be nice to have an option on the settings page where the teacher can set if the Teaching Assistants can see the marking done by other markers (not just the grade). Is the current proposal that a Teaching Assistant would see the entries for students not allocated to them (that means that can see the grade given by another Teaching Assistant)? There would have to be a 'read-only' grading option, allowing the Teaching Assistant to view marking done by others but not change it.
DW: No the current proposal is that they would not see any students not allocated to them.

* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"

EH: Here it would be nice if the Teaching Assistant could pass on a message to the Teacher together with the status change.

* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary

EH: How will the screenshot look? Will the Teacher have access to the grading interface even if the Teacher is not allocated to mark (the Teacher will have to look at the marking details, not just at the grade)?
DW: yes they would see the grading interface
If the Teacher changes feedback or grade, will this mean an automated re-allocation to the Teacher as marker?
DW: The teacher would not be able to provide grades or feedback unless they were the allocated marker
Will the student see who has marked them (there probably should be a setting allowing the Teacher to decide)?
DW: This is a big change - it would currently show them the last person to mark them.
We also need to options here to return the marking to the Teaching Assistant (ideally with comments, explaining why) and to allocate another marker (who then will continue with the marking already started - maybe this is already covered).
DW: This is quite an advanced workflow - we need to make sure we are not adding too much complexity (it is not prevented by this interface - it just does not include any statuses for it - ie "Needs allocation to another marker for a second round of marking")

EH: This description skips the step of the Teacher taking assignments into 'Ready for release' after successful quality checking.

* The teacher changes the status of the grades to 'Released' when they are satisfied with the grading quality.

EH: I think this should read: The Teacher changes the status from 'Ready for review' to 'Ready for Release' when they are satisfied with the grading quality.

Then the next step is: The Teacher changes the status from 'Ready for Release' to 'Released' when they want to release marking to students.

DW: I have added the "ready for release" status - but this will require good help explaining the difference between the statuses to teachers. A visual flow chart of the statuses would help.

GW - I think that the Teacher should have the option to skip the "Ready for Release" status and take the assignment from "Ready for review" straight to "Released". If statuses can be skipped..ie. as long as we don't force users through every status, then i don't think it will be a problem to have the five statuses as proposed above:
'Not marked'
'In marking/Being marked'
'Ready for review'
'Ready for release'
'Released'

PC - I don't agree with skipping the "Ready for Release" status since it is an important part of the review process. However, it is possible to make the switching between statuses fast and efficient by having bulk options such as "Release all" that automatically selects marking with one status and moves it to the next.

Where it would be appropriate to reduce the number of statuses (but possibly not in our first Moodle 2.4 release) is when there is only a
single marker. So, I think we need the following:

Multiple markers - "Allocated"->"In Marking"->"Marking Completed"->"In Review"->"Ready for Release"->"Released"

Single marker - "In Marking"->"In Review"->"Released"

=== A teacher has assistants helping them mark and wants to review all marks before they are released 2 ===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* There are groups containing teaching assistants and sets of students contained in a grouping.
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Groups
** Grouping for marker allocation : "Name of Grouping"
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students
* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"
* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary
* The teacher changes the status of the grades to "Released" when they are satisfied with the grading quality.

If there are multiple markers added to a group then all markers will be able to mark assignments in that group.

GW - If there are no markers in a group, then there is the potential that student assignments would get missed....there is no visual queue that students are unallocated. In addition - our SIS-created groups systematically check for the addition of members who are not in the group in the SIS. Any staff therefore who are added to the groups in Moodle will be removed from the group on the next update...unless we changed our integration script to retain users in SIS-created groups as long as they were not students??

=== Multiple markers which to separately mark the same set of students and then a moderator either takes an average or chooses one of the marks to be released ===
Not supported by this proposal

=== Multiple markers mark one student in sequence ===

EH: This is about two or more markers marking student work, e.g., marker 1 marks parts 1 and 2, marker 2 marks parts 3 and 4 of an assignment. This could be done with a different form of allocation: marker1 picks a student and then marks their part; the interface shows that marker 1 has done their part, marker2 can now allocate themselves and continue the marking. Once all markers involved (as setup initially, here markers 1 and 2 need to mark) have done their parts the status changes to 'ready for review'.

This is not part of the current proposal.

=== Separate release of grades and feedback ===

EH: It would be nice to be able to release feedback (for formative purposes) first and marks/grades later (with a time delay or triggered by the Teacher, or, more sophisticated, dependent on the student doing something).

This is not part of the current proposal.

DW: I think it should be - but I don't what to make it complicated. I think that either the feedback is visible to the student during the entire marking process and they get the grade at the end - or they see nothing and they get the grades + feedback at the end (we could add those 2 options to the settings page). Note: The submission comments are visible to staff and students for the entire duration and provide 2 way comments between students and staff.

GW: The potential issue with this is that feedback might change during the marking process. Is a student-triggered process (ie. viewing the feedback) to release grades "complicated"?

EH: I am with Grette there - feedback should only be visible to students when marking is considered as finished (otherwise we would be back to the current deficiencies in Moodle)

== User Interface ==
=== Assignment settings screen ===
[[File:assign-advgrading-settings.png| Assignment settings screen]]
=== Submission menu in grading table ===
[[File:assign-advgrading-gradingmenu.png| Submission grading menu]]
=== Batch operations menu ===
[[File:assign-advgrading-gradingbatchmenu.png| Grading batch operations menu]]

GW: Will there be an option for the Teacher with "mod/assign:releasegrades" capability to take all assignments that are in "Ready for Review" to either "Ready for Release" or "Release" without having to individually select them?

GW - will there be a batch operation for "Assign to me?"

=== Marker allocation ===
Notes: The current user is "Grader Gary" so the grade option has disappeared for all submissions that this user is not assigned to mark. The current user also has permission to assign graders so they see additional options in the submission menu.

[[File:assign-advgrading-marker-allocation.png| Marker allocation]]

== Database Changes ==

Assignment Advanced Marking

2012-08-21T23:27:00Z

Pcharsle: /* Teacher is creating an assignment with a small number of students and they wish to mark all submissions, then re-mark several submissions to check for "grading drift" before release */

This is a proposal for additional marking features in the Assignment module.

References: https://docs.moodle.org/dev/Lightwork#User_Interface_-_Marker_allocation_and_management

Tracker Issue: http://tracker.moodle.org/browse/MDL-34902

= Goals, rationale and fundamentals =

The main goals of this change are to:

* Control the distribution
* Support the marking process
* Control the release of marking to students

== Control the distribution ==

This is relevant in the context of large courses where groups/groupings are used to divide the students into groups and to associate dedicated staff with these groups. In terms of assignment marking the idea is that staff associated with groups are responsible for the marking of students in their groups and fulfil such marking independently from the marking of other groups.

An example would be: A course with 300 students is divided into 3 groups of students (based on different delivery locations or modes). Two or more staff are associated with each group (one teacher and several teaching assistants). The same assignment is setup for the whole course. The staff associated with each group of students are responsible for marking their groups.

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) staff associated with a group should only see the students belonging to this group. It is not recorded which staff member is marking which students.
The staff member in charge of the overall course might have a setting, which allows to see assignment marking for all students (of all groups).

This functionality is primarily of interest to the EAM project.

== Support the marking process ==

The focus here is on assisting with the marking process, typically in situations where multiple teachers and/or teaching assistants form a marking team. The idea is to allow each individual marker to have an overview of marking assigned to them and of the status this marking is in. The teacher in charge of the assignment wants to be able to see how marking is progressing and what quality the marking is (per marker and across markers).

To achieve this focus two aspects need to be introduced:
* Marker allocations;
* Marking statuses.

With marker allocations, it is recorded which marker (teacher or teaching assistant) is marking which student. Only the marker allocated can mark a student. The teacher in charge of the assignment decides the marker allocation (the teacher selects all staff involved in marking and then distributes marking manually, randomly, or even based on groups). As the marking progresses, allocations can be changed (e.g., when a marker becomes unavailable).

The following marking statuses are suggested:
* Allocated (the marker has not yet started)
* In marking (the marker has started but not yet finished)
* Marking completed (the marker has finished but might need to go back for checking/corrections)
* In review (the marking is now with the teacher in charge for quality checking)
* Ready for release (the teacher in charge is satisfied with the marking but wait before giving students access to the marking)
* Released (students have access to the marking.

The marking statuses are for use by staff. The marking statuses are not visible to students.
The default setting will be that students can see who has marked them (but this can be changed).
Marking can be taken from one status to the next on individual student basis, yet there are also bulk transitions (e.g., to release of ‘ready’ marking). Marking can be taken back into a previous status (e.g., from in review back to in marking if more work is required).

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) it is displayed who is marking which student (and only the staff assigned can edit the marking).

The functionality related to the marking process has its origins in Lightwork and is primarily of interest to the Lightwork online project.

== Control the release of marking to students ==

A problem with the current Moodle assignment module (2.3) is that students can immediately see their marking results (if the teacher does not take extra steps for hiding the assignment from student view and hiding the grade book entry). This is not good, as it does not allow the teacher to make changes (e.g., as required to deal with marker drift or for checking across multiple markers).

The suggestion is to add a release control to the assignment module. This will have three possibilities, visible in the assignment marking overview screen (mod/assign/view.php?id=3&action=grading):
* Nothing shown (no-one has yet saved any marking for a student)
* Not released (someone has saved marking, but this marking is not yet visible to the student)
* Released (marking is visible to the student)

The sole focus here is on if the student can see the marking or not. This is not about trying to manage the marking process.

This functionality is already included in supporting the marking process as proposed by the Lightwork Online project. The EAM project is interested in this functionality as well.

PC: A concern that I have with adding a release control to the assignment module is that teachers already have a form of release control (hiding the grade book entry). It might be simpler if we could use this existing mechanism instead of adding a second release control that may confuse teachers.

== How do these functionalities combine for the user and in implementation? ==

The functionalities would result in three settings to the Assignment update page (course/modedit.php?update=3&return=1).

* Control release of marking to students (Yes/No)
* Set distribution of marking (Yes/No; with Yes offering selection of groups/groupings)
* Manage marking process (Yes/No; with Yes offering allocation algorithms/manual allocation)

Controlling the release of marking to students is not in conflict with setting the distribution of marking, and is already included in managing the marking process.

Fundamentally there is no conflict between setting the distribution of marking and managing the marking process (in fact, it would be welcome as a ‘group’ will likely contain a large number of students and possibly several markers, making it very useful to be able to manage their marking). Yet, an initial implementation might keep things more simple and make these setting mutually exclusive.

The distribution of marking will build on already existing groups and groupings. No further database tables should be necessary to capture this information. Any changes to groups would be reflected during the marking process.

Capturing the marking allocations will require new database tables. If one allows building the allocation on groups, this will mean that the initial setting for the allocations is taken from the groups, but that any changes to groups will not be automatically reflected in marker allocations (but can be done manually, like any changes to allocations).

= Overview =

''(The following sections currently do not match what is proposed under Goals above.)''

== Settings added to the mod_assign settings page ==

Release grades immediately (Checkbox, default to on - this is the current behaviour)

[Help text] When enabled, grades will be visible to students as soon as they have been entered by a grader (If the grade column is visible in the gradebook). When disabled, any grades that are entered will be only visible to graders until they are approved for release.

Allocate markers to students (Select list of options, "None - all markers can mark all students", "Manually allocated - markers are manually allocated students to mark", "Groups - Markers can mark students in their own group")

When the grouping method is chosen above, an additional setting should be enabled to allow a grouping to be specified for the marker allocations.

Grouping for marker allocations (Select from the available groupings - or None for all groups)

GW - we currently create marking groups using the groups interface and then set assignment up using "Separate groups" so that markers can filter the list of assignments. One of the issues we have come up against is unenrolled (suspended) students still appearing in the groups interface. We have a proposal for better management of suspended users. We have identified 23 (possibly 25) areas where suspended users are currently an issue. Where possible, we’d like an option to toggle between hiding and showing suspended users, with the default option being hidden. We are looking to resource a change that will be all encompassing and a complete fix that can be contributed back to the Moodle community. Initially we will build for 2.1.6, but will then review for 2.3 towards the end of the year.

PC - I believe the assignment settings should be simplified or teachers will find it confusing. I would like to see the "Release grades immediately" and "Allocate markers to students" replaced with a single drop down of standard options:

* Simple marking" (the default settings - grades are released immediately)
* Advanced marking - single marker" (Grades are released when status changed to 'Released')
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released')

Note that when choosing "Advanced marking - multiple markers" the teacher would be able choose whether or not to use a Grouping for allocating
markers. If we are going to allow other combinations of "Release grades immediately" and "Allocate markers to students" then we could have an additional menu item to allow teachers to choose their own combination.

EH: Paul, with "Advanced marking - single marker", do you see that an automated marking allocation is made to one person (who has to have the capability to release grades), therefore enforcing that only this person can mark? I think this is a quite different approach to what Damyon is proposing, which basically says 'use marking statuses but do not record/control who is marking'. If I understand correctly what Paul is proposing, this means that one can use marking statuses only if one controls marker allocation. This might be a better solution, as it cuts out variety, simplifying things for the development and the user. We could add a fourth option for using marking statuses without marker allocation, this might give the following options:

* Simple marking" (the default settings - grades are released immediately, marker allocations are not recorded)
* Advanced marking - no marker allocations" ((Grades are released when status changed to 'Released'. No control who is marking)
* Advanced marking - single marker" (Grades are released when status changed to 'Released'. Only single marker specified can mark and release)
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released'. Multiple markers work together)

GW - I think my preference is for three settings:
Release grades immediately
Allocate markers to students

and the third
Grouping for marker allocations (to appear only if group allocation is selected)

I think it may end up being clearer, rather than trying to explain in help text what Simple marking and the Advanced marking options are.

PC - My concern is that being able to choose a combination of settings in this way does not make it clear to the teacher what they will end up with at the end. For instance, a teacher who wants to take advantage of the advanced marking process should not have to work out that they have to select "Release grades immediately - No" in order to do this. Also, see my comment earlier about the use of the "hiding" facility in the grade book to control the release.

== Changes to grading/grading interface ==

=== Marking release ===

If "Release grades immediately" is not enabled, an additional status should be added to the grading status column "Draft/Ready for release/Released". Use background colors as well to visually distinguish the statuses (Blue - draft, Fushia - Ready for Review, Yellow - Ready for Release, Green - Released).

Anyone with mod/assign:grade capability would be able to move the status from "Draft" to "Ready for Review" via the drop down menu on each submission, or via the batch operations form.

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" to "Ready for Release".

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" or "Ready for Release" to "Released". At this point the grade is pushed to the gradebook and made visible to the student.

=== Marker allocations ===

If "Allocate markers to students" is set to "Manually allocated", and the current user has "mod/assign:allocatemarkers" capability, the list of markers allocated to each student needs to be shown in a new column in the grading interface.

Multiple markers should be able to be allocated to a single student. (GW - future dev? Implies the need for markers to be able to lock assignments while they are marking them). If the current user has mod/assign:allocategraders permission, a red X next to each markers will allow immediately removing this marker (Ajax if possible - don't refresh the full page)
An option should be added to the menu for each submission and the batch operations menu which takes you to a separate page where you can choose from the users with mod/assign:grade permission to allocate to a student (or multiple students).

Any student with no markers allocated should have "No markers" in this column and the column background should be shown in a different colour (Red?) to indicate that no-one has been assigned to mark this submission. If the current user has "mod/assign:allocatemarkers" and "mod/assign:grade" capability, there should be an entry in the menu for this submissions for "Assign to me" (preferably AJAX - do not refresh entire page).

If the a submissions has not been allocated to the current user, the option to grade that submission is removed.

If the current user does not have "mod/assign:allocatemarkers" capability, the list of submissions will be limited to only show the submissions where the current user has been allocated as a marker.

PC - How will you be handling marker allocation in the database when "Grouping for allocating markers" isn't selected? Answer from our last meeting : marker allocation tables will be used

== Use Cases ==

=== Teacher is creating an assignment with a small number of students and they do not wish to use advanced marking ===
* Create an assignment and leave the new settings at their defaults
** Release grades immediately: "checked"
** Allocate markers to students: "None"
=== Teacher is creating an assignment with a small number of students and they wish to mark all submissions, then re-mark several submissions to check for "grading drift" before release ===
(I am defining this as the perception of quality changing over time as the marker marks each assignment in turn - can't find a good reference right now)
EH: This is called 'marker drift'. you'll find a brief description in http://etools.massey.ac.nz/documents/LitReview101006.pdf (p. 19 bottom), as well as references to further literature.
* Teacher has "mod/assign:create", "mod/assign:grade" and "mod/assign:releasegrades" capabilities
* Create an assignment and de-select Release grades immediately
** Release grades immediately: "not checked"
** Allocate markers to students: "None"
* Teacher marks each submission individually. Grades are "Draft" and not released to gradebook or students
GW - I think I know why this status is "Draft", but I think it might get confused with the submission status in the interface. I think we can come up with a better term..not that I have thought of one yet.

PC - How about "Provisional"?
* Teacher re-marks a random sample of submissions
* Teacher releases all the grades via the batch operations form

EH: The seems to be our 'In marking'

GW - what about "Ready to mark" - this might be more consistent with the other statuses "Ready for review" and "Ready for release". Is there any relationship between this status and the submission status...ie. if the submission status is "Draft" should the marking status be "Not ready to mark", which changes to "Ready to mark" when the submission status is "submitted"?

'Not marked' 'In Marking' (?) 'Ready for review' 'Ready for release' ' Released'

EH:

I think we should point out as the main reason for the stepped release of grades via the transition from 'Ready for release' to 'Released' as
* The teacher wants to release marking to all students at the same time.

Marker drift or any other checking done by one person on their own marking is important. Yes, in this use case the teacher can use the statuses proposed for that, yet the need for this type of checking applies to all markers (teachers and teaching assistants). This is why we have proposed the statuses of 'In marking' and 'Marking finished', before the marking is being passed on the the teacher for further quality review (e.g., to check across markers).

PC: I believe the following statuses would be good:

Multiple markers - "Allocated"->"In Marking"->"Marking Completed"->"In Review"->"Ready for Release"->"Released"

Single marker - "In Marking"->"In Review"->"Released"

PS: The descriptions here focus on the release of grades - this portraits a very summative viewpoint; it does not acknowledge the importance of feedback (as in the comments hopefully written to guide the students). This is why I tend to talk about marking and marking results.

=== Multiple Teachers are marking submissions for the same assignment and they want to know who is marking which assignment ===
* Assignment has been created and there are multiple markers with "mod:assign/grade and mod:assign/allocatemarker" capabilities
* Each marker selects "Assign to me" for the submissions they wish to mark.
* Each marker then provides grades and feedback which is released immediately to students
* The markers can see which students have been allocated a marker and will not end up marking the same student

=== A teacher has assistants helping them mark and wants to review all marks before they are released 1===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Manually
* The teacher allocates a set of students to each of the Teaching Assistants
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students

EH: It would be nice to have an option on the settings page where the teacher can set if the Teaching Assistants can see the marking done by other markers (not just the grade). Is the current proposal that a Teaching Assistant would see the entries for students not allocated to them (that means that can see the grade given by another Teaching Assistant)? There would have to be a 'read-only' grading option, allowing the Teaching Assistant to view marking done by others but not change it.
DW: No the current proposal is that they would not see any students not allocated to them.

* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"

EH: Here it would be nice if the Teaching Assistant could pass on a message to the Teacher together with the status change.

* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary

EH: How will the screenshot look? Will the Teacher have access to the grading interface even if the Teacher is not allocated to mark (the Teacher will have to look at the marking details, not just at the grade)?
DW: yes they would see the grading interface
If the Teacher changes feedback or grade, will this mean an automated re-allocation to the Teacher as marker?
DW: The teacher would not be able to provide grades or feedback unless they were the allocated marker
Will the student see who has marked them (there probably should be a setting allowing the Teacher to decide)?
DW: This is a big change - it would currently show them the last person to mark them.
We also need to options here to return the marking to the Teaching Assistant (ideally with comments, explaining why) and to allocate another marker (who then will continue with the marking already started - maybe this is already covered).
DW: This is quite an advanced workflow - we need to make sure we are not adding too much complexity (it is not prevented by this interface - it just does not include any statuses for it - ie "Needs allocation to another marker for a second round of marking")

EH: This description skips the step of the Teacher taking assignments into 'Ready for release' after successful quality checking.

* The teacher changes the status of the grades to 'Released' when they are satisfied with the grading quality.

EH: I think this should read: The Teacher changes the status from 'Ready for review' to 'Ready for Release' when they are satisfied with the grading quality.

Then the next step is: The Teacher changes the status from 'Ready for Release' to 'Released' when they want to release marking to students.

DW: I have added the "ready for release" status - but this will require good help explaining the difference between the statuses to teachers. A visual flow chart of the statuses would help.

GW - I think that the Teacher should have the option to skip the "Ready for Release" status and take the assignment from "Ready for review" straight to "Released". If statuses can be skipped..ie. as long as we don't force users through every status, then i don't think it will be a problem to have the five statuses as proposed above:
'Not marked'
'In marking/Being marked'
'Ready for review'
'Ready for release'
'Released'

PC - I don't agree with skipping the "Ready for Release" status since it is an important part of the review process. However, it is possible to make the switching between statuses fast and efficient by having bulk options such as "Release all" that automatically selects marking with one status and moves it to the next.

Where it would be appropriate to reduce the number of statuses (but possibly not in our first Moodle 2.4 release) is when there is only a
single marker. So, I think we need the following:

Multiple markers - "Allocated"->"In Marking"->"Marking Completed"->"In Review"->"Ready for Release"->"Released"

Single marker - "In Marking"->"In Review"->"Released"

=== A teacher has assistants helping them mark and wants to review all marks before they are released 2 ===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* There are groups containing teaching assistants and sets of students contained in a grouping.
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Groups
** Grouping for marker allocation : "Name of Grouping"
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students
* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"
* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary
* The teacher changes the status of the grades to "Released" when they are satisfied with the grading quality.

If there are multiple markers added to a group then all markers will be able to mark assignments in that group.

GW - If there are no markers in a group, then there is the potential that student assignments would get missed....there is no visual queue that students are unallocated. In addition - our SIS-created groups systematically check for the addition of members who are not in the group in the SIS. Any staff therefore who are added to the groups in Moodle will be removed from the group on the next update...unless we changed our integration script to retain users in SIS-created groups as long as they were not students??

=== Multiple markers which to separately mark the same set of students and then a moderator either takes an average or chooses one of the marks to be released ===
Not supported by this proposal

=== Multiple markers mark one student in sequence ===

EH: This is about two or more markers marking student work, e.g., marker 1 marks parts 1 and 2, marker 2 marks parts 3 and 4 of an assignment. This could be done with a different form of allocation: marker1 picks a student and then marks their part; the interface shows that marker 1 has done their part, marker2 can now allocate themselves and continue the marking. Once all markers involved (as setup initially, here markers 1 and 2 need to mark) have done their parts the status changes to 'ready for review'.

This is not part of the current proposal.

=== Separate release of grades and feedback ===

EH: It would be nice to be able to release feedback (for formative purposes) first and marks/grades later (with a time delay or triggered by the Teacher, or, more sophisticated, dependent on the student doing something).

This is not part of the current proposal.

DW: I think it should be - but I don't what to make it complicated. I think that either the feedback is visible to the student during the entire marking process and they get the grade at the end - or they see nothing and they get the grades + feedback at the end (we could add those 2 options to the settings page). Note: The submission comments are visible to staff and students for the entire duration and provide 2 way comments between students and staff.

GW: The potential issue with this is that feedback might change during the marking process. Is a student-triggered process (ie. viewing the feedback) to release grades "complicated"?

EH: I am with Grette there - feedback should only be visible to students when marking is considered as finished (otherwise we would be back to the current deficiencies in Moodle)

== User Interface ==
=== Assignment settings screen ===
[[File:assign-advgrading-settings.png| Assignment settings screen]]
=== Submission menu in grading table ===
[[File:assign-advgrading-gradingmenu.png| Submission grading menu]]
=== Batch operations menu ===
[[File:assign-advgrading-gradingbatchmenu.png| Grading batch operations menu]]

GW: Will there be an option for the Teacher with "mod/assign:releasegrades" capability to take all assignments that are in "Ready for Review" to either "Ready for Release" or "Release" without having to individually select them?

GW - will there be a batch operation for "Assign to me?"

=== Marker allocation ===
Notes: The current user is "Grader Gary" so the grade option has disappeared for all submissions that this user is not assigned to mark. The current user also has permission to assign graders so they see additional options in the submission menu.

[[File:assign-advgrading-marker-allocation.png| Marker allocation]]

== Database Changes ==

Assignment Advanced Marking

2012-08-21T23:16:02Z

Pcharsle: /* Marker allocations */

This is a proposal for additional marking features in the Assignment module.

References: https://docs.moodle.org/dev/Lightwork#User_Interface_-_Marker_allocation_and_management

Tracker Issue: http://tracker.moodle.org/browse/MDL-34902

= Goals, rationale and fundamentals =

The main goals of this change are to:

* Control the distribution
* Support the marking process
* Control the release of marking to students

== Control the distribution ==

This is relevant in the context of large courses where groups/groupings are used to divide the students into groups and to associate dedicated staff with these groups. In terms of assignment marking the idea is that staff associated with groups are responsible for the marking of students in their groups and fulfil such marking independently from the marking of other groups.

An example would be: A course with 300 students is divided into 3 groups of students (based on different delivery locations or modes). Two or more staff are associated with each group (one teacher and several teaching assistants). The same assignment is setup for the whole course. The staff associated with each group of students are responsible for marking their groups.

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) staff associated with a group should only see the students belonging to this group. It is not recorded which staff member is marking which students.
The staff member in charge of the overall course might have a setting, which allows to see assignment marking for all students (of all groups).

This functionality is primarily of interest to the EAM project.

== Support the marking process ==

The focus here is on assisting with the marking process, typically in situations where multiple teachers and/or teaching assistants form a marking team. The idea is to allow each individual marker to have an overview of marking assigned to them and of the status this marking is in. The teacher in charge of the assignment wants to be able to see how marking is progressing and what quality the marking is (per marker and across markers).

To achieve this focus two aspects need to be introduced:
* Marker allocations;
* Marking statuses.

With marker allocations, it is recorded which marker (teacher or teaching assistant) is marking which student. Only the marker allocated can mark a student. The teacher in charge of the assignment decides the marker allocation (the teacher selects all staff involved in marking and then distributes marking manually, randomly, or even based on groups). As the marking progresses, allocations can be changed (e.g., when a marker becomes unavailable).

The following marking statuses are suggested:
* Allocated (the marker has not yet started)
* In marking (the marker has started but not yet finished)
* Marking completed (the marker has finished but might need to go back for checking/corrections)
* In review (the marking is now with the teacher in charge for quality checking)
* Ready for release (the teacher in charge is satisfied with the marking but wait before giving students access to the marking)
* Released (students have access to the marking.

The marking statuses are for use by staff. The marking statuses are not visible to students.
The default setting will be that students can see who has marked them (but this can be changed).
Marking can be taken from one status to the next on individual student basis, yet there are also bulk transitions (e.g., to release of ‘ready’ marking). Marking can be taken back into a previous status (e.g., from in review back to in marking if more work is required).

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) it is displayed who is marking which student (and only the staff assigned can edit the marking).

The functionality related to the marking process has its origins in Lightwork and is primarily of interest to the Lightwork online project.

== Control the release of marking to students ==

A problem with the current Moodle assignment module (2.3) is that students can immediately see their marking results (if the teacher does not take extra steps for hiding the assignment from student view and hiding the grade book entry). This is not good, as it does not allow the teacher to make changes (e.g., as required to deal with marker drift or for checking across multiple markers).

The suggestion is to add a release control to the assignment module. This will have three possibilities, visible in the assignment marking overview screen (mod/assign/view.php?id=3&action=grading):
* Nothing shown (no-one has yet saved any marking for a student)
* Not released (someone has saved marking, but this marking is not yet visible to the student)
* Released (marking is visible to the student)

The sole focus here is on if the student can see the marking or not. This is not about trying to manage the marking process.

This functionality is already included in supporting the marking process as proposed by the Lightwork Online project. The EAM project is interested in this functionality as well.

PC: A concern that I have with adding a release control to the assignment module is that teachers already have a form of release control (hiding the grade book entry). It might be simpler if we could use this existing mechanism instead of adding a second release control that may confuse teachers.

== How do these functionalities combine for the user and in implementation? ==

The functionalities would result in three settings to the Assignment update page (course/modedit.php?update=3&return=1).

* Control release of marking to students (Yes/No)
* Set distribution of marking (Yes/No; with Yes offering selection of groups/groupings)
* Manage marking process (Yes/No; with Yes offering allocation algorithms/manual allocation)

Controlling the release of marking to students is not in conflict with setting the distribution of marking, and is already included in managing the marking process.

Fundamentally there is no conflict between setting the distribution of marking and managing the marking process (in fact, it would be welcome as a ‘group’ will likely contain a large number of students and possibly several markers, making it very useful to be able to manage their marking). Yet, an initial implementation might keep things more simple and make these setting mutually exclusive.

The distribution of marking will build on already existing groups and groupings. No further database tables should be necessary to capture this information. Any changes to groups would be reflected during the marking process.

Capturing the marking allocations will require new database tables. If one allows building the allocation on groups, this will mean that the initial setting for the allocations is taken from the groups, but that any changes to groups will not be automatically reflected in marker allocations (but can be done manually, like any changes to allocations).

= Overview =

''(The following sections currently do not match what is proposed under Goals above.)''

== Settings added to the mod_assign settings page ==

Release grades immediately (Checkbox, default to on - this is the current behaviour)

[Help text] When enabled, grades will be visible to students as soon as they have been entered by a grader (If the grade column is visible in the gradebook). When disabled, any grades that are entered will be only visible to graders until they are approved for release.

Allocate markers to students (Select list of options, "None - all markers can mark all students", "Manually allocated - markers are manually allocated students to mark", "Groups - Markers can mark students in their own group")

When the grouping method is chosen above, an additional setting should be enabled to allow a grouping to be specified for the marker allocations.

Grouping for marker allocations (Select from the available groupings - or None for all groups)

GW - we currently create marking groups using the groups interface and then set assignment up using "Separate groups" so that markers can filter the list of assignments. One of the issues we have come up against is unenrolled (suspended) students still appearing in the groups interface. We have a proposal for better management of suspended users. We have identified 23 (possibly 25) areas where suspended users are currently an issue. Where possible, we’d like an option to toggle between hiding and showing suspended users, with the default option being hidden. We are looking to resource a change that will be all encompassing and a complete fix that can be contributed back to the Moodle community. Initially we will build for 2.1.6, but will then review for 2.3 towards the end of the year.

PC - I believe the assignment settings should be simplified or teachers will find it confusing. I would like to see the "Release grades immediately" and "Allocate markers to students" replaced with a single drop down of standard options:

* Simple marking" (the default settings - grades are released immediately)
* Advanced marking - single marker" (Grades are released when status changed to 'Released')
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released')

Note that when choosing "Advanced marking - multiple markers" the teacher would be able choose whether or not to use a Grouping for allocating
markers. If we are going to allow other combinations of "Release grades immediately" and "Allocate markers to students" then we could have an additional menu item to allow teachers to choose their own combination.

EH: Paul, with "Advanced marking - single marker", do you see that an automated marking allocation is made to one person (who has to have the capability to release grades), therefore enforcing that only this person can mark? I think this is a quite different approach to what Damyon is proposing, which basically says 'use marking statuses but do not record/control who is marking'. If I understand correctly what Paul is proposing, this means that one can use marking statuses only if one controls marker allocation. This might be a better solution, as it cuts out variety, simplifying things for the development and the user. We could add a fourth option for using marking statuses without marker allocation, this might give the following options:

* Simple marking" (the default settings - grades are released immediately, marker allocations are not recorded)
* Advanced marking - no marker allocations" ((Grades are released when status changed to 'Released'. No control who is marking)
* Advanced marking - single marker" (Grades are released when status changed to 'Released'. Only single marker specified can mark and release)
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released'. Multiple markers work together)

GW - I think my preference is for three settings:
Release grades immediately
Allocate markers to students

and the third
Grouping for marker allocations (to appear only if group allocation is selected)

I think it may end up being clearer, rather than trying to explain in help text what Simple marking and the Advanced marking options are.

PC - My concern is that being able to choose a combination of settings in this way does not make it clear to the teacher what they will end up with at the end. For instance, a teacher who wants to take advantage of the advanced marking process should not have to work out that they have to select "Release grades immediately - No" in order to do this. Also, see my comment earlier about the use of the "hiding" facility in the grade book to control the release.

== Changes to grading/grading interface ==

=== Marking release ===

If "Release grades immediately" is not enabled, an additional status should be added to the grading status column "Draft/Ready for release/Released". Use background colors as well to visually distinguish the statuses (Blue - draft, Fushia - Ready for Review, Yellow - Ready for Release, Green - Released).

Anyone with mod/assign:grade capability would be able to move the status from "Draft" to "Ready for Review" via the drop down menu on each submission, or via the batch operations form.

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" to "Ready for Release".

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" or "Ready for Release" to "Released". At this point the grade is pushed to the gradebook and made visible to the student.

=== Marker allocations ===

If "Allocate markers to students" is set to "Manually allocated", and the current user has "mod/assign:allocatemarkers" capability, the list of markers allocated to each student needs to be shown in a new column in the grading interface.

Multiple markers should be able to be allocated to a single student. (GW - future dev? Implies the need for markers to be able to lock assignments while they are marking them). If the current user has mod/assign:allocategraders permission, a red X next to each markers will allow immediately removing this marker (Ajax if possible - don't refresh the full page)
An option should be added to the menu for each submission and the batch operations menu which takes you to a separate page where you can choose from the users with mod/assign:grade permission to allocate to a student (or multiple students).

Any student with no markers allocated should have "No markers" in this column and the column background should be shown in a different colour (Red?) to indicate that no-one has been assigned to mark this submission. If the current user has "mod/assign:allocatemarkers" and "mod/assign:grade" capability, there should be an entry in the menu for this submissions for "Assign to me" (preferably AJAX - do not refresh entire page).

If the a submissions has not been allocated to the current user, the option to grade that submission is removed.

If the current user does not have "mod/assign:allocatemarkers" capability, the list of submissions will be limited to only show the submissions where the current user has been allocated as a marker.

PC - How will you be handling marker allocation in the database when "Grouping for allocating markers" isn't selected? Answer from our last meeting : marker allocation tables will be used

== Use Cases ==

=== Teacher is creating an assignment with a small number of students and they do not wish to use advanced marking ===
* Create an assignment and leave the new settings at their defaults
** Release grades immediately: "checked"
** Allocate markers to students: "None"
=== Teacher is creating an assignment with a small number of students and they wish to mark all submissions, then re-mark several submissions to check for "grading drift" before release ===
(I am defining this as the perception of quality changing over time as the marker marks each assignment in turn - can't find a good reference right now)
EH: This is called 'marker drift'. you'll find a brief description in http://etools.massey.ac.nz/documents/LitReview101006.pdf (p. 19 bottom), as well as references to further literature.
* Teacher has "mod/assign:create", "mod/assign:grade" and "mod/assign:releasegrades" capabilities
* Create an assignment and de-select Release grades immediately
** Release grades immediately: "not checked"
** Allocate markers to students: "None"
* Teacher marks each submission individually. Grades are "Draft" and not released to gradebook or students
GW - I think I know why this status is "Draft", but I think it might get confused with the submission status in the interface. I think we can come up with a better term..not that I have thought of one yet.

PC - How about "Provisional"?
* Teacher re-marks a random sample of submissions
* Teacher releases all the grades via the batch operations form

EH: The seems to be our 'In marking'

GW - what about "Ready to mark" - this might be more consistent with the other statuses "Ready for review" and "Ready for release". Is there any relationship between this status and the submission status...ie. if the submission status is "Draft" should the marking status be "Not ready to mark", which changes to "Ready to mark" when the submission status is "submitted"?

'Not marked' 'In Marking' (?) 'Ready for review' 'Ready for release' ' Released'

EH:

I think we should point out as the main reason for the stepped release of grades via the transition from 'Ready for release' to 'Released' as
* The teacher wants to release marking to all students at the same time.

Marker drift or any other checking done by one person on their own marking is important. Yes, in this use case the teacher can use the statuses proposed for that, yet the need for this type of checking applies to all markers (teachers and teaching assistants). This is why we have proposed the statuses of 'In marking' and 'Marking finished', before the marking is being passed on the the teacher for further quality review (e.g., to check across markers).

PS: The descriptions here focus on the release of grades - this portraits a very summative viewpoint; it does not acknowledge the importance of feedback (as in the comments hopefully written to guide the students). This is why I tend to talk about marking and marking results.

=== Multiple Teachers are marking submissions for the same assignment and they want to know who is marking which assignment ===
* Assignment has been created and there are multiple markers with "mod:assign/grade and mod:assign/allocatemarker" capabilities
* Each marker selects "Assign to me" for the submissions they wish to mark.
* Each marker then provides grades and feedback which is released immediately to students
* The markers can see which students have been allocated a marker and will not end up marking the same student

=== A teacher has assistants helping them mark and wants to review all marks before they are released 1===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Manually
* The teacher allocates a set of students to each of the Teaching Assistants
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students

EH: It would be nice to have an option on the settings page where the teacher can set if the Teaching Assistants can see the marking done by other markers (not just the grade). Is the current proposal that a Teaching Assistant would see the entries for students not allocated to them (that means that can see the grade given by another Teaching Assistant)? There would have to be a 'read-only' grading option, allowing the Teaching Assistant to view marking done by others but not change it.
DW: No the current proposal is that they would not see any students not allocated to them.

* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"

EH: Here it would be nice if the Teaching Assistant could pass on a message to the Teacher together with the status change.

* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary

EH: How will the screenshot look? Will the Teacher have access to the grading interface even if the Teacher is not allocated to mark (the Teacher will have to look at the marking details, not just at the grade)?
DW: yes they would see the grading interface
If the Teacher changes feedback or grade, will this mean an automated re-allocation to the Teacher as marker?
DW: The teacher would not be able to provide grades or feedback unless they were the allocated marker
Will the student see who has marked them (there probably should be a setting allowing the Teacher to decide)?
DW: This is a big change - it would currently show them the last person to mark them.
We also need to options here to return the marking to the Teaching Assistant (ideally with comments, explaining why) and to allocate another marker (who then will continue with the marking already started - maybe this is already covered).
DW: This is quite an advanced workflow - we need to make sure we are not adding too much complexity (it is not prevented by this interface - it just does not include any statuses for it - ie "Needs allocation to another marker for a second round of marking")

EH: This description skips the step of the Teacher taking assignments into 'Ready for release' after successful quality checking.

* The teacher changes the status of the grades to 'Released' when they are satisfied with the grading quality.

EH: I think this should read: The Teacher changes the status from 'Ready for review' to 'Ready for Release' when they are satisfied with the grading quality.

Then the next step is: The Teacher changes the status from 'Ready for Release' to 'Released' when they want to release marking to students.

DW: I have added the "ready for release" status - but this will require good help explaining the difference between the statuses to teachers. A visual flow chart of the statuses would help.

GW - I think that the Teacher should have the option to skip the "Ready for Release" status and take the assignment from "Ready for review" straight to "Released". If statuses can be skipped..ie. as long as we don't force users through every status, then i don't think it will be a problem to have the five statuses as proposed above:
'Not marked'
'In marking/Being marked'
'Ready for review'
'Ready for release'
'Released'

PC - I don't agree with skipping the "Ready for Release" status since it is an important part of the review process. However, it is possible to make the switching between statuses fast and efficient by having bulk options such as "Release all" that automatically selects marking with one status and moves it to the next.

Where it would be appropriate to reduce the number of statuses (but possibly not in our first Moodle 2.4 release) is when there is only a
single marker. So, I think we need the following:

Multiple markers - "Allocated"->"In Marking"->"Marking Completed"->"In Review"->"Ready for Release"->"Released"

Single marker - "In Marking"->"In Review"->"Released"

=== A teacher has assistants helping them mark and wants to review all marks before they are released 2 ===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* There are groups containing teaching assistants and sets of students contained in a grouping.
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Groups
** Grouping for marker allocation : "Name of Grouping"
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students
* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"
* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary
* The teacher changes the status of the grades to "Released" when they are satisfied with the grading quality.

If there are multiple markers added to a group then all markers will be able to mark assignments in that group.

GW - If there are no markers in a group, then there is the potential that student assignments would get missed....there is no visual queue that students are unallocated. In addition - our SIS-created groups systematically check for the addition of members who are not in the group in the SIS. Any staff therefore who are added to the groups in Moodle will be removed from the group on the next update...unless we changed our integration script to retain users in SIS-created groups as long as they were not students??

=== Multiple markers which to separately mark the same set of students and then a moderator either takes an average or chooses one of the marks to be released ===
Not supported by this proposal

=== Multiple markers mark one student in sequence ===

EH: This is about two or more markers marking student work, e.g., marker 1 marks parts 1 and 2, marker 2 marks parts 3 and 4 of an assignment. This could be done with a different form of allocation: marker1 picks a student and then marks their part; the interface shows that marker 1 has done their part, marker2 can now allocate themselves and continue the marking. Once all markers involved (as setup initially, here markers 1 and 2 need to mark) have done their parts the status changes to 'ready for review'.

This is not part of the current proposal.

=== Separate release of grades and feedback ===

EH: It would be nice to be able to release feedback (for formative purposes) first and marks/grades later (with a time delay or triggered by the Teacher, or, more sophisticated, dependent on the student doing something).

This is not part of the current proposal.

DW: I think it should be - but I don't what to make it complicated. I think that either the feedback is visible to the student during the entire marking process and they get the grade at the end - or they see nothing and they get the grades + feedback at the end (we could add those 2 options to the settings page). Note: The submission comments are visible to staff and students for the entire duration and provide 2 way comments between students and staff.

GW: The potential issue with this is that feedback might change during the marking process. Is a student-triggered process (ie. viewing the feedback) to release grades "complicated"?

EH: I am with Grette there - feedback should only be visible to students when marking is considered as finished (otherwise we would be back to the current deficiencies in Moodle)

== User Interface ==
=== Assignment settings screen ===
[[File:assign-advgrading-settings.png| Assignment settings screen]]
=== Submission menu in grading table ===
[[File:assign-advgrading-gradingmenu.png| Submission grading menu]]
=== Batch operations menu ===
[[File:assign-advgrading-gradingbatchmenu.png| Grading batch operations menu]]

GW: Will there be an option for the Teacher with "mod/assign:releasegrades" capability to take all assignments that are in "Ready for Review" to either "Ready for Release" or "Release" without having to individually select them?

GW - will there be a batch operation for "Assign to me?"

=== Marker allocation ===
Notes: The current user is "Grader Gary" so the grade option has disappeared for all submissions that this user is not assigned to mark. The current user also has permission to assign graders so they see additional options in the submission menu.

[[File:assign-advgrading-marker-allocation.png| Marker allocation]]

== Database Changes ==

Assignment Advanced Marking

2012-08-21T23:13:49Z

Pcharsle: /* A teacher has assistants helping them mark and wants to review all marks before they are released 1 */

This is a proposal for additional marking features in the Assignment module.

References: https://docs.moodle.org/dev/Lightwork#User_Interface_-_Marker_allocation_and_management

Tracker Issue: http://tracker.moodle.org/browse/MDL-34902

= Goals, rationale and fundamentals =

The main goals of this change are to:

* Control the distribution
* Support the marking process
* Control the release of marking to students

== Control the distribution ==

This is relevant in the context of large courses where groups/groupings are used to divide the students into groups and to associate dedicated staff with these groups. In terms of assignment marking the idea is that staff associated with groups are responsible for the marking of students in their groups and fulfil such marking independently from the marking of other groups.

An example would be: A course with 300 students is divided into 3 groups of students (based on different delivery locations or modes). Two or more staff are associated with each group (one teacher and several teaching assistants). The same assignment is setup for the whole course. The staff associated with each group of students are responsible for marking their groups.

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) staff associated with a group should only see the students belonging to this group. It is not recorded which staff member is marking which students.
The staff member in charge of the overall course might have a setting, which allows to see assignment marking for all students (of all groups).

This functionality is primarily of interest to the EAM project.

== Support the marking process ==

The focus here is on assisting with the marking process, typically in situations where multiple teachers and/or teaching assistants form a marking team. The idea is to allow each individual marker to have an overview of marking assigned to them and of the status this marking is in. The teacher in charge of the assignment wants to be able to see how marking is progressing and what quality the marking is (per marker and across markers).

To achieve this focus two aspects need to be introduced:
* Marker allocations;
* Marking statuses.

With marker allocations, it is recorded which marker (teacher or teaching assistant) is marking which student. Only the marker allocated can mark a student. The teacher in charge of the assignment decides the marker allocation (the teacher selects all staff involved in marking and then distributes marking manually, randomly, or even based on groups). As the marking progresses, allocations can be changed (e.g., when a marker becomes unavailable).

The following marking statuses are suggested:
* Allocated (the marker has not yet started)
* In marking (the marker has started but not yet finished)
* Marking completed (the marker has finished but might need to go back for checking/corrections)
* In review (the marking is now with the teacher in charge for quality checking)
* Ready for release (the teacher in charge is satisfied with the marking but wait before giving students access to the marking)
* Released (students have access to the marking.

The marking statuses are for use by staff. The marking statuses are not visible to students.
The default setting will be that students can see who has marked them (but this can be changed).
Marking can be taken from one status to the next on individual student basis, yet there are also bulk transitions (e.g., to release of ‘ready’ marking). Marking can be taken back into a previous status (e.g., from in review back to in marking if more work is required).

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) it is displayed who is marking which student (and only the staff assigned can edit the marking).

The functionality related to the marking process has its origins in Lightwork and is primarily of interest to the Lightwork online project.

== Control the release of marking to students ==

A problem with the current Moodle assignment module (2.3) is that students can immediately see their marking results (if the teacher does not take extra steps for hiding the assignment from student view and hiding the grade book entry). This is not good, as it does not allow the teacher to make changes (e.g., as required to deal with marker drift or for checking across multiple markers).

The suggestion is to add a release control to the assignment module. This will have three possibilities, visible in the assignment marking overview screen (mod/assign/view.php?id=3&action=grading):
* Nothing shown (no-one has yet saved any marking for a student)
* Not released (someone has saved marking, but this marking is not yet visible to the student)
* Released (marking is visible to the student)

The sole focus here is on if the student can see the marking or not. This is not about trying to manage the marking process.

This functionality is already included in supporting the marking process as proposed by the Lightwork Online project. The EAM project is interested in this functionality as well.

PC: A concern that I have with adding a release control to the assignment module is that teachers already have a form of release control (hiding the grade book entry). It might be simpler if we could use this existing mechanism instead of adding a second release control that may confuse teachers.

== How do these functionalities combine for the user and in implementation? ==

The functionalities would result in three settings to the Assignment update page (course/modedit.php?update=3&return=1).

* Control release of marking to students (Yes/No)
* Set distribution of marking (Yes/No; with Yes offering selection of groups/groupings)
* Manage marking process (Yes/No; with Yes offering allocation algorithms/manual allocation)

Controlling the release of marking to students is not in conflict with setting the distribution of marking, and is already included in managing the marking process.

Fundamentally there is no conflict between setting the distribution of marking and managing the marking process (in fact, it would be welcome as a ‘group’ will likely contain a large number of students and possibly several markers, making it very useful to be able to manage their marking). Yet, an initial implementation might keep things more simple and make these setting mutually exclusive.

The distribution of marking will build on already existing groups and groupings. No further database tables should be necessary to capture this information. Any changes to groups would be reflected during the marking process.

Capturing the marking allocations will require new database tables. If one allows building the allocation on groups, this will mean that the initial setting for the allocations is taken from the groups, but that any changes to groups will not be automatically reflected in marker allocations (but can be done manually, like any changes to allocations).

= Overview =

''(The following sections currently do not match what is proposed under Goals above.)''

== Settings added to the mod_assign settings page ==

Release grades immediately (Checkbox, default to on - this is the current behaviour)

[Help text] When enabled, grades will be visible to students as soon as they have been entered by a grader (If the grade column is visible in the gradebook). When disabled, any grades that are entered will be only visible to graders until they are approved for release.

Allocate markers to students (Select list of options, "None - all markers can mark all students", "Manually allocated - markers are manually allocated students to mark", "Groups - Markers can mark students in their own group")

When the grouping method is chosen above, an additional setting should be enabled to allow a grouping to be specified for the marker allocations.

Grouping for marker allocations (Select from the available groupings - or None for all groups)

GW - we currently create marking groups using the groups interface and then set assignment up using "Separate groups" so that markers can filter the list of assignments. One of the issues we have come up against is unenrolled (suspended) students still appearing in the groups interface. We have a proposal for better management of suspended users. We have identified 23 (possibly 25) areas where suspended users are currently an issue. Where possible, we’d like an option to toggle between hiding and showing suspended users, with the default option being hidden. We are looking to resource a change that will be all encompassing and a complete fix that can be contributed back to the Moodle community. Initially we will build for 2.1.6, but will then review for 2.3 towards the end of the year.

PC - I believe the assignment settings should be simplified or teachers will find it confusing. I would like to see the "Release grades immediately" and "Allocate markers to students" replaced with a single drop down of standard options:

* Simple marking" (the default settings - grades are released immediately)
* Advanced marking - single marker" (Grades are released when status changed to 'Released')
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released')

Note that when choosing "Advanced marking - multiple markers" the teacher would be able choose whether or not to use a Grouping for allocating
markers. If we are going to allow other combinations of "Release grades immediately" and "Allocate markers to students" then we could have an additional menu item to allow teachers to choose their own combination.

EH: Paul, with "Advanced marking - single marker", do you see that an automated marking allocation is made to one person (who has to have the capability to release grades), therefore enforcing that only this person can mark? I think this is a quite different approach to what Damyon is proposing, which basically says 'use marking statuses but do not record/control who is marking'. If I understand correctly what Paul is proposing, this means that one can use marking statuses only if one controls marker allocation. This might be a better solution, as it cuts out variety, simplifying things for the development and the user. We could add a fourth option for using marking statuses without marker allocation, this might give the following options:

* Simple marking" (the default settings - grades are released immediately, marker allocations are not recorded)
* Advanced marking - no marker allocations" ((Grades are released when status changed to 'Released'. No control who is marking)
* Advanced marking - single marker" (Grades are released when status changed to 'Released'. Only single marker specified can mark and release)
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released'. Multiple markers work together)

GW - I think my preference is for three settings:
Release grades immediately
Allocate markers to students

and the third
Grouping for marker allocations (to appear only if group allocation is selected)

I think it may end up being clearer, rather than trying to explain in help text what Simple marking and the Advanced marking options are.

PC - My concern is that being able to choose a combination of settings in this way does not make it clear to the teacher what they will end up with at the end. For instance, a teacher who wants to take advantage of the advanced marking process should not have to work out that they have to select "Release grades immediately - No" in order to do this. Also, see my comment earlier about the use of the "hiding" facility in the grade book to control the release.

== Changes to grading/grading interface ==

=== Marking release ===

If "Release grades immediately" is not enabled, an additional status should be added to the grading status column "Draft/Ready for release/Released". Use background colors as well to visually distinguish the statuses (Blue - draft, Fushia - Ready for Review, Yellow - Ready for Release, Green - Released).

Anyone with mod/assign:grade capability would be able to move the status from "Draft" to "Ready for Review" via the drop down menu on each submission, or via the batch operations form.

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" to "Ready for Release".

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" or "Ready for Release" to "Released". At this point the grade is pushed to the gradebook and made visible to the student.

=== Marker allocations ===

If "Allocate markers to students" is set to "Manually allocated", and the current user has "mod/assign:allocatemarkers" capability, the list of markers allocated to each student needs to be shown in a new column in the grading interface.

Multiple markers should be able to be allocated to a single student. (GW - future dev? Implies the need for markers to be able to lock assignments while they are marking them). If the current user has mod/assign:allocategraders permission, a red X next to each markers will allow immediately removing this marker (Ajax if possible - don't refresh the full page)
An option should be added to the menu for each submission and the batch operations menu which takes you to a separate page where you can choose from the users with mod/assign:grade permission to allocate to a student (or multiple students).

Any student with no markers allocated should have "No markers" in this column and the column background should be shown in a different colour (Red?) to indicate that no-one has been assigned to mark this submission. If the current user has "mod/assign:allocatemarkers" and "mod/assign:grade" capability, there should be an entry in the menu for this submissions for "Assign to me" (preferably AJAX - do not refresh entire page).

If the a submissions has not been allocated to the current user, the option to grade that submission is removed.

If the current user does not have "mod/assign:allocatemarkers" capability, the list of submissions will be limited to only show the submissions where the current user has been allocated as a marker.

PC - How will you be handling marker allocation in the database when "Grouping for allocating markers" isn't selected? Will you be creating new groups to hold the allocations?

== Use Cases ==

=== Teacher is creating an assignment with a small number of students and they do not wish to use advanced marking ===
* Create an assignment and leave the new settings at their defaults
** Release grades immediately: "checked"
** Allocate markers to students: "None"
=== Teacher is creating an assignment with a small number of students and they wish to mark all submissions, then re-mark several submissions to check for "grading drift" before release ===
(I am defining this as the perception of quality changing over time as the marker marks each assignment in turn - can't find a good reference right now)
EH: This is called 'marker drift'. you'll find a brief description in http://etools.massey.ac.nz/documents/LitReview101006.pdf (p. 19 bottom), as well as references to further literature.
* Teacher has "mod/assign:create", "mod/assign:grade" and "mod/assign:releasegrades" capabilities
* Create an assignment and de-select Release grades immediately
** Release grades immediately: "not checked"
** Allocate markers to students: "None"
* Teacher marks each submission individually. Grades are "Draft" and not released to gradebook or students
GW - I think I know why this status is "Draft", but I think it might get confused with the submission status in the interface. I think we can come up with a better term..not that I have thought of one yet.

PC - How about "Provisional"?
* Teacher re-marks a random sample of submissions
* Teacher releases all the grades via the batch operations form

EH: The seems to be our 'In marking'

GW - what about "Ready to mark" - this might be more consistent with the other statuses "Ready for review" and "Ready for release". Is there any relationship between this status and the submission status...ie. if the submission status is "Draft" should the marking status be "Not ready to mark", which changes to "Ready to mark" when the submission status is "submitted"?

'Not marked' 'In Marking' (?) 'Ready for review' 'Ready for release' ' Released'

EH:

I think we should point out as the main reason for the stepped release of grades via the transition from 'Ready for release' to 'Released' as
* The teacher wants to release marking to all students at the same time.

Marker drift or any other checking done by one person on their own marking is important. Yes, in this use case the teacher can use the statuses proposed for that, yet the need for this type of checking applies to all markers (teachers and teaching assistants). This is why we have proposed the statuses of 'In marking' and 'Marking finished', before the marking is being passed on the the teacher for further quality review (e.g., to check across markers).

PS: The descriptions here focus on the release of grades - this portraits a very summative viewpoint; it does not acknowledge the importance of feedback (as in the comments hopefully written to guide the students). This is why I tend to talk about marking and marking results.

=== Multiple Teachers are marking submissions for the same assignment and they want to know who is marking which assignment ===
* Assignment has been created and there are multiple markers with "mod:assign/grade and mod:assign/allocatemarker" capabilities
* Each marker selects "Assign to me" for the submissions they wish to mark.
* Each marker then provides grades and feedback which is released immediately to students
* The markers can see which students have been allocated a marker and will not end up marking the same student

=== A teacher has assistants helping them mark and wants to review all marks before they are released 1===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Manually
* The teacher allocates a set of students to each of the Teaching Assistants
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students

EH: It would be nice to have an option on the settings page where the teacher can set if the Teaching Assistants can see the marking done by other markers (not just the grade). Is the current proposal that a Teaching Assistant would see the entries for students not allocated to them (that means that can see the grade given by another Teaching Assistant)? There would have to be a 'read-only' grading option, allowing the Teaching Assistant to view marking done by others but not change it.
DW: No the current proposal is that they would not see any students not allocated to them.

* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"

EH: Here it would be nice if the Teaching Assistant could pass on a message to the Teacher together with the status change.

* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary

EH: How will the screenshot look? Will the Teacher have access to the grading interface even if the Teacher is not allocated to mark (the Teacher will have to look at the marking details, not just at the grade)?
DW: yes they would see the grading interface
If the Teacher changes feedback or grade, will this mean an automated re-allocation to the Teacher as marker?
DW: The teacher would not be able to provide grades or feedback unless they were the allocated marker
Will the student see who has marked them (there probably should be a setting allowing the Teacher to decide)?
DW: This is a big change - it would currently show them the last person to mark them.
We also need to options here to return the marking to the Teaching Assistant (ideally with comments, explaining why) and to allocate another marker (who then will continue with the marking already started - maybe this is already covered).
DW: This is quite an advanced workflow - we need to make sure we are not adding too much complexity (it is not prevented by this interface - it just does not include any statuses for it - ie "Needs allocation to another marker for a second round of marking")

EH: This description skips the step of the Teacher taking assignments into 'Ready for release' after successful quality checking.

* The teacher changes the status of the grades to 'Released' when they are satisfied with the grading quality.

EH: I think this should read: The Teacher changes the status from 'Ready for review' to 'Ready for Release' when they are satisfied with the grading quality.

Then the next step is: The Teacher changes the status from 'Ready for Release' to 'Released' when they want to release marking to students.

DW: I have added the "ready for release" status - but this will require good help explaining the difference between the statuses to teachers. A visual flow chart of the statuses would help.

GW - I think that the Teacher should have the option to skip the "Ready for Release" status and take the assignment from "Ready for review" straight to "Released". If statuses can be skipped..ie. as long as we don't force users through every status, then i don't think it will be a problem to have the five statuses as proposed above:
'Not marked'
'In marking/Being marked'
'Ready for review'
'Ready for release'
'Released'

PC - I don't agree with skipping the "Ready for Release" status since it is an important part of the review process. However, it is possible to make the switching between statuses fast and efficient by having bulk options such as "Release all" that automatically selects marking with one status and moves it to the next.

Where it would be appropriate to reduce the number of statuses (but possibly not in our first Moodle 2.4 release) is when there is only a
single marker. So, I think we need the following:

Multiple markers - "Allocated"->"In Marking"->"Marking Completed"->"In Review"->"Ready for Release"->"Released"

Single marker - "In Marking"->"In Review"->"Released"

=== A teacher has assistants helping them mark and wants to review all marks before they are released 2 ===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* There are groups containing teaching assistants and sets of students contained in a grouping.
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Groups
** Grouping for marker allocation : "Name of Grouping"
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students
* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"
* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary
* The teacher changes the status of the grades to "Released" when they are satisfied with the grading quality.

If there are multiple markers added to a group then all markers will be able to mark assignments in that group.

GW - If there are no markers in a group, then there is the potential that student assignments would get missed....there is no visual queue that students are unallocated. In addition - our SIS-created groups systematically check for the addition of members who are not in the group in the SIS. Any staff therefore who are added to the groups in Moodle will be removed from the group on the next update...unless we changed our integration script to retain users in SIS-created groups as long as they were not students??

=== Multiple markers which to separately mark the same set of students and then a moderator either takes an average or chooses one of the marks to be released ===
Not supported by this proposal

=== Multiple markers mark one student in sequence ===

EH: This is about two or more markers marking student work, e.g., marker 1 marks parts 1 and 2, marker 2 marks parts 3 and 4 of an assignment. This could be done with a different form of allocation: marker1 picks a student and then marks their part; the interface shows that marker 1 has done their part, marker2 can now allocate themselves and continue the marking. Once all markers involved (as setup initially, here markers 1 and 2 need to mark) have done their parts the status changes to 'ready for review'.

This is not part of the current proposal.

=== Separate release of grades and feedback ===

EH: It would be nice to be able to release feedback (for formative purposes) first and marks/grades later (with a time delay or triggered by the Teacher, or, more sophisticated, dependent on the student doing something).

This is not part of the current proposal.

DW: I think it should be - but I don't what to make it complicated. I think that either the feedback is visible to the student during the entire marking process and they get the grade at the end - or they see nothing and they get the grades + feedback at the end (we could add those 2 options to the settings page). Note: The submission comments are visible to staff and students for the entire duration and provide 2 way comments between students and staff.

GW: The potential issue with this is that feedback might change during the marking process. Is a student-triggered process (ie. viewing the feedback) to release grades "complicated"?

EH: I am with Grette there - feedback should only be visible to students when marking is considered as finished (otherwise we would be back to the current deficiencies in Moodle)

== User Interface ==
=== Assignment settings screen ===
[[File:assign-advgrading-settings.png| Assignment settings screen]]
=== Submission menu in grading table ===
[[File:assign-advgrading-gradingmenu.png| Submission grading menu]]
=== Batch operations menu ===
[[File:assign-advgrading-gradingbatchmenu.png| Grading batch operations menu]]

GW: Will there be an option for the Teacher with "mod/assign:releasegrades" capability to take all assignments that are in "Ready for Review" to either "Ready for Release" or "Release" without having to individually select them?

GW - will there be a batch operation for "Assign to me?"

=== Marker allocation ===
Notes: The current user is "Grader Gary" so the grade option has disappeared for all submissions that this user is not assigned to mark. The current user also has permission to assign graders so they see additional options in the submission menu.

[[File:assign-advgrading-marker-allocation.png| Marker allocation]]

== Database Changes ==

Assignment Advanced Marking

2012-08-21T22:18:38Z

Pcharsle: /* Settings added to the mod_assign settings page */

This is a proposal for additional marking features in the Assignment module.

References: https://docs.moodle.org/dev/Lightwork#User_Interface_-_Marker_allocation_and_management

Tracker Issue: http://tracker.moodle.org/browse/MDL-34902

= Goals, rationale and fundamentals =

The main goals of this change are to:

* Control the distribution
* Support the marking process
* Control the release of marking to students

== Control the distribution ==

This is relevant in the context of large courses where groups/groupings are used to divide the students into groups and to associate dedicated staff with these groups. In terms of assignment marking the idea is that staff associated with groups are responsible for the marking of students in their groups and fulfil such marking independently from the marking of other groups.

An example would be: A course with 300 students is divided into 3 groups of students (based on different delivery locations or modes). Two or more staff are associated with each group (one teacher and several teaching assistants). The same assignment is setup for the whole course. The staff associated with each group of students are responsible for marking their groups.

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) staff associated with a group should only see the students belonging to this group. It is not recorded which staff member is marking which students.
The staff member in charge of the overall course might have a setting, which allows to see assignment marking for all students (of all groups).

This functionality is primarily of interest to the EAM project.

== Support the marking process ==

The focus here is on assisting with the marking process, typically in situations where multiple teachers and/or teaching assistants form a marking team. The idea is to allow each individual marker to have an overview of marking assigned to them and of the status this marking is in. The teacher in charge of the assignment wants to be able to see how marking is progressing and what quality the marking is (per marker and across markers).

To achieve this focus two aspects need to be introduced:
* Marker allocations;
* Marking statuses.

With marker allocations, it is recorded which marker (teacher or teaching assistant) is marking which student. Only the marker allocated can mark a student. The teacher in charge of the assignment decides the marker allocation (the teacher selects all staff involved in marking and then distributes marking manually, randomly, or even based on groups). As the marking progresses, allocations can be changed (e.g., when a marker becomes unavailable).

The following marking statuses are suggested:
* Allocated (the marker has not yet started)
* In marking (the marker has started but not yet finished)
* Marking completed (the marker has finished but might need to go back for checking/corrections)
* In review (the marking is now with the teacher in charge for quality checking)
* Ready for release (the teacher in charge is satisfied with the marking but wait before giving students access to the marking)
* Released (students have access to the marking.

The marking statuses are for use by staff. The marking statuses are not visible to students.
The default setting will be that students can see who has marked them (but this can be changed).
Marking can be taken from one status to the next on individual student basis, yet there are also bulk transitions (e.g., to release of ‘ready’ marking). Marking can be taken back into a previous status (e.g., from in review back to in marking if more work is required).

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) it is displayed who is marking which student (and only the staff assigned can edit the marking).

The functionality related to the marking process has its origins in Lightwork and is primarily of interest to the Lightwork online project.

== Control the release of marking to students ==

A problem with the current Moodle assignment module (2.3) is that students can immediately see their marking results (if the teacher does not take extra steps for hiding the assignment from student view and hiding the grade book entry). This is not good, as it does not allow the teacher to make changes (e.g., as required to deal with marker drift or for checking across multiple markers).

The suggestion is to add a release control to the assignment module. This will have three possibilities, visible in the assignment marking overview screen (mod/assign/view.php?id=3&action=grading):
* Nothing shown (no-one has yet saved any marking for a student)
* Not released (someone has saved marking, but this marking is not yet visible to the student)
* Released (marking is visible to the student)

The sole focus here is on if the student can see the marking or not. This is not about trying to manage the marking process.

This functionality is already included in supporting the marking process as proposed by the Lightwork Online project. The EAM project is interested in this functionality as well.

PC: A concern that I have with adding a release control to the assignment module is that teachers already have a form of release control (hiding the grade book entry). It might be simpler if we could use this existing mechanism instead of adding a second release control that may confuse teachers.

== How do these functionalities combine for the user and in implementation? ==

The functionalities would result in three settings to the Assignment update page (course/modedit.php?update=3&return=1).

* Control release of marking to students (Yes/No)
* Set distribution of marking (Yes/No; with Yes offering selection of groups/groupings)
* Manage marking process (Yes/No; with Yes offering allocation algorithms/manual allocation)

Controlling the release of marking to students is not in conflict with setting the distribution of marking, and is already included in managing the marking process.

Fundamentally there is no conflict between setting the distribution of marking and managing the marking process (in fact, it would be welcome as a ‘group’ will likely contain a large number of students and possibly several markers, making it very useful to be able to manage their marking). Yet, an initial implementation might keep things more simple and make these setting mutually exclusive.

The distribution of marking will build on already existing groups and groupings. No further database tables should be necessary to capture this information. Any changes to groups would be reflected during the marking process.

Capturing the marking allocations will require new database tables. If one allows building the allocation on groups, this will mean that the initial setting for the allocations is taken from the groups, but that any changes to groups will not be automatically reflected in marker allocations (but can be done manually, like any changes to allocations).

= Overview =

''(The following sections currently do not match what is proposed under Goals above.)''

== Settings added to the mod_assign settings page ==

Release grades immediately (Checkbox, default to on - this is the current behaviour)

[Help text] When enabled, grades will be visible to students as soon as they have been entered by a grader (If the grade column is visible in the gradebook). When disabled, any grades that are entered will be only visible to graders until they are approved for release.

Allocate markers to students (Select list of options, "None - all markers can mark all students", "Manually allocated - markers are manually allocated students to mark", "Groups - Markers can mark students in their own group")

When the grouping method is chosen above, an additional setting should be enabled to allow a grouping to be specified for the marker allocations.

Grouping for marker allocations (Select from the available groupings - or None for all groups)

GW - we currently create marking groups using the groups interface and then set assignment up using "Separate groups" so that markers can filter the list of assignments. One of the issues we have come up against is unenrolled (suspended) students still appearing in the groups interface. We have a proposal for better management of suspended users. We have identified 23 (possibly 25) areas where suspended users are currently an issue. Where possible, we’d like an option to toggle between hiding and showing suspended users, with the default option being hidden. We are looking to resource a change that will be all encompassing and a complete fix that can be contributed back to the Moodle community. Initially we will build for 2.1.6, but will then review for 2.3 towards the end of the year.

PC - I believe the assignment settings should be simplified or teachers will find it confusing. I would like to see the "Release grades immediately" and "Allocate markers to students" replaced with a single drop down of standard options:

* Simple marking" (the default settings - grades are released immediately)
* Advanced marking - single marker" (Grades are released when status changed to 'Released')
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released')

Note that when choosing "Advanced marking - multiple markers" the teacher would be able choose whether or not to use a Grouping for allocating
markers. If we are going to allow other combinations of "Release grades immediately" and "Allocate markers to students" then we could have an additional menu item to allow teachers to choose their own combination.

EH: Paul, with "Advanced marking - single marker", do you see that an automated marking allocation is made to one person (who has to have the capability to release grades), therefore enforcing that only this person can mark? I think this is a quite different approach to what Damyon is proposing, which basically says 'use marking statuses but do not record/control who is marking'. If I understand correctly what Paul is proposing, this means that one can use marking statuses only if one controls marker allocation. This might be a better solution, as it cuts out variety, simplifying things for the development and the user. We could add a fourth option for using marking statuses without marker allocation, this might give the following options:

* Simple marking" (the default settings - grades are released immediately, marker allocations are not recorded)
* Advanced marking - no marker allocations" ((Grades are released when status changed to 'Released'. No control who is marking)
* Advanced marking - single marker" (Grades are released when status changed to 'Released'. Only single marker specified can mark and release)
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released'. Multiple markers work together)

GW - I think my preference is for three settings:
Release grades immediately
Allocate markers to students

and the third
Grouping for marker allocations (to appear only if group allocation is selected)

I think it may end up being clearer, rather than trying to explain in help text what Simple marking and the Advanced marking options are.

PC - My concern is that being able to choose a combination of settings in this way does not make it clear to the teacher what they will end up with at the end. For instance, a teacher who wants to take advantage of the advanced marking process should not have to work out that they have to select "Release grades immediately - No" in order to do this. Also, see my comment earlier about the use of the "hiding" facility in the grade book to control the release.

== Changes to grading/grading interface ==

=== Marking release ===

If "Release grades immediately" is not enabled, an additional status should be added to the grading status column "Draft/Ready for release/Released". Use background colors as well to visually distinguish the statuses (Blue - draft, Fushia - Ready for Review, Yellow - Ready for Release, Green - Released).

Anyone with mod/assign:grade capability would be able to move the status from "Draft" to "Ready for Review" via the drop down menu on each submission, or via the batch operations form.

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" to "Ready for Release".

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" or "Ready for Release" to "Released". At this point the grade is pushed to the gradebook and made visible to the student.

=== Marker allocations ===

If "Allocate markers to students" is set to "Manually allocated", and the current user has "mod/assign:allocatemarkers" capability, the list of markers allocated to each student needs to be shown in a new column in the grading interface.

Multiple markers should be able to be allocated to a single student. (GW - future dev? Implies the need for markers to be able to lock assignments while they are marking them). If the current user has mod/assign:allocategraders permission, a red X next to each markers will allow immediately removing this marker (Ajax if possible - don't refresh the full page)
An option should be added to the menu for each submission and the batch operations menu which takes you to a separate page where you can choose from the users with mod/assign:grade permission to allocate to a student (or multiple students).

Any student with no markers allocated should have "No markers" in this column and the column background should be shown in a different colour (Red?) to indicate that no-one has been assigned to mark this submission. If the current user has "mod/assign:allocatemarkers" and "mod/assign:grade" capability, there should be an entry in the menu for this submissions for "Assign to me" (preferably AJAX - do not refresh entire page).

If the a submissions has not been allocated to the current user, the option to grade that submission is removed.

If the current user does not have "mod/assign:allocatemarkers" capability, the list of submissions will be limited to only show the submissions where the current user has been allocated as a marker.

PC - How will you be handling marker allocation in the database when "Grouping for allocating markers" isn't selected? Will you be creating new groups to hold the allocations?

== Use Cases ==

=== Teacher is creating an assignment with a small number of students and they do not wish to use advanced marking ===
* Create an assignment and leave the new settings at their defaults
** Release grades immediately: "checked"
** Allocate markers to students: "None"
=== Teacher is creating an assignment with a small number of students and they wish to mark all submissions, then re-mark several submissions to check for "grading drift" before release ===
(I am defining this as the perception of quality changing over time as the marker marks each assignment in turn - can't find a good reference right now)
EH: This is called 'marker drift'. you'll find a brief description in http://etools.massey.ac.nz/documents/LitReview101006.pdf (p. 19 bottom), as well as references to further literature.
* Teacher has "mod/assign:create", "mod/assign:grade" and "mod/assign:releasegrades" capabilities
* Create an assignment and de-select Release grades immediately
** Release grades immediately: "not checked"
** Allocate markers to students: "None"
* Teacher marks each submission individually. Grades are "Draft" and not released to gradebook or students
GW - I think I know why this status is "Draft", but I think it might get confused with the submission status in the interface. I think we can come up with a better term..not that I have thought of one yet.

PC - How about "Provisional"?
* Teacher re-marks a random sample of submissions
* Teacher releases all the grades via the batch operations form

EH: The seems to be our 'In marking'

GW - what about "Ready to mark" - this might be more consistent with the other statuses "Ready for review" and "Ready for release". Is there any relationship between this status and the submission status...ie. if the submission status is "Draft" should the marking status be "Not ready to mark", which changes to "Ready to mark" when the submission status is "submitted"?

'Not marked' 'In Marking' (?) 'Ready for review' 'Ready for release' ' Released'

EH:

I think we should point out as the main reason for the stepped release of grades via the transition from 'Ready for release' to 'Released' as
* The teacher wants to release marking to all students at the same time.

Marker drift or any other checking done by one person on their own marking is important. Yes, in this use case the teacher can use the statuses proposed for that, yet the need for this type of checking applies to all markers (teachers and teaching assistants). This is why we have proposed the statuses of 'In marking' and 'Marking finished', before the marking is being passed on the the teacher for further quality review (e.g., to check across markers).

PS: The descriptions here focus on the release of grades - this portraits a very summative viewpoint; it does not acknowledge the importance of feedback (as in the comments hopefully written to guide the students). This is why I tend to talk about marking and marking results.

=== Multiple Teachers are marking submissions for the same assignment and they want to know who is marking which assignment ===
* Assignment has been created and there are multiple markers with "mod:assign/grade and mod:assign/allocatemarker" capabilities
* Each marker selects "Assign to me" for the submissions they wish to mark.
* Each marker then provides grades and feedback which is released immediately to students
* The markers can see which students have been allocated a marker and will not end up marking the same student

=== A teacher has assistants helping them mark and wants to review all marks before they are released 1===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Manually
* The teacher allocates a set of students to each of the Teaching Assistants
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students

EH: It would be nice to have an option on the settings page where the teacher can set if the Teaching Assistants can see the marking done by other markers (not just the grade). Is the current proposal that a Teaching Assistant would see the entries for students not allocated to them (that means that can see the grade given by another Teaching Assistant)? There would have to be a 'read-only' grading option, allowing the Teaching Assistant to view marking done by others but not change it.
DW: No the current proposal is that they would not see any students not allocated to them.

* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"

EH: Here it would be nice if the Teaching Assistant could pass on a message to the Teacher together with the status change.

* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary

EH: How will the screenshot look? Will the Teacher have access to the grading interface even if the Teacher is not allocated to mark (the Teacher will have to look at the marking details, not just at the grade)?
DW: yes they would see the grading interface
If the Teacher changes feedback or grade, will this mean an automated re-allocation to the Teacher as marker?
DW: The teacher would not be able to provide grades or feedback unless they were the allocated marker
Will the student see who has marked them (there probably should be a setting allowing the Teacher to decide)?
DW: This is a big change - it would currently show them the last person to mark them.
We also need to options here to return the marking to the Teaching Assistant (ideally with comments, explaining why) and to allocate another marker (who then will continue with the marking already started - maybe this is already covered).
DW: This is quite an advanced workflow - we need to make sure we are not adding too much complexity (it is not prevented by this interface - it just does not include any statuses for it - ie "Needs allocation to another marker for a second round of marking")

EH: This description skips the step of the Teacher taking assignments into 'Ready for release' after successful quality checking.

* The teacher changes the status of the grades to 'Released' when they are satisfied with the grading quality.

EH: I think this should read: The Teacher changes the status from 'Ready for review' to 'Ready for Release' when they are satisfied with the grading quality.

Then the next step is: The Teacher changes the status from 'Ready for Release' to 'Released' when they want to release marking to students.

DW: I have added the "ready for release" status - but this will require good help explaining the difference between the statuses to teachers. A visual flow chart of the statuses would help.

GW - I think that the Teacher should have the option to skip the "Ready for Release" status and take the assignment from "Ready for review" straight to "Released". If statuses can be skipped..ie. as long as we don't force users through every status, then i don't think it will be a problem to have the five statuses as proposed above:
'Not marked'
'In marking/Being marked'
'Ready for review'
'Ready for release'
'Released'

=== A teacher has assistants helping them mark and wants to review all marks before they are released 2 ===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* There are groups containing teaching assistants and sets of students contained in a grouping.
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Groups
** Grouping for marker allocation : "Name of Grouping"
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students
* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"
* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary
* The teacher changes the status of the grades to "Released" when they are satisfied with the grading quality.

If there are multiple markers added to a group then all markers will be able to mark assignments in that group.

GW - If there are no markers in a group, then there is the potential that student assignments would get missed....there is no visual queue that students are unallocated. In addition - our SIS-created groups systematically check for the addition of members who are not in the group in the SIS. Any staff therefore who are added to the groups in Moodle will be removed from the group on the next update...unless we changed our integration script to retain users in SIS-created groups as long as they were not students??

=== Multiple markers which to separately mark the same set of students and then a moderator either takes an average or chooses one of the marks to be released ===
Not supported by this proposal

=== Multiple markers mark one student in sequence ===

EH: This is about two or more markers marking student work, e.g., marker 1 marks parts 1 and 2, marker 2 marks parts 3 and 4 of an assignment. This could be done with a different form of allocation: marker1 picks a student and then marks their part; the interface shows that marker 1 has done their part, marker2 can now allocate themselves and continue the marking. Once all markers involved (as setup initially, here markers 1 and 2 need to mark) have done their parts the status changes to 'ready for review'.

This is not part of the current proposal.

=== Separate release of grades and feedback ===

EH: It would be nice to be able to release feedback (for formative purposes) first and marks/grades later (with a time delay or triggered by the Teacher, or, more sophisticated, dependent on the student doing something).

This is not part of the current proposal.

DW: I think it should be - but I don't what to make it complicated. I think that either the feedback is visible to the student during the entire marking process and they get the grade at the end - or they see nothing and they get the grades + feedback at the end (we could add those 2 options to the settings page). Note: The submission comments are visible to staff and students for the entire duration and provide 2 way comments between students and staff.

GW: The potential issue with this is that feedback might change during the marking process. Is a student-triggered process (ie. viewing the feedback) to release grades "complicated"?

EH: I am with Grette there - feedback should only be visible to students when marking is considered as finished (otherwise we would be back to the current deficiencies in Moodle)

== User Interface ==
=== Assignment settings screen ===
[[File:assign-advgrading-settings.png| Assignment settings screen]]
=== Submission menu in grading table ===
[[File:assign-advgrading-gradingmenu.png| Submission grading menu]]
=== Batch operations menu ===
[[File:assign-advgrading-gradingbatchmenu.png| Grading batch operations menu]]

GW: Will there be an option for the Teacher with "mod/assign:releasegrades" capability to take all assignments that are in "Ready for Review" to either "Ready for Release" or "Release" without having to individually select them?

GW - will there be a batch operation for "Assign to me?"

=== Marker allocation ===
Notes: The current user is "Grader Gary" so the grade option has disappeared for all submissions that this user is not assigned to mark. The current user also has permission to assign graders so they see additional options in the submission menu.

[[File:assign-advgrading-marker-allocation.png| Marker allocation]]

== Database Changes ==

Assignment Advanced Marking

2012-08-21T21:25:34Z

Pcharsle: /* Control the release of marking to students */

This is a proposal for additional marking features in the Assignment module.

References: https://docs.moodle.org/dev/Lightwork#User_Interface_-_Marker_allocation_and_management

Tracker Issue: http://tracker.moodle.org/browse/MDL-34902

= Goals, rationale and fundamentals =

The main goals of this change are to:

* Control the distribution
* Support the marking process
* Control the release of marking to students

== Control the distribution ==

This is relevant in the context of large courses where groups/groupings are used to divide the students into groups and to associate dedicated staff with these groups. In terms of assignment marking the idea is that staff associated with groups are responsible for the marking of students in their groups and fulfil such marking independently from the marking of other groups.

An example would be: A course with 300 students is divided into 3 groups of students (based on different delivery locations or modes). Two or more staff are associated with each group (one teacher and several teaching assistants). The same assignment is setup for the whole course. The staff associated with each group of students are responsible for marking their groups.

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) staff associated with a group should only see the students belonging to this group. It is not recorded which staff member is marking which students.
The staff member in charge of the overall course might have a setting, which allows to see assignment marking for all students (of all groups).

This functionality is primarily of interest to the EAM project.

== Support the marking process ==

The focus here is on assisting with the marking process, typically in situations where multiple teachers and/or teaching assistants form a marking team. The idea is to allow each individual marker to have an overview of marking assigned to them and of the status this marking is in. The teacher in charge of the assignment wants to be able to see how marking is progressing and what quality the marking is (per marker and across markers).

To achieve this focus two aspects need to be introduced:
* Marker allocations;
* Marking statuses.

With marker allocations, it is recorded which marker (teacher or teaching assistant) is marking which student. Only the marker allocated can mark a student. The teacher in charge of the assignment decides the marker allocation (the teacher selects all staff involved in marking and then distributes marking manually, randomly, or even based on groups). As the marking progresses, allocations can be changed (e.g., when a marker becomes unavailable).

The following marking statuses are suggested:
* Allocated (the marker has not yet started)
* In marking (the marker has started but not yet finished)
* Marking completed (the marker has finished but might need to go back for checking/corrections)
* In review (the marking is now with the teacher in charge for quality checking)
* Ready for release (the teacher in charge is satisfied with the marking but wait before giving students access to the marking)
* Released (students have access to the marking.

The marking statuses are for use by staff. The marking statuses are not visible to students.
The default setting will be that students can see who has marked them (but this can be changed).
Marking can be taken from one status to the next on individual student basis, yet there are also bulk transitions (e.g., to release of ‘ready’ marking). Marking can be taken back into a previous status (e.g., from in review back to in marking if more work is required).

When looking at the assignment marking (mod/assign/view.php?id=3&action=grading) it is displayed who is marking which student (and only the staff assigned can edit the marking).

The functionality related to the marking process has its origins in Lightwork and is primarily of interest to the Lightwork online project.

== Control the release of marking to students ==

A problem with the current Moodle assignment module (2.3) is that students can immediately see their marking results (if the teacher does not take extra steps for hiding the assignment from student view and hiding the grade book entry). This is not good, as it does not allow the teacher to make changes (e.g., as required to deal with marker drift or for checking across multiple markers).

The suggestion is to add a release control to the assignment module. This will have three possibilities, visible in the assignment marking overview screen (mod/assign/view.php?id=3&action=grading):
* Nothing shown (no-one has yet saved any marking for a student)
* Not released (someone has saved marking, but this marking is not yet visible to the student)
* Released (marking is visible to the student)

The sole focus here is on if the student can see the marking or not. This is not about trying to manage the marking process.

This functionality is already included in supporting the marking process as proposed by the Lightwork Online project. The EAM project is interested in this functionality as well.

PC: A concern that I have with adding a release control to the assignment module is that teachers already have a form of release control (hiding the grade book entry). It might be simpler if we could use this existing mechanism instead of adding a second release control that may confuse teachers.

== How do these functionalities combine for the user and in implementation? ==

The functionalities would result in three settings to the Assignment update page (course/modedit.php?update=3&return=1).

* Control release of marking to students (Yes/No)
* Set distribution of marking (Yes/No; with Yes offering selection of groups/groupings)
* Manage marking process (Yes/No; with Yes offering allocation algorithms/manual allocation)

Controlling the release of marking to students is not in conflict with setting the distribution of marking, and is already included in managing the marking process.

Fundamentally there is no conflict between setting the distribution of marking and managing the marking process (in fact, it would be welcome as a ‘group’ will likely contain a large number of students and possibly several markers, making it very useful to be able to manage their marking). Yet, an initial implementation might keep things more simple and make these setting mutually exclusive.

The distribution of marking will build on already existing groups and groupings. No further database tables should be necessary to capture this information. Any changes to groups would be reflected during the marking process.

Capturing the marking allocations will require new database tables. If one allows building the allocation on groups, this will mean that the initial setting for the allocations is taken from the groups, but that any changes to groups will not be automatically reflected in marker allocations (but can be done manually, like any changes to allocations).

= Overview =

''(The following sections currently do not match what is proposed under Goals above.)''

== Settings added to the mod_assign settings page ==

Release grades immediately (Checkbox, default to on - this is the current behaviour)

[Help text] When enabled, grades will be visible to students as soon as they have been entered by a grader (If the grade column is visible in the gradebook). When disabled, any grades that are entered will be only visible to graders until they are approved for release.

Allocate markers to students (Select list of options, "None - all markers can mark all students", "Manually allocated - markers are manually allocated students to mark", "Groups - Markers can mark students in their own group")

When the grouping method is chosen above, an additional setting should be enabled to allow a grouping to be specified for the marker allocations.

Grouping for marker allocations (Select from the available groupings - or None for all groups)

GW - we currently create marking groups using the groups interface and then set assignment up using "Separate groups" so that markers can filter the list of assignments. One of the issues we have come up against is unenrolled (suspended) students still appearing in the groups interface. We have a proposal for better management of suspended users. We have identified 23 (possibly 25) areas where suspended users are currently an issue. Where possible, we’d like an option to toggle between hiding and showing suspended users, with the default option being hidden. We are looking to resource a change that will be all encompassing and a complete fix that can be contributed back to the Moodle community. Initially we will build for 2.1.6, but will then review for 2.3 towards the end of the year.

PC - I believe the assignment settings should be simplified or teachers will find it confusing. I would like to see the "Release grades immediately" and "Allocate markers to students" replaced with a single drop down of standard options:

* Simple marking" (the default settings - grades are released immediately)
* Advanced marking - single marker" (Grades are released when status changed to 'Released')
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released')

Note that when choosing "Advanced marking - multiple markers" the teacher would be able choose whether or not to use a Grouping for allocating
markers. If we are going to allow other combinations of "Release grades immediately" and "Allocate markers to students" then we could have an additional menu item to allow teachers to choose their own combination.

EH: Paul, with "Advanced marking - single marker", do you see that an automated marking allocation is made to one person (who has to have the capability to release grades), therefore enforcing that only this person can mark? I think this is a quite different approach to what Damyon is proposing, which basically says 'use marking statuses but do not record/control who is marking'. If I understand correctly what Paul is proposing, this means that one can use marking statuses only if one controls marker allocation. This might be a better solution, as it cuts out variety, simplifying things for the development and the user. We could add a fourth option for using marking statuses without marker allocation, this might give the following options:

* Simple marking" (the default settings - grades are released immediately, marker allocations are not recorded)
* Advanced marking - no marker allocations" ((Grades are released when status changed to 'Released'. No control who is marking)
* Advanced marking - single marker" (Grades are released when status changed to 'Released'. Only single marker specified can mark and release)
* Advanced marking - multiple markers" (Grades are released when status changed to 'Released'. Multiple markers work together)

GW - I think my preference is for three settings:
Release grades immediately
Allocate markers to students

and the third
Grouping for marker allocations (to appear only if group allocation is selected)

I think it may end up being clearer, rather than trying to explain in help text what Simple marking and the Advanced marking options are.

== Changes to grading/grading interface ==

=== Marking release ===

If "Release grades immediately" is not enabled, an additional status should be added to the grading status column "Draft/Ready for release/Released". Use background colors as well to visually distinguish the statuses (Blue - draft, Fushia - Ready for Review, Yellow - Ready for Release, Green - Released).

Anyone with mod/assign:grade capability would be able to move the status from "Draft" to "Ready for Review" via the drop down menu on each submission, or via the batch operations form.

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" to "Ready for Release".

Anyone with mod/assign:releasegrade (new) capability would be able to move the grade from either "Draft" or "Ready for Review" or "Ready for Release" to "Released". At this point the grade is pushed to the gradebook and made visible to the student.

=== Marker allocations ===

If "Allocate markers to students" is set to "Manually allocated", and the current user has "mod/assign:allocatemarkers" capability, the list of markers allocated to each student needs to be shown in a new column in the grading interface.

Multiple markers should be able to be allocated to a single student. (GW - future dev? Implies the need for markers to be able to lock assignments while they are marking them). If the current user has mod/assign:allocategraders permission, a red X next to each markers will allow immediately removing this marker (Ajax if possible - don't refresh the full page)
An option should be added to the menu for each submission and the batch operations menu which takes you to a separate page where you can choose from the users with mod/assign:grade permission to allocate to a student (or multiple students).

Any student with no markers allocated should have "No markers" in this column and the column background should be shown in a different colour (Red?) to indicate that no-one has been assigned to mark this submission. If the current user has "mod/assign:allocatemarkers" and "mod/assign:grade" capability, there should be an entry in the menu for this submissions for "Assign to me" (preferably AJAX - do not refresh entire page).

If the a submissions has not been allocated to the current user, the option to grade that submission is removed.

If the current user does not have "mod/assign:allocatemarkers" capability, the list of submissions will be limited to only show the submissions where the current user has been allocated as a marker.

PC - How will you be handling marker allocation in the database when "Grouping for allocating markers" isn't selected? Will you be creating new groups to hold the allocations?

== Use Cases ==

=== Teacher is creating an assignment with a small number of students and they do not wish to use advanced marking ===
* Create an assignment and leave the new settings at their defaults
** Release grades immediately: "checked"
** Allocate markers to students: "None"
=== Teacher is creating an assignment with a small number of students and they wish to mark all submissions, then re-mark several submissions to check for "grading drift" before release ===
(I am defining this as the perception of quality changing over time as the marker marks each assignment in turn - can't find a good reference right now)
EH: This is called 'marker drift'. you'll find a brief description in http://etools.massey.ac.nz/documents/LitReview101006.pdf (p. 19 bottom), as well as references to further literature.
* Teacher has "mod/assign:create", "mod/assign:grade" and "mod/assign:releasegrades" capabilities
* Create an assignment and de-select Release grades immediately
** Release grades immediately: "not checked"
** Allocate markers to students: "None"
* Teacher marks each submission individually. Grades are "Draft" and not released to gradebook or students
GW - I think I know why this status is "Draft", but I think it might get confused with the submission status in the interface. I think we can come up with a better term..not that I have thought of one yet.

PC - How about "Provisional"?
* Teacher re-marks a random sample of submissions
* Teacher releases all the grades via the batch operations form

EH: The seems to be our 'In marking'

GW - what about "Ready to mark" - this might be more consistent with the other statuses "Ready for review" and "Ready for release". Is there any relationship between this status and the submission status...ie. if the submission status is "Draft" should the marking status be "Not ready to mark", which changes to "Ready to mark" when the submission status is "submitted"?

'Not marked' 'In Marking' (?) 'Ready for review' 'Ready for release' ' Released'

EH:

I think we should point out as the main reason for the stepped release of grades via the transition from 'Ready for release' to 'Released' as
* The teacher wants to release marking to all students at the same time.

Marker drift or any other checking done by one person on their own marking is important. Yes, in this use case the teacher can use the statuses proposed for that, yet the need for this type of checking applies to all markers (teachers and teaching assistants). This is why we have proposed the statuses of 'In marking' and 'Marking finished', before the marking is being passed on the the teacher for further quality review (e.g., to check across markers).

PS: The descriptions here focus on the release of grades - this portraits a very summative viewpoint; it does not acknowledge the importance of feedback (as in the comments hopefully written to guide the students). This is why I tend to talk about marking and marking results.

=== Multiple Teachers are marking submissions for the same assignment and they want to know who is marking which assignment ===
* Assignment has been created and there are multiple markers with "mod:assign/grade and mod:assign/allocatemarker" capabilities
* Each marker selects "Assign to me" for the submissions they wish to mark.
* Each marker then provides grades and feedback which is released immediately to students
* The markers can see which students have been allocated a marker and will not end up marking the same student

=== A teacher has assistants helping them mark and wants to review all marks before they are released 1===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Manually
* The teacher allocates a set of students to each of the Teaching Assistants
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students

EH: It would be nice to have an option on the settings page where the teacher can set if the Teaching Assistants can see the marking done by other markers (not just the grade). Is the current proposal that a Teaching Assistant would see the entries for students not allocated to them (that means that can see the grade given by another Teaching Assistant)? There would have to be a 'read-only' grading option, allowing the Teaching Assistant to view marking done by others but not change it.
DW: No the current proposal is that they would not see any students not allocated to them.

* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"

EH: Here it would be nice if the Teaching Assistant could pass on a message to the Teacher together with the status change.

* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary

EH: How will the screenshot look? Will the Teacher have access to the grading interface even if the Teacher is not allocated to mark (the Teacher will have to look at the marking details, not just at the grade)?
DW: yes they would see the grading interface
If the Teacher changes feedback or grade, will this mean an automated re-allocation to the Teacher as marker?
DW: The teacher would not be able to provide grades or feedback unless they were the allocated marker
Will the student see who has marked them (there probably should be a setting allowing the Teacher to decide)?
DW: This is a big change - it would currently show them the last person to mark them.
We also need to options here to return the marking to the Teaching Assistant (ideally with comments, explaining why) and to allocate another marker (who then will continue with the marking already started - maybe this is already covered).
DW: This is quite an advanced workflow - we need to make sure we are not adding too much complexity (it is not prevented by this interface - it just does not include any statuses for it - ie "Needs allocation to another marker for a second round of marking")

EH: This description skips the step of the Teacher taking assignments into 'Ready for release' after successful quality checking.

* The teacher changes the status of the grades to 'Released' when they are satisfied with the grading quality.

EH: I think this should read: The Teacher changes the status from 'Ready for review' to 'Ready for Release' when they are satisfied with the grading quality.

Then the next step is: The Teacher changes the status from 'Ready for Release' to 'Released' when they want to release marking to students.

DW: I have added the "ready for release" status - but this will require good help explaining the difference between the statuses to teachers. A visual flow chart of the statuses would help.

GW - I think that the Teacher should have the option to skip the "Ready for Release" status and take the assignment from "Ready for review" straight to "Released". If statuses can be skipped..ie. as long as we don't force users through every status, then i don't think it will be a problem to have the five statuses as proposed above:
'Not marked'
'In marking/Being marked'
'Ready for review'
'Ready for release'
'Released'

=== A teacher has assistants helping them mark and wants to review all marks before they are released 2 ===
* Assignment has been created and there are is a teacher with "mod/assign:grade", "mod/assign:allocatemarker" and "mod/assign:releasegrades" capabilities
* There are multiple teaching assistants who have "mod/assign:grade" capability but not "mod/assign:releasegrades" or "mod/assign:allocatemarker" capabilities
* There are groups containing teaching assistants and sets of students contained in a grouping.
* The Teacher configures the assignment to have:
** Release grades immediately : not checked
** Allocate markers to students : Groups
** Grouping for marker allocation : "Name of Grouping"
* The teaching assistants login and can only grade their own students. The grades and feedback are "Draft" and not released to gradebook or students
* When finished, for each submission the teaching assistant changes the status of the grades to "Ready for review"
* The teacher can see which grades/feedback are ready for them to review by the grading status.
* The teacher reviews all grades and feedback that are "Ready for review", making changes if necessary
* The teacher changes the status of the grades to "Released" when they are satisfied with the grading quality.

If there are multiple markers added to a group then all markers will be able to mark assignments in that group.

GW - If there are no markers in a group, then there is the potential that student assignments would get missed....there is no visual queue that students are unallocated. In addition - our SIS-created groups systematically check for the addition of members who are not in the group in the SIS. Any staff therefore who are added to the groups in Moodle will be removed from the group on the next update...unless we changed our integration script to retain users in SIS-created groups as long as they were not students??

=== Multiple markers which to separately mark the same set of students and then a moderator either takes an average or chooses one of the marks to be released ===
Not supported by this proposal

=== Multiple markers mark one student in sequence ===

EH: This is about two or more markers marking student work, e.g., marker 1 marks parts 1 and 2, marker 2 marks parts 3 and 4 of an assignment. This could be done with a different form of allocation: marker1 picks a student and then marks their part; the interface shows that marker 1 has done their part, marker2 can now allocate themselves and continue the marking. Once all markers involved (as setup initially, here markers 1 and 2 need to mark) have done their parts the status changes to 'ready for review'.

This is not part of the current proposal.

=== Separate release of grades and feedback ===

EH: It would be nice to be able to release feedback (for formative purposes) first and marks/grades later (with a time delay or triggered by the Teacher, or, more sophisticated, dependent on the student doing something).

This is not part of the current proposal.

DW: I think it should be - but I don't what to make it complicated. I think that either the feedback is visible to the student during the entire marking process and they get the grade at the end - or they see nothing and they get the grades + feedback at the end (we could add those 2 options to the settings page). Note: The submission comments are visible to staff and students for the entire duration and provide 2 way comments between students and staff.

GW: The potential issue with this is that feedback might change during the marking process. Is a student-triggered process (ie. viewing the feedback) to release grades "complicated"?

EH: I am with Grette there - feedback should only be visible to students when marking is considered as finished (otherwise we would be back to the current deficiencies in Moodle)

== User Interface ==
=== Assignment settings screen ===
[[File:assign-advgrading-settings.png| Assignment settings screen]]
=== Submission menu in grading table ===
[[File:assign-advgrading-gradingmenu.png| Submission grading menu]]
=== Batch operations menu ===
[[File:assign-advgrading-gradingbatchmenu.png| Grading batch operations menu]]

GW: Will there be an option for the Teacher with "mod/assign:releasegrades" capability to take all assignments that are in "Ready for Review" to either "Ready for Release" or "Release" without having to individually select them?

GW - will there be a batch operation for "Assign to me?"

=== Marker allocation ===
Notes: The current user is "Grader Gary" so the grade option has disappeared for all submissions that this user is not assigned to mark. The current user also has permission to assign graders so they see additional options in the submission menu.

[[File:assign-advgrading-marker-allocation.png| Marker allocation]]

== Database Changes ==

Lightwork

2012-08-19T22:04:09Z

Pcharsle: /* The new Lightwork web services */

{{Work in progress}}
{{Infobox Project
|name = Lightwork
|state = In Development
|tracker = http://tracker.moodle.org/browse/MDL-31409
|discussion = http://moodle.org/mod/forum/discuss.php?d=187818
|assignee = Lightwork
}}
{{Moodle 2.4}}

== 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_customisation|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.4 release as described in the rest of this document.

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

== 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:

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''methodname'''
|'''classname'''
|'''classpath'''
|'''parameters'''
|'''type'''
|'''description and comments'''

|-
|'''core_webservice_get_site_info'''
|core_webservice_external
|webservice/externallib.php
|None
|read
|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_users_get_users_with_capability'''
|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
|http://tracker.moodle.org/browse/MDL-31859 Return list of participants to specified courses. This should include students and teachers. User details are returned together with 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_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
|}

== Migration of existing SOAP OKtech web services to Moodle core web services ==

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

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

== 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 ===

[[File:UpdateAssignment.png|600px|thumb|center|Create and update assignment page]]

=== Advanced grading, Define Marking guide page ===

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

[[File:UpdateRubric.png|600px|thumb|center|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

[[File:LookAtRubric.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_2.png|600px|thumb|center|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.

[[File:StudentView.png|600px|thumb|center|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

[[File:ViewSubmittedAssignments_1.png|600px|thumb|center|Allocate markers to students]]

=== Review the marking ===

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

[[File:ViewSubmittedAssignments_3.png|600px|thumb|center|Review the marking]]

=== Release the marking ===

[[File:ViewSubmittedAssignments_4.png|600px|thumb|center|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: [http://lightwork.massey.ac.nz/documents/show/6 TestPlan_MarkingGuide]

Testing results can be recorded in: [http://lightwork.massey.ac.nz/documents/show/6 Testing_Record_MarkingGuide]

Assignment Advanced Marking

2012-08-17T02:18:13Z

Pcharsle: /* Marker allocations */