-
New Feature
-
Resolution: Unresolved
-
Minor
-
None
-
3.2, 3.2.1, 3.2.2, 3.3, 4.2.1
-
MOODLE_32_STABLE, MOODLE_33_STABLE, MOODLE_402_STABLE
Here at NC State University we have external tools that interact in various ways directly and indirectly with Moodle. We wanted to use Moodle's Web Service functionality to retrieve user(s) grades for a particular course and so created the following new function in grade/report/overview/classes/external.php. The function was registered in grade/report/overview/db/services.php
A Web Service Role, user, and token was created in Moodle following the documentation for creating web services. https://docs.moodle.org/33/en/Web_services
Testing instructions: Use this client - https://github.com/davidlanier/Moodle-Course-Grades-WebService-Client
/**
|
* Describes the parameters for get_course_users_grade.
|
*
|
* @return external_external_function_parameters
|
* @since Moodle 3.2
|
*/
|
public static function get_course_users_grade_parameters() { |
return new external_function_parameters ( |
array( |
'courseid' => new external_value(PARAM_INT, 'Get grades for this course (required)', VALUE_REQUIRED, 0), |
'userid' => new external_value(PARAM_INT, 'Return grade only for this user (optional)', VALUE_DEFAULT, 0), |
'gradeformat' => new external_value(PARAM_RAW, 'The desired format for the grade (optional)', VALUE_DEFAULT, 0), |
'localized' => new external_value(PARAM_RAW, 'Use localized decimals separator (optional)', VALUE_DEFAULT, 0), |
'decimals' => new external_value(PARAM_RAW, 'Number of floating points after the decimal (optional)', VALUE_DEFAULT, 0), |
)
|
);
|
}
|
|
|
/**
|
* Get the given user courses final grades
|
*
|
* @param int $courseid get grades for users in this course (required)
|
* @param int $userid get grade for user in this course (optional)
|
* @param const $gradeformat returns grades in specified format (default: GRADE_DISPLAY_TYPE_REAL)
|
* @param bool $localized use localized decimal separator
|
* @param int $decimals The number of decimal places
|
*
|
* Available grade formats:
|
* GRADE_DISPLAY_TYPE_REAL
|
* GRADE_DISPLAY_TYPE_PERCENTAGE
|
* GRADE_DISPLAY_TYPE_LETTER
|
* GRADE_DISPLAY_TYPE_REAL_PERCENTAGE
|
* GRADE_DISPLAY_TYPE_REAL_LETTER
|
* GRADE_DISPLAY_TYPE_PERCENTAGE_REAL
|
* GRADE_DISPLAY_TYPE_LETTER_REAL
|
* GRADE_DISPLAY_TYPE_LETTER_PERCENTAGE
|
* GRADE_DISPLAY_TYPE_PERCENTAGE_LETTER
|
*
|
* @return array the grades tables
|
* @since Moodle 3.2
|
*/
|
public static function get_course_users_grade($courseid, $userid=0, $gradeformat=GRADE_DISPLAY_TYPE_LETTER, $localized=true, $decimals=null) { |
$warnings = []; |
|
|
// Validate the parameter. |
$params = self::validate_parameters(self::get_course_users_grade_parameters(), |
array( |
'courseid' => $courseid, |
'userid' => $userid, |
'gradeformat' => $gradeformat, |
)
|
);
|
$courseid = $params['courseid']; |
|
|
$systemcontext = context_system::instance(); |
self::validate_context($systemcontext); |
|
|
$userids = []; |
// We need the site course, and course context. |
$course = get_course($courseid); |
$context = context_course::instance($course->id); |
|
|
if ($userid == 0) { |
$foptions[] = [ |
'name' => 'userfields', |
'value' => 'id,idnumber,firstname,lastname,email', |
];
|
|
|
$users = core_enrol_external::get_enrolled_users($courseid, $foptions); |
|
|
foreach ($users as $user) { |
if (!empty($user['idnumber'])) { |
$userids[] = $user['id']; |
}
|
}
|
}
|
else { |
$userids[] = $userid; |
// todo Need to populate $users for a single userid. |
// Not sure which function will accept a single userid and return the same data as get_enrolled_users? |
}
|
|
|
// Force a regrade if required. |
grade_regrade_final_grades_if_required($course); |
|
|
$coursegradeitem = grade_item::fetch_course_item($course->id); |
$usergradegrade = grade_grade::fetch_users_grades($coursegradeitem, $userids); |
$graderesultarray = []; |
|
|
foreach($usergradegrade as $gradeuserid => $gradegrade) { |
$usergrade = []; |
$usergrade['userid'] = $gradeuserid; |
foreach ($users as $user) { |
if ($usergrade['userid'] == $user['id']) { |
$usergrade['idnumber'] = $user['idnumber']; |
$usergrade['fullname'] = $user['fullname']; |
$usergrade['email'] = $user['email']; |
}
|
else { |
continue; |
}
|
}
|
$usergrade['finalgrade'] = $gradegrade->finalgrade; |
$usergrade['grademax'] = $gradegrade->rawgrademax; |
if (is_null($displaytype)) { |
$displaytype = $coursegradeitem->get_displaytype(); |
}
|
if (is_null($decimals)) { |
$decimals = $coursegradeitem->get_decimals(); |
}
|
|
|
$value = (float) $gradegrade->finalgrade; |
switch ($gradeformat) { |
case GRADE_DISPLAY_TYPE_REAL: |
$usergrade['gradeformatted'] = grade_format_gradevalue_real($value, $coursegradeitem, $decimals, $localized); |
break; |
case GRADE_DISPLAY_TYPE_PERCENTAGE: |
$usergrade['gradeformatted'] = grade_format_gradevalue_percentage($value, $coursegradeitem, $decimals, $localized); |
break; |
case GRADE_DISPLAY_TYPE_LETTER: |
$usergrade['gradeformatted'] = grade_format_gradevalue_letter($value, $coursegradeitem); |
break; |
case GRADE_DISPLAY_TYPE_REAL_PERCENTAGE: |
$usergrade['gradeformatted'] = grade_format_gradevalue_real($value, $coursegradeitem, $decimals, $localized) |
. ' (' . grade_format_gradevalue_percentage($value, $coursegradeitem, $decimals, $localized) . ')'; |
break; |
case GRADE_DISPLAY_TYPE_REAL_LETTER: |
$usergrade['gradeformatted'] = grade_format_gradevalue_real($value, $coursegradeitem, $decimals, $localized) |
. ' (' . grade_format_gradevalue_letter($value, $coursegradeitem) . ')'; |
break; |
case GRADE_DISPLAY_TYPE_PERCENTAGE_REAL: |
$usergrade['gradeformatted'] = grade_format_gradevalue_percentage($value, $coursegradeitem, $decimals, $localized) |
. ' (' . grade_format_gradevalue_real($value, $coursegradeitem, $decimals, $localized) . ')'; |
break; |
case GRADE_DISPLAY_TYPE_LETTER_REAL: |
$usergrade['gradeformatted'] = grade_format_gradevalue_letter($value, $coursegradeitem) |
. ' (' . grade_format_gradevalue_real($value, $coursegradeitem, $decimals, $localized) . ')'; |
break; |
case GRADE_DISPLAY_TYPE_LETTER_PERCENTAGE: |
$usergrade['gradeformatted'] = grade_format_gradevalue_letter($value, $coursegradeitem) |
. ' (' . grade_format_gradevalue_percentage($value, $coursegradeitem, $decimals, $localized) . ')'; |
break; |
case GRADE_DISPLAY_TYPE_PERCENTAGE_LETTER: |
$usergrade['gradeformatted'] = grade_format_gradevalue_percentage($value, $coursegradeitem, $decimals, $localized) |
. ' (' . grade_format_gradevalue_letter($value, $coursegradeitem) . ')'; |
break; |
default: |
$usergrade['gradeformatted'] = ''; |
break; |
}
|
|
|
$graderesultarray[] = $usergrade; |
}
|
|
|
$result = array(); |
$result['grades'] = $graderesultarray; |
$result['warnings'] = array(); |
return $result; |
}
|
|
|
/**
|
* Describes the get_course_users_grade return value.
|
*
|
* @return external_single_structure
|
* @since Moodle 3.2
|
*/
|
public static function get_course_users_grade_returns() { |
return new external_single_structure( |
array( |
'grades' => new external_multiple_structure( |
new external_single_structure( |
array( |
'id' => new external_value(PARAM_INT, 'User ID', VALUE_OPTIONAL), |
'fullname' => new external_value(PARAM_RAW, 'Full Name', VALUE_OPTIONAL), |
'email' => new external_value(PARAM_RAW, 'Email', VALUE_OPTIONAL), |
'userid' => new external_value(PARAM_RAW, 'ID Number', VALUE_OPTIONAL), |
'idnumber' => new external_value(PARAM_RAW, 'ID Number', VALUE_OPTIONAL), |
'courseid' => new external_value(PARAM_RAW, 'Course ID', VALUE_OPTIONAL), |
'finalgrade' => new external_value(PARAM_RAW, 'raw final grade', VALUE_OPTIONAL), |
'grademax' => new external_value(PARAM_RAW, 'max final grade', VALUE_OPTIONAL), |
'gradeformatted'=> new external_value(PARAM_RAW, 'Grade formatted', VALUE_OPTIONAL), |
)
|
)
|
),
|
'warnings' => new external_warnings() |
)
|
);
|
}
|
|