From 6b2806e7454ca88768c8acecd94cfecbdeab3b17 Mon Sep 17 00:00:00 2001 From: Juan Leyva Date: Wed, 29 Nov 2023 17:22:26 +0100 Subject: [PATCH] MDL-73008 tool_policy: New WS to set user acceptances --- .../external/set_acceptances_status.php | 137 ++++++++++++++++++ admin/tool/policy/db/services.php | 7 + admin/tool/policy/tests/externallib_test.php | 106 ++++++++++++++ 3 files changed, 250 insertions(+) create mode 100644 admin/tool/policy/classes/external/set_acceptances_status.php diff --git a/admin/tool/policy/classes/external/set_acceptances_status.php b/admin/tool/policy/classes/external/set_acceptances_status.php new file mode 100644 index 00000000000..0bfb6d410b8 --- /dev/null +++ b/admin/tool/policy/classes/external/set_acceptances_status.php @@ -0,0 +1,137 @@ +. + +namespace tool_policy\external; + +use core_external\external_api; +use core_external\external_function_parameters; +use core_external\external_single_structure; +use core_external\external_multiple_structure; +use core_external\external_value; +use core_external\external_warnings; +use tool_policy\api; +use tool_policy\policy_version; +use core_user; + +/** + * External function for setting user policies acceptances. + * + * @package tool_policy + * @copyright 2023 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 4.4 + */ +class set_acceptances_status extends external_api { + + /** + * Webservice parameters. + * + * @return external_function_parameters + */ + public static function execute_parameters(): external_function_parameters { + return new external_function_parameters( + [ + 'policies' => new external_multiple_structure( + new external_single_structure([ + 'versionid' => new external_value(PARAM_INT, 'The policy version id.'), + 'status' => new external_value(PARAM_INT, 'The policy acceptance status. 0: decline, 1: accept.'), + ]), 'Policies acceptances for the given user.' + ), + 'userid' => new external_value(PARAM_INT, + 'The user id we want to set the acceptances. Default is the current user.', VALUE_DEFAULT, 0 + ), + ] + ); + } + + /** + * Set the acceptance status (accept or decline only) for the indicated policies for the given user. + * + * @param array $policies the policies to set the acceptance status + * @param int $userid the user id we want to retrieve the acceptances + * @throws \moodle_exception + * @return array policies and acceptance status + */ + public static function execute(array $policies, int $userid = 0): array { + global $USER; + + $params = self::validate_parameters(self::execute_parameters(), + [ + 'policies' => $policies, + 'userid' => $userid, + ] + ); + + // Do not check for the site policies in validate_context() to avoid the redirect loop. + if (!defined('NO_SITEPOLICY_CHECK')) { + define('NO_SITEPOLICY_CHECK', true); + } + + $systemcontext = \context_system::instance(); + external_api::validate_context($systemcontext); + + if (empty($params['userid']) || $params['userid'] == $USER->id) { + $user = $USER; + } else { + $user = core_user::get_user($params['userid'], '*', MUST_EXIST); + core_user::require_active_user($user); + } + + // Split acceptances. + $allcurrentpolicies = api::list_current_versions(policy_version::AUDIENCE_LOGGEDIN); + $requestedpolicies = $agreepolicies = $declinepolicies = []; + foreach ($params['policies'] as $policy) { + $requestedpolicies[$policy['versionid']] = $policy['status']; + } + + foreach ($allcurrentpolicies as $policy) { + if (isset($requestedpolicies[$policy->id])) { + if ($requestedpolicies[$policy->id] === 1) { + $agreepolicies[] = $policy->id; + } else if ($requestedpolicies[$policy->id] === 0) { + $declinepolicies[] = $policy->id; + } + } + } + + // Permissions check. + api::can_accept_policies($agreepolicies, $user->id, true); + api::can_decline_policies($declinepolicies, $user->id, true); + + // Good to go. + api::accept_policies($agreepolicies, $user->id, null); + api::decline_policies($declinepolicies, $user->id, null); + + $return = [ + 'policyagreed' => (int) $user->policyagreed, // Final policy agreement status for $user. + 'warnings' => [], + ]; + return $return; + } + + /** + * Webservice returns. + * + * @return external_single_structure + */ + public static function execute_returns(): external_single_structure { + return new external_single_structure([ + 'policyagreed' => new external_value(PARAM_INT, + 'Whether the user has provided acceptance to all current site policies. 1 if yes, 0 if not'), + 'warnings' => new external_warnings(), + ]); + } +} diff --git a/admin/tool/policy/db/services.php b/admin/tool/policy/db/services.php index 1fb133c5b73..eadaae2526b 100644 --- a/admin/tool/policy/db/services.php +++ b/admin/tool/policy/db/services.php @@ -52,4 +52,11 @@ $functions = [ 'type' => 'read', 'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE], ], + + 'tool_policy_set_acceptances_status' => [ + 'classname' => '\tool_policy\external\set_acceptances_status', + 'description' => 'Set the acceptance status (accept or decline only) for the indicated policies for the given user.', + 'type' => 'write', + 'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE], + ], ]; diff --git a/admin/tool/policy/tests/externallib_test.php b/admin/tool/policy/tests/externallib_test.php index 97eb5c07fce..9796b2fae00 100644 --- a/admin/tool/policy/tests/externallib_test.php +++ b/admin/tool/policy/tests/externallib_test.php @@ -290,4 +290,110 @@ class externallib_test extends externallib_advanced_testcase { $this->expectException(\required_capability_exception::class); $policies = \tool_policy\external\get_user_acceptances::execute($user->id); } + + /** + * Test for external function set_acceptances_status(). + */ + public function test_external_set_acceptances_status() { + global $CFG; + + $this->resetAfterTest(true); + $CFG->sitepolicyhandler = 'tool_policy'; + $user = $this->getDataGenerator()->create_user(); + $this->setUser($user); + + // Create optional policy. + $formdata = api::form_policydoc_data(new \tool_policy\policy_version(0)); + $formdata->name = 'Test optional policy'; + $formdata->revision = 'v1'; + $formdata->optional = 1; + $formdata->summary_editor = ['text' => 'summary', 'format' => FORMAT_HTML, 'itemid' => 0]; + $formdata->content_editor = ['text' => 'content', 'format' => FORMAT_HTML, 'itemid' => 0]; + $optionalpolicy = api::form_policydoc_add($formdata); + api::make_current($optionalpolicy->get('id')); + + // Accept all the policies. + $ids = [['versionid' => $this->policy2->get('id'), 'status' => 1], ['versionid' => $optionalpolicy->get('id'), 'status' => 1]]; + + $policies = \tool_policy\external\set_acceptances_status::execute($ids); + $policies = \core_external\external_api::clean_returnvalue( + \tool_policy\external\set_acceptances_status::execute_returns(), $policies); + + $this->assertEquals(1, $policies['policyagreed']); + $this->assertCount(0, $policies['warnings']); + + $policies = \tool_policy\external\get_user_acceptances::execute(); + $policies = \core_external\external_api::clean_returnvalue( + \tool_policy\external\get_user_acceptances::execute_returns(), $policies); + + $this->assertCount(2, $policies['policies']); + foreach ($policies['policies'] as $policy) { + $this->assertEquals(1, $policy['acceptance']['status']); // Check all accepted. + } + + // Decline optional only. + $policies = \tool_policy\external\set_acceptances_status::execute([['versionid' => $optionalpolicy->get('id'), 'status' => 0]]); + $policies = \core_external\external_api::clean_returnvalue( + \tool_policy\external\set_acceptances_status::execute_returns(), $policies); + + $this->assertEquals(1, $policies['policyagreed']); + $this->assertCount(0, $policies['warnings']); + + $policies = \tool_policy\external\get_user_acceptances::execute(); + $policies = \core_external\external_api::clean_returnvalue( + \tool_policy\external\get_user_acceptances::execute_returns(), $policies); + + $this->assertCount(2, $policies['policies']); + foreach ($policies['policies'] as $policy) { + if ($policy['versionid'] == $this->policy2->get('id')) { + $this->assertEquals(1, $policy['acceptance']['status']); // Still accepted. + } else { + $this->assertEquals(0, $policy['acceptance']['status']); // Not accepted. + } + } + + // Parent & child case now. Accept the optional ONLY on behalf of someone else. + $this->parent->policyagreed = 1; + $this->setUser($this->parent); + $policies = \tool_policy\external\set_acceptances_status::execute([['versionid' => $optionalpolicy->get('id'), 'status' => 1]], $this->child->id); + $policies = \core_external\external_api::clean_returnvalue( + \tool_policy\external\set_acceptances_status::execute_returns(), $policies); + + $this->assertEquals(0, $policies['policyagreed']); // Mandatory missing. + $this->assertCount(0, $policies['warnings']); + + $policies = \tool_policy\external\get_user_acceptances::execute($this->child->id); + $policies = \core_external\external_api::clean_returnvalue( + \tool_policy\external\get_user_acceptances::execute_returns(), $policies); + + $this->assertCount(2, $policies['policies']); + foreach ($policies['policies'] as $policy) { + if ($policy['versionid'] == $this->policy2->get('id')) { + $this->assertNotContains('acceptance', $policy); // Not yet accepted. + } else { + $this->assertEquals(1, $policy['acceptance']['status']); // Accepted. + } + } + + // Try to accept on behalf of other user with no permissions. + $this->expectException(\required_capability_exception::class); + $policies = \tool_policy\external\set_acceptances_status::execute([['versionid' => $optionalpolicy->get('id'), 'status' => 1]], $user->id); + } + + /** + * Test for external function set_acceptances_status decline mandatory. + */ + public function test_external_set_acceptances_status_decline_mandatory() { + global $CFG; + + $this->resetAfterTest(true); + $CFG->sitepolicyhandler = 'tool_policy'; + $this->parent->policyagreed = 1; + $this->setUser($this->parent); + + $this->expectException(\moodle_exception::class); + $this->expectExceptionMessage(get_string('errorpolicyversioncompulsory', 'tool_policy')); + $ids = [['versionid' => $this->policy2->get('id'), 'status' => 0]]; + $policies = \tool_policy\external\set_acceptances_status::execute($ids, $this->child->id); + } }