Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**

 * External assign API

 *

 * @package    mod_assign

 * @since      Moodle 2.4

 * @copyright  2012 Paul Charsley

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

use core_external\external_files;

use core_external\external_format_value;

use core_external\external_function_parameters;

use core_external\external_multiple_structure;

use core_external\external_single_structure;

use core_external\external_value;

use core_external\external_warnings;

use core_external\util as external_util;

defined('MOODLE_INTERNAL') || die;

require_once("$CFG->dirroot/user/externallib.php");

require_once("$CFG->dirroot/mod/assign/locallib.php");

/**

 * Assign functions

 * @copyright 2012 Paul Charsley

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class mod_assign_external extends \mod_assign\external\external_api {

    /**

     * Describes the parameters for get_grades

     * @return external_function_parameters

     * @since  Moodle 2.4

     */

    public static function get_grades_parameters() {

        return new external_function_parameters(

            array(

                'assignmentids' => new external_multiple_structure(

                    new external_value(PARAM_INT, 'assignment id'),

                    '1 or more assignment ids',

                    VALUE_REQUIRED),

                'since' => new external_value(PARAM_INT,

                          'timestamp, only return records where timemodified >= since',

                          VALUE_DEFAULT, 0)

            )

        );

    }

    /**

     * Returns grade information from assign_grades for the requested assignment ids

     * @param int[] $assignmentids

     * @param int $since only return records with timemodified >= since

     * @return array of grade records for each requested assignment

     * @since  Moodle 2.4

     */

    public static function get_grades($assignmentids, $since = 0) {

        global $DB;

        $params = self::validate_parameters(self::get_grades_parameters(),

                        array('assignmentids' => $assignmentids,

                              'since' => $since));

        $assignments = array();

        $warnings = array();

        $requestedassignmentids = $params['assignmentids'];

        // Check the user is allowed to get the grades for the assignments requested.

        $placeholders = array();

        list($sqlassignmentids, $placeholders) = $DB->get_in_or_equal($requestedassignmentids, SQL_PARAMS_NAMED);

        $sql = "SELECT cm.id, cm.instance FROM {course_modules} cm JOIN {modules} md ON md.id = cm.module ".

               "WHERE md.name = :modname AND cm.instance ".$sqlassignmentids;

        $placeholders['modname'] = 'assign';

        $cms = $DB->get_records_sql($sql, $placeholders);

        foreach ($cms as $cm) {

            try {

                $context = context_module::instance($cm->id);

                self::validate_context($context);

                $assign = new assign($context, null, null);

                $assign->require_view_grades();

            } catch (Exception $e) {

                $requestedassignmentids = array_diff($requestedassignmentids, array($cm->instance));

                $warning = array();

                $warning['item'] = 'assignment';

                $warning['itemid'] = $cm->instance;

                $warning['warningcode'] = '1';

                $warning['message'] = 'No access rights in module context';

                $warnings[] = $warning;

            }

        }

        // Create the query and populate an array of grade records from the recordset results.

        if (count ($requestedassignmentids) > 0) {

            $placeholders = array();

            list($inorequalsql, $placeholders) = $DB->get_in_or_equal($requestedassignmentids, SQL_PARAMS_NAMED);

            $sql = "SELECT ag.id,

                           ag.assignment,

                           ag.userid,

                           ag.timecreated,

                           ag.timemodified,

                           ag.grader,

                           ag.grade,

                           ag.attemptnumber

                      FROM {assign_grades} ag, {assign_submission} s

                     WHERE s.assignment $inorequalsql

                       AND s.userid = ag.userid

                       AND s.latest = 1

                       AND s.attemptnumber = ag.attemptnumber

                       AND ag.timemodified  >= :since

                       AND ag.assignment = s.assignment

                  ORDER BY ag.assignment, ag.id";

            $placeholders['since'] = $params['since'];

            $rs = $DB->get_recordset_sql($sql, $placeholders);

            $currentassignmentid = null;

            $assignment = null;

            foreach ($rs as $rd) {

                $grade = array();

                $grade['id'] = $rd->id;

                $grade['userid'] = $rd->userid;

                $grade['timecreated'] = $rd->timecreated;

                $grade['timemodified'] = $rd->timemodified;

                $grade['grader'] = $rd->grader;

                $grade['attemptnumber'] = $rd->attemptnumber;

                $grade['grade'] = (string)$rd->grade;

                if (is_null($currentassignmentid) || ($rd->assignment != $currentassignmentid )) {

                    if (!is_null($assignment)) {

                        $assignments[] = $assignment;

                    }

                    $assignment = array();

                    $assignment['assignmentid'] = $rd->assignment;

                    $assignment['grades'] = array();

                    $requestedassignmentids = array_diff($requestedassignmentids, array($rd->assignment));

                }

                $assignment['grades'][] = $grade;

                $currentassignmentid = $rd->assignment;

            }

            if (!is_null($assignment)) {

                $assignments[] = $assignment;

            }

            $rs->close();

        }

        foreach ($requestedassignmentids as $assignmentid) {

            $warning = array();

            $warning['item'] = 'assignment';

            $warning['itemid'] = $assignmentid;

            $warning['warningcode'] = '3';

            $warning['message'] = 'No grades found';

            $warnings[] = $warning;

        }

        $result = array();

        $result['assignments'] = $assignments;

        $result['warnings'] = $warnings;

        return $result;

    }

    /**

     * Creates a grade single structure.

     *

     * @return external_single_structure a grade single structure.

     * @since  Moodle 3.1

     */

    private static function get_grade_structure($required = VALUE_REQUIRED) {

        return new external_single_structure(

            array(

                'id'                => new external_value(PARAM_INT, 'grade id'),

                'assignment'        => new external_value(PARAM_INT, 'assignment id', VALUE_OPTIONAL),

                'userid'            => new external_value(PARAM_INT, 'student id'),

                'attemptnumber'     => new external_value(PARAM_INT, 'attempt number'),

                'timecreated'       => new external_value(PARAM_INT, 'grade creation time'),

                'timemodified'      => new external_value(PARAM_INT, 'grade last modified time'),

                'grader'            => new external_value(PARAM_INT, 'grader, -1 if grader is hidden'),

                'grade'             => new external_value(PARAM_TEXT, 'grade'),

                'gradefordisplay'   => new external_value(PARAM_RAW, 'grade rendered into a format suitable for display',

                                                            VALUE_OPTIONAL),

            ), 'grade information', $required

        );

    }

    /**

     * Creates an assign_grades external_single_structure

     * @return external_single_structure

     * @since  Moodle 2.4

     */

    private static function assign_grades() {

        return new external_single_structure(

            array (

                'assignmentid'  => new external_value(PARAM_INT, 'assignment id'),

                'grades'        => new external_multiple_structure(self::get_grade_structure())

            )

        );

    }

    /**

     * Describes the get_grades return value

     * @return external_single_structure

     * @since  Moodle 2.4

     */

    public static function get_grades_returns() {

        return new external_single_structure(

            array(

                'assignments' => new external_multiple_structure(self::assign_grades(), 'list of assignment grade information'),

                'warnings'      => new external_warnings('item is always \'assignment\'',

                    'when errorcode is 3 then itemid is an assignment id. When errorcode is 1, itemid is a course module id',

                    'errorcode can be 3 (no grades found) or 1 (no permission to get grades)')

            )

        );

    }

    /**

     * Returns description of method parameters

     *

     * @return external_function_parameters

     * @since  Moodle 2.4

     */

    public static function get_assignments_parameters() {

        return new external_function_parameters(

            array(

                'courseids' => new external_multiple_structure(

                    new external_value(PARAM_INT, 'course id, empty for retrieving all the courses where the user is enroled in'),

                    '0 or more course ids',

                    VALUE_DEFAULT, array()

                ),

                'capabilities'  => new external_multiple_structure(

                    new external_value(PARAM_CAPABILITY, 'capability'),

                    'list of capabilities used to filter courses',

                    VALUE_DEFAULT, array()

                ),

                'includenotenrolledcourses' => new external_value(PARAM_BOOL, 'whether to return courses that the user can see

                                                                    even if is not enroled in. This requires the parameter courseids

                                                                    to not be empty.', VALUE_DEFAULT, false)

            )

        );

    }

    /**

     * Returns an array of courses the user is enrolled, and for each course all of the assignments that the user can

     * view within that course.

     *

     * @param array $courseids An optional array of course ids. If provided only assignments within the given course

     * will be returned. If the user is not enrolled in or can't view a given course a warning will be generated and returned.

     * @param array $capabilities An array of additional capability checks you wish to be made on the course context.

     * @param bool $includenotenrolledcourses Wheter to return courses that the user can see even if is not enroled in.

     * This requires the parameter $courseids to not be empty.

     * @return An array of courses and warnings.

     * @since  Moodle 2.4

     */

    public static function get_assignments($courseids = array(), $capabilities = array(), $includenotenrolledcourses = false) {

        global $USER, $DB, $CFG;

        $params = self::validate_parameters(

            self::get_assignments_parameters(),

            array(

                'courseids' => $courseids,

                'capabilities' => $capabilities,

                'includenotenrolledcourses' => $includenotenrolledcourses

            )

        );

        $warnings = array();

        $courses = array();

        $fields = 'sortorder,shortname,fullname,timemodified';

        // If the courseids list is empty, we return only the courses where the user is enrolled in.

        if (empty($params['courseids'])) {

            $courses = enrol_get_users_courses($USER->id, true, $fields);

            $courseids = array_keys($courses);

        } else if ($includenotenrolledcourses) {

            // In this case, we don't have to check here for enrolmnents. Maybe the user can see the course even if is not enrolled.

            $courseids = $params['courseids'];

        } else {

            // We need to check for enrolments.

            $mycourses = enrol_get_users_courses($USER->id, true, $fields);

            $mycourseids = array_keys($mycourses);

            foreach ($params['courseids'] as $courseid) {

                if (!in_array($courseid, $mycourseids)) {

                    unset($courses[$courseid]);

                    $warnings[] = array(

                        'item' => 'course',

                        'itemid' => $courseid,

                        'warningcode' => '2',

                        'message' => 'User is not enrolled or does not have requested capability'

                    );

                } else {

                    $courses[$courseid] = $mycourses[$courseid];

                }

            }

            $courseids = array_keys($courses);

        }

        foreach ($courseids as $cid) {

            try {

                $context = context_course::instance($cid);

                self::validate_context($context);

                // Check if this course was already loaded (by enrol_get_users_courses).

                if (!isset($courses[$cid])) {

                    $courses[$cid] = get_course($cid);

                }

                $courses[$cid]->contextid = $context->id;

            } catch (Exception $e) {

                unset($courses[$cid]);

                $warnings[] = array(

                    'item' => 'course',

                    'itemid' => $cid,

                    'warningcode' => '1',

                    'message' => 'No access rights in course context '.$e->getMessage()

                );

                continue;

            }

            if (count($params['capabilities']) > 0 && !has_all_capabilities($params['capabilities'], $context)) {

                unset($courses[$cid]);

            }

        }

        $extrafields='m.id as assignmentid, ' .

                     'm.course, ' .

                     'm.nosubmissions, ' .

                     'm.submissiondrafts, ' .

                     'm.sendnotifications, '.

                     'm.sendlatenotifications, ' .

                     'm.sendstudentnotifications, ' .

                     'm.duedate, ' .

                     'm.allowsubmissionsfromdate, '.

                     'm.grade, ' .

                     'm.timemodified, '.

                     'm.completionsubmit, ' .

                     'm.cutoffdate, ' .

                     'm.gradingduedate, ' .

                     'm.teamsubmission, ' .

                     'm.requireallteammemberssubmit, '.

                     'm.teamsubmissiongroupingid, ' .

                     'm.blindmarking, ' .

                     'm.hidegrader, ' .

                     'm.revealidentities, ' .

                     'm.attemptreopenmethod, '.

                     'm.maxattempts, ' .

                     'm.markingworkflow, ' .

                     'm.markingallocation, ' .

                     'm.markinganonymous, ' .

                     'm.requiresubmissionstatement, '.

                     'm.preventsubmissionnotingroup, '.

                     'm.intro, '.

                     'm.introformat,' .

                     'm.activity,' .

                     'm.activityformat,' .

                     'm.timelimit,' .

                     'm.submissionattachments';

        $coursearray = array();

        foreach ($courses as $id => $course) {

            $assignmentarray = array();

            // Get a list of assignments for the course.

            if ($modules = get_coursemodules_in_course('assign', $courses[$id]->id, $extrafields)) {

                foreach ($modules as $module) {

                    $context = context_module::instance($module->id);

                    try {

                        self::validate_context($context);

                        require_capability('mod/assign:view', $context);

                    } catch (Exception $e) {

                        $warnings[] = array(

                            'item' => 'module',

                            'itemid' => $module->id,

                            'warningcode' => '1',

                            'message' => 'No access rights in module context'

                        );

                        continue;

                    }

                    $assign = new assign($context, null, null);

                    // Update assign with override information.

                    $assign->update_effective_access($USER->id);

                    // Get configurations for only enabled plugins.

                    $plugins = $assign->get_submission_plugins();

                    $plugins = array_merge($plugins, $assign->get_feedback_plugins());

                    $configarray = array();

                    foreach ($plugins as $plugin) {

                        if ($plugin->is_enabled() && $plugin->is_visible()) {

                            $configrecords = $plugin->get_config_for_external();

                            foreach ($configrecords as $name => $value) {

                                $configarray[] = array(

                                    'plugin' => $plugin->get_type(),

                                    'subtype' => $plugin->get_subtype(),

                                    'name' => $name,

                                    'value' => $value

                                );

                            }

                        }

                    }

                    $assignment = array(

                        'id' => $module->assignmentid,

                        'cmid' => $module->id,

                        'course' => $module->course,

                        'name' => \core_external\util::format_string($module->name, $context),

                        'nosubmissions' => $module->nosubmissions,

                        'submissiondrafts' => $module->submissiondrafts,

                        'sendnotifications' => $module->sendnotifications,

                        'sendlatenotifications' => $module->sendlatenotifications,

                        'sendstudentnotifications' => $module->sendstudentnotifications,

                        'duedate' => $assign->get_instance()->duedate,

                        'allowsubmissionsfromdate' => $assign->get_instance()->allowsubmissionsfromdate,

                        'grade' => $module->grade,

                        'timemodified' => $module->timemodified,

                        'completionsubmit' => $module->completionsubmit,

                        'cutoffdate' => $assign->get_instance()->cutoffdate,

                        'gradingduedate' => $assign->get_instance()->gradingduedate,

                        'teamsubmission' => $module->teamsubmission,

                        'requireallteammemberssubmit' => $module->requireallteammemberssubmit,

                        'teamsubmissiongroupingid' => $module->teamsubmissiongroupingid,

                        'blindmarking' => $module->blindmarking,

                        'hidegrader' => $module->hidegrader,

                        'revealidentities' => $module->revealidentities,

                        'attemptreopenmethod' => $module->attemptreopenmethod,

                        'maxattempts' => $module->maxattempts,

                        'markingworkflow' => $module->markingworkflow,

                        'markingallocation' => $module->markingallocation,

                        'markinganonymous' => $module->markinganonymous,

                        'requiresubmissionstatement' => $module->requiresubmissionstatement,

                        'preventsubmissionnotingroup' => $module->preventsubmissionnotingroup,

                        'timelimit' => $module->timelimit,

                        'submissionattachments' => $module->submissionattachments,

                        'configs' => $configarray

                    );

                    // Return or not intro and file attachments depending on the plugin settings.

                    if ($assign->show_intro()) {

                        $options = array('noclean' => true);

                        [$assignment['intro'], $assignment['introformat']] = \core_external\util::format_text(

                            $module->intro,

                            $module->introformat,

                            $context,

                            'mod_assign',

                            'intro',

                            null,

                            $options

                        );

                        $assignment['introfiles'] = external_util::get_area_files($context->id, 'mod_assign', 'intro', false,

                                                                                    false);

                        if ($assign->should_provide_intro_attachments($USER->id)) {

                            $assignment['introattachments'] = external_util::get_area_files($context->id, 'mod_assign',

                                ASSIGN_INTROATTACHMENT_FILEAREA, 0);

                        }

                    }

                    if ($module->requiresubmissionstatement) {

                        // Submission statement is required, return the submission statement value.

                        $adminconfig = get_config('assign');

                        // Single submission.

                        if (!$module->teamsubmission) {

                            list($assignment['submissionstatement'], $assignment['submissionstatementformat']) =

                                \core_external\util::format_text($adminconfig->submissionstatement, FORMAT_MOODLE, $context->id,

                                    'mod_assign', '', 0);

                        } else { // Team submission.

                            // One user can submit for the whole team.

                            if (!empty($adminconfig->submissionstatementteamsubmission) && !$module->requireallteammemberssubmit) {

                                list($assignment['submissionstatement'], $assignment['submissionstatementformat']) =

                                    \core_external\util::format_text($adminconfig->submissionstatementteamsubmission,

                                        FORMAT_MOODLE, $context->id, 'mod_assign', '', 0);

                            } else if (!empty($adminconfig->submissionstatementteamsubmissionallsubmit) &&

                                $module->requireallteammemberssubmit) {

                                // All team members must submit.

                                list($assignment['submissionstatement'], $assignment['submissionstatementformat']) =

                                    \core_external\util::format_text($adminconfig->submissionstatementteamsubmissionallsubmit,

                                        FORMAT_MOODLE, $context->id, 'mod_assign', '', 0);

                            }

                        }

                    }

                    if ($module->activity && $assign->submissions_open($USER->id, true)) {

                        list($assignment['activity'], $assignment['activityformat']) = \core_external\util::format_text(

                            $module->activity,

                            $module->activityformat,

                            $context,

                            'mod_assign',

                            ASSIGN_ACTIVITYATTACHMENT_FILEAREA,

                        );

                        $assignment['activityattachments'] = external_util::get_area_files($context->id, 'mod_assign',

                            ASSIGN_ACTIVITYATTACHMENT_FILEAREA, 0);

                    }

                    $assignmentarray[] = $assignment;

                }

            }

            $coursearray[]= array(

                'id' => $courses[$id]->id,

                'fullname' => \core_external\util::format_string($courses[$id]->fullname, $course->contextid),

                'shortname' => \core_external\util::format_string($courses[$id]->shortname, $course->contextid),

                'timemodified' => $courses[$id]->timemodified,

                'assignments' => $assignmentarray

            );

        }

        $result = array(

            'courses' => $coursearray,

            'warnings' => $warnings

        );

        return $result;

    }

    /**

     * Creates an assignment external_single_structure

     *

     * @return external_single_structure

     * @since Moodle 2.4

     */

    private static function get_assignments_assignment_structure() {

        return new external_single_structure(

            array(

                'id' => new external_value(PARAM_INT, 'assignment id'),

                'cmid' => new external_value(PARAM_INT, 'course module id'),

                'course' => new external_value(PARAM_INT, 'course id'),

                'name' => new external_value(PARAM_RAW, 'assignment name'),

                'nosubmissions' => new external_value(PARAM_INT, 'no submissions'),

                'submissiondrafts' => new external_value(PARAM_INT, 'submissions drafts'),

                'sendnotifications' => new external_value(PARAM_INT, 'send notifications'),

                'sendlatenotifications' => new external_value(PARAM_INT, 'send notifications'),

                'sendstudentnotifications' => new external_value(PARAM_INT, 'send student notifications (default)'),

                'duedate' => new external_value(PARAM_INT, 'assignment due date'),

                'allowsubmissionsfromdate' => new external_value(PARAM_INT, 'allow submissions from date'),

                'grade' => new external_value(PARAM_INT, 'grade type'),

                'timemodified' => new external_value(PARAM_INT, 'last time assignment was modified'),

                'completionsubmit' => new external_value(PARAM_INT, 'if enabled, set activity as complete following submission'),

                'cutoffdate' => new external_value(PARAM_INT, 'date after which submission is not accepted without an extension'),

                'gradingduedate' => new external_value(PARAM_INT, 'the expected date for marking the submissions'),

                'teamsubmission' => new external_value(PARAM_INT, 'if enabled, students submit as a team'),

                'requireallteammemberssubmit' => new external_value(PARAM_INT, 'if enabled, all team members must submit'),

                'teamsubmissiongroupingid' => new external_value(PARAM_INT, 'the grouping id for the team submission groups'),

                'blindmarking' => new external_value(PARAM_INT, 'if enabled, hide identities until reveal identities actioned'),

                'hidegrader' => new external_value(PARAM_INT, 'If enabled, hide grader to student'),

                'revealidentities' => new external_value(PARAM_INT, 'show identities for a blind marking assignment'),

                'attemptreopenmethod' => new external_value(PARAM_TEXT, 'method used to control opening new attempts'),

                'maxattempts' => new external_value(PARAM_INT, 'maximum number of attempts allowed'),

                'markingworkflow' => new external_value(PARAM_INT, 'enable marking workflow'),

                'markingallocation' => new external_value(PARAM_INT, 'enable marking allocation'),

                'markinganonymous' => new external_value(PARAM_INT, 'enable marking anonymous'),

                'requiresubmissionstatement' => new external_value(PARAM_INT, 'student must accept submission statement'),

                'preventsubmissionnotingroup' => new external_value(PARAM_INT, 'Prevent submission not in group', VALUE_OPTIONAL),

                'submissionstatement' => new external_value(PARAM_RAW, 'Submission statement formatted.', VALUE_OPTIONAL),

                'submissionstatementformat' => new external_format_value('submissionstatement', VALUE_OPTIONAL),

                'configs' => new external_multiple_structure(self::get_assignments_config_structure(), 'configuration settings'),

                'intro' => new external_value(PARAM_RAW,

                    'assignment intro, not allways returned because it deppends on the activity configuration', VALUE_OPTIONAL),

                'introformat' => new external_format_value('intro', VALUE_OPTIONAL),

                'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),

                'introattachments' => new external_files('intro attachments files', VALUE_OPTIONAL),

                'activity' => new external_value(PARAM_RAW, 'Description of activity', VALUE_OPTIONAL),

                'activityformat' => new external_format_value('activity', VALUE_OPTIONAL),

                'activityattachments' => new external_files('Files from activity field', VALUE_OPTIONAL),

                'timelimit' => new external_value(PARAM_INT, 'Time limit to complete assigment', VALUE_OPTIONAL),

                'submissionattachments' => new external_value(PARAM_INT,

                    'Flag to only show files during submission', VALUE_OPTIONAL),

            ), 'assignment information object');

    }

    /**

     * Creates an assign_plugin_config external_single_structure

     *

     * @return external_single_structure

     * @since Moodle 2.4

     */

    private static function get_assignments_config_structure() {

        return new external_single_structure(

            array(

                'id' => new external_value(PARAM_INT, 'assign_plugin_config id', VALUE_OPTIONAL),

                'assignment' => new external_value(PARAM_INT, 'assignment id', VALUE_OPTIONAL),

                'plugin' => new external_value(PARAM_TEXT, 'plugin'),

                'subtype' => new external_value(PARAM_TEXT, 'subtype'),

                'name' => new external_value(PARAM_TEXT, 'name'),

                'value' => new external_value(PARAM_TEXT, 'value')

            ), 'assignment configuration object'

        );

    }

    /**

     * Creates a course external_single_structure

     *

     * @return external_single_structure

     * @since Moodle 2.4

     */

    private static function get_assignments_course_structure() {

        return new external_single_structure(

            array(

                'id' => new external_value(PARAM_INT, 'course id'),

                'fullname' => new external_value(PARAM_RAW, 'course full name'),

                'shortname' => new external_value(PARAM_RAW, 'course short name'),

                'timemodified' => new external_value(PARAM_INT, 'last time modified'),

                'assignments' => new external_multiple_structure(self::get_assignments_assignment_structure(), 'assignment info')

              ), 'course information object'

        );

    }

    /**

     * Describes the return value for get_assignments

     *

     * @return external_single_structure

     * @since Moodle 2.4

     */

    public static function get_assignments_returns() {

        return new external_single_structure(

            array(

                'courses' => new external_multiple_structure(self::get_assignments_course_structure(), 'list of courses'),

                'warnings'  => new external_warnings('item can be \'course\' (errorcode 1 or 2) or \'module\' (errorcode 1)',

                    'When item is a course then itemid is a course id. When the item is a module then itemid is a module id',

                    'errorcode can be 1 (no access rights) or 2 (not enrolled or no permissions)')

            )

        );

    }

    /**

     * Return information (files and text fields) for the given plugins in the assignment.

     *

     * @param  assign $assign the assignment object

     * @param  array $assignplugins array of assignment plugins (submission or feedback)

     * @param  stdClass $item the item object (submission or grade)

     * @return array an array containing the plugins returned information

     */

    private static function get_plugins_data($assign, $assignplugins, $item) {

        global $CFG;

        $plugins = array();

        $fs = get_file_storage();

        foreach ($assignplugins as $assignplugin) {

            if (!$assignplugin->is_enabled() or !$assignplugin->is_visible()) {

                continue;

            }

            $plugin = array(

                'name' => $assignplugin->get_name(),

                'type' => $assignplugin->get_type()

            );

            // Subtype is 'assignsubmission', type is currently 'file' or 'onlinetext'.

            $component = $assignplugin->get_subtype().'_'.$assignplugin->get_type();

            $fileareas = $assignplugin->get_file_areas();

            foreach ($fileareas as $filearea => $name) {

                $fileareainfo = array('area' => $filearea);

                $fileareainfo['files'] = external_util::get_area_files(

                    $assign->get_context()->id,

                    $component,

                    $filearea,

                    $item->id

                );

                $plugin['fileareas'][] = $fileareainfo;

            }

            $editorfields = $assignplugin->get_editor_fields();

            foreach ($editorfields as $name => $description) {

                $editorfieldinfo = array(

                    'name' => $name,

                    'description' => $description,

                    'text' => $assignplugin->get_editor_text($name, $item->id),

                    'format' => $assignplugin->get_editor_format($name, $item->id)

                );

                // Now format the text.

                foreach ($fileareas as $filearea => $name) {

                    list($editorfieldinfo['text'], $editorfieldinfo['format']) = \core_external\util::format_text(

                        $editorfieldinfo['text'], $editorfieldinfo['format'], $assign->get_context(),

                        $component, $filearea, $item->id);

                }

                $plugin['editorfields'][] = $editorfieldinfo;

            }

            $plugins[] = $plugin;

        }

        return $plugins;

    }

    /**

     * Describes the parameters for get_submissions

     *

     * @return external_function_parameters

     * @since Moodle 2.5

     */

    public static function get_submissions_parameters() {

        return new external_function_parameters(

            array(

                'assignmentids' => new external_multiple_structure(

                    new external_value(PARAM_INT, 'assignment id'),

                    '1 or more assignment ids',

                    VALUE_REQUIRED),

                'status' => new external_value(PARAM_ALPHA, 'status', VALUE_DEFAULT, ''),

                'since' => new external_value(PARAM_INT, 'submitted since', VALUE_DEFAULT, 0),

                'before' => new external_value(PARAM_INT, 'submitted before', VALUE_DEFAULT, 0)

            )

        );

    }

    /**

     * Returns submissions for the requested assignment ids

     *

     * @param int[] $assignmentids

     * @param string $status only return submissions with this status

     * @param int $since only return submissions with timemodified >= since

     * @param int $before only return submissions with timemodified <= before

     * @return array of submissions for each requested assignment

     * @since Moodle 2.5

     */

    public static function get_submissions($assignmentids, $status = '', $since = 0, $before = 0) {

        global $DB, $CFG;

        $params = self::validate_parameters(self::get_submissions_parameters(),

                        array('assignmentids' => $assignmentids,

                              'status' => $status,

                              'since' => $since,

                              'before' => $before));

        $warnings = array();

        $assignments = array();

        // Check the user is allowed to get the submissions for the assignments requested.

        $placeholders = array();

        list($inorequalsql, $placeholders) = $DB->get_in_or_equal($params['assignmentids'], SQL_PARAMS_NAMED);

        $sql = "SELECT cm.id, cm.instance FROM {course_modules} cm JOIN {modules} md ON md.id = cm.module ".

               "WHERE md.name = :modname AND cm.instance ".$inorequalsql;

        $placeholders['modname'] = 'assign';

        $cms = $DB->get_records_sql($sql, $placeholders);

        $assigns = array();

        foreach ($cms as $cm) {

            try {

                $context = context_module::instance($cm->id);

                self::validate_context($context);

                $assign = new assign($context, null, null);

                $assign->require_view_grades();

                $assigns[] = $assign;

            } catch (Exception $e) {

                $warnings[] = array(

                    'item' => 'assignment',

                    'itemid' => $cm->instance,

                    'warningcode' => '1',

                    'message' => 'No access rights in module context'

                );

            }

        }

        foreach ($assigns as $assign) {

            $submissions = array();

            $placeholders = array('assignid1' => $assign->get_instance()->id,

                                  'assignid2' => $assign->get_instance()->id);

            $submissionmaxattempt = 'SELECT mxs.userid, mxs.groupid, MAX(mxs.attemptnumber) AS maxattempt

                                     FROM {assign_submission} mxs

                                     WHERE mxs.assignment = :assignid1 GROUP BY mxs.userid, mxs.groupid';

            $sql = "SELECT mas.id, mas.assignment,mas.userid,".

                   "mas.timecreated,mas.timemodified,mas.timestarted,mas.status,mas.groupid,mas.attemptnumber ".

                   "FROM {assign_submission} mas ".

                   "JOIN ( " . $submissionmaxattempt . " ) smx ON mas.userid = smx.userid ".

                   "AND mas.groupid = smx.groupid ".

                   "WHERE mas.assignment = :assignid2 AND mas.attemptnumber = smx.maxattempt";

            if (!empty($params['status'])) {

                $placeholders['status'] = $params['status'];

                $sql = $sql." AND mas.status = :status";

            }

            if (!empty($params['before'])) {

                $placeholders['since'] = $params['since'];

                $placeholders['before'] = $params['before'];

                $sql = $sql." AND mas.timemodified BETWEEN :since AND :before";

            } else {

                $placeholders['since'] = $params['since'];

                $sql = $sql." AND mas.timemodified >= :since";

            }

            $submissionrecords = $DB->get_records_sql($sql, $placeholders);

            if (!empty($submissionrecords)) {

                $submissionplugins = $assign->get_submission_plugins();

                foreach ($submissionrecords as $submissionrecord) {

                    $submission = array(

                        'id' => $submissionrecord->id,

                        'userid' => $submissionrecord->userid,

                        'timecreated' => $submissionrecord->timecreated,

                        'timemodified' => $submissionrecord->timemodified,

                        'timestarted' => $submissionrecord->timestarted,

                        'status' => $submissionrecord->status,

                        'attemptnumber' => $submissionrecord->attemptnumber,

                        'groupid' => $submissionrecord->groupid,

                        'plugins' => self::get_plugins_data($assign, $submissionplugins, $submissionrecord),

                        'gradingstatus' => $assign->get_grading_status($submissionrecord->userid)

                    );

                    if (($assign->get_instance()->teamsubmission

                        && $assign->can_view_group_submission($submissionrecord->groupid))

                        || (!$assign->get_instance()->teamsubmission

                        && $assign->can_view_submission($submissionrecord->userid))

                    ) {

                        $submissions[] = $submission;

                    }

                }

            } else {

                $warnings[] = array(

                    'item' => 'module',

                    'itemid' => $assign->get_instance()->id,

                    'warningcode' => '3',

                    'message' => 'No submissions found'

                );

            }

            $assignments[] = array(

                'assignmentid' => $assign->get_instance()->id,

                'submissions' => $submissions

            );

        }

        $result = array(

            'assignments' => $assignments,

            'warnings' => $warnings

        );

        return $result;

    }

    /**

     * Creates an assignment plugin structure.

     *

     * @return external_single_structure the plugin structure

     */

    private static function get_plugin_structure() {

        return new external_single_structure(

            array(

                'type' => new external_value(PARAM_TEXT, 'submission plugin type'),

                'name' => new external_value(PARAM_TEXT, 'submission plugin name'),

                'fileareas' => new external_multiple_structure(

                    new external_single_structure(

                        array (

                            'area' => new external_value (PARAM_TEXT, 'file area'),

                            'files' => new external_files('files', VALUE_OPTIONAL),

                        )

                    ), 'fileareas', VALUE_OPTIONAL

                ),

                'editorfields' => new external_multiple_structure(

                    new external_single_structure(

                        array(

                            'name' => new external_value(PARAM_TEXT, 'field name'),

                            'description' => new external_value(PARAM_RAW, 'field description'),

                            'text' => new external_value (PARAM_RAW, 'field value'),

                            'format' => new external_format_value ('text')

                        )

                    )

                    , 'editorfields', VALUE_OPTIONAL

                )

            )

        );

    }

    /**

     * Creates a submission structure.

     *

     * @return external_single_structure the submission structure

     */

    private static function get_submission_structure($required = VALUE_REQUIRED) {

        return new external_single_structure(

            array(

                'id' => new external_value(PARAM_INT, 'submission id'),

                'userid' => new external_value(PARAM_INT, 'student id'),

                'attemptnumber' => new external_value(PARAM_INT, 'attempt number'),

                'timecreated' => new external_value(PARAM_INT, 'submission creation time'),

                'timemodified' => new external_value(PARAM_INT, 'submission last modified time'),

                'timestarted' => new external_value(PARAM_INT, 'submission start time', VALUE_OPTIONAL),

                'status' => new external_value(PARAM_TEXT, 'submission status'),

                'groupid' => new external_value(PARAM_INT, 'group id'),

                'assignment' => new external_value(PARAM_INT, 'assignment id', VALUE_OPTIONAL),

                'latest' => new external_value(PARAM_INT, 'latest attempt', VALUE_OPTIONAL),

                'plugins' => new external_multiple_structure(self::get_plugin_structure(), 'plugins', VALUE_OPTIONAL),

                'gradingstatus' => new external_value(PARAM_ALPHANUMEXT, 'Grading status.', VALUE_OPTIONAL),

            ), 'submission info', $required

        );

    }

    /**

     * Creates an assign_submissions external_single_structure

     *

     * @return external_single_structure

     * @since Moodle 2.5

     */

    private static function get_submissions_structure() {

        return new external_single_structure(

            array (

                'assignmentid' => new external_value(PARAM_INT, 'assignment id'),

                'submissions' => new external_multiple_structure(self::get_submission_structure())

            )

        );

    }

    /**

     * Describes the get_submissions return value

     *

     * @return external_single_structure

     * @since Moodle 2.5

     */

    public static function get_submissions_returns() {

        return new external_single_structure(

            array(

                'assignments' => new external_multiple_structure(self::get_submissions_structure(), 'assignment submissions'),

                'warnings' => new external_warnings()

            )

        );

    }

    /**

     * Describes the parameters for set_user_flags

     * @return external_function_parameters

     * @since  Moodle 2.6

     */

    public static function set_user_flags_parameters() {

        return new external_function_parameters(

            array(

                'assignmentid'    => new external_value(PARAM_INT, 'assignment id'),

                'userflags' => new external_multiple_structure(

                    new external_single_structure(

                        array(

                            'userid'           => new external_value(PARAM_INT, 'student id'),

                            'locked'           => new external_value(PARAM_INT, 'locked', VALUE_OPTIONAL),

                            'mailed'           => new external_value(PARAM_INT, 'mailed', VALUE_OPTIONAL),

                            'extensionduedate' => new external_value(PARAM_INT, 'extension due date', VALUE_OPTIONAL),

                            'workflowstate'    => new external_value(PARAM_ALPHA, 'marking workflow state', VALUE_OPTIONAL),

                            'allocatedmarker'  => new external_value(PARAM_INT, 'allocated marker', VALUE_OPTIONAL)

                        )

                    )

                )

            )

        );

    }

    /**

     * Create or update user_flags records

     *

     * @param int $assignmentid the assignment for which the userflags are created or updated

     * @param array $userflags  An array of userflags to create or update

     * @return array containing success or failure information for each record

     * @since Moodle 2.6

     */

    public static function set_user_flags($assignmentid, $userflags = array()) {

        global $CFG, $DB;

        $params = self::validate_parameters(self::set_user_flags_parameters(),

                                            array('assignmentid' => $assignmentid,

                                                  'userflags' => $userflags));

        // Load assignment if it exists and if the user has the capability.

        list($assign, $course, $cm, $context) = self::validate_assign($params['assignmentid']);

        require_capability('mod/assign:grade', $context);

        $results = array();

        foreach ($params['userflags'] as $userflag) {

            $success = true;

            $result = array();

            $record = $assign->get_user_flags($userflag['userid'], false);

            if ($record) {

                if (isset($userflag['locked'])) {

                    $record->locked = $userflag['locked'];

                }

                if (isset($userflag['mailed'])) {

                    $record->mailed = $userflag['mailed'];

                }

                if (isset($userflag['extensionduedate'])) {

                    $record->extensionduedate = $userflag['extensionduedate'];

                }

                if (isset($userflag['workflowstate'])) {

                    $record->workflowstate = $userflag['workflowstate'];

                }

                if (isset($userflag['allocatedmarker'])) {

                    $record->allocatedmarker = $userflag['allocatedmarker'];

                }

                if ($assign->update_user_flags($record)) {

                    $result['id'] = $record->id;

                    $result['userid'] = $userflag['userid'];

                } else {