Merge branch 'MDL-67301-dynreg-squashed-310' of https://github.com/cengage/moodle...
[moodle.git] / mod / lti / service / memberships / classes / local / service / memberships.php
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/>.
17 /**
18  * This file contains a class definition for the Memberships service
19  *
20  * @package    ltiservice_memberships
21  * @copyright  2015 Vital Source Technologies http://vitalsource.com
22  * @author     Stephen Vickers
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 namespace ltiservice_memberships\local\service;
28 defined('MOODLE_INTERNAL') || die();
30 /**
31  * A service implementing Memberships.
32  *
33  * @package    ltiservice_memberships
34  * @since      Moodle 3.0
35  * @copyright  2015 Vital Source Technologies http://vitalsource.com
36  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37  */
38 class memberships extends \mod_lti\local\ltiservice\service_base {
40     /** Default prefix for context-level roles */
41     const CONTEXT_ROLE_PREFIX = 'http://purl.imsglobal.org/vocab/lis/v2/membership#';
42     /** Context-level role for Instructor */
43     const CONTEXT_ROLE_INSTRUCTOR = 'http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor';
44     /** Context-level role for Learner */
45     const CONTEXT_ROLE_LEARNER = 'http://purl.imsglobal.org/vocab/lis/v2/membership#Learner';
46     /** Capability used to identify Instructors */
47     const INSTRUCTOR_CAPABILITY = 'moodle/course:manageactivities';
48     /** Always include field */
49     const ALWAYS_INCLUDE_FIELD = 1;
50     /** Allow the instructor to decide if included */
51     const DELEGATE_TO_INSTRUCTOR = 2;
52     /** Instructor chose to include field */
53     const INSTRUCTOR_INCLUDED = 1;
54     /** Instructor delegated and approved for include */
55     const INSTRUCTOR_DELEGATE_INCLUDED = array(self::DELEGATE_TO_INSTRUCTOR && self::INSTRUCTOR_INCLUDED);
56     /** Scope for reading membership data */
57     const SCOPE_MEMBERSHIPS_READ = 'https://purl.imsglobal.org/spec/lti-nrps/scope/contextmembership.readonly';
59     /**
60      * Class constructor.
61      */
62     public function __construct() {
64         parent::__construct();
65         $this->id = 'memberships';
66         $this->name = get_string($this->get_component_id(), $this->get_component_id());
68     }
70     /**
71      * Get the resources for this service.
72      *
73      * @return array
74      */
75     public function get_resources() {
77         if (empty($this->resources)) {
78             $this->resources = array();
79             $this->resources[] = new \ltiservice_memberships\local\resources\contextmemberships($this);
80             $this->resources[] = new \ltiservice_memberships\local\resources\linkmemberships($this);
81         }
83         return $this->resources;
85     }
87     /**
88      * Get the scope(s) permitted for the tool relevant to this service.
89      *
90      * @return array
91      */
92     public function get_permitted_scopes() {
94         $scopes = array();
95         $ok = !empty($this->get_type());
96         if ($ok && isset($this->get_typeconfig()[$this->get_component_id()]) &&
97             ($this->get_typeconfig()[$this->get_component_id()] == parent::SERVICE_ENABLED)) {
98             $scopes[] = self::SCOPE_MEMBERSHIPS_READ;
99         }
101         return $scopes;
103     }
105     /**
106      * Get the scope(s) defined by this service.
107      *
108      * @return array
109      */
110     public function get_scopes() {
111         return [self::SCOPE_MEMBERSHIPS_READ];
112     }
114     /**
115      * Get the JSON for members.
116      *
117      * @param \mod_lti\local\ltiservice\resource_base $resource       Resource handling the request
118      * @param \context_course   $context    Course context
119      * @param string            $contextid  Course ID
120      * @param object            $tool       Tool instance object
121      * @param string            $role       User role requested (empty if none)
122      * @param int               $limitfrom  Position of first record to be returned
123      * @param int               $limitnum   Maximum number of records to be returned
124      * @param object            $lti        LTI instance record
125      * @param \core_availability\info_module $info Conditional availability information
126      * for LTI instance (null if context-level request)
127      *
128      * @return string
129      * @deprecated since Moodle 3.7 MDL-62599 - please do not use this function any more.
130      * @see memberships::get_members_json($resource, $context, $course, $role, $limitfrom, $limitnum, $lti, $info, $response)
131      */
132     public static function get_users_json($resource, $context, $contextid, $tool, $role, $limitfrom, $limitnum, $lti, $info) {
133         global $DB;
135         debugging('get_users_json() has been deprecated, ' .
136                   'please use memberships::get_members_json() instead.', DEBUG_DEVELOPER);
138         $course = $DB->get_record('course', array('id' => $contextid), 'id,shortname,fullname', IGNORE_MISSING);
140         $memberships = new memberships();
141         $memberships->check_tool($tool->id, null, array(self::SCOPE_MEMBERSHIPS_READ));
143         $response = new \mod_lti\local\ltiservice\response();
145         $json = $memberships->get_members_json($resource, $context, $course, $role, $limitfrom, $limitnum, $lti, $info, $response);
147         return $json;
148     }
150     /**
151      * Get the JSON for members.
152      *
153      * @param \mod_lti\local\ltiservice\resource_base $resource       Resource handling the request
154      * @param \context_course   $context    Course context
155      * @param \course           $course     Course
156      * @param string            $role       User role requested (empty if none)
157      * @param int               $limitfrom  Position of first record to be returned
158      * @param int               $limitnum   Maximum number of records to be returned
159      * @param object            $lti        LTI instance record
160      * @param \core_availability\info_module $info Conditional availability information
161      *      for LTI instance (null if context-level request)
162      * @param \mod_lti\local\ltiservice\response $response       Response object for the request
163      *
164      * @return string
165      */
166     public function get_members_json($resource, $context, $course, $role, $limitfrom, $limitnum, $lti, $info, $response) {
168         $withcapability = '';
169         $exclude = array();
170         if (!empty($role)) {
171             if ((strpos($role, 'http://') !== 0) && (strpos($role, 'https://') !== 0)) {
172                 $role = self::CONTEXT_ROLE_PREFIX . $role;
173             }
174             if ($role === self::CONTEXT_ROLE_INSTRUCTOR) {
175                 $withcapability = self::INSTRUCTOR_CAPABILITY;
176             } else if ($role === self::CONTEXT_ROLE_LEARNER) {
177                 $exclude = array_keys(get_enrolled_users($context, self::INSTRUCTOR_CAPABILITY, 0, 'u.id',
178                                                          null, null, null, true));
179             }
180         }
181         $users = get_enrolled_users($context, $withcapability, 0, 'u.*', null, 0, 0, true);
182         if (($response->get_accept() === 'application/vnd.ims.lti-nrps.v2.membershipcontainer+json') ||
183             (($response->get_accept() !== 'application/vnd.ims.lis.v2.membershipcontainer+json') &&
184             ($this->get_type()->ltiversion === LTI_VERSION_1P3))) {
185             $json = $this->users_to_json($resource, $users, $course, $exclude, $limitfrom, $limitnum, $lti, $info, $response);
186         } else {
187             $json = $this->users_to_jsonld($resource, $users, $course->id, $exclude, $limitfrom, $limitnum, $lti, $info, $response);
188         }
190         return $json;
191     }
193     /**
194      * Get the JSON-LD representation of the users.
195      *
196      * Note that when a limit is set and the exclude array is not empty, then the number of memberships
197      * returned may be less than the limit.
198      *
199      * @param \mod_lti\local\ltiservice\resource_base $resource       Resource handling the request
200      * @param array  $users               Array of user records
201      * @param string $contextid           Course ID
202      * @param array  $exclude             Array of user records to be excluded from the response
203      * @param int    $limitfrom           Position of first record to be returned
204      * @param int    $limitnum            Maximum number of records to be returned
205      * @param object $lti                 LTI instance record
206      * @param \core_availability\info_module $info Conditional availability information
207      *      for LTI instance (null if context-level request)
208      * @param \mod_lti\local\ltiservice\response $response       Response object for the request
209      *
210      * @return string
211      */
212     private function users_to_jsonld($resource, $users, $contextid, $exclude, $limitfrom, $limitnum,
213             $lti, $info, $response) {
214         global $DB;
216         $tool = $this->get_type();
217         $toolconfig = $this->get_typeconfig();
218         $arrusers = [
219             '@context' => 'http://purl.imsglobal.org/ctx/lis/v2/MembershipContainer',
220             '@type' => 'Page',
221             '@id' => $resource->get_endpoint(),
222         ];
224         $arrusers['pageOf'] = [
225             '@type' => 'LISMembershipContainer',
226             'membershipSubject' => [
227                 '@type' => 'Context',
228                 'contextId' => $contextid,
229                 'membership' => []
230             ]
231         ];
233         $enabledcapabilities = lti_get_enabled_capabilities($tool);
234         $islti2 = $tool->toolproxyid > 0;
235         $n = 0;
236         $more = false;
237         foreach ($users as $user) {
238             if (in_array($user->id, $exclude)) {
239                 continue;
240             }
241             if (!empty($info) && !$info->is_user_visible($info->get_course_module(), $user->id)) {
242                 continue;
243             }
244             $n++;
245             if ($limitnum > 0) {
246                 if ($n <= $limitfrom) {
247                     continue;
248                 }
249                 if (count($arrusers['pageOf']['membershipSubject']['membership']) >= $limitnum) {
250                     $more = true;
251                     break;
252                 }
253             }
255             $member = new \stdClass();
256             $member->{"@type" } = 'LISPerson';
257             $membership = new \stdClass();
258             $membership->status = 'Active';
259             $membership->role = explode(',', lti_get_ims_role($user->id, null, $contextid, true));
261             $instanceconfig = null;
262             if (!is_null($lti)) {
263                 $instanceconfig = lti_get_type_config_from_instance($lti->id);
264             }
265             $isallowedlticonfig = self::is_allowed_field_set($toolconfig, $instanceconfig,
266                                     ['name' => 'sendname', 'email' => 'sendemailaddr']);
268             $includedcapabilities = [
269                 'User.id'              => ['type' => 'id',
270                                             'member.field' => 'userId',
271                                             'source.value' => $user->id],
272                 'Person.sourcedId'     => ['type' => 'id',
273                                             'member.field' => 'sourcedId',
274                                             'source.value' => format_string($user->idnumber)],
275                 'Person.name.full'     => ['type' => 'name',
276                                             'member.field' => 'name',
277                                             'source.value' => format_string("{$user->firstname} {$user->lastname}")],
278                 'Person.name.given'    => ['type' => 'name',
279                                             'member.field' => 'givenName',
280                                             'source.value' => format_string($user->firstname)],
281                 'Person.name.family'   => ['type' => 'name',
282                                             'member.field' => 'familyName',
283                                             'source.value' => format_string($user->lastname)],
284                 'Person.email.primary' => ['type' => 'email',
285                                             'member.field' => 'email',
286                                             'source.value' => format_string($user->email)],
287                 'User.username'        => ['type' => 'name',
288                                            'member.field' => 'ext_user_username',
289                                            'source.value' => format_string($user->username)]
290             ];
292             if (!is_null($lti)) {
293                 $message = new \stdClass();
294                 $message->message_type = 'basic-lti-launch-request';
295                 $conditions = array('courseid' => $contextid, 'itemtype' => 'mod',
296                         'itemmodule' => 'lti', 'iteminstance' => $lti->id);
298                 if (!empty($lti->servicesalt) && $DB->record_exists('grade_items', $conditions)) {
299                     $message->lis_result_sourcedid = json_encode(lti_build_sourcedid($lti->id,
300                                                                                      $user->id,
301                                                                                      $lti->servicesalt,
302                                                                                      $lti->typeid));
303                     // Not per specification but added to comply with earlier version of the service.
304                     $member->resultSourcedId = $message->lis_result_sourcedid;
305                 }
306                 $membership->message = [$message];
307             }
309             foreach ($includedcapabilities as $capabilityname => $capability) {
310                 if ($islti2) {
311                     if (in_array($capabilityname, $enabledcapabilities)) {
312                         $member->{$capability['member.field']} = $capability['source.value'];
313                     }
314                 } else {
315                     if (($capability['type'] === 'id')
316                      || ($capability['type'] === 'name' && $isallowedlticonfig['name'])
317                      || ($capability['type'] === 'email' && $isallowedlticonfig['email'])) {
318                         $member->{$capability['member.field']} = $capability['source.value'];
319                     }
320                 }
321             }
323             $membership->member = $member;
325             $arrusers['pageOf']['membershipSubject']['membership'][] = $membership;
326         }
327         if ($more) {
328             $nextlimitfrom = $limitfrom + $limitnum;
329             $nextpage = "{$resource->get_endpoint()}?limit={$limitnum}&from={$nextlimitfrom}";
330             if (!is_null($lti)) {
331                 $nextpage .= "&rlid={$lti->id}";
332             }
333             $arrusers['nextPage'] = $nextpage;
334         }
336         $response->set_content_type('application/vnd.ims.lis.v2.membershipcontainer+json');
338         return json_encode($arrusers);
339     }
341     /**
342      * Get the NRP service JSON representation of the users.
343      *
344      * Note that when a limit is set and the exclude array is not empty, then the number of memberships
345      * returned may be less than the limit.
346      *
347      * @param \mod_lti\local\ltiservice\resource_base $resource       Resource handling the request
348      * @param array   $users               Array of user records
349      * @param \course $course              Course
350      * @param array   $exclude             Array of user records to be excluded from the response
351      * @param int     $limitfrom           Position of first record to be returned
352      * @param int     $limitnum            Maximum number of records to be returned
353      * @param object  $lti                 LTI instance record
354      * @param \core_availability\info_module  $info     Conditional availability information for LTI instance
355      * @param \mod_lti\local\ltiservice\response $response       Response object for the request
356      *
357      * @return string
358      */
359     private function users_to_json($resource, $users, $course, $exclude, $limitfrom, $limitnum,
360             $lti, $info, $response) {
361         global $DB, $CFG;
363         $tool = $this->get_type();
364         $toolconfig = $this->get_typeconfig();
366         $context = new \stdClass();
367         $context->id = $course->id;
368         $context->label = trim(html_to_text($course->shortname, 0));
369         $context->title = trim(html_to_text($course->fullname, 0));
371         $arrusers = [
372             'id' => $resource->get_endpoint(),
373             'context' => $context,
374             'members' => []
375         ];
377         $islti2 = $tool->toolproxyid > 0;
378         $n = 0;
379         $more = false;
380         foreach ($users as $user) {
381             if (in_array($user->id, $exclude)) {
382                 continue;
383             }
384             if (!empty($info) && !$info->is_user_visible($info->get_course_module(), $user->id)) {
385                 continue;
386             }
387             $n++;
388             if ($limitnum > 0) {
389                 if ($n <= $limitfrom) {
390                     continue;
391                 }
392                 if (count($arrusers['members']) >= $limitnum) {
393                     $more = true;
394                     break;
395                 }
396             }
398             $member = new \stdClass();
399             $member->status = 'Active';
400             $member->roles = explode(',', lti_get_ims_role($user->id, null, $course->id, true));
402             $instanceconfig = null;
403             if (!is_null($lti)) {
404                 $instanceconfig = lti_get_type_config_from_instance($lti->id);
405             }
406             if (!$islti2) {
407                 $isallowedlticonfig = self::is_allowed_field_set($toolconfig, $instanceconfig,
408                                         ['name' => 'sendname', 'givenname' => 'sendname', 'familyname' => 'sendname',
409                                          'email' => 'sendemailaddr']);
410             } else {
411                 $isallowedlticonfig = self::is_allowed_capability_set($tool,
412                                         ['name' => 'Person.name.full', 'givenname' => 'Person.name.given',
413                                          'familyname' => 'Person.name.family', 'email' => 'Person.email.primary']);
414             }
415             $includedcapabilities = [
416                 'User.id'              => ['type' => 'id',
417                                             'member.field' => 'user_id',
418                                             'source.value' => $user->id],
419                 'Person.sourcedId'     => ['type' => 'id',
420                                             'member.field' => 'lis_person_sourcedid',
421                                             'source.value' => format_string($user->idnumber)],
422                 'Person.name.full'     => ['type' => 'name',
423                                             'member.field' => 'name',
424                                             'source.value' => format_string("{$user->firstname} {$user->lastname}")],
425                 'Person.name.given'    => ['type' => 'givenname',
426                                             'member.field' => 'given_name',
427                                             'source.value' => format_string($user->firstname)],
428                 'Person.name.family'   => ['type' => 'familyname',
429                                             'member.field' => 'family_name',
430                                             'source.value' => format_string($user->lastname)],
431                 'Person.email.primary' => ['type' => 'email',
432                                             'member.field' => 'email',
433                                             'source.value' => format_string($user->email)]
434             ];
436             if (!is_null($lti)) {
437                 $message = new \stdClass();
438                 $message->{'https://purl.imsglobal.org/spec/lti/claim/message_type'} = 'LtiResourceLinkRequest';
439                 $conditions = array('courseid' => $course->id, 'itemtype' => 'mod',
440                         'itemmodule' => 'lti', 'iteminstance' => $lti->id);
442                 if (!empty($lti->servicesalt) && $DB->record_exists('grade_items', $conditions)) {
443                     $basicoutcome = new \stdClass();
444                     $basicoutcome->lis_result_sourcedid = json_encode(lti_build_sourcedid($lti->id,
445                                                                                      $user->id,
446                                                                                      $lti->servicesalt,
447                                                                                      $lti->typeid));
448                     // Add outcome service URL.
449                     $serviceurl = new \moodle_url('/mod/lti/service.php');
450                     $serviceurl = $serviceurl->out();
451                     $forcessl = false;
452                     if (!empty($CFG->mod_lti_forcessl)) {
453                         $forcessl = true;
454                     }
455                     if ((isset($toolconfig['forcessl']) && ($toolconfig['forcessl'] == '1')) or $forcessl) {
456                         $serviceurl = lti_ensure_url_is_https($serviceurl);
457                     }
458                     $basicoutcome->lis_outcome_service_url = $serviceurl;
459                     $message->{'https://purl.imsglobal.org/spec/lti-bo/claim/basicoutcome'} = $basicoutcome;
460                 }
461                 $member->message = [$message];
462             }
464             foreach ($includedcapabilities as $capabilityname => $capability) {
465                 if (($capability['type'] === 'id') || $isallowedlticonfig[$capability['type']]) {
466                     $member->{$capability['member.field']} = $capability['source.value'];
467                 }
468             }
470             $arrusers['members'][] = $member;
471         }
472         if ($more) {
473             $nextlimitfrom = $limitfrom + $limitnum;
474             $nextpage = "{$resource->get_endpoint()}?limit={$limitnum}&from={$nextlimitfrom}";
475             if (!is_null($lti)) {
476                 $nextpage .= "&rlid={$lti->id}";
477             }
478             $response->add_additional_header("Link: <{$nextpage}>; rel=\"next\"");
479         }
481         $response->set_content_type('application/vnd.ims.lti-nrps.v2.membershipcontainer+json');
483         return json_encode($arrusers);
484     }
486     /**
487      * Determines whether a user attribute may be used as part of LTI membership
488      * @param array             $toolconfig      Tool config
489      * @param object            $instanceconfig  Tool instance config
490      * @param array             $fields          Set of fields to return if allowed or not
491      * @return array Verification which associates an attribute with a boolean (allowed or not)
492      */
493     private static function is_allowed_field_set($toolconfig, $instanceconfig, $fields) {
494         $isallowedstate = [];
495         foreach ($fields as $key => $field) {
496             $allowed = isset($toolconfig[$field]) && (self::ALWAYS_INCLUDE_FIELD == $toolconfig[$field]);
497             if (!$allowed && isset($toolconfig[$field]) && (self::DELEGATE_TO_INSTRUCTOR == $toolconfig[$field]) &&
498                 !is_null($instanceconfig)) {
499                 $allowed = isset($instanceconfig->{"lti_{$field}"}) &&
500                           ($instanceconfig->{"lti_{$field}"} == self::INSTRUCTOR_INCLUDED);
501             }
502             $isallowedstate[$key] = $allowed;
503         }
504         return $isallowedstate;
505     }
507     /**
508      * Adds form elements for membership add/edit page.
509      *
510      * @param \MoodleQuickForm $mform
511      */
512     public function get_configuration_options(&$mform) {
513         $elementname = $this->get_component_id();
514         $options = [
515             get_string('notallow', $this->get_component_id()),
516             get_string('allow', $this->get_component_id())
517         ];
519         $mform->addElement('select', $elementname, get_string($elementname, $this->get_component_id()), $options);
520         $mform->setType($elementname, 'int');
521         $mform->setDefault($elementname, 0);
522         $mform->addHelpButton($elementname, $elementname, $this->get_component_id());
523     }
525     /**
526      * Return an array of key/values to add to the launch parameters.
527      *
528      * @param string $messagetype 'basic-lti-launch-request' or 'ContentItemSelectionRequest'.
529      * @param string $courseid The course id.
530      * @param string $user The user id.
531      * @param string $typeid The tool lti type id.
532      * @param string $modlti The id of the lti activity.
533      *
534      * The type is passed to check the configuration
535      * and not return parameters for services not used.
536      *
537      * @return array of key/value pairs to add as launch parameters.
538      */
539     public function get_launch_parameters($messagetype, $courseid, $user, $typeid, $modlti = null) {
540         global $COURSE;
542         $launchparameters = array();
543         $tool = lti_get_type_type_config($typeid);
544         if (isset($tool->{$this->get_component_id()})) {
545             if ($tool->{$this->get_component_id()} == parent::SERVICE_ENABLED && $this->is_used_in_context($typeid, $courseid)) {
546                 $launchparameters['context_memberships_url'] = '$ToolProxyBinding.memberships.url';
547                 $launchparameters['context_memberships_versions'] = '1.0,2.0';
548             }
549         }
550         return $launchparameters;
551     }