MDL-52954 marking guide: Wrap radio fields in a label for styling
[moodle.git] / mod / assign / externallib.php
CommitLineData
1f8c8f61
PC
1<?php
2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
16
17/**
18 * External assign API
19 *
20 * @package mod_assign
21 * @since Moodle 2.4
22 * @copyright 2012 Paul Charsley
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 */
25
26defined('MOODLE_INTERNAL') || die;
27
28require_once("$CFG->libdir/externallib.php");
bdf1ac27 29require_once("$CFG->dirroot/mod/assign/locallib.php");
1f8c8f61
PC
30
31/**
32 * Assign functions
1561a37c
DW
33 * @copyright 2012 Paul Charsley
34 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1f8c8f61
PC
35 */
36class mod_assign_external extends external_api {
37
05a6445a
DW
38 /**
39 * Generate a warning in a standard structure for a known failure.
40 *
41 * @param int $assignmentid - The assignment
1561a37c 42 * @param string $warningcode - The key for the warning message
05a6445a
DW
43 * @param string $detail - A description of the error
44 * @return array - Warning structure containing item, itemid, warningcode, message
45 */
46 private static function generate_warning($assignmentid, $warningcode, $detail) {
47 $warningmessages = array(
48 'couldnotlock'=>'Could not lock the submission for this user.',
49 'couldnotunlock'=>'Could not unlock the submission for this user.',
50 'couldnotsubmitforgrading'=>'Could not submit assignment for grading.',
51 'couldnotrevealidentities'=>'Could not reveal identities.',
52 'couldnotgrantextensions'=>'Could not grant submission date extensions.',
53 'couldnotrevert'=>'Could not revert submission to draft.',
54 'invalidparameters'=>'Invalid parameters.',
55 'couldnotsavesubmission'=>'Could not save submission.',
56 'couldnotsavegrade'=>'Could not save grade.'
57 );
58
59 $message = $warningmessages[$warningcode];
60 if (empty($message)) {
61 $message = 'Unknown warning type.';
62 }
63
64 return array('item'=>$detail,
65 'itemid'=>$assignmentid,
66 'warningcode'=>$warningcode,
67 'message'=>$message);
68 }
69
1f8c8f61
PC
70 /**
71 * Describes the parameters for get_grades
72 * @return external_external_function_parameters
73 * @since Moodle 2.4
74 */
75 public static function get_grades_parameters() {
76 return new external_function_parameters(
77 array(
78 'assignmentids' => new external_multiple_structure(
79 new external_value(PARAM_INT, 'assignment id'),
80 '1 or more assignment ids',
81 VALUE_REQUIRED),
82 'since' => new external_value(PARAM_INT,
83 'timestamp, only return records where timemodified >= since',
84 VALUE_DEFAULT, 0)
85 )
86 );
87 }
88
89 /**
90 * Returns grade information from assign_grades for the requested assignment ids
1561a37c 91 * @param int[] $assignmentids
1f8c8f61
PC
92 * @param int $since only return records with timemodified >= since
93 * @return array of grade records for each requested assignment
94 * @since Moodle 2.4
95 */
96 public static function get_grades($assignmentids, $since = 0) {
97 global $DB;
98 $params = self::validate_parameters(self::get_grades_parameters(),
99 array('assignmentids' => $assignmentids,
100 'since' => $since));
101
102 $assignments = array();
103 $warnings = array();
104 $requestedassignmentids = $params['assignmentids'];
105
106 // Check the user is allowed to get the grades for the assignments requested.
107 $placeholders = array();
108 list($sqlassignmentids, $placeholders) = $DB->get_in_or_equal($requestedassignmentids, SQL_PARAMS_NAMED);
109 $sql = "SELECT cm.id, cm.instance FROM {course_modules} cm JOIN {modules} md ON md.id = cm.module ".
110 "WHERE md.name = :modname AND cm.instance ".$sqlassignmentids;
111 $placeholders['modname'] = 'assign';
112 $cms = $DB->get_records_sql($sql, $placeholders);
113 foreach ($cms as $cm) {
114 try {
115 $context = context_module::instance($cm->id);
116 self::validate_context($context);
117 require_capability('mod/assign:grade', $context);
118 } catch (Exception $e) {
119 $requestedassignmentids = array_diff($requestedassignmentids, array($cm->instance));
120 $warning = array();
121 $warning['item'] = 'assignment';
122 $warning['itemid'] = $cm->instance;
123 $warning['warningcode'] = '1';
124 $warning['message'] = 'No access rights in module context';
125 $warnings[] = $warning;
126 }
127 }
128
129 // Create the query and populate an array of grade records from the recordset results.
130 if (count ($requestedassignmentids) > 0) {
131 $placeholders = array();
132 list($inorequalsql, $placeholders) = $DB->get_in_or_equal($requestedassignmentids, SQL_PARAMS_NAMED);
a13fbf5f 133
ad030ab4
DW
134 $sql = "SELECT ag.id,
135 ag.assignment,
136 ag.userid,
137 ag.timecreated,
138 ag.timemodified,
139 ag.grader,
140 ag.grade,
141 ag.attemptnumber
9e3eee67
DW
142 FROM {assign_grades} ag, {assign_submission} s
143 WHERE s.assignment $inorequalsql
144 AND s.userid = ag.userid
145 AND s.latest = 1
146 AND s.attemptnumber = ag.attemptnumber
ad030ab4 147 AND ag.timemodified >= :since
9e3eee67 148 AND ag.assignment = s.assignment
ad030ab4 149 ORDER BY ag.assignment, ag.id";
a13fbf5f 150
1f8c8f61
PC
151 $placeholders['since'] = $params['since'];
152 $rs = $DB->get_recordset_sql($sql, $placeholders);
153 $currentassignmentid = null;
154 $assignment = null;
155 foreach ($rs as $rd) {
156 $grade = array();
157 $grade['id'] = $rd->id;
158 $grade['userid'] = $rd->userid;
159 $grade['timecreated'] = $rd->timecreated;
160 $grade['timemodified'] = $rd->timemodified;
161 $grade['grader'] = $rd->grader;
05a6445a 162 $grade['attemptnumber'] = $rd->attemptnumber;
1f8c8f61 163 $grade['grade'] = (string)$rd->grade;
1f8c8f61
PC
164
165 if (is_null($currentassignmentid) || ($rd->assignment != $currentassignmentid )) {
166 if (!is_null($assignment)) {
167 $assignments[] = $assignment;
168 }
169 $assignment = array();
170 $assignment['assignmentid'] = $rd->assignment;
171 $assignment['grades'] = array();
172 $requestedassignmentids = array_diff($requestedassignmentids, array($rd->assignment));
173 }
174 $assignment['grades'][] = $grade;
175
176 $currentassignmentid = $rd->assignment;
177 }
178 if (!is_null($assignment)) {
179 $assignments[] = $assignment;
180 }
181 $rs->close();
182 }
183 foreach ($requestedassignmentids as $assignmentid) {
184 $warning = array();
185 $warning['item'] = 'assignment';
186 $warning['itemid'] = $assignmentid;
187 $warning['warningcode'] = '3';
188 $warning['message'] = 'No grades found';
189 $warnings[] = $warning;
190 }
191
192 $result = array();
193 $result['assignments'] = $assignments;
194 $result['warnings'] = $warnings;
195 return $result;
196 }
197
bdf1ac27
JL
198 /**
199 * Creates a grade single structure.
200 *
201 * @return external_single_structure a grade single structure.
202 * @since Moodle 3.1
203 */
204 private static function get_grade_structure($required = VALUE_REQUIRED) {
205 return new external_single_structure(
206 array(
207 'id' => new external_value(PARAM_INT, 'grade id'),
208 'assignment' => new external_value(PARAM_INT, 'assignment id', VALUE_OPTIONAL),
209 'userid' => new external_value(PARAM_INT, 'student id'),
210 'attemptnumber' => new external_value(PARAM_INT, 'attempt number'),
211 'timecreated' => new external_value(PARAM_INT, 'grade creation time'),
212 'timemodified' => new external_value(PARAM_INT, 'grade last modified time'),
213 'grader' => new external_value(PARAM_INT, 'grader'),
214 'grade' => new external_value(PARAM_TEXT, 'grade'),
215 'gradefordisplay' => new external_value(PARAM_RAW, 'grade rendered into a format suitable for display',
216 VALUE_OPTIONAL),
217 ), 'grade information', $required
218 );
219 }
220
1f8c8f61
PC
221 /**
222 * Creates an assign_grades external_single_structure
223 * @return external_single_structure
224 * @since Moodle 2.4
225 */
226 private static function assign_grades() {
227 return new external_single_structure(
228 array (
bdf1ac27
JL
229 'assignmentid' => new external_value(PARAM_INT, 'assignment id'),
230 'grades' => new external_multiple_structure(self::get_grade_structure())
1f8c8f61
PC
231 )
232 );
233 }
234
235 /**
236 * Describes the get_grades return value
237 * @return external_single_structure
238 * @since Moodle 2.4
239 */
240 public static function get_grades_returns() {
241 return new external_single_structure(
242 array(
243 'assignments' => new external_multiple_structure(self::assign_grades(), 'list of assignment grade information'),
8118dbd0 244 'warnings' => new external_warnings('item is always \'assignment\'',
b0da618b 245 'when errorcode is 3 then itemid is an assignment id. When errorcode is 1, itemid is a course module id',
8118dbd0 246 'errorcode can be 3 (no grades found) or 1 (no permission to get grades)')
1f8c8f61
PC
247 )
248 );
249 }
250
1378838e
PC
251 /**
252 * Returns description of method parameters
2ea4312a 253 *
1378838e
PC
254 * @return external_function_parameters
255 * @since Moodle 2.4
256 */
257 public static function get_assignments_parameters() {
258 return new external_function_parameters(
259 array(
260 'courseids' => new external_multiple_structure(
8e76a2fa 261 new external_value(PARAM_INT, 'course id, empty for retrieving all the courses where the user is enroled in'),
1378838e
PC
262 '0 or more course ids',
263 VALUE_DEFAULT, array()
264 ),
265 'capabilities' => new external_multiple_structure(
266 new external_value(PARAM_CAPABILITY, 'capability'),
267 'list of capabilities used to filter courses',
268 VALUE_DEFAULT, array()
8e76a2fa
JL
269 ),
270 'includenotenrolledcourses' => new external_value(PARAM_BOOL, 'whether to return courses that the user can see
271 even if is not enroled in. This requires the parameter courseids
272 to not be empty.', VALUE_DEFAULT, false)
1378838e
PC
273 )
274 );
275 }
276
277 /**
8e76a2fa 278 * Returns an array of courses the user is enrolled, and for each course all of the assignments that the user can
1378838e 279 * view within that course.
2ea4312a 280 *
1378838e 281 * @param array $courseids An optional array of course ids. If provided only assignments within the given course
8e76a2fa 282 * will be returned. If the user is not enrolled in or can't view a given course a warning will be generated and returned.
1378838e 283 * @param array $capabilities An array of additional capability checks you wish to be made on the course context.
8e76a2fa
JL
284 * @param bool $includenotenrolledcourses Wheter to return courses that the user can see even if is not enroled in.
285 * This requires the parameter $courseids to not be empty.
1378838e
PC
286 * @return An array of courses and warnings.
287 * @since Moodle 2.4
288 */
8e76a2fa 289 public static function get_assignments($courseids = array(), $capabilities = array(), $includenotenrolledcourses = false) {
4e2e3c95 290 global $USER, $DB, $CFG;
1378838e
PC
291
292 $params = self::validate_parameters(
293 self::get_assignments_parameters(),
8e76a2fa
JL
294 array(
295 'courseids' => $courseids,
296 'capabilities' => $capabilities,
297 'includenotenrolledcourses' => $includenotenrolledcourses
298 )
1378838e
PC
299 );
300
301 $warnings = array();
8e76a2fa 302 $courses = array();
1378838e 303 $fields = 'sortorder,shortname,fullname,timemodified';
8e76a2fa
JL
304
305 // If the courseids list is empty, we return only the courses where the user is enrolled in.
306 if (empty($params['courseids'])) {
307 $courses = enrol_get_users_courses($USER->id, true, $fields);
308 $courseids = array_keys($courses);
309 } else if ($includenotenrolledcourses) {
310 // In this case, we don't have to check here for enrolmnents. Maybe the user can see the course even if is not enrolled.
311 $courseids = $params['courseids'];
312 } else {
313 // We need to check for enrolments.
314 $mycourses = enrol_get_users_courses($USER->id, true, $fields);
315 $mycourseids = array_keys($mycourses);
316
1378838e 317 foreach ($params['courseids'] as $courseid) {
8e76a2fa 318 if (!in_array($courseid, $mycourseids)) {
1378838e
PC
319 unset($courses[$courseid]);
320 $warnings[] = array(
321 'item' => 'course',
322 'itemid' => $courseid,
323 'warningcode' => '2',
324 'message' => 'User is not enrolled or does not have requested capability'
325 );
8e76a2fa
JL
326 } else {
327 $courses[$courseid] = $mycourses[$courseid];
1378838e
PC
328 }
329 }
8e76a2fa 330 $courseids = array_keys($courses);
1378838e 331 }
8e76a2fa
JL
332
333 foreach ($courseids as $cid) {
334
1378838e 335 try {
8e76a2fa 336 $context = context_course::instance($cid);
1378838e 337 self::validate_context($context);
8e76a2fa
JL
338
339 // Check if this course was already loaded (by enrol_get_users_courses).
340 if (!isset($courses[$cid])) {
341 $courses[$cid] = get_course($cid);
342 }
1378838e 343 } catch (Exception $e) {
8e76a2fa 344 unset($courses[$cid]);
1378838e
PC
345 $warnings[] = array(
346 'item' => 'course',
8e76a2fa 347 'itemid' => $cid,
1378838e 348 'warningcode' => '1',
8e76a2fa 349 'message' => 'No access rights in course context '.$e->getMessage()
1378838e
PC
350 );
351 continue;
352 }
353 if (count($params['capabilities']) > 0 && !has_all_capabilities($params['capabilities'], $context)) {
8e76a2fa 354 unset($courses[$cid]);
1378838e
PC
355 }
356 }
8e1266bf
DW
357 $extrafields='m.id as assignmentid, ' .
358 'm.course, ' .
359 'm.nosubmissions, ' .
360 'm.submissiondrafts, ' .
361 'm.sendnotifications, '.
362 'm.sendlatenotifications, ' .
363 'm.sendstudentnotifications, ' .
364 'm.duedate, ' .
365 'm.allowsubmissionsfromdate, '.
366 'm.grade, ' .
367 'm.timemodified, '.
368 'm.completionsubmit, ' .
369 'm.cutoffdate, ' .
370 'm.teamsubmission, ' .
371 'm.requireallteammemberssubmit, '.
372 'm.teamsubmissiongroupingid, ' .
373 'm.blindmarking, ' .
374 'm.revealidentities, ' .
375 'm.attemptreopenmethod, '.
376 'm.maxattempts, ' .
377 'm.markingworkflow, ' .
378 'm.markingallocation, ' .
4e2e3c95
JL
379 'm.requiresubmissionstatement, '.
380 'm.intro, '.
381 'm.introformat';
1378838e
PC
382 $coursearray = array();
383 foreach ($courses as $id => $course) {
384 $assignmentarray = array();
385 // Get a list of assignments for the course.
386 if ($modules = get_coursemodules_in_course('assign', $courses[$id]->id, $extrafields)) {
387 foreach ($modules as $module) {
388 $context = context_module::instance($module->id);
389 try {
390 self::validate_context($context);
391 require_capability('mod/assign:view', $context);
392 } catch (Exception $e) {
393 $warnings[] = array(
394 'item' => 'module',
395 'itemid' => $module->id,
396 'warningcode' => '1',
397 'message' => 'No access rights in module context'
398 );
399 continue;
400 }
401 $configrecords = $DB->get_recordset('assign_plugin_config', array('assignment' => $module->assignmentid));
402 $configarray = array();
403 foreach ($configrecords as $configrecord) {
404 $configarray[] = array(
405 'id' => $configrecord->id,
406 'assignment' => $configrecord->assignment,
407 'plugin' => $configrecord->plugin,
408 'subtype' => $configrecord->subtype,
409 'name' => $configrecord->name,
410 'value' => $configrecord->value
411 );
412 }
413 $configrecords->close();
414
4e2e3c95 415 $assignment = array(
1378838e
PC
416 'id' => $module->assignmentid,
417 'cmid' => $module->id,
418 'course' => $module->course,
419 'name' => $module->name,
420 'nosubmissions' => $module->nosubmissions,
421 'submissiondrafts' => $module->submissiondrafts,
422 'sendnotifications' => $module->sendnotifications,
423 'sendlatenotifications' => $module->sendlatenotifications,
8e1266bf 424 'sendstudentnotifications' => $module->sendstudentnotifications,
1378838e
PC
425 'duedate' => $module->duedate,
426 'allowsubmissionsfromdate' => $module->allowsubmissionsfromdate,
427 'grade' => $module->grade,
428 'timemodified' => $module->timemodified,
429 'completionsubmit' => $module->completionsubmit,
430 'cutoffdate' => $module->cutoffdate,
431 'teamsubmission' => $module->teamsubmission,
432 'requireallteammemberssubmit' => $module->requireallteammemberssubmit,
433 'teamsubmissiongroupingid' => $module->teamsubmissiongroupingid,
434 'blindmarking' => $module->blindmarking,
435 'revealidentities' => $module->revealidentities,
912cbaf1
PC
436 'attemptreopenmethod' => $module->attemptreopenmethod,
437 'maxattempts' => $module->maxattempts,
438 'markingworkflow' => $module->markingworkflow,
439 'markingallocation' => $module->markingallocation,
1378838e
PC
440 'requiresubmissionstatement' => $module->requiresubmissionstatement,
441 'configs' => $configarray
442 );
4e2e3c95
JL
443
444 // Return or not intro and file attachments depending on the plugin settings.
445 $assign = new assign($context, null, null);
446
447 if ($assign->show_intro()) {
448
449 list($assignment['intro'], $assignment['introformat']) = external_format_text($module->intro,
450 $module->introformat, $context->id, 'mod_assign', ASSIGN_INTROATTACHMENT_FILEAREA, 0);
451
452 $fs = get_file_storage();
453 if ($files = $fs->get_area_files($context->id, 'mod_assign', ASSIGN_INTROATTACHMENT_FILEAREA,
454 0, 'timemodified', false)) {
455
456 $assignment['introattachments'] = array();
457 foreach ($files as $file) {
458 $filename = $file->get_filename();
459
460 $assignment['introattachments'][] = array(
461 'filename' => $filename,
462 'mimetype' => $file->get_mimetype(),
463 'fileurl' => moodle_url::make_webservice_pluginfile_url(
464 $context->id, 'mod_assign', ASSIGN_INTROATTACHMENT_FILEAREA, 0, '/', $filename)->out(false)
465 );
466 }
467 }
468 }
469
470 $assignmentarray[] = $assignment;
1378838e
PC
471 }
472 }
473 $coursearray[]= array(
474 'id' => $courses[$id]->id,
475 'fullname' => $courses[$id]->fullname,
476 'shortname' => $courses[$id]->shortname,
477 'timemodified' => $courses[$id]->timemodified,
478 'assignments' => $assignmentarray
479 );
480 }
481
482 $result = array(
483 'courses' => $coursearray,
484 'warnings' => $warnings
485 );
486 return $result;
487 }
488
489 /**
490 * Creates an assignment external_single_structure
2ea4312a 491 *
1378838e
PC
492 * @return external_single_structure
493 * @since Moodle 2.4
494 */
495 private static function get_assignments_assignment_structure() {
496 return new external_single_structure(
497 array(
498 'id' => new external_value(PARAM_INT, 'assignment id'),
912cbaf1 499 'cmid' => new external_value(PARAM_INT, 'course module id'),
1378838e
PC
500 'course' => new external_value(PARAM_INT, 'course id'),
501 'name' => new external_value(PARAM_TEXT, 'assignment name'),
502 'nosubmissions' => new external_value(PARAM_INT, 'no submissions'),
503 'submissiondrafts' => new external_value(PARAM_INT, 'submissions drafts'),
504 'sendnotifications' => new external_value(PARAM_INT, 'send notifications'),
505 'sendlatenotifications' => new external_value(PARAM_INT, 'send notifications'),
8e1266bf 506 'sendstudentnotifications' => new external_value(PARAM_INT, 'send student notifications (default)'),
1378838e
PC
507 'duedate' => new external_value(PARAM_INT, 'assignment due date'),
508 'allowsubmissionsfromdate' => new external_value(PARAM_INT, 'allow submissions from date'),
509 'grade' => new external_value(PARAM_INT, 'grade type'),
510 'timemodified' => new external_value(PARAM_INT, 'last time assignment was modified'),
511 'completionsubmit' => new external_value(PARAM_INT, 'if enabled, set activity as complete following submission'),
512 'cutoffdate' => new external_value(PARAM_INT, 'date after which submission is not accepted without an extension'),
513 'teamsubmission' => new external_value(PARAM_INT, 'if enabled, students submit as a team'),
514 'requireallteammemberssubmit' => new external_value(PARAM_INT, 'if enabled, all team members must submit'),
515 'teamsubmissiongroupingid' => new external_value(PARAM_INT, 'the grouping id for the team submission groups'),
516 'blindmarking' => new external_value(PARAM_INT, 'if enabled, hide identities until reveal identities actioned'),
517 'revealidentities' => new external_value(PARAM_INT, 'show identities for a blind marking assignment'),
912cbaf1
PC
518 'attemptreopenmethod' => new external_value(PARAM_TEXT, 'method used to control opening new attempts'),
519 'maxattempts' => new external_value(PARAM_INT, 'maximum number of attempts allowed'),
520 'markingworkflow' => new external_value(PARAM_INT, 'enable marking workflow'),
521 'markingallocation' => new external_value(PARAM_INT, 'enable marking allocation'),
1378838e 522 'requiresubmissionstatement' => new external_value(PARAM_INT, 'student must accept submission statement'),
4e2e3c95
JL
523 'configs' => new external_multiple_structure(self::get_assignments_config_structure(), 'configuration settings'),
524 'intro' => new external_value(PARAM_RAW,
525 'assignment intro, not allways returned because it deppends on the activity configuration', VALUE_OPTIONAL),
526 'introformat' => new external_format_value('intro', VALUE_OPTIONAL),
527 'introattachments' => new external_multiple_structure(
528 new external_single_structure(
529 array (
530 'filename' => new external_value(PARAM_FILE, 'file name'),
531 'mimetype' => new external_value(PARAM_RAW, 'mime type'),
532 'fileurl' => new external_value(PARAM_URL, 'file download url')
533 )
534 ), 'intro attachments files', VALUE_OPTIONAL
535 )
1378838e
PC
536 ), 'assignment information object');
537 }
538
539 /**
540 * Creates an assign_plugin_config external_single_structure
2ea4312a 541 *
1378838e
PC
542 * @return external_single_structure
543 * @since Moodle 2.4
544 */
545 private static function get_assignments_config_structure() {
546 return new external_single_structure(
547 array(
548 'id' => new external_value(PARAM_INT, 'assign_plugin_config id'),
549 'assignment' => new external_value(PARAM_INT, 'assignment id'),
550 'plugin' => new external_value(PARAM_TEXT, 'plugin'),
551 'subtype' => new external_value(PARAM_TEXT, 'subtype'),
552 'name' => new external_value(PARAM_TEXT, 'name'),
553 'value' => new external_value(PARAM_TEXT, 'value')
554 ), 'assignment configuration object'
555 );
556 }
557
558 /**
559 * Creates a course external_single_structure
2ea4312a 560 *
1378838e 561 * @return external_single_structure
2ea4312a 562 * @since Moodle 2.4
1378838e
PC
563 */
564 private static function get_assignments_course_structure() {
565 return new external_single_structure(
566 array(
567 'id' => new external_value(PARAM_INT, 'course id'),
568 'fullname' => new external_value(PARAM_TEXT, 'course full name'),
569 'shortname' => new external_value(PARAM_TEXT, 'course short name'),
570 'timemodified' => new external_value(PARAM_INT, 'last time modified'),
571 'assignments' => new external_multiple_structure(self::get_assignments_assignment_structure(), 'assignment info')
572 ), 'course information object'
573 );
574 }
575
2ea4312a 576 /**
1378838e 577 * Describes the return value for get_assignments
2ea4312a 578 *
1378838e
PC
579 * @return external_single_structure
580 * @since Moodle 2.4
581 */
582 public static function get_assignments_returns() {
583 return new external_single_structure(
584 array(
585 'courses' => new external_multiple_structure(self::get_assignments_course_structure(), 'list of courses'),
8118dbd0
JM
586 'warnings' => new external_warnings('item can be \'course\' (errorcode 1 or 2) or \'module\' (errorcode 1)',
587 'When item is a course then itemid is a course id. When the item is a module then itemid is a module id',
588 'errorcode can be 1 (no access rights) or 2 (not enrolled or no permissions)')
1378838e
PC
589 )
590 );
591 }
c144959c 592
bdf1ac27
JL
593 /**
594 * Return information (files and text fields) for the given plugins in the assignment.
595 *
596 * @param assign $assign the assignment object
597 * @param array $assignplugins array of assignment plugins (submission or feedback)
598 * @param stdClass $item the item object (submission or grade)
599 * @return array an array containing the plugins returned information
600 */
601 private static function get_plugins_data($assign, $assignplugins, $item) {
602 global $CFG;
603
604 $plugins = array();
605 $fs = get_file_storage();
606
607 foreach ($assignplugins as $assignplugin) {
608
609 if (!$assignplugin->is_enabled() or !$assignplugin->is_visible()) {
610 continue;
611 }
612
613 $plugin = array(
614 'name' => $assignplugin->get_name(),
615 'type' => $assignplugin->get_type()
616 );
617 // Subtype is 'assignsubmission', type is currently 'file' or 'onlinetext'.
618 $component = $assignplugin->get_subtype().'_'.$assignplugin->get_type();
619
620 $fileareas = $assignplugin->get_file_areas();
621 foreach ($fileareas as $filearea => $name) {
622 $fileareainfo = array('area' => $filearea);
623 $files = $fs->get_area_files(
624 $assign->get_context()->id,
625 $component,
626 $filearea,
627 $item->id,
628 "timemodified",
629 false
630 );
631 foreach ($files as $file) {
632 $filepath = $file->get_filepath().$file->get_filename();
633 $fileurl = file_encode_url($CFG->wwwroot . '/webservice/pluginfile.php', '/' . $assign->get_context()->id .
634 '/' . $component. '/'. $filearea . '/' . $item->id . $filepath);
635 $fileinfo = array(
636 'filepath' => $filepath,
637 'fileurl' => $fileurl
638 );
639 $fileareainfo['files'][] = $fileinfo;
640 }
641 $plugin['fileareas'][] = $fileareainfo;
642 }
643
644 $editorfields = $assignplugin->get_editor_fields();
645 foreach ($editorfields as $name => $description) {
646 $editorfieldinfo = array(
647 'name' => $name,
648 'description' => $description,
649 'text' => $assignplugin->get_editor_text($name, $item->id),
650 'format' => $assignplugin->get_editor_format($name, $item->id)
651 );
652 $plugin['editorfields'][] = $editorfieldinfo;
653 }
654 $plugins[] = $plugin;
655 }
656 return $plugins;
657 }
658
c144959c
PC
659 /**
660 * Describes the parameters for get_submissions
661 *
662 * @return external_external_function_parameters
2d971403 663 * @since Moodle 2.5
c144959c
PC
664 */
665 public static function get_submissions_parameters() {
666 return new external_function_parameters(
667 array(
668 'assignmentids' => new external_multiple_structure(
669 new external_value(PARAM_INT, 'assignment id'),
670 '1 or more assignment ids',
671 VALUE_REQUIRED),
672 'status' => new external_value(PARAM_ALPHA, 'status', VALUE_DEFAULT, ''),
673 'since' => new external_value(PARAM_INT, 'submitted since', VALUE_DEFAULT, 0),
674 'before' => new external_value(PARAM_INT, 'submitted before', VALUE_DEFAULT, 0)
675 )
676 );
677 }
678
679 /**
680 * Returns submissions for the requested assignment ids
681 *
1561a37c 682 * @param int[] $assignmentids
c144959c
PC
683 * @param string $status only return submissions with this status
684 * @param int $since only return submissions with timemodified >= since
685 * @param int $before only return submissions with timemodified <= before
686 * @return array of submissions for each requested assignment
2d971403 687 * @since Moodle 2.5
c144959c
PC
688 */
689 public static function get_submissions($assignmentids, $status = '', $since = 0, $before = 0) {
690 global $DB, $CFG;
bdf1ac27 691
c144959c
PC
692 $params = self::validate_parameters(self::get_submissions_parameters(),
693 array('assignmentids' => $assignmentids,
694 'status' => $status,
695 'since' => $since,
696 'before' => $before));
697
698 $warnings = array();
699 $assignments = array();
700
701 // Check the user is allowed to get the submissions for the assignments requested.
702 $placeholders = array();
703 list($inorequalsql, $placeholders) = $DB->get_in_or_equal($params['assignmentids'], SQL_PARAMS_NAMED);
704 $sql = "SELECT cm.id, cm.instance FROM {course_modules} cm JOIN {modules} md ON md.id = cm.module ".
705 "WHERE md.name = :modname AND cm.instance ".$inorequalsql;
706 $placeholders['modname'] = 'assign';
707 $cms = $DB->get_records_sql($sql, $placeholders);
708 $assigns = array();
709 foreach ($cms as $cm) {
710 try {
711 $context = context_module::instance($cm->id);
712 self::validate_context($context);
713 require_capability('mod/assign:grade', $context);
714 $assign = new assign($context, null, null);
715 $assigns[] = $assign;
716 } catch (Exception $e) {
717 $warnings[] = array(
718 'item' => 'assignment',
719 'itemid' => $cm->instance,
720 'warningcode' => '1',
721 'message' => 'No access rights in module context'
722 );
723 }
724 }
725
726 foreach ($assigns as $assign) {
727 $submissions = array();
a13fbf5f
DW
728 $placeholders = array('assignid1' => $assign->get_instance()->id,
729 'assignid2' => $assign->get_instance()->id);
730
731 $submissionmaxattempt = 'SELECT mxs.userid, MAX(mxs.attemptnumber) AS maxattempt
732 FROM {assign_submission} mxs
733 WHERE mxs.assignment = :assignid1 GROUP BY mxs.userid';
734
c144959c 735 $sql = "SELECT mas.id, mas.assignment,mas.userid,".
05a6445a 736 "mas.timecreated,mas.timemodified,mas.status,mas.groupid,mas.attemptnumber ".
c144959c 737 "FROM {assign_submission} mas ".
a13fbf5f
DW
738 "JOIN ( " . $submissionmaxattempt . " ) smx ON mas.userid = smx.userid ".
739 "WHERE mas.assignment = :assignid2 AND mas.attemptnumber = smx.maxattempt";
c144959c
PC
740
741 if (!empty($params['status'])) {
742 $placeholders['status'] = $params['status'];
743 $sql = $sql." AND mas.status = :status";
744 }
745 if (!empty($params['before'])) {
746 $placeholders['since'] = $params['since'];
747 $placeholders['before'] = $params['before'];
748 $sql = $sql." AND mas.timemodified BETWEEN :since AND :before";
749 } else {
750 $placeholders['since'] = $params['since'];
751 $sql = $sql." AND mas.timemodified >= :since";
752 }
753
754 $submissionrecords = $DB->get_records_sql($sql, $placeholders);
755
756 if (!empty($submissionrecords)) {
bdf1ac27 757 $submissionplugins = $assign->get_submission_plugins();
c144959c
PC
758 foreach ($submissionrecords as $submissionrecord) {
759 $submission = array(
760 'id' => $submissionrecord->id,
761 'userid' => $submissionrecord->userid,
762 'timecreated' => $submissionrecord->timecreated,
763 'timemodified' => $submissionrecord->timemodified,
764 'status' => $submissionrecord->status,
05a6445a 765 'attemptnumber' => $submissionrecord->attemptnumber,
bdf1ac27
JL
766 'groupid' => $submissionrecord->groupid,
767 'plugins' => self::get_plugins_data($assign, $submissionplugins, $submissionrecord)
c144959c 768 );
c144959c
PC
769 $submissions[] = $submission;
770 }
771 } else {
772 $warnings[] = array(
773 'item' => 'module',
774 'itemid' => $assign->get_instance()->id,
775 'warningcode' => '3',
776 'message' => 'No submissions found'
777 );
778 }
779
780 $assignments[] = array(
781 'assignmentid' => $assign->get_instance()->id,
782 'submissions' => $submissions
783 );
784
785 }
786
787 $result = array(
788 'assignments' => $assignments,
789 'warnings' => $warnings
790 );
791 return $result;
792 }
793
794 /**
bdf1ac27 795 * Creates an assignment plugin structure.
c144959c 796 *
bdf1ac27 797 * @return external_single_structure the plugin structure
c144959c 798 */
bdf1ac27 799 private static function get_plugin_structure() {
c144959c 800 return new external_single_structure(
bdf1ac27
JL
801 array(
802 'type' => new external_value(PARAM_TEXT, 'submission plugin type'),
803 'name' => new external_value(PARAM_TEXT, 'submission plugin name'),
804 'fileareas' => new external_multiple_structure(
c144959c 805 new external_single_structure(
bdf1ac27
JL
806 array (
807 'area' => new external_value (PARAM_TEXT, 'file area'),
808 'files' => new external_multiple_structure(
c144959c 809 new external_single_structure(
bdf1ac27
JL
810 array (
811 'filepath' => new external_value (PARAM_TEXT, 'file path'),
812 'fileurl' => new external_value (PARAM_URL, 'file download url',
813 VALUE_OPTIONAL)
c144959c 814 )
bdf1ac27 815 ), 'files', VALUE_OPTIONAL
c144959c
PC
816 )
817 )
bdf1ac27
JL
818 ), 'fileareas', VALUE_OPTIONAL
819 ),
820 'editorfields' => new external_multiple_structure(
821 new external_single_structure(
822 array(
823 'name' => new external_value(PARAM_TEXT, 'field name'),
824 'description' => new external_value(PARAM_TEXT, 'field description'),
825 'text' => new external_value (PARAM_RAW, 'field value'),
826 'format' => new external_format_value ('text')
827 )
c144959c 828 )
bdf1ac27 829 , 'editorfields', VALUE_OPTIONAL
c144959c
PC
830 )
831 )
832 );
833 }
834
bdf1ac27
JL
835 /**
836 * Creates a submission structure.
837 *
838 * @return external_single_structure the submission structure
839 */
840 private static function get_submission_structure($required = VALUE_REQUIRED) {
841 return new external_single_structure(
842 array(
843 'id' => new external_value(PARAM_INT, 'submission id'),
844 'userid' => new external_value(PARAM_INT, 'student id'),
845 'attemptnumber' => new external_value(PARAM_INT, 'attempt number'),
846 'timecreated' => new external_value(PARAM_INT, 'submission creation time'),
847 'timemodified' => new external_value(PARAM_INT, 'submission last modified time'),
848 'status' => new external_value(PARAM_TEXT, 'submission status'),
849 'groupid' => new external_value(PARAM_INT, 'group id'),
850 'assignment' => new external_value(PARAM_INT, 'assignment id', VALUE_OPTIONAL),
851 'latest' => new external_value(PARAM_INT, 'latest attempt', VALUE_OPTIONAL),
852 'plugins' => new external_multiple_structure(self::get_plugin_structure(), 'plugins', VALUE_OPTIONAL)
853 ), 'submission info', $required
854 );
855 }
856
857 /**
858 * Creates an assign_submissions external_single_structure
859 *
860 * @return external_single_structure
861 * @since Moodle 2.5
862 */
863 private static function get_submissions_structure() {
864 return new external_single_structure(
865 array (
866 'assignmentid' => new external_value(PARAM_INT, 'assignment id'),
867 'submissions' => new external_multiple_structure(self::get_submission_structure())
868 )
869 );
870 }
871
c144959c
PC
872 /**
873 * Describes the get_submissions return value
874 *
875 * @return external_single_structure
2d971403 876 * @since Moodle 2.5
c144959c
PC
877 */
878 public static function get_submissions_returns() {
879 return new external_single_structure(
880 array(
881 'assignments' => new external_multiple_structure(self::get_submissions_structure(), 'assignment submissions'),
882 'warnings' => new external_warnings()
883 )
884 );
885 }
07df8c38 886
e8b443df
PC
887 /**
888 * Describes the parameters for set_user_flags
889 * @return external_function_parameters
890 * @since Moodle 2.6
891 */
892 public static function set_user_flags_parameters() {
893 return new external_function_parameters(
894 array(
895 'assignmentid' => new external_value(PARAM_INT, 'assignment id'),
896 'userflags' => new external_multiple_structure(
897 new external_single_structure(
898 array(
899 'userid' => new external_value(PARAM_INT, 'student id'),
900 'locked' => new external_value(PARAM_INT, 'locked', VALUE_OPTIONAL),
901 'mailed' => new external_value(PARAM_INT, 'mailed', VALUE_OPTIONAL),
902 'extensionduedate' => new external_value(PARAM_INT, 'extension due date', VALUE_OPTIONAL),
903 'workflowstate' => new external_value(PARAM_TEXT, 'marking workflow state', VALUE_OPTIONAL),
904 'allocatedmarker' => new external_value(PARAM_INT, 'allocated marker', VALUE_OPTIONAL)
905 )
906 )
907 )
908 )
909 );
910 }
911
912 /**
913 * Create or update user_flags records
914 *
915 * @param int $assignmentid the assignment for which the userflags are created or updated
916 * @param array $userflags An array of userflags to create or update
917 * @return array containing success or failure information for each record
918 * @since Moodle 2.6
919 */
920 public static function set_user_flags($assignmentid, $userflags = array()) {
921 global $CFG, $DB;
e8b443df
PC
922
923 $params = self::validate_parameters(self::set_user_flags_parameters(),
924 array('assignmentid' => $assignmentid,
925 'userflags' => $userflags));
926
927 // Load assignment if it exists and if the user has the capability.
928 $cm = get_coursemodule_from_instance('assign', $params['assignmentid'], 0, false, MUST_EXIST);
929 $context = context_module::instance($cm->id);
930 self::validate_context($context);
931 require_capability('mod/assign:grade', $context);
932 $assign = new assign($context, null, null);
933
934 $results = array();
935 foreach ($params['userflags'] as $userflag) {
936 $success = true;
937 $result = array();
938
939 $record = $assign->get_user_flags($userflag['userid'], false);
940 if ($record) {
941 if (isset($userflag['locked'])) {
942 $record->locked = $userflag['locked'];
943 }
944 if (isset($userflag['mailed'])) {
945 $record->mailed = $userflag['mailed'];
946 }
947 if (isset($userflag['extensionduedate'])) {
948 $record->extensionduedate = $userflag['extensionduedate'];
949 }
950 if (isset($userflag['workflowstate'])) {
951 $record->workflowstate = $userflag['workflowstate'];
952 }
953 if (isset($userflag['allocatedmarker'])) {
954 $record->allocatedmarker = $userflag['allocatedmarker'];
955 }
956 if ($assign->update_user_flags($record)) {
957 $result['id'] = $record->id;
958 $result['userid'] = $userflag['userid'];
959 } else {
960 $result['id'] = $record->id;
961 $result['userid'] = $userflag['userid'];
962 $result['errormessage'] = 'Record created but values could not be set';
963 }
964 } else {
965 $record = $assign->get_user_flags($userflag['userid'], true);
966 $setfields = isset($userflag['locked'])
967 || isset($userflag['mailed'])
968 || isset($userflag['extensionduedate'])
969 || isset($userflag['workflowstate'])
970 || isset($userflag['allocatedmarker']);
971 if ($record) {
972 if ($setfields) {
973 if (isset($userflag['locked'])) {
974 $record->locked = $userflag['locked'];
975 }
976 if (isset($userflag['mailed'])) {
977 $record->mailed = $userflag['mailed'];
978 }
979 if (isset($userflag['extensionduedate'])) {
980 $record->extensionduedate = $userflag['extensionduedate'];
981 }
982 if (isset($userflag['workflowstate'])) {
983 $record->workflowstate = $userflag['workflowstate'];
984 }
985 if (isset($userflag['allocatedmarker'])) {
986 $record->allocatedmarker = $userflag['allocatedmarker'];
987 }
988 if ($assign->update_user_flags($record)) {
989 $result['id'] = $record->id;
990 $result['userid'] = $userflag['userid'];
991 } else {
992 $result['id'] = $record->id;
993 $result['userid'] = $userflag['userid'];
994 $result['errormessage'] = 'Record created but values could not be set';
995 }
996 } else {
997 $result['id'] = $record->id;
998 $result['userid'] = $userflag['userid'];
999 }
1000 } else {
1001 $result['id'] = -1;
1002 $result['userid'] = $userflag['userid'];
1003 $result['errormessage'] = 'Record could not be created';
1004 }
1005 }
1006
1007 $results[] = $result;
1008 }
1009 return $results;
1010 }
1011
1012 /**
1013 * Describes the set_user_flags return value
1014 * @return external_multiple_structure
1015 * @since Moodle 2.6
1016 */
1017 public static function set_user_flags_returns() {
1018 return new external_multiple_structure(
1019 new external_single_structure(
1020 array(
1021 'id' => new external_value(PARAM_INT, 'id of record if successful, -1 for failure'),
1022 'userid' => new external_value(PARAM_INT, 'userid of record'),
1023 'errormessage' => new external_value(PARAM_TEXT, 'Failure error message', VALUE_OPTIONAL)
1024 )
1025 )
1026 );
1027 }
1028
07df8c38
PC
1029 /**
1030 * Describes the parameters for get_user_flags
1031 * @return external_function_parameters
1032 * @since Moodle 2.6
1033 */
1034 public static function get_user_flags_parameters() {
1035 return new external_function_parameters(
1036 array(
1037 'assignmentids' => new external_multiple_structure(
1038 new external_value(PARAM_INT, 'assignment id'),
1039 '1 or more assignment ids',
1040 VALUE_REQUIRED)
1041 )
1042 );
1043 }
1044
1045 /**
1046 * Returns user flag information from assign_user_flags for the requested assignment ids
1561a37c 1047 * @param int[] $assignmentids
07df8c38
PC
1048 * @return array of user flag records for each requested assignment
1049 * @since Moodle 2.6
1050 */
1051 public static function get_user_flags($assignmentids) {
1052 global $DB;
1053 $params = self::validate_parameters(self::get_user_flags_parameters(),
1054 array('assignmentids' => $assignmentids));
1055
1056 $assignments = array();
1057 $warnings = array();
1058 $requestedassignmentids = $params['assignmentids'];
1059
1060 // Check the user is allowed to get the user flags for the assignments requested.
1061 $placeholders = array();
1062 list($sqlassignmentids, $placeholders) = $DB->get_in_or_equal($requestedassignmentids, SQL_PARAMS_NAMED);
1063 $sql = "SELECT cm.id, cm.instance FROM {course_modules} cm JOIN {modules} md ON md.id = cm.module ".
1064 "WHERE md.name = :modname AND cm.instance ".$sqlassignmentids;
1065 $placeholders['modname'] = 'assign';
1066 $cms = $DB->get_records_sql($sql, $placeholders);
1067 foreach ($cms as $cm) {
1068 try {
1069 $context = context_module::instance($cm->id);
1070 self::validate_context($context);
1071 require_capability('mod/assign:grade', $context);
1072 } catch (Exception $e) {
1073 $requestedassignmentids = array_diff($requestedassignmentids, array($cm->instance));
1074 $warning = array();
1075 $warning['item'] = 'assignment';
1076 $warning['itemid'] = $cm->instance;
1077 $warning['warningcode'] = '1';
1078 $warning['message'] = 'No access rights in module context';
1079 $warnings[] = $warning;
1080 }
1081 }
1082
1083 // Create the query and populate an array of assign_user_flags records from the recordset results.
1084 if (count ($requestedassignmentids) > 0) {
1085 $placeholders = array();
1086 list($inorequalsql, $placeholders) = $DB->get_in_or_equal($requestedassignmentids, SQL_PARAMS_NAMED);
1087
1088 $sql = "SELECT auf.id,auf.assignment,auf.userid,auf.locked,auf.mailed,".
1089 "auf.extensionduedate,auf.workflowstate,auf.allocatedmarker ".
1090 "FROM {assign_user_flags} auf ".
1091 "WHERE auf.assignment ".$inorequalsql.
1092 " ORDER BY auf.assignment, auf.id";
1093
1094 $rs = $DB->get_recordset_sql($sql, $placeholders);
1095 $currentassignmentid = null;
1096 $assignment = null;
1097 foreach ($rs as $rd) {
1098 $userflag = array();
1099 $userflag['id'] = $rd->id;
1100 $userflag['userid'] = $rd->userid;
1101 $userflag['locked'] = $rd->locked;
1102 $userflag['mailed'] = $rd->mailed;
1103 $userflag['extensionduedate'] = $rd->extensionduedate;
1104 $userflag['workflowstate'] = $rd->workflowstate;
1105 $userflag['allocatedmarker'] = $rd->allocatedmarker;
1106
1107 if (is_null($currentassignmentid) || ($rd->assignment != $currentassignmentid )) {
1108 if (!is_null($assignment)) {
1109 $assignments[] = $assignment;
1110 }
1111 $assignment = array();
1112 $assignment['assignmentid'] = $rd->assignment;
1113 $assignment['userflags'] = array();
1114 $requestedassignmentids = array_diff($requestedassignmentids, array($rd->assignment));
1115 }
1116 $assignment['userflags'][] = $userflag;
1117
1118 $currentassignmentid = $rd->assignment;
1119 }
1120 if (!is_null($assignment)) {
1121 $assignments[] = $assignment;
1122 }
1123 $rs->close();
1124
1125 }
1126
1127 foreach ($requestedassignmentids as $assignmentid) {
1128 $warning = array();
1129 $warning['item'] = 'assignment';
1130 $warning['itemid'] = $assignmentid;
1131 $warning['warningcode'] = '3';
1132 $warning['message'] = 'No user flags found';
1133 $warnings[] = $warning;
1134 }
1135
1136 $result = array();
1137 $result['assignments'] = $assignments;
1138 $result['warnings'] = $warnings;
1139 return $result;
1140 }
1141
1142 /**
1143 * Creates an assign_user_flags external_single_structure
1144 * @return external_single_structure
1145 * @since Moodle 2.6
1146 */
1147 private static function assign_user_flags() {
1148 return new external_single_structure(
1149 array (
1150 'assignmentid' => new external_value(PARAM_INT, 'assignment id'),
1151 'userflags' => new external_multiple_structure(new external_single_structure(
1152 array(
1153 'id' => new external_value(PARAM_INT, 'user flag id'),
1154 'userid' => new external_value(PARAM_INT, 'student id'),
1155 'locked' => new external_value(PARAM_INT, 'locked'),
1156 'mailed' => new external_value(PARAM_INT, 'mailed'),
1157 'extensionduedate' => new external_value(PARAM_INT, 'extension due date'),
1158 'workflowstate' => new external_value(PARAM_TEXT, 'marking workflow state', VALUE_OPTIONAL),
1159 'allocatedmarker' => new external_value(PARAM_INT, 'allocated marker')
1160 )
1161 )
1162 )
1163 )
1164 );
1165 }
1166
1167 /**
1168 * Describes the get_user_flags return value
1169 * @return external_single_structure
1170 * @since Moodle 2.6
1171 */
1172 public static function get_user_flags_returns() {
1173 return new external_single_structure(
1174 array(
1175 'assignments' => new external_multiple_structure(self::assign_user_flags(), 'list of assign user flag information'),
1176 'warnings' => new external_warnings('item is always \'assignment\'',
1177 'when errorcode is 3 then itemid is an assignment id. When errorcode is 1, itemid is a course module id',
1178 'errorcode can be 3 (no user flags found) or 1 (no permission to get user flags)')
1179 )
1180 );
1181 }
1182
1183 /**
1184 * Describes the parameters for get_user_mappings
1185 * @return external_function_parameters
1186 * @since Moodle 2.6
1187 */
1188 public static function get_user_mappings_parameters() {
1189 return new external_function_parameters(
1190 array(
1191 'assignmentids' => new external_multiple_structure(
1192 new external_value(PARAM_INT, 'assignment id'),
1193 '1 or more assignment ids',
1194 VALUE_REQUIRED)
1195 )
1196 );
1197 }
1198
1199 /**
1200 * Returns user mapping information from assign_user_mapping for the requested assignment ids
1561a37c 1201 * @param int[] $assignmentids
07df8c38
PC
1202 * @return array of user mapping records for each requested assignment
1203 * @since Moodle 2.6
1204 */
1205 public static function get_user_mappings($assignmentids) {
1206 global $DB;
1207 $params = self::validate_parameters(self::get_user_mappings_parameters(),
1208 array('assignmentids' => $assignmentids));
1209
1210 $assignments = array();
1211 $warnings = array();
1212 $requestedassignmentids = $params['assignmentids'];
1213
1214 // Check the user is allowed to get the mappings for the assignments requested.
1215 $placeholders = array();
1216 list($sqlassignmentids, $placeholders) = $DB->get_in_or_equal($requestedassignmentids, SQL_PARAMS_NAMED);
1217 $sql = "SELECT cm.id, cm.instance FROM {course_modules} cm JOIN {modules} md ON md.id = cm.module ".
1218 "WHERE md.name = :modname AND cm.instance ".$sqlassignmentids;
1219 $placeholders['modname'] = 'assign';
1220 $cms = $DB->get_records_sql($sql, $placeholders);
1221 foreach ($cms as $cm) {
1222 try {
1223 $context = context_module::instance($cm->id);
1224 self::validate_context($context);
1225 require_capability('mod/assign:revealidentities', $context);
1226 } catch (Exception $e) {
1227 $requestedassignmentids = array_diff($requestedassignmentids, array($cm->instance));
1228 $warning = array();
1229 $warning['item'] = 'assignment';
1230 $warning['itemid'] = $cm->instance;
1231 $warning['warningcode'] = '1';
1232 $warning['message'] = 'No access rights in module context';
1233 $warnings[] = $warning;
1234 }
1235 }
1236
1237 // Create the query and populate an array of assign_user_mapping records from the recordset results.
1238 if (count ($requestedassignmentids) > 0) {
1239 $placeholders = array();
1240 list($inorequalsql, $placeholders) = $DB->get_in_or_equal($requestedassignmentids, SQL_PARAMS_NAMED);
1241
1242 $sql = "SELECT aum.id,aum.assignment,aum.userid ".
1243 "FROM {assign_user_mapping} aum ".
1244 "WHERE aum.assignment ".$inorequalsql.
1245 " ORDER BY aum.assignment, aum.id";
1246
1247 $rs = $DB->get_recordset_sql($sql, $placeholders);
1248 $currentassignmentid = null;
1249 $assignment = null;
1250 foreach ($rs as $rd) {
1251 $mapping = array();
1252 $mapping['id'] = $rd->id;
1253 $mapping['userid'] = $rd->userid;
1254
1255 if (is_null($currentassignmentid) || ($rd->assignment != $currentassignmentid )) {
1256 if (!is_null($assignment)) {
1257 $assignments[] = $assignment;
1258 }
1259 $assignment = array();
1260 $assignment['assignmentid'] = $rd->assignment;
1261 $assignment['mappings'] = array();
1262 $requestedassignmentids = array_diff($requestedassignmentids, array($rd->assignment));
1263 }
1264 $assignment['mappings'][] = $mapping;
1265
1266 $currentassignmentid = $rd->assignment;
1267 }
1268 if (!is_null($assignment)) {
1269 $assignments[] = $assignment;
1270 }
1271 $rs->close();
1272
1273 }
1274
1275 foreach ($requestedassignmentids as $assignmentid) {
1276 $warning = array();
1277 $warning['item'] = 'assignment';
1278 $warning['itemid'] = $assignmentid;
1279 $warning['warningcode'] = '3';
1280 $warning['message'] = 'No mappings found';
1281 $warnings[] = $warning;
1282 }
1283
1284 $result = array();
1285 $result['assignments'] = $assignments;
1286 $result['warnings'] = $warnings;
1287 return $result;
1288 }
1289
1290 /**
1291 * Creates an assign_user_mappings external_single_structure
1292 * @return external_single_structure
1293 * @since Moodle 2.6
1294 */
1295 private static function assign_user_mappings() {
1296 return new external_single_structure(
1297 array (
1298 'assignmentid' => new external_value(PARAM_INT, 'assignment id'),
1299 'mappings' => new external_multiple_structure(new external_single_structure(
1300 array(
1301 'id' => new external_value(PARAM_INT, 'user mapping id'),
1302 'userid' => new external_value(PARAM_INT, 'student id')
1303 )
1304 )
1305 )
1306 )
1307 );
1308 }
1309
1310 /**
1311 * Describes the get_user_mappings return value
1312 * @return external_single_structure
1313 * @since Moodle 2.6
1314 */
1315 public static function get_user_mappings_returns() {
1316 return new external_single_structure(
1317 array(
1318 'assignments' => new external_multiple_structure(self::assign_user_mappings(), 'list of assign user mapping data'),
1319 'warnings' => new external_warnings('item is always \'assignment\'',
1320 'when errorcode is 3 then itemid is an assignment id. When errorcode is 1, itemid is a course module id',
1321 'errorcode can be 3 (no user mappings found) or 1 (no permission to get user mappings)')
1322 )
1323 );
1324 }
1325
05a6445a
DW
1326 /**
1327 * Describes the parameters for lock_submissions
1328 * @return external_external_function_parameters
1329 * @since Moodle 2.6
1330 */
1331 public static function lock_submissions_parameters() {
1332 return new external_function_parameters(
1333 array(
1334 'assignmentid' => new external_value(PARAM_INT, 'The assignment id to operate on'),
1335 'userids' => new external_multiple_structure(
1336 new external_value(PARAM_INT, 'user id'),
1337 '1 or more user ids',
1338 VALUE_REQUIRED),
1339 )
1340 );
1341 }
1342
1343 /**
1344 * Locks (prevent updates to) submissions in this assignment.
1345 *
1346 * @param int $assignmentid The id of the assignment
1347 * @param array $userids Array of user ids to lock
1348 * @return array of warnings for each submission that could not be locked.
1349 * @since Moodle 2.6
1350 */
1351 public static function lock_submissions($assignmentid, $userids) {
1352 global $CFG;
05a6445a
DW
1353
1354 $params = self::validate_parameters(self::lock_submissions_parameters(),
1355 array('assignmentid' => $assignmentid,
1356 'userids' => $userids));
1357
695a18b6 1358 $cm = get_coursemodule_from_instance('assign', $params['assignmentid'], 0, false, MUST_EXIST);
05a6445a 1359 $context = context_module::instance($cm->id);
695a18b6 1360 self::validate_context($context);
05a6445a
DW
1361
1362 $assignment = new assign($context, $cm, null);
1363
1364 $warnings = array();
695a18b6 1365 foreach ($params['userids'] as $userid) {
05a6445a 1366 if (!$assignment->lock_submission($userid)) {
695a18b6
FM
1367 $detail = 'User id: ' . $userid . ', Assignment id: ' . $params['assignmentid'];
1368 $warnings[] = self::generate_warning($params['assignmentid'],
05a6445a
DW
1369 'couldnotlock',
1370 $detail);
1371 }
1372 }
1373
1374 return $warnings;
1375 }
1376
1377 /**
1378 * Describes the return value for lock_submissions
1379 *
1380 * @return external_single_structure
1381 * @since Moodle 2.6
1382 */
1383 public static function lock_submissions_returns() {
13e814bc 1384 return new external_warnings();
05a6445a
DW
1385 }
1386
1387 /**
1388 * Describes the parameters for revert_submissions_to_draft
1389 * @return external_external_function_parameters
1390 * @since Moodle 2.6
1391 */
1392 public static function revert_submissions_to_draft_parameters() {
1393 return new external_function_parameters(
1394 array(
1395 'assignmentid' => new external_value(PARAM_INT, 'The assignment id to operate on'),
1396 'userids' => new external_multiple_structure(
1397 new external_value(PARAM_INT, 'user id'),
1398 '1 or more user ids',
1399 VALUE_REQUIRED),
1400 )
1401 );
1402 }
1403
1404 /**
1405 * Reverts a list of user submissions to draft for a single assignment.
1406 *
1407 * @param int $assignmentid The id of the assignment
1408 * @param array $userids Array of user ids to revert
1409 * @return array of warnings for each submission that could not be reverted.
1410 * @since Moodle 2.6
1411 */
1412 public static function revert_submissions_to_draft($assignmentid, $userids) {
1413 global $CFG;
05a6445a
DW
1414
1415 $params = self::validate_parameters(self::revert_submissions_to_draft_parameters(),
1416 array('assignmentid' => $assignmentid,
1417 'userids' => $userids));
1418
695a18b6 1419 $cm = get_coursemodule_from_instance('assign', $params['assignmentid'], 0, false, MUST_EXIST);
05a6445a 1420 $context = context_module::instance($cm->id);
695a18b6 1421 self::validate_context($context);
05a6445a
DW
1422
1423 $assignment = new assign($context, $cm, null);
1424
1425 $warnings = array();
695a18b6 1426 foreach ($params['userids'] as $userid) {
05a6445a 1427 if (!$assignment->revert_to_draft($userid)) {
695a18b6
FM
1428 $detail = 'User id: ' . $userid . ', Assignment id: ' . $params['assignmentid'];
1429 $warnings[] = self::generate_warning($params['assignmentid'],
05a6445a
DW
1430 'couldnotrevert',
1431 $detail);
1432 }
1433 }
1434
1435 return $warnings;
1436 }
1437
1438 /**
1439 * Describes the return value for revert_submissions_to_draft
1440 *
1441 * @return external_single_structure
1442 * @since Moodle 2.6
1443 */
1444 public static function revert_submissions_to_draft_returns() {
13e814bc 1445 return new external_warnings();
05a6445a
DW
1446 }
1447
1448 /**
1449 * Describes the parameters for unlock_submissions
1450 * @return external_external_function_parameters
1451 * @since Moodle 2.6
1452 */
1453 public static function unlock_submissions_parameters() {
1454 return new external_function_parameters(
1455 array(
1456 'assignmentid' => new external_value(PARAM_INT, 'The assignment id to operate on'),
1457 'userids' => new external_multiple_structure(
1458 new external_value(PARAM_INT, 'user id'),
1459 '1 or more user ids',
1460 VALUE_REQUIRED),
1461 )
1462 );
1463 }
1464
1465 /**
1466 * Locks (prevent updates to) submissions in this assignment.
1467 *
1468 * @param int $assignmentid The id of the assignment
1469 * @param array $userids Array of user ids to lock
1470 * @return array of warnings for each submission that could not be locked.
1471 * @since Moodle 2.6
1472 */
1473 public static function unlock_submissions($assignmentid, $userids) {
1474 global $CFG;
05a6445a
DW
1475
1476 $params = self::validate_parameters(self::unlock_submissions_parameters(),
1477 array('assignmentid' => $assignmentid,
1478 'userids' => $userids));
1479
695a18b6 1480 $cm = get_coursemodule_from_instance('assign', $params['assignmentid'], 0, false, MUST_EXIST);
05a6445a 1481 $context = context_module::instance($cm->id);
695a18b6 1482 self::validate_context($context);
05a6445a
DW
1483
1484 $assignment = new assign($context, $cm, null);
1485
1486 $warnings = array();
695a18b6 1487 foreach ($params['userids'] as $userid) {
05a6445a 1488 if (!$assignment->unlock_submission($userid)) {
695a18b6
FM
1489 $detail = 'User id: ' . $userid . ', Assignment id: ' . $params['assignmentid'];
1490 $warnings[] = self::generate_warning($params['assignmentid'],
05a6445a
DW
1491 'couldnotunlock',
1492 $detail);
1493 }
1494 }
1495
1496 return $warnings;
1497 }
1498
1499 /**
1500 * Describes the return value for unlock_submissions
1501 *
1502 * @return external_single_structure
1503 * @since Moodle 2.6
1504 */
1505 public static function unlock_submissions_returns() {
13e814bc 1506 return new external_warnings();
05a6445a
DW
1507 }
1508
84a32f15
DW
1509 /**
1510 * Describes the parameters for submit_grading_form webservice.
1511 * @return external_external_function_parameters
1512 * @since Moodle 3.1
1513 */
1514 public static function submit_grading_form_parameters() {
1515 return new external_function_parameters(
1516 array(
1517 'assignmentid' => new external_value(PARAM_INT, 'The assignment id to operate on'),
1518 'userid' => new external_value(PARAM_INT, 'The user id the submission belongs to'),
1519 'jsonformdata' => new external_value(PARAM_RAW, 'The data from the grading form, encoded as a json array')
1520 )
1521 );
1522 }
1523
1524 /**
1525 * Submit the logged in users assignment for grading.
1526 *
1527 * @param int $assignmentid The id of the assignment
1528 * @param int $userid The id of the user the submission belongs to.
1529 * @param string $jsonformdata The data from the form, encoded as a json array.
1530 * @return array of warnings to indicate any errors.
1531 * @since Moodle 2.6
1532 */
1533 public static function submit_grading_form($assignmentid, $userid, $jsonformdata) {
1534 global $CFG, $USER;
1535
1536 require_once($CFG->dirroot . '/mod/assign/locallib.php');
1537 require_once($CFG->dirroot . '/mod/assign/gradeform.php');
1538
1539 $params = self::validate_parameters(self::submit_grading_form_parameters(),
1540 array('assignmentid' => $assignmentid,
1541 'userid' => $userid,
1542 'jsonformdata' => $jsonformdata));
1543
1544 $cm = get_coursemodule_from_instance('assign', $params['assignmentid'], 0, false, MUST_EXIST);
1545 $context = context_module::instance($cm->id);
1546 self::validate_context($context);
1547
1548 $assignment = new assign($context, $cm, null);
1549
1550 $serialiseddata = json_decode($params['jsonformdata']);
1551
1552 $data = array();
1553 parse_str($serialiseddata, $data);
1554
1555 $warnings = array();
1556
1557 $options = array('userid'=>$params['userid'],
1558 'attemptnumber'=>$data['attemptnumber'],
1559 'rownum'=>0,
1560 'gradingpanel' => true);
1561
1562 $customdata = (object) $data;
1563 $formparams = array($assignment, $customdata, $options);
1564
1565 // Data is injected into the form by the last param for the constructor.
1566 $mform = new mod_assign_grade_form(null, $formparams, 'post', '', null, true, $data);
1567 $validateddata = $mform->get_data();
1568
1569 if ($validateddata) {
1570 $assignment->save_grade($params['userid'], $validateddata);
1571 } else {
1572 $warnings[] = self::generate_warning($params['assignmentid'],
1573 'couldnotsavegrade',
1574 'Form validation failed.');
1575 }
1576
1577
1578 return $warnings;
1579 }
1580
1581 /**
1582 * Describes the return for submit_grading_form
1583 * @return external_external_function_parameters
1584 * @since Moodle 3.1
1585 */
1586 public static function submit_grading_form_returns() {
1587 return new external_warnings();
1588 }
1589
05a6445a 1590 /**
91327d96 1591 * Describes the parameters for submit_for_grading
05a6445a
DW
1592 * @return external_external_function_parameters
1593 * @since Moodle 2.6
1594 */
1595 public static function submit_for_grading_parameters() {
1596 return new external_function_parameters(
1597 array(
91327d96
DW
1598 'assignmentid' => new external_value(PARAM_INT, 'The assignment id to operate on'),
1599 'acceptsubmissionstatement' => new external_value(PARAM_BOOL, 'Accept the assignment submission statement')
05a6445a
DW
1600 )
1601 );
1602 }
1603
1604 /**
1605 * Submit the logged in users assignment for grading.
1606 *
1607 * @param int $assignmentid The id of the assignment
1608 * @return array of warnings to indicate any errors.
1609 * @since Moodle 2.6
1610 */
91327d96 1611 public static function submit_for_grading($assignmentid, $acceptsubmissionstatement) {
05a6445a 1612 global $CFG, $USER;
05a6445a
DW
1613
1614 $params = self::validate_parameters(self::submit_for_grading_parameters(),
91327d96
DW
1615 array('assignmentid' => $assignmentid,
1616 'acceptsubmissionstatement' => $acceptsubmissionstatement));
05a6445a 1617
695a18b6 1618 $cm = get_coursemodule_from_instance('assign', $params['assignmentid'], 0, false, MUST_EXIST);
05a6445a 1619 $context = context_module::instance($cm->id);
695a18b6 1620 self::validate_context($context);
05a6445a
DW
1621
1622 $assignment = new assign($context, $cm, null);
1623
1624 $warnings = array();
91327d96 1625 $data = new stdClass();
695a18b6 1626 $data->submissionstatement = $params['acceptsubmissionstatement'];
57fbd5f9 1627 $notices = array();
91327d96 1628
57fbd5f9 1629 if (!$assignment->submit_for_grading($data, $notices)) {
695a18b6
FM
1630 $detail = 'User id: ' . $USER->id . ', Assignment id: ' . $params['assignmentid'] . ' Notices:' . implode(', ', $notices);
1631 $warnings[] = self::generate_warning($params['assignmentid'],
05a6445a
DW
1632 'couldnotsubmitforgrading',
1633 $detail);
1634 }
1635
1636 return $warnings;
1637 }
1638
1639 /**
1640 * Describes the return value for submit_for_grading
1641 *
1642 * @return external_single_structure
1643 * @since Moodle 2.6
1644 */
1645 public static function submit_for_grading_returns() {
13e814bc 1646 return new external_warnings();
05a6445a
DW
1647 }
1648
1649 /**
1650 * Describes the parameters for save_user_extensions
1651 * @return external_external_function_parameters
1652 * @since Moodle 2.6
1653 */
1654 public static function save_user_extensions_parameters() {
1655 return new external_function_parameters(
1656 array(
1657 'assignmentid' => new external_value(PARAM_INT, 'The assignment id to operate on'),
1658 'userids' => new external_multiple_structure(
1659 new external_value(PARAM_INT, 'user id'),
1660 '1 or more user ids',
1661 VALUE_REQUIRED),
1662 'dates' => new external_multiple_structure(
1663 new external_value(PARAM_INT, 'dates'),
1664 '1 or more extension dates (timestamp)',
1665 VALUE_REQUIRED),
1666 )
1667 );
1668 }
1669
1670 /**
1671 * Grant extension dates to students for an assignment.
1672 *
1673 * @param int $assignmentid The id of the assignment
1674 * @param array $userids Array of user ids to grant extensions to
1675 * @param array $dates Array of extension dates
1676 * @return array of warnings for each extension date that could not be granted
1677 * @since Moodle 2.6
1678 */
1679 public static function save_user_extensions($assignmentid, $userids, $dates) {
1680 global $CFG;
05a6445a
DW
1681
1682 $params = self::validate_parameters(self::save_user_extensions_parameters(),
1683 array('assignmentid' => $assignmentid,
1684 'userids' => $userids,
1685 'dates' => $dates));
1686
695a18b6 1687 if (count($params['userids']) != count($params['dates'])) {
05a6445a 1688 $detail = 'Length of userids and dates parameters differ.';
695a18b6 1689 $warnings[] = self::generate_warning($params['assignmentid'],
05a6445a
DW
1690 'invalidparameters',
1691 $detail);
1692
1693 return $warnings;
1694 }
1695
695a18b6 1696 $cm = get_coursemodule_from_instance('assign', $params['assignmentid'], 0, false, MUST_EXIST);
05a6445a 1697 $context = context_module::instance($cm->id);
695a18b6 1698 self::validate_context($context);
05a6445a
DW
1699
1700 $assignment = new assign($context, $cm, null);
1701
1702 $warnings = array();
695a18b6
FM
1703 foreach ($params['userids'] as $idx => $userid) {
1704 $duedate = $params['dates'][$idx];
05a6445a 1705 if (!$assignment->save_user_extension($userid, $duedate)) {
695a18b6
FM
1706 $detail = 'User id: ' . $userid . ', Assignment id: ' . $params['assignmentid'] . ', Extension date: ' . $duedate;
1707 $warnings[] = self::generate_warning($params['assignmentid'],
05a6445a
DW
1708 'couldnotgrantextensions',
1709 $detail);
1710 }
1711 }
1712
1713 return $warnings;
1714 }
1715
1716 /**
1717 * Describes the return value for save_user_extensions
1718 *
1719 * @return external_single_structure
1720 * @since Moodle 2.6
1721 */
1722 public static function save_user_extensions_returns() {
13e814bc 1723 return new external_warnings();
05a6445a
DW
1724 }
1725
1726 /**
1727 * Describes the parameters for reveal_identities
1728 * @return external_external_function_parameters
1729 * @since Moodle 2.6
1730 */
1731 public static function reveal_identities_parameters() {
1732 return new external_function_parameters(
1733 array(
1734 'assignmentid' => new external_value(PARAM_INT, 'The assignment id to operate on')
1735 )
1736 );
1737 }
1738
1739 /**
1740 * Reveal the identities of anonymous students to markers for a single assignment.
1741 *
1742 * @param int $assignmentid The id of the assignment
1743 * @return array of warnings to indicate any errors.
1744 * @since Moodle 2.6
1745 */
1746 public static function reveal_identities($assignmentid) {
1747 global $CFG, $USER;
05a6445a
DW
1748
1749 $params = self::validate_parameters(self::reveal_identities_parameters(),
1750 array('assignmentid' => $assignmentid));
1751
695a18b6 1752 $cm = get_coursemodule_from_instance('assign', $params['assignmentid'], 0, false, MUST_EXIST);
05a6445a 1753 $context = context_module::instance($cm->id);
695a18b6 1754 self::validate_context($context);
05a6445a
DW
1755
1756 $assignment = new assign($context, $cm, null);
1757
1758 $warnings = array();
1759 if (!$assignment->reveal_identities()) {
695a18b6
FM
1760 $detail = 'User id: ' . $USER->id . ', Assignment id: ' . $params['assignmentid'];
1761 $warnings[] = self::generate_warning($params['assignmentid'],
05a6445a
DW
1762 'couldnotrevealidentities',
1763 $detail);
1764 }
1765
1766 return $warnings;
1767 }
1768
1769 /**
1770 * Describes the return value for reveal_identities
1771 *
1772 * @return external_single_structure
1773 * @since Moodle 2.6
1774 */
1775 public static function reveal_identities_returns() {
13e814bc 1776 return new external_warnings();
05a6445a
DW
1777 }
1778
1779 /**
1780 * Describes the parameters for save_submission
1781 * @return external_external_function_parameters
1782 * @since Moodle 2.6
1783 */
1784 public static function save_submission_parameters() {
1785 global $CFG;
05a6445a
DW
1786 $instance = new assign(null, null, null);
1787 $pluginsubmissionparams = array();
1788
1789 foreach ($instance->get_submission_plugins() as $plugin) {
69115a5a
JL
1790 if ($plugin->is_visible()) {
1791 $pluginparams = $plugin->get_external_parameters();
1792 if (!empty($pluginparams)) {
1793 $pluginsubmissionparams = array_merge($pluginsubmissionparams, $pluginparams);
1794 }
05a6445a
DW
1795 }
1796 }
1797
1798 return new external_function_parameters(
1799 array(
1800 'assignmentid' => new external_value(PARAM_INT, 'The assignment id to operate on'),
1801 'plugindata' => new external_single_structure(
1802 $pluginsubmissionparams
1803 )
1804 )
1805 );
1806 }
1807
1808 /**
1561a37c 1809 * Save a student submission for a single assignment
05a6445a
DW
1810 *
1811 * @param int $assignmentid The id of the assignment
1561a37c
DW
1812 * @param array $plugindata - The submitted data for plugins
1813 * @return array of warnings to indicate any errors
05a6445a
DW
1814 * @since Moodle 2.6
1815 */
1816 public static function save_submission($assignmentid, $plugindata) {
1817 global $CFG, $USER;
05a6445a
DW
1818
1819 $params = self::validate_parameters(self::save_submission_parameters(),
1820 array('assignmentid' => $assignmentid,
1821 'plugindata' => $plugindata));
1822
695a18b6 1823 $cm = get_coursemodule_from_instance('assign', $params['assignmentid'], 0, false, MUST_EXIST);
05a6445a 1824 $context = context_module::instance($cm->id);
695a18b6 1825 self::validate_context($context);
05a6445a
DW
1826
1827 $assignment = new assign($context, $cm, null);
1828
1829 $notices = array();
1830
711f9468
JL
1831 if (!$assignment->submissions_open($USER->id)) {
1832 $notices[] = get_string('duedatereached', 'assign');
1833 } else {
1834 $submissiondata = (object)$params['plugindata'];
1835 $assignment->save_submission($submissiondata, $notices);
1836 }
05a6445a
DW
1837
1838 $warnings = array();
1839 foreach ($notices as $notice) {
695a18b6 1840 $warnings[] = self::generate_warning($params['assignmentid'],
05a6445a
DW
1841 'couldnotsavesubmission',
1842 $notice);
1843 }
1844
1845 return $warnings;
1846 }
1847
1848 /**
1849 * Describes the return value for save_submission
1850 *
1851 * @return external_single_structure
1852 * @since Moodle 2.6
1853 */
1854 public static function save_submission_returns() {
13e814bc 1855 return new external_warnings();
05a6445a
DW
1856 }
1857
1858 /**
1859 * Describes the parameters for save_grade
1860 * @return external_external_function_parameters
1861 * @since Moodle 2.6
1862 */
1863 public static function save_grade_parameters() {
1864 global $CFG;
40c3dacf 1865 require_once("$CFG->dirroot/grade/grading/lib.php");
05a6445a
DW
1866 $instance = new assign(null, null, null);
1867 $pluginfeedbackparams = array();
1868
1869 foreach ($instance->get_feedback_plugins() as $plugin) {
69115a5a
JL
1870 if ($plugin->is_visible()) {
1871 $pluginparams = $plugin->get_external_parameters();
1872 if (!empty($pluginparams)) {
1873 $pluginfeedbackparams = array_merge($pluginfeedbackparams, $pluginparams);
1874 }
05a6445a
DW
1875 }
1876 }
1877
40c3dacf
PC
1878 $advancedgradingdata = array();
1879 $methods = array_keys(grading_manager::available_methods(false));
1880 foreach ($methods as $method) {
1881 require_once($CFG->dirroot.'/grade/grading/form/'.$method.'/lib.php');
1882 $details = call_user_func('gradingform_'.$method.'_controller::get_external_instance_filling_details');
1883 if (!empty($details)) {
1884 $items = array();
1885 foreach ($details as $key => $value) {
1886 $value->required = VALUE_OPTIONAL;
1887 unset($value->content->keys['id']);
1888 $items[$key] = new external_multiple_structure (new external_single_structure(
1889 array(
1890 'criterionid' => new external_value(PARAM_INT, 'criterion id'),
1891 'fillings' => $value
1892 )
1893 ));
1894 }
1895 $advancedgradingdata[$method] = new external_single_structure($items, 'items', VALUE_OPTIONAL);
1896 }
1897 }
1898
05a6445a
DW
1899 return new external_function_parameters(
1900 array(
1901 'assignmentid' => new external_value(PARAM_INT, 'The assignment id to operate on'),
1902 'userid' => new external_value(PARAM_INT, 'The student id to operate on'),
40c3dacf 1903 'grade' => new external_value(PARAM_FLOAT, 'The new grade for this user. Ignored if advanced grading used'),
05a6445a
DW
1904 'attemptnumber' => new external_value(PARAM_INT, 'The attempt number (-1 means latest attempt)'),
1905 'addattempt' => new external_value(PARAM_BOOL, 'Allow another attempt if the attempt reopen method is manual'),
1906 'workflowstate' => new external_value(PARAM_ALPHA, 'The next marking workflow state'),
1907 'applytoall' => new external_value(PARAM_BOOL, 'If true, this grade will be applied ' .
1908 'to all members ' .
1909 'of the group (for group assignments).'),
40c3dacf
PC
1910 'plugindata' => new external_single_structure($pluginfeedbackparams, 'plugin data', VALUE_DEFAULT, array()),
1911 'advancedgradingdata' => new external_single_structure($advancedgradingdata, 'advanced grading data',
1912 VALUE_DEFAULT, array())
05a6445a
DW
1913 )
1914 );
1915 }
1916
1917 /**
1918 * Save a student grade for a single assignment.
1919 *
1920 * @param int $assignmentid The id of the assignment
1561a37c 1921 * @param int $userid The id of the user
40c3dacf 1922 * @param float $grade The grade (ignored if the assignment uses advanced grading)
1561a37c
DW
1923 * @param int $attemptnumber The attempt number
1924 * @param bool $addattempt Allow another attempt
1925 * @param string $workflowstate New workflow state
1926 * @param bool $applytoall Apply the grade to all members of the group
1927 * @param array $plugindata Custom data used by plugins
40c3dacf 1928 * @param array $advancedgradingdata Advanced grading data
05a6445a
DW
1929 * @return null
1930 * @since Moodle 2.6
1931 */
539af602
DW
1932 public static function save_grade($assignmentid,
1933 $userid,
1934 $grade,
1935 $attemptnumber,
1936 $addattempt,
1937 $workflowstate,
1938 $applytoall,
40c3dacf
PC
1939 $plugindata = array(),
1940 $advancedgradingdata = array()) {
05a6445a 1941 global $CFG, $USER;
05a6445a
DW
1942
1943 $params = self::validate_parameters(self::save_grade_parameters(),
1944 array('assignmentid' => $assignmentid,
1945 'userid' => $userid,
1946 'grade' => $grade,
1947 'attemptnumber' => $attemptnumber,
1948 'workflowstate' => $workflowstate,
1949 'addattempt' => $addattempt,
1950 'applytoall' => $applytoall,
40c3dacf
PC
1951 'plugindata' => $plugindata,
1952 'advancedgradingdata' => $advancedgradingdata));
05a6445a 1953
40c3dacf 1954 $cm = get_coursemodule_from_instance('assign', $params['assignmentid'], 0, false, MUST_EXIST);
05a6445a 1955 $context = context_module::instance($cm->id);
40c3dacf 1956 self::validate_context($context);
695a18b6 1957
05a6445a
DW
1958 $assignment = new assign($context, $cm, null);
1959
40c3dacf
PC
1960 $gradedata = (object)$params['plugindata'];
1961
1962 $gradedata->addattempt = $params['addattempt'];
1963 $gradedata->attemptnumber = $params['attemptnumber'];
1964 $gradedata->workflowstate = $params['workflowstate'];
1965 $gradedata->applytoall = $params['applytoall'];
1966 $gradedata->grade = $params['grade'];
1967
1968 if (!empty($params['advancedgradingdata'])) {
1969 $advancedgrading = array();
1970 $criteria = reset($params['advancedgradingdata']);
1971 foreach ($criteria as $key => $criterion) {
1972 $details = array();
1973 foreach ($criterion as $value) {
1974 foreach ($value['fillings'] as $filling) {
1975 $details[$value['criterionid']] = $filling;
1976 }
1977 }
1978 $advancedgrading[$key] = $details;
1979 }
1980 $gradedata->advancedgrading = $advancedgrading;
1981 }
05a6445a 1982
40c3dacf 1983 $assignment->save_grade($params['userid'], $gradedata);
05a6445a
DW
1984
1985 return null;
1986 }
1987
1988 /**
1989 * Describes the return value for save_grade
1990 *
1991 * @return external_single_structure
1992 * @since Moodle 2.6
1993 */
1994 public static function save_grade_returns() {
1995 return null;
1996 }
1997
40c3dacf
PC
1998 /**
1999 * Describes the parameters for save_grades
2000 * @return external_external_function_parameters
2001 * @since Moodle 2.7
2002 */
2003 public static function save_grades_parameters() {
2004 global $CFG;
40c3dacf
PC
2005 require_once("$CFG->dirroot/grade/grading/lib.php");
2006 $instance = new assign(null, null, null);
2007 $pluginfeedbackparams = array();
2008
2009 foreach ($instance->get_feedback_plugins() as $plugin) {
69115a5a
JL
2010 if ($plugin->is_visible()) {
2011 $pluginparams = $plugin->get_external_parameters();
2012 if (!empty($pluginparams)) {
2013 $pluginfeedbackparams = array_merge($pluginfeedbackparams, $pluginparams);
2014 }
40c3dacf
PC
2015 }
2016 }
2017
2018 $advancedgradingdata = array();
2019 $methods = array_keys(grading_manager::available_methods(false));
2020 foreach ($methods as $method) {
2021 require_once($CFG->dirroot.'/grade/grading/form/'.$method.'/lib.php');
2022 $details = call_user_func('gradingform_'.$method.'_controller::get_external_instance_filling_details');
2023 if (!empty($details)) {
2024 $items = array();
2025 foreach ($details as $key => $value) {
2026 $value->required = VALUE_OPTIONAL;
2027 unset($value->content->keys['id']);
2028 $items[$key] = new external_multiple_structure (new external_single_structure(
2029 array(
2030 'criterionid' => new external_value(PARAM_INT, 'criterion id'),
2031 'fillings' => $value
2032 )
2033 ));
2034 }
2035 $advancedgradingdata[$method] = new external_single_structure($items, 'items', VALUE_OPTIONAL);
2036 }
2037 }
2038
2039 return new external_function_parameters(
2040 array(
2041 'assignmentid' => new external_value(PARAM_INT, 'The assignment id to operate on'),
2042 'applytoall' => new external_value(PARAM_BOOL, 'If true, this grade will be applied ' .
2043 'to all members ' .
2044 'of the group (for group assignments).'),
2045 'grades' => new external_multiple_structure(
2046 new external_single_structure(
2047 array (
2048 'userid' => new external_value(PARAM_INT, 'The student id to operate on'),
2049 'grade' => new external_value(PARAM_FLOAT, 'The new grade for this user. '.
2050 'Ignored if advanced grading used'),
2051 'attemptnumber' => new external_value(PARAM_INT, 'The attempt number (-1 means latest attempt)'),
2052 'addattempt' => new external_value(PARAM_BOOL, 'Allow another attempt if manual attempt reopen method'),
2053 'workflowstate' => new external_value(PARAM_ALPHA, 'The next marking workflow state'),
2054 'plugindata' => new external_single_structure($pluginfeedbackparams, 'plugin data',
2055 VALUE_DEFAULT, array()),
2056 'advancedgradingdata' => new external_single_structure($advancedgradingdata, 'advanced grading data',
2057 VALUE_DEFAULT, array())
2058 )
2059 )
2060 )
2061 )
2062 );
2063 }
2064
2065 /**
2066 * Save multiple student grades for a single assignment.
2067 *
2068 * @param int $assignmentid The id of the assignment
2069 * @param boolean $applytoall If set to true and this is a team assignment,
2070 * apply the grade to all members of the group
2071 * @param array $grades grade data for one or more students that includes
2072 * userid - The id of the student being graded
2073 * grade - The grade (ignored if the assignment uses advanced grading)
2074 * attemptnumber - The attempt number
2075 * addattempt - Allow another attempt
2076 * workflowstate - New workflow state
2077 * plugindata - Custom data used by plugins
2078 * advancedgradingdata - Optional Advanced grading data
2079 * @throws invalid_parameter_exception if multiple grades are supplied for
2080 * a team assignment that has $applytoall set to true
2081 * @return null
2082 * @since Moodle 2.7
2083 */
2084 public static function save_grades($assignmentid, $applytoall = false, $grades) {
2085 global $CFG, $USER;
40c3dacf
PC
2086
2087 $params = self::validate_parameters(self::save_grades_parameters(),
2088 array('assignmentid' => $assignmentid,
2089 'applytoall' => $applytoall,
2090 'grades' => $grades));
2091
2092 $cm = get_coursemodule_from_instance('assign', $params['assignmentid'], 0, false, MUST_EXIST);
2093 $context = context_module::instance($cm->id);
2094 self::validate_context($context);
2095 $assignment = new assign($context, $cm, null);
2096
2097 if ($assignment->get_instance()->teamsubmission && $params['applytoall']) {
2098 // Check that only 1 user per submission group is provided.
2099 $groupids = array();
2100 foreach ($params['grades'] as $gradeinfo) {
2101 $group = $assignment->get_submission_group($gradeinfo['userid']);
2102 if (in_array($group->id, $groupids)) {
2103 throw new invalid_parameter_exception('Multiple grades for the same team have been supplied '
2104 .' this is not permitted when the applytoall flag is set');
2105 } else {
2106 $groupids[] = $group->id;
2107 }
2108 }
2109 }
2110
2111 foreach ($params['grades'] as $gradeinfo) {
2112 $gradedata = (object)$gradeinfo['plugindata'];
2113 $gradedata->addattempt = $gradeinfo['addattempt'];
2114 $gradedata->attemptnumber = $gradeinfo['attemptnumber'];
2115 $gradedata->workflowstate = $gradeinfo['workflowstate'];
2116 $gradedata->applytoall = $params['applytoall'];
2117 $gradedata->grade = $gradeinfo['grade'];
2118
2119 if (!empty($gradeinfo['advancedgradingdata'])) {
2120 $advancedgrading = array();
2121 $criteria = reset($gradeinfo['advancedgradingdata']);
2122 foreach ($criteria as $key => $criterion) {
2123 $details = array();
2124 foreach ($criterion as $value) {
2125 foreach ($value['fillings'] as $filling) {
2126 $details[$value['criterionid']] = $filling;
2127 }
2128 }
2129 $advancedgrading[$key] = $details;
2130 }
2131 $gradedata->advancedgrading = $advancedgrading;
2132 }
2133 $assignment->save_grade($gradeinfo['userid'], $gradedata);
2134 }
2135
2136 return null;
2137 }
2138
2139 /**
2140 * Describes the return value for save_grades
2141 *
2142 * @return external_single_structure
2143 * @since Moodle 2.7
2144 */
2145 public static function save_grades_returns() {
2146 return null;
2147 }
2148
05a6445a
DW
2149 /**
2150 * Describes the parameters for copy_previous_attempt
2151 * @return external_external_function_parameters
2152 * @since Moodle 2.6
2153 */
2154 public static function copy_previous_attempt_parameters() {
2155 return new external_function_parameters(
2156 array(
2157 'assignmentid' => new external_value(PARAM_INT, 'The assignment id to operate on'),
2158 )
2159 );
2160 }
2161
2162 /**
2163 * Copy a students previous attempt to a new attempt.
2164 *
1561a37c 2165 * @param int $assignmentid
05a6445a
DW
2166 * @return array of warnings to indicate any errors.
2167 * @since Moodle 2.6
2168 */
2169 public static function copy_previous_attempt($assignmentid) {
2170 global $CFG, $USER;
05a6445a
DW
2171
2172 $params = self::validate_parameters(self::copy_previous_attempt_parameters(),
2173 array('assignmentid' => $assignmentid));
2174
2175 $cm = get_coursemodule_from_instance('assign', $assignmentid, 0, false, MUST_EXIST);
2176 $context = context_module::instance($cm->id);
695a18b6 2177 self::validate_context($context);
05a6445a
DW
2178
2179 $assignment = new assign($context, $cm, null);
2180
2181 $notices = array();
2182
2183 $assignment->copy_previous_attempt($submissiondata, $notices);
2184
2185 $warnings = array();
2186 foreach ($notices as $notice) {
2187 $warnings[] = self::generate_warning($assignmentid,
2188 'couldnotcopyprevioussubmission',
2189 $notice);
2190 }
2191
2192 return $warnings;
2193 }
2194
2195 /**
2196 * Describes the return value for save_submission
2197 *
2198 * @return external_single_structure
2199 * @since Moodle 2.6
2200 */
2201 public static function copy_previous_attempt_returns() {
13e814bc 2202 return new external_warnings();
05a6445a 2203 }
e0d6d10a
JL
2204
2205 /**
2206 * Returns description of method parameters
2207 *
2208 * @return external_function_parameters
2209 * @since Moodle 3.0
2210 */
2211 public static function view_grading_table_parameters() {
2212 return new external_function_parameters(
2213 array(
2214 'assignid' => new external_value(PARAM_INT, 'assign instance id')
2215 )
2216 );
2217 }
2218
2219 /**
1c2b7882 2220 * Trigger the grading_table_viewed event.
e0d6d10a
JL
2221 *
2222 * @param int $assignid the assign instance id
2223 * @return array of warnings and status result
2224 * @since Moodle 3.0
2225 * @throws moodle_exception
2226 */
2227 public static function view_grading_table($assignid) {
2228 global $DB, $CFG;
e0d6d10a
JL
2229
2230 $params = self::validate_parameters(self::view_grading_table_parameters(),
2231 array(
2232 'assignid' => $assignid
2233 ));
2234 $warnings = array();
2235
2236 // Request and permission validation.
2237 $assign = $DB->get_record('assign', array('id' => $params['assignid']), 'id', MUST_EXIST);
2238 list($course, $cm) = get_course_and_cm_from_instance($assign, 'assign');
2239
2240 $context = context_module::instance($cm->id);
2241 self::validate_context($context);
2242
2243 require_capability('mod/assign:view', $context);
2244
2245 $assign = new assign($context, null, null);
2246 $assign->require_view_grades();
2247 \mod_assign\event\grading_table_viewed::create_from_assign($assign)->trigger();
2248
2249 $result = array();
2250 $result['status'] = true;
2251 $result['warnings'] = $warnings;
2252 return $result;
2253 }
2254
2255 /**
2256 * Returns description of method result value
2257 *
2258 * @return external_description
2259 * @since Moodle 3.0
2260 */
2261 public static function view_grading_table_returns() {
2262 return new external_single_structure(
2263 array(
2264 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
2265 'warnings' => new external_warnings()
2266 )
2267 );
2268 }
e3e036ee
JL
2269 /**
2270 * Describes the parameters for view_submission_status.
2271 *
2272 * @return external_external_function_parameters
2273 * @since Moodle 3.1
2274 */
2275 public static function view_submission_status_parameters() {
2276 return new external_function_parameters (
2277 array(
2278 'assignid' => new external_value(PARAM_INT, 'assign instance id'),
2279 )
2280 );
2281 }
2282
2283 /**
2284 * Trigger the submission status viewed event.
2285 *
2286 * @param int $assignid assign instance id
2287 * @return array of warnings and status result
2288 * @since Moodle 3.1
2289 */
2290 public static function view_submission_status($assignid) {
ee6aa740 2291 global $DB, $CFG;
e3e036ee
JL
2292
2293 $warnings = array();
2294 $params = array(
2295 'assignid' => $assignid,
2296 );
2297 $params = self::validate_parameters(self::view_submission_status_parameters(), $params);
2298
2299 // Request and permission validation.
2300 $assign = $DB->get_record('assign', array('id' => $params['assignid']), 'id', MUST_EXIST);
2301 list($course, $cm) = get_course_and_cm_from_instance($assign, 'assign');
2302
2303 $context = context_module::instance($cm->id);
2304 // Please, note that is not required to check mod/assign:view because is done by validate_context->require_login.
2305 self::validate_context($context);
2306
2307 $assign = new assign($context, $cm, $course);
2308 \mod_assign\event\submission_status_viewed::create_from_assign($assign)->trigger();
2309
2310 $result = array();
2311 $result['status'] = true;
2312 $result['warnings'] = $warnings;
2313 return $result;
2314 }
2315
2316 /**
2317 * Describes the view_submission_status return value.
2318 *
2319 * @return external_single_structure
2320 * @since Moodle 3.1
2321 */
2322 public static function view_submission_status_returns() {
2323 return new external_single_structure(
2324 array(
2325 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
2326 'warnings' => new external_warnings(),
2327 )
2328 );
2329 }
2330
bdf1ac27
JL
2331 /**
2332 * Describes the parameters for get_submission_status.
2333 *
2334 * @return external_external_function_parameters
2335 * @since Moodle 3.1
2336 */
2337 public static function get_submission_status_parameters() {
2338 return new external_function_parameters (
2339 array(
2340 'assignid' => new external_value(PARAM_INT, 'assignment instance id'),
2341 'userid' => new external_value(PARAM_INT, 'user id (empty for current user)', VALUE_DEFAULT, 0),
2342 )
2343 );
2344 }
2345
2346 /**
2347 * Returns information about an assignment submission status for a given user.
2348 *
2349 * @param int $assignid assignment instance id
2350 * @param int $userid user id (empty for current user)
2351 * @return array of warnings and grading, status, feedback and previous attempts information
2352 * @since Moodle 3.1
2353 * @throws required_capability_exception
2354 */
2355 public static function get_submission_status($assignid, $userid = 0) {
2356 global $USER, $DB;
2357
2358 $warnings = array();
2359
2360 $params = array(
2361 'assignid' => $assignid,
2362 'userid' => $userid,
2363 );
2364 $params = self::validate_parameters(self::get_submission_status_parameters(), $params);
2365
2366 // Request and permission validation.
2367 $assign = $DB->get_record('assign', array('id' => $params['assignid']), 'id', MUST_EXIST);
2368 list($course, $cm) = get_course_and_cm_from_instance($assign, 'assign');
2369
2370 $context = context_module::instance($cm->id);
2371 self::validate_context($context);
2372
2373 $assign = new assign($context, $cm, $course);
2374
2375 // Default value for userid.
2376 if (empty($params['userid'])) {
2377 $params['userid'] = $USER->id;
2378 }
2379 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
2380 core_user::require_active_user($user);
2381
2382 if (!$assign->can_view_submission($user->id)) {
2383 throw new required_capability_exception($context, 'mod/assign:viewgrades', 'nopermission', '');
2384 }
2385
2386 $gradingsummary = $lastattempt = $feedback = $previousattempts = null;
2387
2388 // Get the renderable since it contais all the info we need.
2389 if ($assign->can_view_grades()) {
2390 $gradingsummary = $assign->get_assign_grading_summary_renderable();
2391 }
2392
2393 // Retrieve the rest of the renderable objects.
2394 if (has_capability('mod/assign:submit', $assign->get_context(), $user)) {
2395 $lastattempt = $assign->get_assign_submission_status_renderable($user, true);
2396 }
2397
2398 $feedback = $assign->get_assign_feedback_status_renderable($user);
2399
2400 $previousattempts = $assign->get_assign_attempt_history_renderable($user);
2401
2402 // Now, build the result.
2403 $result = array();
2404
2405 // First of all, grading summary, this is suitable for teachers/managers.
2406 if ($gradingsummary) {
2407 $result['gradingsummary'] = $gradingsummary;
2408 }
2409
2410 // Did we submit anything?
2411 if ($lastattempt) {
2412 $submissionplugins = $assign->get_submission_plugins();
2413
2414 if (empty($lastattempt->submission)) {
2415 unset($lastattempt->submission);
2416 } else {
2417 $lastattempt->submission->plugins = self::get_plugins_data($assign, $submissionplugins, $lastattempt->submission);
2418 }
2419
2420 if (empty($lastattempt->teamsubmission)) {
2421 unset($lastattempt->teamsubmission);
2422 } else {
2423 $lastattempt->teamsubmission->plugins = self::get_plugins_data($assign, $submissionplugins,
2424 $lastattempt->teamsubmission);
2425 }
2426
2427 // We need to change the type of some of the structures retrieved from the renderable.
2428 if (!empty($lastattempt->submissiongroup)) {
2429 $lastattempt->submissiongroup = $lastattempt->submissiongroup->id;
2430 }
2431 if (!empty($lastattempt->usergroups)) {
2432 $lastattempt->usergroups = array_keys($lastattempt->usergroups);
2433 }
2434 // We cannot use array_keys here.
2435 if (!empty($lastattempt->submissiongroupmemberswhoneedtosubmit)) {
2436 $lastattempt->submissiongroupmemberswhoneedtosubmit = array_map(
2437 function($e){
2438 return $e->id;
2439 },
2440 $lastattempt->submissiongroupmemberswhoneedtosubmit);
2441 }
2442
2443 $result['lastattempt'] = $lastattempt;
2444 }
2445
2446 // The feedback for our latest submission.
2447 if ($feedback) {
2448 if ($feedback->grade) {
2449 $feedbackplugins = $assign->get_feedback_plugins();
2450 $feedback->plugins = self::get_plugins_data($assign, $feedbackplugins, $feedback->grade);
2451 } else {
2452 unset($feedback->plugins);
2453 unset($feedback->grade);
2454 }
2455
2456 $result['feedback'] = $feedback;
2457 }
2458
2459 // Retrieve only previous attempts.
2460 if ($previousattempts and count($previousattempts->submissions) > 1) {
2461 // Don't show the last one because it is the current submission.
2462 array_pop($previousattempts->submissions);
2463
2464 // Show newest to oldest.
2465 $previousattempts->submissions = array_reverse($previousattempts->submissions);
2466
2467 foreach ($previousattempts->submissions as $i => $submission) {
2468 $attempt = array();
2469
2470 $grade = null;
2471 foreach ($previousattempts->grades as $onegrade) {
2472 if ($onegrade->attemptnumber == $submission->attemptnumber) {
2473 $grade = $onegrade;
2474 break;
2475 }
2476 }
2477
2478 $attempt['attemptnumber'] = $submission->attemptnumber;
2479
2480 if ($submission) {
2481 $submission->plugins = self::get_plugins_data($assign, $previousattempts->submissionplugins, $submission);
2482 $attempt['submission'] = $submission;
2483 }
2484
2485 if ($grade) {
2486 // From object to id.
2487 $grade->grader = $grade->grader->id;
2488 $feedbackplugins = self::get_plugins_data($assign, $previousattempts->feedbackplugins, $grade);
2489
2490 $attempt['grade'] = $grade;
2491 $attempt['feedbackplugins'] = $feedbackplugins;
2492 }
2493 $result['previousattempts'][] = $attempt;
2494 }
2495 }
2496
2497 $result['warnings'] = $warnings;
2498 return $result;
2499 }
2500
2501 /**
2502 * Describes the get_submission_status return value.
2503 *
2504 * @return external_single_structure
2505 * @since Moodle 3.1
2506 */
2507 public static function get_submission_status_returns() {
2508 return new external_single_structure(
2509 array(
2510 'gradingsummary' => new external_single_structure(
2511 array(
2512 'participantcount' => new external_value(PARAM_INT, 'Number of users who can submit.'),
2513 'submissiondraftscount' => new external_value(PARAM_INT, 'Number of submissions in draft status.'),
2514 'submissiondraftscount' => new external_value(PARAM_INT, 'Number of submissions in draft status.'),
2515 'submissionsenabled' => new external_value(PARAM_BOOL, 'Whether submissions are enabled or not.'),
2516 'submissionssubmittedcount' => new external_value(PARAM_INT, 'Number of submissions in submitted status.'),
2517 'submissionsneedgradingcount' => new external_value(PARAM_INT, 'Number of submissions that need grading.'),
2518 'warnofungroupedusers' => new external_value(PARAM_BOOL, 'Whether we need to warn people that there
2519 are users without groups.'),
2520 ), 'Grading information.', VALUE_OPTIONAL
2521 ),
2522 'lastattempt' => new external_single_structure(
2523 array(
2524 'submission' => self::get_submission_structure(VALUE_OPTIONAL),
2525 'teamsubmission' => self::get_submission_structure(VALUE_OPTIONAL),
2526 'submissiongroup' => new external_value(PARAM_INT, 'The submission group id (for group submissions only).',
2527 VALUE_OPTIONAL),
2528 'submissiongroupmemberswhoneedtosubmit' => new external_multiple_structure(
2529 new external_value(PARAM_INT, 'USER id.'),
2530 'List of users who still need to submit (for group submissions only).',
2531 VALUE_OPTIONAL
2532 ),
2533 'submissionsenabled' => new external_value(PARAM_BOOL, 'Whether submissions are enabled or not.'),
2534 'locked' => new external_value(PARAM_BOOL, 'Whether new submissions are locked.'),
2535 'graded' => new external_value(PARAM_BOOL, 'Whether the submission is graded.'),
2536 'canedit' => new external_value(PARAM_BOOL, 'Whether the user can edit the current submission.'),
2537 'cansubmit' => new external_value(PARAM_BOOL, 'Whether the user can submit.'),
2538 'extensionduedate' => new external_value(PARAM_INT, 'Extension due date.'),
2539 'blindmarking' => new external_value(PARAM_BOOL, 'Whether blind marking is enabled.'),
2540 'gradingstatus' => new external_value(PARAM_ALPHANUMEXT, 'Grading status.'),
2541 'usergroups' => new external_multiple_structure(
2542 new external_value(PARAM_INT, 'Group id.'), 'User groups in the course.'
2543 ),
2544 ), 'Last attempt information.', VALUE_OPTIONAL
2545 ),
2546 'feedback' => new external_single_structure(
2547 array(
2548 'grade' => self::get_grade_structure(VALUE_OPTIONAL),
2549 'gradefordisplay' => new external_value(PARAM_RAW, 'Grade rendered into a format suitable for display.'),
2550 'gradeddate' => new external_value(PARAM_INT, 'The date the user was graded.'),
2551 'plugins' => new external_multiple_structure(self::get_plugin_structure(), 'Plugins info.', VALUE_OPTIONAL),
2552 ), 'Feedback for the last attempt.', VALUE_OPTIONAL
2553 ),
2554 'previousattempts' => new external_multiple_structure(
2555 new external_single_structure(
2556 array(
2557 'attemptnumber' => new external_value(PARAM_INT, 'Attempt number.'),
2558 'submission' => self::get_submission_structure(VALUE_OPTIONAL),
2559 'grade' => self::get_grade_structure(VALUE_OPTIONAL),
2560 'feedbackplugins' => new external_multiple_structure(self::get_plugin_structure(), 'Feedback info.',
2561 VALUE_OPTIONAL),
2562 )
2563 ), 'List all the previous attempts did by the user.', VALUE_OPTIONAL
2564 ),
2565 'warnings' => new external_warnings(),
2566 )
2567 );
2568 }
2569
1f8c8f61 2570}