Merge branch 'MDL-62589-master' of git://github.com/andrewnicols/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;
44 use tool_dataprivacy\data_request;
46 defined('MOODLE_INTERNAL') || die();
48 /**
49  * Class containing helper methods for processing data requests.
50  *
51  * @copyright  2018 Jun Pataleta
52  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
53  */
54 class api {
56     /** Data export request type. */
57     const DATAREQUEST_TYPE_EXPORT = 1;
59     /** Data deletion request type. */
60     const DATAREQUEST_TYPE_DELETE = 2;
62     /** Other request type. Usually of enquiries to the DPO. */
63     const DATAREQUEST_TYPE_OTHERS = 3;
65     /** Newly submitted and we haven't yet started finding out where they have data. */
66     const DATAREQUEST_STATUS_PENDING = 0;
68     /** Newly submitted and we have started to find the location of data. */
69     const DATAREQUEST_STATUS_PREPROCESSING = 1;
71     /** Metadata ready and awaiting review and approval by the Data Protection officer. */
72     const DATAREQUEST_STATUS_AWAITING_APPROVAL = 2;
74     /** Request approved and will be processed soon. */
75     const DATAREQUEST_STATUS_APPROVED = 3;
77     /** The request is now being processed. */
78     const DATAREQUEST_STATUS_PROCESSING = 4;
80     /** Information/other request completed. */
81     const DATAREQUEST_STATUS_COMPLETE = 5;
83     /** Data request cancelled by the user. */
84     const DATAREQUEST_STATUS_CANCELLED = 6;
86     /** Data request rejected by the DPO. */
87     const DATAREQUEST_STATUS_REJECTED = 7;
89     /** Data request download ready. */
90     const DATAREQUEST_STATUS_DOWNLOAD_READY = 8;
92     /** Data request expired. */
93     const DATAREQUEST_STATUS_EXPIRED = 9;
95     /** Data delete request completed, account is removed. */
96     const DATAREQUEST_STATUS_DELETED = 10;
98     /** Approve data request. */
99     const DATAREQUEST_ACTION_APPROVE = 1;
101     /** Reject data request. */
102     const DATAREQUEST_ACTION_REJECT = 2;
104     /**
105      * Determines whether the user can contact the site's Data Protection Officer via Moodle.
106      *
107      * @return boolean True when tool_dataprivacy|contactdataprotectionofficer is enabled.
108      * @throws dml_exception
109      */
110     public static function can_contact_dpo() {
111         return get_config('tool_dataprivacy', 'contactdataprotectionofficer') == 1;
112     }
114     /**
115      * Checks whether the current user has the capability to manage data requests.
116      *
117      * @param int $userid The user ID.
118      * @return bool
119      */
120     public static function can_manage_data_requests($userid) {
121         // Privacy officers can manage data requests.
122         return self::is_site_dpo($userid);
123     }
125     /**
126      * Checks if the current user can manage the data registry at the provided id.
127      *
128      * @param int $contextid Fallback to system context id.
129      * @throws \required_capability_exception
130      * @return null
131      */
132     public static function check_can_manage_data_registry($contextid = false) {
133         if ($contextid) {
134             $context = \context_helper::instance_by_id($contextid);
135         } else {
136             $context = \context_system::instance();
137         }
139         require_capability('tool/dataprivacy:managedataregistry', $context);
140     }
142     /**
143      * Fetches the list of configured privacy officer roles.
144      *
145      * Every time this function is called, it checks each role if they have the 'managedatarequests' capability and removes
146      * any role that doesn't have the required capability anymore.
147      *
148      * @return int[]
149      * @throws dml_exception
150      */
151     public static function get_assigned_privacy_officer_roles() {
152         $roleids = [];
154         // Get roles from config.
155         $configroleids = explode(',', str_replace(' ', '', get_config('tool_dataprivacy', 'dporoles')));
156         if (!empty($configroleids)) {
157             // Fetch roles that have the capability to manage data requests.
158             $capableroles = array_keys(get_roles_with_capability('tool/dataprivacy:managedatarequests'));
160             // Extract the configured roles that have the capability from the list of capable roles.
161             $roleids = array_intersect($capableroles, $configroleids);
162         }
164         return $roleids;
165     }
167     /**
168      * Fetches the role shortnames of Data Protection Officer roles.
169      *
170      * @return array An array of the DPO role shortnames
171      */
172     public static function get_dpo_role_names() : array {
173         global $DB;
175         $dporoleids = self::get_assigned_privacy_officer_roles();
176         $dponames = array();
178         if (!empty($dporoleids)) {
179             list($insql, $inparams) = $DB->get_in_or_equal($dporoleids);
180             $dponames = $DB->get_fieldset_select('role', 'shortname', "id {$insql}", $inparams);
181         }
183         return $dponames;
184     }
186     /**
187      * Fetches the list of users with the Privacy Officer role.
188      */
189     public static function get_site_dpos() {
190         // Get role(s) that can manage data requests.
191         $dporoles = self::get_assigned_privacy_officer_roles();
193         $dpos = [];
194         $context = context_system::instance();
195         foreach ($dporoles as $roleid) {
196             $allnames = get_all_user_name_fields(true, 'u');
197             $fields = 'u.id, u.confirmed, u.username, '. $allnames . ', ' .
198                       'u.maildisplay, u.mailformat, u.maildigest, u.email, u.emailstop, u.city, '.
199                       'u.country, u.picture, u.idnumber, u.department, u.institution, '.
200                       'u.lang, u.timezone, u.lastaccess, u.mnethostid, u.auth, u.suspended, u.deleted, ' .
201                       'r.name AS rolename, r.sortorder, '.
202                       'r.shortname AS roleshortname, rn.name AS rolecoursealias';
203             // Fetch users that can manage data requests.
204             $dpos += get_role_users($roleid, $context, false, $fields);
205         }
207         // If the site has no data protection officer, defer to site admin(s).
208         if (empty($dpos)) {
209             $dpos = get_admins();
210         }
211         return $dpos;
212     }
214     /**
215      * Checks whether a given user is a site Privacy Officer.
216      *
217      * @param int $userid The user ID.
218      * @return bool
219      */
220     public static function is_site_dpo($userid) {
221         $dpos = self::get_site_dpos();
222         return array_key_exists($userid, $dpos) || is_siteadmin();
223     }
225     /**
226      * Lodges a data request and sends the request details to the site Data Protection Officer(s).
227      *
228      * @param int $foruser The user whom the request is being made for.
229      * @param int $type The request type.
230      * @param string $comments Request comments.
231      * @param int $creationmethod The creation method of the data request.
232      * @return data_request
233      * @throws invalid_persistent_exception
234      * @throws coding_exception
235      */
236     public static function create_data_request($foruser, $type, $comments = '',
237                                                $creationmethod = data_request::DATAREQUEST_CREATION_MANUAL) {
238         global $USER, $ADMIN;
240         $datarequest = new data_request();
241         // The user the request is being made for.
242         $datarequest->set('userid', $foruser);
244         // The cron is considered to be a guest user when it creates a data request.
245         // NOTE: This should probably be changed. We should leave the default value for $requestinguser if
246         // the request is not explicitly created by a specific user.
247         $requestinguser = (isguestuser() && $creationmethod == data_request::DATAREQUEST_CREATION_AUTO) ?
248                 $ADMIN->id : $USER->id;
249         // The user making the request.
250         $datarequest->set('requestedby', $requestinguser);
251         // Set status.
252         $datarequest->set('status', self::DATAREQUEST_STATUS_PENDING);
253         // Set request type.
254         $datarequest->set('type', $type);
255         // Set request comments.
256         $datarequest->set('comments', $comments);
257         // Set the creation method.
258         $datarequest->set('creationmethod', $creationmethod);
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 int[] $creationmethods The request creation method filters.
282      * @param string $sort The order by clause.
283      * @param int $offset Amount of records to skip.
284      * @param int $limit Amount of records to fetch.
285      * @return data_request[]
286      * @throws coding_exception
287      * @throws dml_exception
288      */
289     public static function get_data_requests($userid = 0, $statuses = [], $types = [], $creationmethods = [],
290                                              $sort = '', $offset = 0, $limit = 0) {
291         global $DB, $USER;
292         $results = [];
293         $sqlparams = [];
294         $sqlconditions = [];
296         // Set default sort.
297         if (empty($sort)) {
298             $sort = 'status ASC, timemodified ASC';
299         }
301         // Set status filters.
302         if (!empty($statuses)) {
303             list($statusinsql, $sqlparams) = $DB->get_in_or_equal($statuses, SQL_PARAMS_NAMED);
304             $sqlconditions[] = "status $statusinsql";
305         }
307         // Set request type filter.
308         if (!empty($types)) {
309             list($typeinsql, $typeparams) = $DB->get_in_or_equal($types, SQL_PARAMS_NAMED);
310             $sqlconditions[] = "type $typeinsql";
311             $sqlparams = array_merge($sqlparams, $typeparams);
312         }
314         // Set request creation method filter.
315         if (!empty($creationmethods)) {
316             list($typeinsql, $typeparams) = $DB->get_in_or_equal($creationmethods, SQL_PARAMS_NAMED);
317             $sqlconditions[] = "creationmethod $typeinsql";
318             $sqlparams = array_merge($sqlparams, $typeparams);
319         }
321         if ($userid) {
322             // Get the data requests for the user or data requests made by the user.
323             $sqlconditions[] = "(userid = :userid OR requestedby = :requestedby)";
324             $params = [
325                 'userid' => $userid,
326                 'requestedby' => $userid
327             ];
329             // Build a list of user IDs that the user is allowed to make data requests for.
330             // Of course, the user should be included in this list.
331             $alloweduserids = [$userid];
332             // Get any users that the user can make data requests for.
333             if ($children = helper::get_children_of_user($userid)) {
334                 // Get the list of user IDs of the children and merge to the allowed user IDs.
335                 $alloweduserids = array_merge($alloweduserids, array_keys($children));
336             }
337             list($insql, $inparams) = $DB->get_in_or_equal($alloweduserids, SQL_PARAMS_NAMED);
338             $sqlconditions[] .= "userid $insql";
339             $select = implode(' AND ', $sqlconditions);
340             $params = array_merge($params, $inparams, $sqlparams);
342             $results = data_request::get_records_select($select, $params, $sort, '*', $offset, $limit);
343         } else {
344             // If the current user is one of the site's Data Protection Officers, then fetch all data requests.
345             if (self::is_site_dpo($USER->id)) {
346                 if (!empty($sqlconditions)) {
347                     $select = implode(' AND ', $sqlconditions);
348                     $results = data_request::get_records_select($select, $sqlparams, $sort, '*', $offset, $limit);
349                 } else {
350                     $results = data_request::get_records(null, $sort, '', $offset, $limit);
351                 }
352             }
353         }
355         // If any are due to expire, expire them and re-fetch updated data.
356         if (empty($statuses)
357                 || in_array(self::DATAREQUEST_STATUS_DOWNLOAD_READY, $statuses)
358                 || in_array(self::DATAREQUEST_STATUS_EXPIRED, $statuses)) {
359             $expiredrequests = data_request::get_expired_requests($userid);
361             if (!empty($expiredrequests)) {
362                 data_request::expire($expiredrequests);
363                 $results = self::get_data_requests($userid, $statuses, $types, $creationmethods, $sort, $offset, $limit);
364             }
365         }
367         return $results;
368     }
370     /**
371      * Fetches the count of data request records based on the given parameters.
372      *
373      * @param int $userid The User ID.
374      * @param int[] $statuses The status filters.
375      * @param int[] $types The request type filters.
376      * @param int[] $creationmethods The request creation method filters.
377      * @return int
378      * @throws coding_exception
379      * @throws dml_exception
380      */
381     public static function get_data_requests_count($userid = 0, $statuses = [], $types = [], $creationmethods = []) {
382         global $DB, $USER;
383         $count = 0;
384         $sqlparams = [];
385         $sqlconditions = [];
386         if (!empty($statuses)) {
387             list($statusinsql, $sqlparams) = $DB->get_in_or_equal($statuses, SQL_PARAMS_NAMED);
388             $sqlconditions[] = "status $statusinsql";
389         }
390         if (!empty($types)) {
391             list($typeinsql, $typeparams) = $DB->get_in_or_equal($types, SQL_PARAMS_NAMED);
392             $sqlconditions[] = "type $typeinsql";
393             $sqlparams = array_merge($sqlparams, $typeparams);
394         }
395         if (!empty($creationmethods)) {
396             list($typeinsql, $typeparams) = $DB->get_in_or_equal($creationmethods, SQL_PARAMS_NAMED);
397             $sqlconditions[] = "creationmethod $typeinsql";
398             $sqlparams = array_merge($sqlparams, $typeparams);
399         }
400         if ($userid) {
401             // Get the data requests for the user or data requests made by the user.
402             $sqlconditions[] = "(userid = :userid OR requestedby = :requestedby)";
403             $params = [
404                 'userid' => $userid,
405                 'requestedby' => $userid
406             ];
408             // Build a list of user IDs that the user is allowed to make data requests for.
409             // Of course, the user should be included in this list.
410             $alloweduserids = [$userid];
411             // Get any users that the user can make data requests for.
412             if ($children = helper::get_children_of_user($userid)) {
413                 // Get the list of user IDs of the children and merge to the allowed user IDs.
414                 $alloweduserids = array_merge($alloweduserids, array_keys($children));
415             }
416             list($insql, $inparams) = $DB->get_in_or_equal($alloweduserids, SQL_PARAMS_NAMED);
417             $sqlconditions[] .= "userid $insql";
418             $select = implode(' AND ', $sqlconditions);
419             $params = array_merge($params, $inparams, $sqlparams);
421             $count = data_request::count_records_select($select, $params);
422         } else {
423             // If the current user is one of the site's Data Protection Officers, then fetch all data requests.
424             if (self::is_site_dpo($USER->id)) {
425                 if (!empty($sqlconditions)) {
426                     $select = implode(' AND ', $sqlconditions);
427                     $count = data_request::count_records_select($select, $sqlparams);
428                 } else {
429                     $count = data_request::count_records();
430                 }
431             }
432         }
434         return $count;
435     }
437     /**
438      * Checks whether there is already an existing pending/in-progress data request for a user for a given request type.
439      *
440      * @param int $userid The user ID.
441      * @param int $type The request type.
442      * @return bool
443      * @throws coding_exception
444      * @throws dml_exception
445      */
446     public static function has_ongoing_request($userid, $type) {
447         global $DB;
449         // Check if the user already has an incomplete data request of the same type.
450         $nonpendingstatuses = [
451             self::DATAREQUEST_STATUS_COMPLETE,
452             self::DATAREQUEST_STATUS_CANCELLED,
453             self::DATAREQUEST_STATUS_REJECTED,
454             self::DATAREQUEST_STATUS_DOWNLOAD_READY,
455             self::DATAREQUEST_STATUS_EXPIRED,
456             self::DATAREQUEST_STATUS_DELETED,
457         ];
458         list($insql, $inparams) = $DB->get_in_or_equal($nonpendingstatuses, SQL_PARAMS_NAMED, 'st', false);
459         $select = "type = :type AND userid = :userid AND status {$insql}";
460         $params = array_merge([
461             'type' => $type,
462             'userid' => $userid
463         ], $inparams);
465         return data_request::record_exists_select($select, $params);
466     }
468     /**
469      * Find whether any ongoing requests exist for a set of users.
470      *
471      * @param   array   $userids
472      * @return  array
473      */
474     public static function find_ongoing_request_types_for_users(array $userids) : array {
475         global $DB;
477         if (empty($userids)) {
478             return [];
479         }
481         // Check if the user already has an incomplete data request of the same type.
482         $nonpendingstatuses = [
483             self::DATAREQUEST_STATUS_COMPLETE,
484             self::DATAREQUEST_STATUS_CANCELLED,
485             self::DATAREQUEST_STATUS_REJECTED,
486             self::DATAREQUEST_STATUS_DOWNLOAD_READY,
487             self::DATAREQUEST_STATUS_EXPIRED,
488             self::DATAREQUEST_STATUS_DELETED,
489         ];
490         list($statusinsql, $statusparams) = $DB->get_in_or_equal($nonpendingstatuses, SQL_PARAMS_NAMED, 'st', false);
491         list($userinsql, $userparams) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED, 'us');
493         $select = "userid {$userinsql} AND status {$statusinsql}";
494         $params = array_merge($statusparams, $userparams);
496         $requests = $DB->get_records_select(data_request::TABLE, $select, $params, 'userid', 'id, userid, type');
498         $returnval = [];
499         foreach ($userids as $userid) {
500             $returnval[$userid] = (object) [];
501         }
503         foreach ($requests as $request) {
504             $returnval[$request->userid]->{$request->type} = true;
505         }
507         return $returnval;
508     }
510     /**
511      * Determines whether a request is active or not based on its status.
512      *
513      * @param int $status The request status.
514      * @return bool
515      */
516     public static function is_active($status) {
517         // List of statuses which doesn't require any further processing.
518         $finalstatuses = [
519             self::DATAREQUEST_STATUS_COMPLETE,
520             self::DATAREQUEST_STATUS_CANCELLED,
521             self::DATAREQUEST_STATUS_REJECTED,
522             self::DATAREQUEST_STATUS_DOWNLOAD_READY,
523             self::DATAREQUEST_STATUS_EXPIRED,
524             self::DATAREQUEST_STATUS_DELETED,
525         ];
527         return !in_array($status, $finalstatuses);
528     }
530     /**
531      * Cancels the data request for a given request ID.
532      *
533      * @param int $requestid The request identifier.
534      * @param int $status The request status.
535      * @param int $dpoid The user ID of the Data Protection Officer
536      * @param string $comment The comment about the status update.
537      * @return bool
538      * @throws invalid_persistent_exception
539      * @throws coding_exception
540      */
541     public static function update_request_status($requestid, $status, $dpoid = 0, $comment = '') {
542         // Update the request.
543         $datarequest = new data_request($requestid);
544         $datarequest->set('status', $status);
545         if ($dpoid) {
546             $datarequest->set('dpo', $dpoid);
547         }
548         // Update the comment if necessary.
549         if (!empty(trim($comment))) {
550             $params = [
551                 'date' => userdate(time()),
552                 'comment' => $comment
553             ];
554             $commenttosave = get_string('datecomment', 'tool_dataprivacy', $params);
555             // Check if there's an existing DPO comment.
556             $currentcomment = trim($datarequest->get('dpocomment'));
557             if ($currentcomment) {
558                 // Append the new comment to the current comment and give them 1 line space in between.
559                 $commenttosave = $currentcomment . PHP_EOL . PHP_EOL . $commenttosave;
560             }
561             $datarequest->set('dpocomment', $commenttosave);
562         }
564         return $datarequest->update();
565     }
567     /**
568      * Fetches a request based on the request ID.
569      *
570      * @param int $requestid The request identifier
571      * @return data_request
572      */
573     public static function get_request($requestid) {
574         return new data_request($requestid);
575     }
577     /**
578      * Approves a data request based on the request ID.
579      *
580      * @param int $requestid The request identifier
581      * @return bool
582      * @throws coding_exception
583      * @throws dml_exception
584      * @throws invalid_persistent_exception
585      * @throws required_capability_exception
586      * @throws moodle_exception
587      */
588     public static function approve_data_request($requestid) {
589         global $USER;
591         // Check first whether the user can manage data requests.
592         if (!self::can_manage_data_requests($USER->id)) {
593             $context = context_system::instance();
594             throw new required_capability_exception($context, 'tool/dataprivacy:managedatarequests', 'nopermissions', '');
595         }
597         // Check if request is already awaiting for approval.
598         $request = new data_request($requestid);
599         if ($request->get('status') != self::DATAREQUEST_STATUS_AWAITING_APPROVAL) {
600             throw new moodle_exception('errorrequestnotwaitingforapproval', 'tool_dataprivacy');
601         }
603         // Update the status and the DPO.
604         $result = self::update_request_status($requestid, self::DATAREQUEST_STATUS_APPROVED, $USER->id);
606         // Approve all the contexts attached to the request.
607         // Currently, approving the request implicitly approves all associated contexts, but this may change in future, allowing
608         // users to selectively approve certain contexts only.
609         self::update_request_contexts_with_status($requestid, contextlist_context::STATUS_APPROVED);
611         // Fire an ad hoc task to initiate the data request process.
612         $task = new process_data_request_task();
613         $task->set_custom_data(['requestid' => $requestid]);
614         if ($request->get('type') == self::DATAREQUEST_TYPE_EXPORT) {
615             $task->set_userid($request->get('userid'));
616         }
617         manager::queue_adhoc_task($task, true);
619         return $result;
620     }
622     /**
623      * Rejects a data request based on the request ID.
624      *
625      * @param int $requestid The request identifier
626      * @return bool
627      * @throws coding_exception
628      * @throws dml_exception
629      * @throws invalid_persistent_exception
630      * @throws required_capability_exception
631      * @throws moodle_exception
632      */
633     public static function deny_data_request($requestid) {
634         global $USER;
636         if (!self::can_manage_data_requests($USER->id)) {
637             $context = context_system::instance();
638             throw new required_capability_exception($context, 'tool/dataprivacy:managedatarequests', 'nopermissions', '');
639         }
641         // Check if request is already awaiting for approval.
642         $request = new data_request($requestid);
643         if ($request->get('status') != self::DATAREQUEST_STATUS_AWAITING_APPROVAL) {
644             throw new moodle_exception('errorrequestnotwaitingforapproval', 'tool_dataprivacy');
645         }
647         // Update the status and the DPO.
648         return self::update_request_status($requestid, self::DATAREQUEST_STATUS_REJECTED, $USER->id);
649     }
651     /**
652      * Sends a message to the site's Data Protection Officer about a request.
653      *
654      * @param stdClass $dpo The DPO user record
655      * @param data_request $request The data request
656      * @return int|false
657      * @throws coding_exception
658      * @throws moodle_exception
659      */
660     public static function notify_dpo($dpo, data_request $request) {
661         global $PAGE, $SITE;
663         $output = $PAGE->get_renderer('tool_dataprivacy');
665         $usercontext = \context_user::instance($request->get('requestedby'));
666         $requestexporter = new data_request_exporter($request, ['context' => $usercontext]);
667         $requestdata = $requestexporter->export($output);
669         // Create message to send to the Data Protection Officer(s).
670         $typetext = null;
671         $typetext = $requestdata->typename;
672         $subject = get_string('datarequestemailsubject', 'tool_dataprivacy', $typetext);
674         $requestedby = $requestdata->requestedbyuser;
675         $datarequestsurl = new moodle_url('/admin/tool/dataprivacy/datarequests.php');
676         $message = new message();
677         $message->courseid          = $SITE->id;
678         $message->component         = 'tool_dataprivacy';
679         $message->name              = 'contactdataprotectionofficer';
680         $message->userfrom          = $requestedby->id;
681         $message->replyto           = $requestedby->email;
682         $message->replytoname       = $requestedby->fullname;
683         $message->subject           = $subject;
684         $message->fullmessageformat = FORMAT_HTML;
685         $message->notification      = 1;
686         $message->contexturl        = $datarequestsurl;
687         $message->contexturlname    = get_string('datarequests', 'tool_dataprivacy');
689         // Prepare the context data for the email message body.
690         $messagetextdata = [
691             'requestedby' => $requestedby->fullname,
692             'requesttype' => $typetext,
693             'requestdate' => userdate($requestdata->timecreated),
694             'requestorigin' => $SITE->fullname,
695             'requestoriginurl' => new moodle_url('/'),
696             'requestcomments' => $requestdata->messagehtml,
697             'datarequestsurl' => $datarequestsurl
698         ];
699         $requestingfor = $requestdata->foruser;
700         if ($requestedby->id == $requestingfor->id) {
701             $messagetextdata['requestfor'] = $messagetextdata['requestedby'];
702         } else {
703             $messagetextdata['requestfor'] = $requestingfor->fullname;
704         }
706         // Email the data request to the Data Protection Officer(s)/Admin(s).
707         $messagetextdata['dponame'] = fullname($dpo);
708         // Render message email body.
709         $messagehtml = $output->render_from_template('tool_dataprivacy/data_request_email', $messagetextdata);
710         $message->userto = $dpo;
711         $message->fullmessage = html_to_text($messagehtml);
712         $message->fullmessagehtml = $messagehtml;
714         // Send message.
715         return message_send($message);
716     }
718     /**
719      * Checks whether a non-DPO user can make a data request for another user.
720      *
721      * @param   int     $user The user ID of the target user.
722      * @param   int     $requester The user ID of the user making the request.
723      * @return  bool
724      */
725     public static function can_create_data_request_for_user($user, $requester = null) {
726         $usercontext = \context_user::instance($user);
728         return has_capability('tool/dataprivacy:makedatarequestsforchildren', $usercontext, $requester);
729     }
731     /**
732      * Require that the current user can make a data request for the specified other user.
733      *
734      * @param   int     $user The user ID of the target user.
735      * @param   int     $requester The user ID of the user making the request.
736      * @return  bool
737      */
738     public static function require_can_create_data_request_for_user($user, $requester = null) {
739         $usercontext = \context_user::instance($user);
741         require_capability('tool/dataprivacy:makedatarequestsforchildren', $usercontext, $requester);
743         return true;
744     }
746     /**
747      * Checks whether a user can download a data request.
748      *
749      * @param int $userid Target user id (subject of data request)
750      * @param int $requesterid Requester user id (person who requsted it)
751      * @param int|null $downloaderid Person who wants to download user id (default current)
752      * @return bool
753      * @throws coding_exception
754      */
755     public static function can_download_data_request_for_user($userid, $requesterid, $downloaderid = null) {
756         global $USER;
758         if (!$downloaderid) {
759             $downloaderid = $USER->id;
760         }
762         $usercontext = \context_user::instance($userid);
763         // If it's your own and you have the right capability, you can download it.
764         if ($userid == $downloaderid && has_capability('tool/dataprivacy:downloadownrequest', $usercontext, $downloaderid)) {
765             return true;
766         }
767         // If you can download anyone's in that context, you can download it.
768         if (has_capability('tool/dataprivacy:downloadallrequests', $usercontext, $downloaderid)) {
769             return true;
770         }
771         // If you can have the 'child access' ability to request in that context, and you are the one
772         // who requested it, then you can download it.
773         if ($requesterid == $downloaderid && self::can_create_data_request_for_user($userid, $requesterid)) {
774             return true;
775         }
776         return false;
777     }
779     /**
780      * Gets an action menu link to download a data request.
781      *
782      * @param \context_user $usercontext User context (of user who the data is for)
783      * @param int $requestid Request id
784      * @return \action_menu_link_secondary Action menu link
785      * @throws coding_exception
786      */
787     public static function get_download_link(\context_user $usercontext, $requestid) {
788         $downloadurl = moodle_url::make_pluginfile_url($usercontext->id,
789                 'tool_dataprivacy', 'export', $requestid, '/', 'export.zip', true);
790         $downloadtext = get_string('download', 'tool_dataprivacy');
791         return new \action_menu_link_secondary($downloadurl, null, $downloadtext);
792     }
794     /**
795      * Creates a new data purpose.
796      *
797      * @param stdClass $record
798      * @return \tool_dataprivacy\purpose.
799      */
800     public static function create_purpose(stdClass $record) {
801         $purpose = new purpose(0, $record);
802         $purpose->create();
804         return $purpose;
805     }
807     /**
808      * Updates an existing data purpose.
809      *
810      * @param stdClass $record
811      * @return \tool_dataprivacy\purpose.
812      */
813     public static function update_purpose(stdClass $record) {
814         if (!isset($record->sensitivedatareasons)) {
815             $record->sensitivedatareasons = '';
816         }
818         $purpose = new purpose($record->id);
819         $purpose->from_record($record);
821         $result = $purpose->update();
823         return $purpose;
824     }
826     /**
827      * Deletes a data purpose.
828      *
829      * @param int $id
830      * @return bool
831      */
832     public static function delete_purpose($id) {
833         $purpose = new purpose($id);
834         if ($purpose->is_used()) {
835             throw new \moodle_exception('Purpose with id ' . $id . ' can not be deleted because it is used.');
836         }
837         return $purpose->delete();
838     }
840     /**
841      * Get all system data purposes.
842      *
843      * @return \tool_dataprivacy\purpose[]
844      */
845     public static function get_purposes() {
846         return purpose::get_records([], 'name', 'ASC');
847     }
849     /**
850      * Creates a new data category.
851      *
852      * @param stdClass $record
853      * @return \tool_dataprivacy\category.
854      */
855     public static function create_category(stdClass $record) {
856         $category = new category(0, $record);
857         $category->create();
859         return $category;
860     }
862     /**
863      * Updates an existing data category.
864      *
865      * @param stdClass $record
866      * @return \tool_dataprivacy\category.
867      */
868     public static function update_category(stdClass $record) {
869         $category = new category($record->id);
870         $category->from_record($record);
872         $result = $category->update();
874         return $category;
875     }
877     /**
878      * Deletes a data category.
879      *
880      * @param int $id
881      * @return bool
882      */
883     public static function delete_category($id) {
884         $category = new category($id);
885         if ($category->is_used()) {
886             throw new \moodle_exception('Category with id ' . $id . ' can not be deleted because it is used.');
887         }
888         return $category->delete();
889     }
891     /**
892      * Get all system data categories.
893      *
894      * @return \tool_dataprivacy\category[]
895      */
896     public static function get_categories() {
897         return category::get_records([], 'name', 'ASC');
898     }
900     /**
901      * Sets the context instance purpose and category.
902      *
903      * @param \stdClass $record
904      * @return \tool_dataprivacy\context_instance
905      */
906     public static function set_context_instance($record) {
907         if ($instance = context_instance::get_record_by_contextid($record->contextid, false)) {
908             // Update.
909             $instance->from_record($record);
911             if (empty($record->purposeid) && empty($record->categoryid)) {
912                 // We accept one of them to be null but we delete it if both are null.
913                 self::unset_context_instance($instance);
914                 return;
915             }
917         } else {
918             // Add.
919             $instance = new context_instance(0, $record);
920         }
921         $instance->save();
923         return $instance;
924     }
926     /**
927      * Unsets the context instance record.
928      *
929      * @param \tool_dataprivacy\context_instance $instance
930      * @return null
931      */
932     public static function unset_context_instance(context_instance $instance) {
933         $instance->delete();
934     }
936     /**
937      * Sets the context level purpose and category.
938      *
939      * @throws \coding_exception
940      * @param \stdClass $record
941      * @return contextlevel
942      */
943     public static function set_contextlevel($record) {
944         global $DB;
946         if ($record->contextlevel != CONTEXT_SYSTEM && $record->contextlevel != CONTEXT_USER) {
947             throw new \coding_exception('Only context system and context user can set a contextlevel ' .
948                 'purpose and retention');
949         }
951         if ($contextlevel = contextlevel::get_record_by_contextlevel($record->contextlevel, false)) {
952             // Update.
953             $contextlevel->from_record($record);
954         } else {
955             // Add.
956             $contextlevel = new contextlevel(0, $record);
957         }
958         $contextlevel->save();
960         // We sync with their defaults as we removed these options from the defaults page.
961         $classname = \context_helper::get_class_for_level($record->contextlevel);
962         list($purposevar, $categoryvar) = data_registry::var_names_from_context($classname);
963         set_config($purposevar, $record->purposeid, 'tool_dataprivacy');
964         set_config($categoryvar, $record->categoryid, 'tool_dataprivacy');
966         return $contextlevel;
967     }
969     /**
970      * Returns the effective category given a context instance.
971      *
972      * @param \context $context
973      * @param int $forcedvalue Use this categoryid value as if this was this context instance category.
974      * @return category|false
975      */
976     public static function get_effective_context_category(\context $context, $forcedvalue = false) {
977         if (!data_registry::defaults_set()) {
978             return false;
979         }
981         return data_registry::get_effective_context_value($context, 'category', $forcedvalue);
982     }
984     /**
985      * Returns the effective purpose given a context instance.
986      *
987      * @param \context $context
988      * @param int $forcedvalue Use this purposeid value as if this was this context instance purpose.
989      * @return purpose|false
990      */
991     public static function get_effective_context_purpose(\context $context, $forcedvalue = false) {
992         if (!data_registry::defaults_set()) {
993             return false;
994         }
996         return data_registry::get_effective_context_value($context, 'purpose', $forcedvalue);
997     }
999     /**
1000      * Returns the effective category given a context level.
1001      *
1002      * @param int $contextlevel
1003      * @return category|false
1004      */
1005     public static function get_effective_contextlevel_category($contextlevel) {
1006         if (!data_registry::defaults_set()) {
1007             return false;
1008         }
1010         return data_registry::get_effective_contextlevel_value($contextlevel, 'category');
1011     }
1013     /**
1014      * Returns the effective purpose given a context level.
1015      *
1016      * @param int $contextlevel
1017      * @param int $forcedvalue Use this purposeid value as if this was this context level purpose.
1018      * @return purpose|false
1019      */
1020     public static function get_effective_contextlevel_purpose($contextlevel, $forcedvalue=false) {
1021         if (!data_registry::defaults_set()) {
1022             return false;
1023         }
1025         return data_registry::get_effective_contextlevel_value($contextlevel, 'purpose', $forcedvalue);
1026     }
1028     /**
1029      * Creates an expired context record for the provided context id.
1030      *
1031      * @param int $contextid
1032      * @return \tool_dataprivacy\expired_context
1033      */
1034     public static function create_expired_context($contextid) {
1035         $record = (object)[
1036             'contextid' => $contextid,
1037             'status' => expired_context::STATUS_EXPIRED,
1038         ];
1039         $expiredctx = new expired_context(0, $record);
1040         $expiredctx->save();
1042         return $expiredctx;
1043     }
1045     /**
1046      * Deletes an expired context record.
1047      *
1048      * @param int $id The tool_dataprivacy_ctxexpire id.
1049      * @return bool True on success.
1050      */
1051     public static function delete_expired_context($id) {
1052         $expiredcontext = new expired_context($id);
1053         return $expiredcontext->delete();
1054     }
1056     /**
1057      * Updates the status of an expired context.
1058      *
1059      * @param \tool_dataprivacy\expired_context $expiredctx
1060      * @param int $status
1061      * @return null
1062      */
1063     public static function set_expired_context_status(expired_context $expiredctx, $status) {
1064         $expiredctx->set('status', $status);
1065         $expiredctx->save();
1066     }
1068     /**
1069      * Adds the contexts from the contextlist_collection to the request with the status provided.
1070      *
1071      * @param contextlist_collection $clcollection a collection of contextlists for all components.
1072      * @param int $requestid the id of the request.
1073      * @param int $status the status to set the contexts to.
1074      */
1075     public static function add_request_contexts_with_status(contextlist_collection $clcollection, int $requestid, int $status) {
1076         $request = new data_request($requestid);
1077         $user = \core_user::get_user($request->get('userid'));
1078         foreach ($clcollection as $contextlist) {
1079             // Convert the \core_privacy\local\request\contextlist into a contextlist persistent and store it.
1080             $clp = \tool_dataprivacy\contextlist::from_contextlist($contextlist);
1081             $clp->create();
1082             $contextlistid = $clp->get('id');
1084             // Store the associated contexts in the contextlist.
1085             foreach ($contextlist->get_contextids() as $contextid) {
1086                 if ($request->get('type') == static::DATAREQUEST_TYPE_DELETE) {
1087                     $context = \context::instance_by_id($contextid);
1088                     $purpose = static::get_effective_context_purpose($context);
1090                     // Data can only be deleted from it if the context is either expired, or unprotected.
1091                     if (!expired_contexts_manager::is_context_expired_or_unprotected_for_user($context, $user)) {
1092                         continue;
1093                     }
1094                 }
1096                 $context = new contextlist_context();
1097                 $context->set('contextid', $contextid)
1098                     ->set('contextlistid', $contextlistid)
1099                     ->set('status', $status)
1100                     ->create();
1101             }
1103             // Create the relation to the request.
1104             $requestcontextlist = request_contextlist::create_relation($requestid, $contextlistid);
1105             $requestcontextlist->create();
1106         }
1107     }
1109     /**
1110      * Sets the status of all contexts associated with the request.
1111      *
1112      * @param int $requestid the requestid to which the contexts belong.
1113      * @param int $status the status to set to.
1114      * @throws \dml_exception if the requestid is invalid.
1115      * @throws \moodle_exception if the status is invalid.
1116      */
1117     public static function update_request_contexts_with_status(int $requestid, int $status) {
1118         // Validate contextlist_context status using the persistent's attribute validation.
1119         $contextlistcontext = new contextlist_context();
1120         $contextlistcontext->set('status', $status);
1121         if (array_key_exists('status', $contextlistcontext->get_errors())) {
1122             throw new moodle_exception("Invalid contextlist_context status: $status");
1123         }
1125         // Validate requestid using the persistent's record validation.
1126         // A dml_exception is thrown if the record is missing.
1127         $datarequest = new data_request($requestid);
1129         // Bulk update the status of the request contexts.
1130         global $DB;
1132         $select = "SELECT ctx.id as id
1133                      FROM {" . request_contextlist::TABLE . "} rcl
1134                      JOIN {" . contextlist::TABLE . "} cl ON rcl.contextlistid = cl.id
1135                      JOIN {" . contextlist_context::TABLE . "} ctx ON cl.id = ctx.contextlistid
1136                     WHERE rcl.requestid = ?";
1138         // Fetch records IDs to be updated and update by chunks, if applicable (limit of 1000 records per update).
1139         $limit = 1000;
1140         $idstoupdate = $DB->get_fieldset_sql($select, [$requestid]);
1141         $count = count($idstoupdate);
1142         $idchunks = $idstoupdate;
1143         if ($count > $limit) {
1144             $idchunks = array_chunk($idstoupdate, $limit);
1145         }
1146         $transaction = $DB->start_delegated_transaction();
1147         $initialparams = [$status];
1148         foreach ($idchunks as $chunk) {
1149             list($insql, $inparams) = $DB->get_in_or_equal($chunk);
1150             $update = "UPDATE {" . contextlist_context::TABLE . "}
1151                           SET status = ?
1152                         WHERE id $insql";
1153             $params = array_merge($initialparams, $inparams);
1154             $DB->execute($update, $params);
1155         }
1156         $transaction->allow_commit();
1157     }
1159     /**
1160      * Finds all request contextlists having at least on approved context, and returns them as in a contextlist_collection.
1161      *
1162      * @param data_request $request the data request with which the contextlists are associated.
1163      * @return contextlist_collection the collection of approved_contextlist objects.
1164      */
1165     public static function get_approved_contextlist_collection_for_request(data_request $request) : contextlist_collection {
1166         $foruser = core_user::get_user($request->get('userid'));
1168         // Fetch all approved contextlists and create the core_privacy\local\request\contextlist objects here.
1169         global $DB;
1170         $sql = "SELECT cl.component, ctx.contextid
1171                   FROM {" . request_contextlist::TABLE . "} rcl
1172                   JOIN {" . contextlist::TABLE . "} cl ON rcl.contextlistid = cl.id
1173                   JOIN {" . contextlist_context::TABLE . "} ctx ON cl.id = ctx.contextlistid
1174                  WHERE rcl.requestid = ?
1175                    AND ctx.status = ?
1176               ORDER BY cl.component, ctx.contextid";
1178         // Create the approved contextlist collection object.
1179         $lastcomponent = null;
1180         $approvedcollection = new contextlist_collection($foruser->id);
1182         $rs = $DB->get_recordset_sql($sql, [$request->get('id'), contextlist_context::STATUS_APPROVED]);
1183         foreach ($rs as $record) {
1184             // If we encounter a new component, and we've built up contexts for the last, then add the approved_contextlist for the
1185             // last (the one we've just finished with) and reset the context array for the next one.
1186             if ($lastcomponent != $record->component) {
1187                 if (!empty($contexts)) {
1188                     $approvedcollection->add_contextlist(new approved_contextlist($foruser, $lastcomponent, $contexts));
1189                 }
1190                 $contexts = [];
1191             }
1193             if ($request->get('type') == static::DATAREQUEST_TYPE_DELETE) {
1194                 $context = \context::instance_by_id($record->contextid);
1195                 $purpose = static::get_effective_context_purpose($context);
1196                 // Data can only be deleted from it if the context is either expired, or unprotected.
1197                 if (!expired_contexts_manager::is_context_expired_or_unprotected_for_user($context, $foruser)) {
1198                     continue;
1199                 }
1200             }
1202             $contexts[] = $record->contextid;
1203             $lastcomponent = $record->component;
1204         }
1205         $rs->close();
1207         // The data for the last component contextlist won't have been written yet, so write it now.
1208         if (!empty($contexts)) {
1209             $approvedcollection->add_contextlist(new approved_contextlist($foruser, $lastcomponent, $contexts));
1210         }
1212         return $approvedcollection;
1213     }
1215     /**
1216      * Updates the default category and purpose for a given context level (and optionally, a plugin).
1217      *
1218      * @param int $contextlevel The context level.
1219      * @param int $categoryid The ID matching the category.
1220      * @param int $purposeid The ID matching the purpose record.
1221      * @param int $activity The name of the activity that we're making a defaults configuration for.
1222      * @param bool $override Whether to override the purpose/categories of existing instances to these defaults.
1223      * @return boolean True if set/unset config succeeds. Otherwise, it throws an exception.
1224      */
1225     public static function set_context_defaults($contextlevel, $categoryid, $purposeid, $activity = null, $override = false) {
1226         global $DB;
1228         // Get the class name associated with this context level.
1229         $classname = context_helper::get_class_for_level($contextlevel);
1230         list($purposevar, $categoryvar) = data_registry::var_names_from_context($classname, $activity);
1232         // Check the default category to be set.
1233         if ($categoryid == context_instance::INHERIT) {
1234             unset_config($categoryvar, 'tool_dataprivacy');
1236         } else {
1237             // Make sure the given category ID exists first.
1238             $categorypersistent = new category($categoryid);
1239             $categorypersistent->read();
1241             // Then set the new default value.
1242             set_config($categoryvar, $categoryid, 'tool_dataprivacy');
1243         }
1245         // Check the default purpose to be set.
1246         if ($purposeid == context_instance::INHERIT) {
1247             // If the defaults is set to inherit, just unset the config value.
1248             unset_config($purposevar, 'tool_dataprivacy');
1250         } else {
1251             // Make sure the given purpose ID exists first.
1252             $purposepersistent = new purpose($purposeid);
1253             $purposepersistent->read();
1255             // Then set the new default value.
1256             set_config($purposevar, $purposeid, 'tool_dataprivacy');
1257         }
1259         // Unset instances that have been assigned with custom purpose and category, if override was specified.
1260         if ($override) {
1261             // We'd like to find context IDs that we want to unset.
1262             $statements = ["SELECT c.id as contextid FROM {context} c"];
1263             // Based on this context level.
1264             $params = ['contextlevel' => $contextlevel];
1266             if ($contextlevel == CONTEXT_MODULE) {
1267                 // If we're deleting module context instances, we need to make sure the instance ID is in the course modules table.
1268                 $statements[] = "JOIN {course_modules} cm ON cm.id = c.instanceid";
1269                 // And that the module is listed on the modules table.
1270                 $statements[] = "JOIN {modules} m ON m.id = cm.module";
1272                 if ($activity) {
1273                     // If we're overriding for an activity module, make sure that the context instance matches that activity.
1274                     $statements[] = "AND m.name = :modname";
1275                     $params['modname'] = $activity;
1276                 }
1277             }
1278             // Make sure this context instance exists in the tool_dataprivacy_ctxinstance table.
1279             $statements[] = "JOIN {tool_dataprivacy_ctxinstance} tdc ON tdc.contextid = c.id";
1280             // And that the context level of this instance matches the given context level.
1281             $statements[] = "WHERE c.contextlevel = :contextlevel";
1283             // Build our SQL query by gluing the statements.
1284             $sql = implode("\n", $statements);
1286             // Get the context records matching our query.
1287             $contextids = $DB->get_fieldset_sql($sql, $params);
1289             // Delete the matching context instances.
1290             foreach ($contextids as $contextid) {
1291                 if ($instance = context_instance::get_record_by_contextid($contextid, false)) {
1292                     self::unset_context_instance($instance);
1293                 }
1294             }
1295         }
1297         return true;
1298     }
1300     /**
1301      * Format the supplied date interval as a retention period.
1302      *
1303      * @param   \DateInterval   $interval
1304      * @return  string
1305      */
1306     public static function format_retention_period(\DateInterval $interval) : string {
1307         // It is one or another.
1308         if ($interval->y) {
1309             $formattedtime = get_string('numyears', 'moodle', $interval->format('%y'));
1310         } else if ($interval->m) {
1311             $formattedtime = get_string('nummonths', 'moodle', $interval->format('%m'));
1312         } else if ($interval->d) {
1313             $formattedtime = get_string('numdays', 'moodle', $interval->format('%d'));
1314         } else {
1315             $formattedtime = get_string('retentionperiodzero', 'tool_dataprivacy');
1316         }
1318         return $formattedtime;
1319     }