MDL-81007 tool_policy: Allow adding notes to policies acceptances

admin/tool/policy/classes/external/set_acceptances_status.php

@@ -48,11 +48,14 @@ public static function execute_parameters(): external_function_parameters {
                     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.'),
+                        'note' => new external_value(PARAM_NOTAGS,
+                            'Any comments added by a user when giving consent on behalf of another user.', VALUE_OPTIONAL, null),
                     ]), '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
                 ),
+
             ]
         );
     }
@@ -91,9 +94,13 @@ public static function execute(array $policies, int $userid = 0): array {
         }
 
         // Split acceptances.
-        $requestedpolicies = $agreepolicies = $declinepolicies = [];
+        $requestedpolicies = $agreepolicies = $declinepolicies = $notes = [];
         foreach ($params['policies'] as $policy) {
             $requestedpolicies[$policy['versionid']] = $policy['status'];
+            if ($USER->id != $user->id) {
+                // Notes are only allowed when setting acceptances on behalf of another user.
+                $notes[$policy['versionid']] = $policy['note'] ?? null;
+            }
         }
 
         // Retrieve all  policies and their acceptances.
@@ -115,8 +122,12 @@ public static function execute(array $policies, int $userid = 0): array {
         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);
+        foreach ($agreepolicies as $policyversionid) {
+            api::accept_policies($policyversionid, $user->id, $notes[$policyversionid] ?? null);
+        }
+        foreach ($declinepolicies as $policyversionid) {
+            api::decline_policies($policyversionid, $user->id, $notes[$policyversionid] ?? null);
+        }
 
         $return = [
             'policyagreed' => (int) $user->policyagreed,  // Final policy agreement status for $user.

admin/tool/policy/tests/externallib_test.php

@@ -359,7 +359,7 @@ public function test_external_set_acceptances_status() {
         $this->assertCount(0, $policies['warnings']);
 
         // And now accept and old one.
-        $ids = [['versionid' => $optionalpolicy->get('id'), 'status' => 1],];
+        $ids = [['versionid' => $optionalpolicy->get('id'), 'status' => 1, 'note' => 'I accept for me.']];  // The note will be ignored.
         $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);
@@ -372,6 +372,7 @@ public function test_external_set_acceptances_status() {
         $this->assertCount(3, $policies['policies']);
         foreach ($policies['policies'] as $policy) {
             $this->assertEquals(1, $policy['acceptance']['status']);    // Check all accepted.
+            $this->assertEmpty($policy['acceptance']['note']);  // The note was not recorded because it was for itself.
         }
 
         // Decline optional only.
@@ -398,7 +399,9 @@ public function test_external_set_acceptances_status() {
         // 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' => $optionalpolicynew->get('id'), 'status' => 1]], $this->child->id);
+        $notetext = 'I accept this on behalf of my child Santiago.';
+        $policies = \tool_policy\external\set_acceptances_status::execute(
+            [['versionid' => $optionalpolicynew->get('id'), 'status' => 1, 'note' => $notetext]], $this->child->id);
         $policies = \core_external\external_api::clean_returnvalue(
             \tool_policy\external\set_acceptances_status::execute_returns(), $policies);
 
@@ -413,8 +416,10 @@ public function test_external_set_acceptances_status() {
         foreach ($policies['policies'] as $policy) {
             if ($policy['versionid'] == $this->policy2->get('id')) {
                 $this->assertNotContains('acceptance', $policy);    // Not yet accepted.
+                $this->assertArrayNotHasKey('acceptance', $policy);
             } else {
                 $this->assertEquals(1, $policy['acceptance']['status']);    // Accepted.
+                $this->assertEquals($notetext, $policy['acceptance']['note']);
             }
         }