Merge branch 'MDL-63009-master' of git://github.com/mickhawkins/moodle
[moodle.git] / admin / tool / dataprivacy / classes / api.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  * Class containing helper methods for processing data requests.
19  *
20  * @package    tool_dataprivacy
21  * @copyright  2018 Jun Pataleta
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
24 namespace tool_dataprivacy;
26 use coding_exception;
27 use context_helper;
28 use context_system;
29 use core\invalid_persistent_exception;
30 use core\message\message;
31 use core\task\manager;
32 use core_privacy\local\request\approved_contextlist;
33 use core_privacy\local\request\contextlist_collection;
34 use core_user;
35 use dml_exception;
36 use moodle_exception;
37 use moodle_url;
38 use required_capability_exception;
39 use stdClass;
40 use tool_dataprivacy\external\data_request_exporter;
41 use tool_dataprivacy\local\helper;
42 use tool_dataprivacy\task\initiate_data_request_task;
43 use tool_dataprivacy\task\process_data_request_task;
45 defined('MOODLE_INTERNAL') || die();
47 /**
48  * Class containing helper methods for processing data requests.
49  *
50  * @copyright  2018 Jun Pataleta
51  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
52  */
53 class api {
55     /** Data export request type. */
56     const DATAREQUEST_TYPE_EXPORT = 1;
58     /** Data deletion request type. */
59     const DATAREQUEST_TYPE_DELETE = 2;
61     /** Other request type. Usually of enquiries to the DPO. */
62     const DATAREQUEST_TYPE_OTHERS = 3;
64     /** Newly submitted and we haven't yet started finding out where they have data. */
65     const DATAREQUEST_STATUS_PENDING = 0;
67     /** Newly submitted and we have started to find the location of data. */
68     const DATAREQUEST_STATUS_PREPROCESSING = 1;
70     /** Metadata ready and awaiting review and approval by the Data Protection officer. */
71     const DATAREQUEST_STATUS_AWAITING_APPROVAL = 2;
73     /** Request approved and will be processed soon. */
74     const DATAREQUEST_STATUS_APPROVED = 3;
76     /** The request is now being processed. */
77     const DATAREQUEST_STATUS_PROCESSING = 4;
79     /** Information/other request completed. */
80     const DATAREQUEST_STATUS_COMPLETE = 5;
82     /** Data request cancelled by the user. */
83     const DATAREQUEST_STATUS_CANCELLED = 6;
85     /** Data request rejected by the DPO. */
86     const DATAREQUEST_STATUS_REJECTED = 7;
88     /** Data request download ready. */
89     const DATAREQUEST_STATUS_DOWNLOAD_READY = 8;
91     /** Data request expired. */
92     const DATAREQUEST_STATUS_EXPIRED = 9;
94     /** Data delete request completed, account is removed. */
95     const DATAREQUEST_STATUS_DELETED = 10;
97     /**
98      * Determines whether the user can contact the site's Data Protection Officer via Moodle.
99      *
100      * @return boolean True when tool_dataprivacy|contactdataprotectionofficer is enabled.
101      * @throws dml_exception
102      */
103     public static function can_contact_dpo() {
104         return get_config('tool_dataprivacy', 'contactdataprotectionofficer') == 1;
105     }
107     /**
108      * Checks whether the current user has the capability to manage data requests.
109      *
110      * @param int $userid The user ID.
111      * @return bool
112      */
113     public static function can_manage_data_requests($userid) {
114         // Privacy officers can manage data requests.
115         return self::is_site_dpo($userid);
116     }
118     /**
119      * Checks if the current user can manage the data registry at the provided id.
120      *
121      * @param int $contextid Fallback to system context id.
122      * @throws \required_capability_exception
123      * @return null
124      */
125     public static function check_can_manage_data_registry($contextid = false) {
126         if ($contextid) {
127             $context = \context_helper::instance_by_id($contextid);
128         } else {
129             $context = \context_system::instance();
130         }
132         require_capability('tool/dataprivacy:managedataregistry', $context);
133     }
135     /**
136      * Fetches the list of configured privacy officer roles.
137      *
138      * Every time this function is called, it checks each role if they have the 'managedatarequests' capability and removes
139      * any role that doesn't have the required capability anymore.
140      *
141      * @return int[]
142      * @throws dml_exception
143      */
144     public static function get_assigned_privacy_officer_roles() {
145         $roleids = [];
147         // Get roles from config.
148         $configroleids = explode(',', str_replace(' ', '', get_config('tool_dataprivacy', 'dporoles')));
149         if (!empty($configroleids)) {
150             // Fetch roles that have the capability to manage data requests.
151             $capableroles = array_keys(get_roles_with_capability('tool/dataprivacy:managedatarequests'));
153             // Extract the configured roles that have the capability from the list of capable roles.
154             $roleids = array_intersect($capableroles, $configroleids);
155         }
157         return $roleids;
158     }
160     /**
161      * Fetches the role shortnames of Data Protection Officer roles.
162      *
163      * @return array An array of the DPO role shortnames
164      */
165     public static function get_dpo_role_names() : array {
166         global $DB;
168         $dporoleids = self::get_assigned_privacy_officer_roles();
169         $dponames = array();
171         if (!empty($dporoleids)) {
172             list($insql, $inparams) = $DB->get_in_or_equal($dporoleids);
173             $dponames = $DB->get_fieldset_select('role', 'shortname', "id {$insql}", $inparams);
174         }
176         return $dponames;
177     }
179     /**
180      * Fetches the list of users with the Privacy Officer role.
181      */
182     public static function get_site_dpos() {
183         // Get role(s) that can manage data requests.
184         $dporoles = self::get_assigned_privacy_officer_roles();
186         $dpos = [];
187         $context = context_system::instance();
188         foreach ($dporoles as $roleid) {
189             $allnames = get_all_user_name_fields(true, 'u');
190             $fields = 'u.id, u.confirmed, u.username, '. $allnames . ', ' .
191                       'u.maildisplay, u.mailformat, u.maildigest, u.email, u.emailstop, u.city, '.
192                       'u.country, u.picture, u.idnumber, u.department, u.institution, '.
193                       'u.lang, u.timezone, u.lastaccess, u.mnethostid, u.auth, u.suspended, u.deleted, ' .
194                       'r.name AS rolename, r.sortorder, '.
195                       'r.shortname AS roleshortname, rn.name AS rolecoursealias';
196             // Fetch users that can manage data requests.
197             $dpos += get_role_users($roleid, $context, false, $fields);
198         }
200         // If the site has no data protection officer, defer to site admin(s).
201         if (empty($dpos)) {
202             $dpos = get_admins();
203         }
204         return $dpos;
205     }
207     /**
208      * Checks whether a given user is a site Privacy Officer.
209      *
210      * @param int $userid The user ID.
211      * @return bool
212      */
213     public static function is_site_dpo($userid) {
214         $dpos = self::get_site_dpos();
215         return array_key_exists($userid, $dpos) || is_siteadmin();
216     }
218     /**
219      * Lodges a data request and sends the request details to the site Data Protection Officer(s).
220      *
221      * @param int $foruser The user whom the request is being made for.
222      * @param int $type The request type.
223      * @param string $comments Request comments.
224      * @return data_request
225      * @throws invalid_persistent_exception
226      * @throws coding_exception
227      */
228     public static function create_data_request($foruser, $type, $comments = '') {
229         global $USER;
231         $datarequest = new data_request();
232         // The user the request is being made for.
233         $datarequest->set('userid', $foruser);
235         $requestinguser = $USER->id;
236         // Check when the user is making a request on behalf of another.
237         if ($requestinguser != $foruser) {
238             if (self::is_site_dpo($requestinguser)) {
239                 // The user making the request is a DPO. Should be fine.
240                 $datarequest->set('dpo', $requestinguser);
241             } else {
242                 // If not a DPO, only users with the capability to make data requests for the user should be allowed.
243                 // (e.g. users with the Parent role, etc).
244                 if (!self::can_create_data_request_for_user($foruser)) {
245                     $forusercontext = \context_user::instance($foruser);
246                     throw new required_capability_exception($forusercontext,
247                             'tool/dataprivacy:makedatarequestsforchildren', 'nopermissions', '');
248                 }
249             }
250         }
251         // The user making the request.
252         $datarequest->set('requestedby', $requestinguser);
253         // Set status.
254         $datarequest->set('status', self::DATAREQUEST_STATUS_PENDING);
255         // Set request type.
256         $datarequest->set('type', $type);
257         // Set request comments.
258         $datarequest->set('comments', $comments);
260         // Store subject access request.
261         $datarequest->create();
263         // Fire an ad hoc task to initiate the data request process.
264         $task = new initiate_data_request_task();
265         $task->set_custom_data(['requestid' => $datarequest->get('id')]);
266         manager::queue_adhoc_task($task, true);
268         return $datarequest;
269     }
271     /**
272      * Fetches the list of the data requests.
273      *
274      * If user ID is provided, it fetches the data requests for the user.
275      * Otherwise, it fetches all of the data requests, provided that the user has the capability to manage data requests.
276      * (e.g. Users with the Data Protection Officer roles)
277      *
278      * @param int $userid The User ID.
279      * @param int[] $statuses The status filters.
280      * @param int[] $types The request type filters.
281      * @param string $sort The order by clause.
282      * @param int $offset Amount of records to skip.
283      * @param int $limit Amount of records to fetch.
284      * @return data_request[]
285      * @throws coding_exception
286      * @throws dml_exception
287      */
288     public static function get_data_requests($userid = 0, $statuses = [], $types = [], $sort = '', $offset = 0, $limit = 0) {
289         global $DB, $USER;
290         $results = [];
291         $sqlparams = [];
292         $sqlconditions = [];
294         // Set default sort.
295         if (empty($sort)) {
296             $sort = 'status ASC, timemodified ASC';
297         }
299         // Set status filters.
300         if (!empty($statuses)) {
301             list($statusinsql, $sqlparams) = $DB->get_in_or_equal($statuses, SQL_PARAMS_NAMED);
302             $sqlconditions[] = "status $statusinsql";
303         }
305         // Set request type filter.
306         if (!empty($types)) {
307             list($typeinsql, $typeparams) = $DB->get_in_or_equal($types, SQL_PARAMS_NAMED);
308             $sqlconditions[] = "type $typeinsql";
309             $sqlparams = array_merge($sqlparams, $typeparams);
310         }
312         if ($userid) {
313             // Get the data requests for the user or data requests made by the user.
314             $sqlconditions[] = "(userid = :userid OR requestedby = :requestedby)";
315             $params = [
316                 'userid' => $userid,
317                 'requestedby' => $userid
318             ];
320             // Build a list of user IDs that the user is allowed to make data requests for.
321             // Of course, the user should be included in this list.
322             $alloweduserids = [$userid];
323             // Get any users that the user can make data requests for.
324             if ($children = helper::get_children_of_user($userid)) {
325                 // Get the list of user IDs of the children and merge to the allowed user IDs.
326                 $alloweduserids = array_merge($alloweduserids, array_keys($children));
327             }
328             list($insql, $inparams) = $DB->get_in_or_equal($alloweduserids, SQL_PARAMS_NAMED);
329             $sqlconditions[] .= "userid $insql";
330             $select = implode(' AND ', $sqlconditions);
331             $params = array_merge($params, $inparams, $sqlparams);
333             $results = data_request::get_records_select($select, $params, $sort, '*', $offset, $limit);
334         } else {
335             // If the current user is one of the site's Data Protection Officers, then fetch all data requests.
336             if (self::is_site_dpo($USER->id)) {
337                 if (!empty($sqlconditions)) {
338                     $select = implode(' AND ', $sqlconditions);
339                     $results = data_request::get_records_select($select, $sqlparams, $sort, '*', $offset, $limit);
340                 } else {
341                     $results = data_request::get_records(null, $sort, '', $offset, $limit);
342                 }
343             }
344         }
346         // If any are due to expire, expire them and re-fetch updated data.
347         if (empty($statuses)
348                 || in_array(self::DATAREQUEST_STATUS_DOWNLOAD_READY, $statuses)
349                 || in_array(self::DATAREQUEST_STATUS_EXPIRED, $statuses)) {
350             $expiredrequests = data_request::get_expired_requests($userid);
352             if (!empty($expiredrequests)) {
353                 data_request::expire($expiredrequests);
354                 $results = self::get_data_requests($userid, $statuses, $types, $sort, $offset, $limit);
355             }
356         }
358         return $results;
359     }
361     /**
362      * Fetches the count of data request records based on the given parameters.
363      *
364      * @param int $userid The User ID.
365      * @param int[] $statuses The status filters.
366      * @param int[] $types The request type filters.
367      * @return int
368      * @throws coding_exception
369      * @throws dml_exception
370      */
371     public static function get_data_requests_count($userid = 0, $statuses = [], $types = []) {
372         global $DB, $USER;
373         $count = 0;
374         $sqlparams = [];
375         $sqlconditions = [];
376         if (!empty($statuses)) {
377             list($statusinsql, $sqlparams) = $DB->get_in_or_equal($statuses, SQL_PARAMS_NAMED);
378             $sqlconditions[] = "status $statusinsql";
379         }
380         if (!empty($types)) {
381             list($typeinsql, $typeparams) = $DB->get_in_or_equal($types, SQL_PARAMS_NAMED);
382             $sqlconditions[] = "type $typeinsql";
383             $sqlparams = array_merge($sqlparams, $typeparams);
384         }
385         if ($userid) {
386             // Get the data requests for the user or data requests made by the user.
387             $sqlconditions[] = "(userid = :userid OR requestedby = :requestedby)";
388             $params = [
389                 'userid' => $userid,
390                 'requestedby' => $userid
391             ];
393             // Build a list of user IDs that the user is allowed to make data requests for.
394             // Of course, the user should be included in this list.
395             $alloweduserids = [$userid];
396             // Get any users that the user can make data requests for.
397             if ($children = helper::get_children_of_user($userid)) {
398                 // Get the list of user IDs of the children and merge to the allowed user IDs.
399                 $alloweduserids = array_merge($alloweduserids, array_keys($children));
400             }
401             list($insql, $inparams) = $DB->get_in_or_equal($alloweduserids, SQL_PARAMS_NAMED);
402             $sqlconditions[] .= "userid $insql";
403             $select = implode(' AND ', $sqlconditions);
404             $params = array_merge($params, $inparams, $sqlparams);
406             $count = data_request::count_records_select($select, $params);
407         } else {
408             // If the current user is one of the site's Data Protection Officers, then fetch all data requests.
409             if (self::is_site_dpo($USER->id)) {
410                 if (!empty($sqlconditions)) {
411                     $select = implode(' AND ', $sqlconditions);
412                     $count = data_request::count_records_select($select, $sqlparams);
413                 } else {
414                     $count = data_request::count_records();
415                 }
416             }
417         }
419         return $count;
420     }
422     /**
423      * Checks whether there is already an existing pending/in-progress data request for a user for a given request type.
424      *
425      * @param int $userid The user ID.
426      * @param int $type The request type.
427      * @return bool
428      * @throws coding_exception
429      * @throws dml_exception
430      */
431     public static function has_ongoing_request($userid, $type) {
432         global $DB;
434         // Check if the user already has an incomplete data request of the same type.
435         $nonpendingstatuses = [
436             self::DATAREQUEST_STATUS_COMPLETE,
437             self::DATAREQUEST_STATUS_CANCELLED,
438             self::DATAREQUEST_STATUS_REJECTED,
439             self::DATAREQUEST_STATUS_DOWNLOAD_READY,
440             self::DATAREQUEST_STATUS_EXPIRED,
441             self::DATAREQUEST_STATUS_DELETED,
442         ];
443         list($insql, $inparams) = $DB->get_in_or_equal($nonpendingstatuses, SQL_PARAMS_NAMED);
444         $select = 'type = :type AND userid = :userid AND status NOT ' . $insql;
445         $params = array_merge([
446             'type' => $type,
447             'userid' => $userid
448         ], $inparams);
450         return data_request::record_exists_select($select, $params);
451     }
453     /**
454      * Determines whether a request is active or not based on its status.
455      *
456      * @param int $status The request status.
457      * @return bool
458      */
459     public static function is_active($status) {
460         // List of statuses which doesn't require any further processing.
461         $finalstatuses = [
462             self::DATAREQUEST_STATUS_COMPLETE,
463             self::DATAREQUEST_STATUS_CANCELLED,
464             self::DATAREQUEST_STATUS_REJECTED,
465             self::DATAREQUEST_STATUS_DOWNLOAD_READY,
466             self::DATAREQUEST_STATUS_EXPIRED,
467             self::DATAREQUEST_STATUS_DELETED,
468         ];
470         return !in_array($status, $finalstatuses);
471     }
473     /**
474      * Cancels the data request for a given request ID.
475      *
476      * @param int $requestid The request identifier.
477      * @param int $status The request status.
478      * @param int $dpoid The user ID of the Data Protection Officer
479      * @param string $comment The comment about the status update.
480      * @return bool
481      * @throws invalid_persistent_exception
482      * @throws coding_exception
483      */
484     public static function update_request_status($requestid, $status, $dpoid = 0, $comment = '') {
485         // Update the request.
486         $datarequest = new data_request($requestid);
487         $datarequest->set('status', $status);
488         if ($dpoid) {
489             $datarequest->set('dpo', $dpoid);
490         }
491         // Update the comment if necessary.
492         if (!empty(trim($comment))) {
493             $params = [
494                 'date' => userdate(time()),
495                 'comment' => $comment
496             ];
497             $commenttosave = get_string('datecomment', 'tool_dataprivacy', $params);
498             // Check if there's an existing DPO comment.
499             $currentcomment = trim($datarequest->get('dpocomment'));
500             if ($currentcomment) {
501                 // Append the new comment to the current comment and give them 1 line space in between.
502                 $commenttosave = $currentcomment . PHP_EOL . PHP_EOL . $commenttosave;
503             }
504             $datarequest->set('dpocomment', $commenttosave);
505         }
507         return $datarequest->update();
508     }
510     /**
511      * Fetches a request based on the request ID.
512      *
513      * @param int $requestid The request identifier
514      * @return data_request
515      */
516     public static function get_request($requestid) {
517         return new data_request($requestid);
518     }
520     /**
521      * Approves a data request based on the request ID.
522      *
523      * @param int $requestid The request identifier
524      * @return bool
525      * @throws coding_exception
526      * @throws dml_exception
527      * @throws invalid_persistent_exception
528      * @throws required_capability_exception
529      * @throws moodle_exception
530      */
531     public static function approve_data_request($requestid) {
532         global $USER;
534         // Check first whether the user can manage data requests.
535         if (!self::can_manage_data_requests($USER->id)) {
536             $context = context_system::instance();
537             throw new required_capability_exception($context, 'tool/dataprivacy:managedatarequests', 'nopermissions', '');
538         }
540         // Check if request is already awaiting for approval.
541         $request = new data_request($requestid);
542         if ($request->get('status') != self::DATAREQUEST_STATUS_AWAITING_APPROVAL) {
543             throw new moodle_exception('errorrequestnotwaitingforapproval', 'tool_dataprivacy');
544         }
546         // Update the status and the DPO.
547         $result = self::update_request_status($requestid, self::DATAREQUEST_STATUS_APPROVED, $USER->id);
549         // Approve all the contexts attached to the request.
550         // Currently, approving the request implicitly approves all associated contexts, but this may change in future, allowing
551         // users to selectively approve certain contexts only.
552         self::update_request_contexts_with_status($requestid, contextlist_context::STATUS_APPROVED);
554         // Fire an ad hoc task to initiate the data request process.
555         $task = new process_data_request_task();
556         $task->set_custom_data(['requestid' => $requestid]);
557         if ($request->get('type') == self::DATAREQUEST_TYPE_EXPORT) {
558             $task->set_userid($request->get('userid'));
559         }
560         manager::queue_adhoc_task($task, true);
562         return $result;
563     }
565     /**
566      * Rejects a data request based on the request ID.
567      *
568      * @param int $requestid The request identifier
569      * @return bool
570      * @throws coding_exception
571      * @throws dml_exception
572      * @throws invalid_persistent_exception
573      * @throws required_capability_exception
574      * @throws moodle_exception
575      */
576     public static function deny_data_request($requestid) {
577         global $USER;
579         if (!self::can_manage_data_requests($USER->id)) {
580             $context = context_system::instance();
581             throw new required_capability_exception($context, 'tool/dataprivacy:managedatarequests', 'nopermissions', '');
582         }
584         // Check if request is already awaiting for approval.
585         $request = new data_request($requestid);
586         if ($request->get('status') != self::DATAREQUEST_STATUS_AWAITING_APPROVAL) {
587             throw new moodle_exception('errorrequestnotwaitingforapproval', 'tool_dataprivacy');
588         }
590         // Update the status and the DPO.
591         return self::update_request_status($requestid, self::DATAREQUEST_STATUS_REJECTED, $USER->id);
592     }
594     /**
595      * Sends a message to the site's Data Protection Officer about a request.
596      *
597      * @param stdClass $dpo The DPO user record
598      * @param data_request $request The data request
599      * @return int|false
600      * @throws coding_exception
601      * @throws moodle_exception
602      */
603     public static function notify_dpo($dpo, data_request $request) {
604         global $PAGE, $SITE;
606         $output = $PAGE->get_renderer('tool_dataprivacy');
608         $usercontext = \context_user::instance($request->get('requestedby'));
609         $requestexporter = new data_request_exporter($request, ['context' => $usercontext]);
610         $requestdata = $requestexporter->export($output);
612         // Create message to send to the Data Protection Officer(s).
613         $typetext = null;
614         $typetext = $requestdata->typename;
615         $subject = get_string('datarequestemailsubject', 'tool_dataprivacy', $typetext);
617         $requestedby = $requestdata->requestedbyuser;
618         $datarequestsurl = new moodle_url('/admin/tool/dataprivacy/datarequests.php');
619         $message = new message();
620         $message->courseid          = $SITE->id;
621         $message->component         = 'tool_dataprivacy';
622         $message->name              = 'contactdataprotectionofficer';
623         $message->userfrom          = $requestedby->id;
624         $message->replyto           = $requestedby->email;
625         $message->replytoname       = $requestedby->fullname;
626         $message->subject           = $subject;
627         $message->fullmessageformat = FORMAT_HTML;
628         $message->notification      = 1;
629         $message->contexturl        = $datarequestsurl;
630         $message->contexturlname    = get_string('datarequests', 'tool_dataprivacy');
632         // Prepare the context data for the email message body.
633         $messagetextdata = [
634             'requestedby' => $requestedby->fullname,
635             'requesttype' => $typetext,
636             'requestdate' => userdate($requestdata->timecreated),
637             'requestorigin' => $SITE->fullname,
638             'requestoriginurl' => new moodle_url('/'),
639             'requestcomments' => $requestdata->messagehtml,
640             'datarequestsurl' => $datarequestsurl
641         ];
642         $requestingfor = $requestdata->foruser;
643         if ($requestedby->id == $requestingfor->id) {
644             $messagetextdata['requestfor'] = $messagetextdata['requestedby'];
645         } else {
646             $messagetextdata['requestfor'] = $requestingfor->fullname;
647         }
649         // Email the data request to the Data Protection Officer(s)/Admin(s).
650         $messagetextdata['dponame'] = fullname($dpo);
651         // Render message email body.
652         $messagehtml = $output->render_from_template('tool_dataprivacy/data_request_email', $messagetextdata);
653         $message->userto = $dpo;
654         $message->fullmessage = html_to_text($messagehtml);
655         $message->fullmessagehtml = $messagehtml;
657         // Send message.
658         return message_send($message);
659     }
661     /**
662      * Checks whether a non-DPO user can make a data request for another user.
663      *
664      * @param int $user The user ID of the target user.
665      * @param int $requester The user ID of the user making the request.
666      * @return bool
667      * @throws coding_exception
668      */
669     public static function can_create_data_request_for_user($user, $requester = null) {
670         $usercontext = \context_user::instance($user);
671         return has_capability('tool/dataprivacy:makedatarequestsforchildren', $usercontext, $requester);
672     }
674     /**
675      * Checks whether a user can download a data request.
676      *
677      * @param int $userid Target user id (subject of data request)
678      * @param int $requesterid Requester user id (person who requsted it)
679      * @param int|null $downloaderid Person who wants to download user id (default current)
680      * @return bool
681      * @throws coding_exception
682      */
683     public static function can_download_data_request_for_user($userid, $requesterid, $downloaderid = null) {
684         global $USER;
686         if (!$downloaderid) {
687             $downloaderid = $USER->id;
688         }
690         $usercontext = \context_user::instance($userid);
691         // If it's your own and you have the right capability, you can download it.
692         if ($userid == $downloaderid && has_capability('tool/dataprivacy:downloadownrequest', $usercontext, $downloaderid)) {
693             return true;
694         }
695         // If you can download anyone's in that context, you can download it.
696         if (has_capability('tool/dataprivacy:downloadallrequests', $usercontext, $downloaderid)) {
697             return true;
698         }
699         // If you can have the 'child access' ability to request in that context, and you are the one
700         // who requested it, then you can download it.
701         if ($requesterid == $downloaderid && self::can_create_data_request_for_user($userid, $requesterid)) {
702             return true;
703         }
704         return false;
705     }
707     /**
708      * Gets an action menu link to download a data request.
709      *
710      * @param \context_user $usercontext User context (of user who the data is for)
711      * @param int $requestid Request id
712      * @return \action_menu_link_secondary Action menu link
713      * @throws coding_exception
714      */
715     public static function get_download_link(\context_user $usercontext, $requestid) {
716         $downloadurl = moodle_url::make_pluginfile_url($usercontext->id,
717                 'tool_dataprivacy', 'export', $requestid, '/', 'export.zip', true);
718         $downloadtext = get_string('download', 'tool_dataprivacy');
719         return new \action_menu_link_secondary($downloadurl, null, $downloadtext);
720     }
722     /**
723      * Creates a new data purpose.
724      *
725      * @param stdClass $record
726      * @return \tool_dataprivacy\purpose.
727      */
728     public static function create_purpose(stdClass $record) {
729         self::check_can_manage_data_registry();
731         $purpose = new purpose(0, $record);
732         $purpose->create();
734         return $purpose;
735     }
737     /**
738      * Updates an existing data purpose.
739      *
740      * @param stdClass $record
741      * @return \tool_dataprivacy\purpose.
742      */
743     public static function update_purpose(stdClass $record) {
744         self::check_can_manage_data_registry();
746         if (!isset($record->sensitivedatareasons)) {
747             $record->sensitivedatareasons = '';
748         }
750         $purpose = new purpose($record->id);
751         $purpose->from_record($record);
753         $result = $purpose->update();
755         return $purpose;
756     }
758     /**
759      * Deletes a data purpose.
760      *
761      * @param int $id
762      * @return bool
763      */
764     public static function delete_purpose($id) {
765         self::check_can_manage_data_registry();
767         $purpose = new purpose($id);
768         if ($purpose->is_used()) {
769             throw new \moodle_exception('Purpose with id ' . $id . ' can not be deleted because it is used.');
770         }
771         return $purpose->delete();
772     }
774     /**
775      * Get all system data purposes.
776      *
777      * @return \tool_dataprivacy\purpose[]
778      */
779     public static function get_purposes() {
780         self::check_can_manage_data_registry();
782         return purpose::get_records([], 'name', 'ASC');
783     }
785     /**
786      * Creates a new data category.
787      *
788      * @param stdClass $record
789      * @return \tool_dataprivacy\category.
790      */
791     public static function create_category(stdClass $record) {
792         self::check_can_manage_data_registry();
794         $category = new category(0, $record);
795         $category->create();
797         return $category;
798     }
800     /**
801      * Updates an existing data category.
802      *
803      * @param stdClass $record
804      * @return \tool_dataprivacy\category.
805      */
806     public static function update_category(stdClass $record) {
807         self::check_can_manage_data_registry();
809         $category = new category($record->id);
810         $category->from_record($record);
812         $result = $category->update();
814         return $category;
815     }
817     /**
818      * Deletes a data category.
819      *
820      * @param int $id
821      * @return bool
822      */
823     public static function delete_category($id) {
824         self::check_can_manage_data_registry();
826         $category = new category($id);
827         if ($category->is_used()) {
828             throw new \moodle_exception('Category with id ' . $id . ' can not be deleted because it is used.');
829         }
830         return $category->delete();
831     }
833     /**
834      * Get all system data categories.
835      *
836      * @return \tool_dataprivacy\category[]
837      */
838     public static function get_categories() {
839         self::check_can_manage_data_registry();
841         return category::get_records([], 'name', 'ASC');
842     }
844     /**
845      * Sets the context instance purpose and category.
846      *
847      * @param \stdClass $record
848      * @return \tool_dataprivacy\context_instance
849      */
850     public static function set_context_instance($record) {
851         self::check_can_manage_data_registry($record->contextid);
853         if ($instance = context_instance::get_record_by_contextid($record->contextid, false)) {
854             // Update.
855             $instance->from_record($record);
857             if (empty($record->purposeid) && empty($record->categoryid)) {
858                 // We accept one of them to be null but we delete it if both are null.
859                 self::unset_context_instance($instance);
860                 return;
861             }
863         } else {
864             // Add.
865             $instance = new context_instance(0, $record);
866         }
867         $instance->save();
869         return $instance;
870     }
872     /**
873      * Unsets the context instance record.
874      *
875      * @param \tool_dataprivacy\context_instance $instance
876      * @return null
877      */
878     public static function unset_context_instance(context_instance $instance) {
879         self::check_can_manage_data_registry($instance->get('contextid'));
880         $instance->delete();
881     }
883     /**
884      * Sets the context level purpose and category.
885      *
886      * @throws \coding_exception
887      * @param \stdClass $record
888      * @return contextlevel
889      */
890     public static function set_contextlevel($record) {
891         global $DB;
893         // Only manager at system level can set this.
894         self::check_can_manage_data_registry();
896         if ($record->contextlevel != CONTEXT_SYSTEM && $record->contextlevel != CONTEXT_USER) {
897             throw new \coding_exception('Only context system and context user can set a contextlevel ' .
898                 'purpose and retention');
899         }
901         if ($contextlevel = contextlevel::get_record_by_contextlevel($record->contextlevel, false)) {
902             // Update.
903             $contextlevel->from_record($record);
904         } else {
905             // Add.
906             $contextlevel = new contextlevel(0, $record);
907         }
908         $contextlevel->save();
910         // We sync with their defaults as we removed these options from the defaults page.
911         $classname = \context_helper::get_class_for_level($record->contextlevel);
912         list($purposevar, $categoryvar) = data_registry::var_names_from_context($classname);
913         set_config($purposevar, $record->purposeid, 'tool_dataprivacy');
914         set_config($categoryvar, $record->categoryid, 'tool_dataprivacy');
916         return $contextlevel;
917     }
919     /**
920      * Returns the effective category given a context instance.
921      *
922      * @param \context $context
923      * @param int $forcedvalue Use this categoryid value as if this was this context instance category.
924      * @return category|false
925      */
926     public static function get_effective_context_category(\context $context, $forcedvalue=false) {
927         self::check_can_manage_data_registry($context->id);
928         if (!data_registry::defaults_set()) {
929             return false;
930         }
932         return data_registry::get_effective_context_value($context, 'category', $forcedvalue);
933     }
935     /**
936      * Returns the effective purpose given a context instance.
937      *
938      * @param \context $context
939      * @param int $forcedvalue Use this purposeid value as if this was this context instance purpose.
940      * @return purpose|false
941      */
942     public static function get_effective_context_purpose(\context $context, $forcedvalue=false) {
943         self::check_can_manage_data_registry($context->id);
944         if (!data_registry::defaults_set()) {
945             return false;
946         }
948         return data_registry::get_effective_context_value($context, 'purpose', $forcedvalue);
949     }
951     /**
952      * Returns the effective category given a context level.
953      *
954      * @param int $contextlevel
955      * @param int $forcedvalue Use this categoryid value as if this was this context level category.
956      * @return category|false
957      */
958     public static function get_effective_contextlevel_category($contextlevel, $forcedvalue=false) {
959         self::check_can_manage_data_registry(\context_system::instance()->id);
960         if (!data_registry::defaults_set()) {
961             return false;
962         }
964         return data_registry::get_effective_contextlevel_value($contextlevel, 'category', $forcedvalue);
965     }
967     /**
968      * Returns the effective purpose given a context level.
969      *
970      * @param int $contextlevel
971      * @param int $forcedvalue Use this purposeid value as if this was this context level purpose.
972      * @return purpose|false
973      */
974     public static function get_effective_contextlevel_purpose($contextlevel, $forcedvalue=false) {
975         self::check_can_manage_data_registry(\context_system::instance()->id);
976         if (!data_registry::defaults_set()) {
977             return false;
978         }
980         return data_registry::get_effective_contextlevel_value($contextlevel, 'purpose', $forcedvalue);
981     }
983     /**
984      * Creates an expired context record for the provided context id.
985      *
986      * @param int $contextid
987      * @return \tool_dataprivacy\expired_context
988      */
989     public static function create_expired_context($contextid) {
990         self::check_can_manage_data_registry();
992         $record = (object)[
993             'contextid' => $contextid,
994             'status' => expired_context::STATUS_EXPIRED,
995         ];
996         $expiredctx = new expired_context(0, $record);
997         $expiredctx->save();
999         return $expiredctx;
1000     }
1002     /**
1003      * Deletes an expired context record.
1004      *
1005      * @param int $id The tool_dataprivacy_ctxexpire id.
1006      * @return bool True on success.
1007      */
1008     public static function delete_expired_context($id) {
1009         self::check_can_manage_data_registry();
1011         $expiredcontext = new expired_context($id);
1012         return $expiredcontext->delete();
1013     }
1015     /**
1016      * Updates the status of an expired context.
1017      *
1018      * @param \tool_dataprivacy\expired_context $expiredctx
1019      * @param int $status
1020      * @return null
1021      */
1022     public static function set_expired_context_status(expired_context $expiredctx, $status) {
1023         self::check_can_manage_data_registry();
1025         $expiredctx->set('status', $status);
1026         $expiredctx->save();
1027     }
1029     /**
1030      * Adds the contexts from the contextlist_collection to the request with the status provided.
1031      *
1032      * @param contextlist_collection $clcollection a collection of contextlists for all components.
1033      * @param int $requestid the id of the request.
1034      * @param int $status the status to set the contexts to.
1035      */
1036     public static function add_request_contexts_with_status(contextlist_collection $clcollection, int $requestid, int $status) {
1037         $request = new data_request($requestid);
1038         foreach ($clcollection as $contextlist) {
1039             // Convert the \core_privacy\local\request\contextlist into a contextlist persistent and store it.
1040             $clp = \tool_dataprivacy\contextlist::from_contextlist($contextlist);
1041             $clp->create();
1042             $contextlistid = $clp->get('id');
1044             // Store the associated contexts in the contextlist.
1045             foreach ($contextlist->get_contextids() as $contextid) {
1046                 if ($request->get('type') == static::DATAREQUEST_TYPE_DELETE) {
1047                     $context = \context::instance_by_id($contextid);
1048                     if (($purpose = static::get_effective_context_purpose($context)) && !empty($purpose->get('protected'))) {
1049                         continue;
1050                     }
1051                 }
1052                 $context = new contextlist_context();
1053                 $context->set('contextid', $contextid)
1054                     ->set('contextlistid', $contextlistid)
1055                     ->set('status', $status)
1056                     ->create();
1057             }
1059             // Create the relation to the request.
1060             $requestcontextlist = request_contextlist::create_relation($requestid, $contextlistid);
1061             $requestcontextlist->create();
1062         }
1063     }
1065     /**
1066      * Sets the status of all contexts associated with the request.
1067      *
1068      * @param int $requestid the requestid to which the contexts belong.
1069      * @param int $status the status to set to.
1070      * @throws \dml_exception if the requestid is invalid.
1071      * @throws \moodle_exception if the status is invalid.
1072      */
1073     public static function update_request_contexts_with_status(int $requestid, int $status) {
1074         // Validate contextlist_context status using the persistent's attribute validation.
1075         $contextlistcontext = new contextlist_context();
1076         $contextlistcontext->set('status', $status);
1077         if (array_key_exists('status', $contextlistcontext->get_errors())) {
1078             throw new moodle_exception("Invalid contextlist_context status: $status");
1079         }
1081         // Validate requestid using the persistent's record validation.
1082         // A dml_exception is thrown if the record is missing.
1083         $datarequest = new data_request($requestid);
1085         // Bulk update the status of the request contexts.
1086         global $DB;
1088         $select = "SELECT ctx.id as id
1089                      FROM {" . request_contextlist::TABLE . "} rcl
1090                      JOIN {" . contextlist::TABLE . "} cl ON rcl.contextlistid = cl.id
1091                      JOIN {" . contextlist_context::TABLE . "} ctx ON cl.id = ctx.contextlistid
1092                     WHERE rcl.requestid = ?";
1094         // Fetch records IDs to be updated and update by chunks, if applicable (limit of 1000 records per update).
1095         $limit = 1000;
1096         $idstoupdate = $DB->get_fieldset_sql($select, [$requestid]);
1097         $count = count($idstoupdate);
1098         $idchunks = $idstoupdate;
1099         if ($count > $limit) {
1100             $idchunks = array_chunk($idstoupdate, $limit);
1101         }
1102         $transaction = $DB->start_delegated_transaction();
1103         $initialparams = [$status];
1104         foreach ($idchunks as $chunk) {
1105             list($insql, $inparams) = $DB->get_in_or_equal($chunk);
1106             $update = "UPDATE {" . contextlist_context::TABLE . "}
1107                           SET status = ?
1108                         WHERE id $insql";
1109             $params = array_merge($initialparams, $inparams);
1110             $DB->execute($update, $params);
1111         }
1112         $transaction->allow_commit();
1113     }
1115     /**
1116      * Finds all request contextlists having at least on approved context, and returns them as in a contextlist_collection.
1117      *
1118      * @param data_request $request the data request with which the contextlists are associated.
1119      * @return contextlist_collection the collection of approved_contextlist objects.
1120      */
1121     public static function get_approved_contextlist_collection_for_request(data_request $request) : contextlist_collection {
1122         $foruser = core_user::get_user($request->get('userid'));
1124         // Fetch all approved contextlists and create the core_privacy\local\request\contextlist objects here.
1125         global $DB;
1126         $sql = "SELECT cl.component, ctx.contextid
1127                   FROM {" . request_contextlist::TABLE . "} rcl
1128                   JOIN {" . contextlist::TABLE . "} cl ON rcl.contextlistid = cl.id
1129                   JOIN {" . contextlist_context::TABLE . "} ctx ON cl.id = ctx.contextlistid
1130                  WHERE rcl.requestid = ?
1131                    AND ctx.status = ?
1132               ORDER BY cl.component, ctx.contextid";
1134         // Create the approved contextlist collection object.
1135         $lastcomponent = null;
1136         $approvedcollection = new contextlist_collection($foruser->id);
1138         $rs = $DB->get_recordset_sql($sql, [$request->get('id'), contextlist_context::STATUS_APPROVED]);
1139         foreach ($rs as $record) {
1140             // If we encounter a new component, and we've built up contexts for the last, then add the approved_contextlist for the
1141             // last (the one we've just finished with) and reset the context array for the next one.
1142             if ($lastcomponent != $record->component) {
1143                 if (!empty($contexts)) {
1144                     $approvedcollection->add_contextlist(new approved_contextlist($foruser, $lastcomponent, $contexts));
1145                 }
1146                 $contexts = [];
1147             }
1149             $contexts[] = $record->contextid;
1150             $lastcomponent = $record->component;
1151         }
1152         $rs->close();
1154         // The data for the last component contextlist won't have been written yet, so write it now.
1155         if (!empty($contexts)) {
1156             $approvedcollection->add_contextlist(new approved_contextlist($foruser, $lastcomponent, $contexts));
1157         }
1159         return $approvedcollection;
1160     }
1162     /**
1163      * Updates the default category and purpose for a given context level (and optionally, a plugin).
1164      *
1165      * @param int $contextlevel The context level.
1166      * @param int $categoryid The ID matching the category.
1167      * @param int $purposeid The ID matching the purpose record.
1168      * @param int $activity The name of the activity that we're making a defaults configuration for.
1169      * @param bool $override Whether to override the purpose/categories of existing instances to these defaults.
1170      * @return boolean True if set/unset config succeeds. Otherwise, it throws an exception.
1171      */
1172     public static function set_context_defaults($contextlevel, $categoryid, $purposeid, $activity = null, $override = false) {
1173         global $DB;
1175         self::check_can_manage_data_registry();
1177         // Get the class name associated with this context level.
1178         $classname = context_helper::get_class_for_level($contextlevel);
1179         list($purposevar, $categoryvar) = data_registry::var_names_from_context($classname, $activity);
1181         // Check the default category to be set.
1182         if ($categoryid == context_instance::INHERIT) {
1183             unset_config($categoryvar, 'tool_dataprivacy');
1185         } else {
1186             // Make sure the given category ID exists first.
1187             $categorypersistent = new category($categoryid);
1188             $categorypersistent->read();
1190             // Then set the new default value.
1191             set_config($categoryvar, $categoryid, 'tool_dataprivacy');
1192         }
1194         // Check the default purpose to be set.
1195         if ($purposeid == context_instance::INHERIT) {
1196             // If the defaults is set to inherit, just unset the config value.
1197             unset_config($purposevar, 'tool_dataprivacy');
1199         } else {
1200             // Make sure the given purpose ID exists first.
1201             $purposepersistent = new purpose($purposeid);
1202             $purposepersistent->read();
1204             // Then set the new default value.
1205             set_config($purposevar, $purposeid, 'tool_dataprivacy');
1206         }
1208         // Unset instances that have been assigned with custom purpose and category, if override was specified.
1209         if ($override) {
1210             // We'd like to find context IDs that we want to unset.
1211             $statements = ["SELECT c.id as contextid FROM {context} c"];
1212             // Based on this context level.
1213             $params = ['contextlevel' => $contextlevel];
1215             if ($contextlevel == CONTEXT_MODULE) {
1216                 // If we're deleting module context instances, we need to make sure the instance ID is in the course modules table.
1217                 $statements[] = "JOIN {course_modules} cm ON cm.id = c.instanceid";
1218                 // And that the module is listed on the modules table.
1219                 $statements[] = "JOIN {modules} m ON m.id = cm.module";
1221                 if ($activity) {
1222                     // If we're overriding for an activity module, make sure that the context instance matches that activity.
1223                     $statements[] = "AND m.name = :modname";
1224                     $params['modname'] = $activity;
1225                 }
1226             }
1227             // Make sure this context instance exists in the tool_dataprivacy_ctxinstance table.
1228             $statements[] = "JOIN {tool_dataprivacy_ctxinstance} tdc ON tdc.contextid = c.id";
1229             // And that the context level of this instance matches the given context level.
1230             $statements[] = "WHERE c.contextlevel = :contextlevel";
1232             // Build our SQL query by gluing the statements.
1233             $sql = implode("\n", $statements);
1235             // Get the context records matching our query.
1236             $contextids = $DB->get_fieldset_sql($sql, $params);
1238             // Delete the matching context instances.
1239             foreach ($contextids as $contextid) {
1240                 if ($instance = context_instance::get_record_by_contextid($contextid, false)) {
1241                     self::unset_context_instance($instance);
1242                 }
1243             }
1244         }
1246         return true;
1247     }