MDL-43949 groups: Add idnumber to web services
authorDavid Monllao <davidm@moodle.com>
Fri, 19 Jun 2015 05:33:00 +0000 (13:33 +0800)
committerDavid Monllao <davidm@moodle.com>
Thu, 25 Jun 2015 08:55:14 +0000 (16:55 +0800)
Thanks to Vitor Martins for his contribution.

group/externallib.php
group/tests/externallib_test.php
lib/upgrade.txt

index 45eadb3..1f9b739 100644 (file)
@@ -54,6 +54,7 @@ class core_group_external extends external_api {
                             'description' => new external_value(PARAM_RAW, 'group description text'),
                             'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
                             'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase', VALUE_OPTIONAL),
+                            'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL)
                         )
                     ), 'List of group object. A group has a courseid, a name, a description and an enrolment key.'
                 )
@@ -87,6 +88,9 @@ class core_group_external extends external_api {
             if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
                 throw new invalid_parameter_exception('Group with the same name already exists in the course');
             }
+            if (!empty($group->idnumber) && $DB->count_records('groups', array('idnumber' => $group->idnumber))) {
+                throw new invalid_parameter_exception('Group with the same idnumber already exists');
+            }
 
             // now security checks
             $context = context_course::instance($group->courseid, IGNORE_MISSING);
@@ -108,6 +112,10 @@ class core_group_external extends external_api {
             if (!isset($group->enrolmentkey)) {
                 $group->enrolmentkey = '';
             }
+            if (!isset($group->idnumber)) {
+                $group->idnumber = '';
+            }
+
             $groups[] = (array)$group;
         }
 
@@ -132,6 +140,7 @@ class core_group_external extends external_api {
                     'description' => new external_value(PARAM_RAW, 'group description text'),
                     'descriptionformat' => new external_format_value('description'),
                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
+                    'idnumber' => new external_value(PARAM_RAW, 'id number')
                 )
             ), 'List of group object. A group has an id, a courseid, a name, a description and an enrolment key.'
         );
@@ -165,7 +174,7 @@ class core_group_external extends external_api {
         $groups = array();
         foreach ($params['groupids'] as $groupid) {
             // validate params
-            $group = groups_get_group($groupid, 'id, courseid, name, description, descriptionformat, enrolmentkey', MUST_EXIST);
+            $group = groups_get_group($groupid, 'id, courseid, name, idnumber, description, descriptionformat, enrolmentkey', MUST_EXIST);
 
             // now security checks
             $context = context_course::instance($group->courseid, IGNORE_MISSING);
@@ -205,6 +214,7 @@ class core_group_external extends external_api {
                     'description' => new external_value(PARAM_RAW, 'group description text'),
                     'descriptionformat' => new external_format_value('description'),
                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
+                    'idnumber' => new external_value(PARAM_RAW, 'id number')
                 )
             )
         );
@@ -247,7 +257,7 @@ class core_group_external extends external_api {
         require_capability('moodle/course:managegroups', $context);
 
         $gs = groups_get_all_groups($params['courseid'], 0, 0,
-            'g.id, g.courseid, g.name, g.description, g.descriptionformat, g.enrolmentkey');
+            'g.id, g.courseid, g.name, g.idnumber, g.description, g.descriptionformat, g.enrolmentkey');
 
         $groups = array();
         foreach ($gs as $group) {
@@ -276,6 +286,7 @@ class core_group_external extends external_api {
                     'description' => new external_value(PARAM_RAW, 'group description text'),
                     'descriptionformat' => new external_format_value('description'),
                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
+                    'idnumber' => new external_value(PARAM_RAW, 'id number')
                 )
             )
         );
@@ -579,7 +590,8 @@ class core_group_external extends external_api {
                             'courseid' => new external_value(PARAM_INT, 'id of course'),
                             'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
                             'description' => new external_value(PARAM_RAW, 'grouping description text'),
-                            'descriptionformat' => new external_format_value('description', VALUE_DEFAULT)
+                            'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
+                            'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL)
                         )
                     ), 'List of grouping object. A grouping has a courseid, a name and a description.'
                 )
@@ -613,6 +625,9 @@ class core_group_external extends external_api {
             if ($DB->count_records('groupings', array('courseid'=>$grouping->courseid, 'name'=>$grouping->name))) {
                 throw new invalid_parameter_exception('Grouping with the same name already exists in the course');
             }
+            if (!empty($grouping->idnumber) && $DB->count_records('groupings', array('idnumber' => $grouping->idnumber))) {
+                throw new invalid_parameter_exception('Grouping with the same idnumber already exists');
+            }
 
             // Now security checks            .
             $context = context_course::instance($grouping->courseid);
@@ -652,7 +667,8 @@ class core_group_external extends external_api {
                     'courseid' => new external_value(PARAM_INT, 'id of course'),
                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
                     'description' => new external_value(PARAM_RAW, 'grouping description text'),
-                    'descriptionformat' => new external_format_value('description')
+                    'descriptionformat' => new external_format_value('description'),
+                    'idnumber' => new external_value(PARAM_RAW, 'id number')
                 )
             ), 'List of grouping object. A grouping has an id, a courseid, a name and a description.'
         );
@@ -673,7 +689,8 @@ class core_group_external extends external_api {
                             'id' => new external_value(PARAM_INT, 'id of grouping'),
                             'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
                             'description' => new external_value(PARAM_RAW, 'grouping description text'),
-                            'descriptionformat' => new external_format_value('description', VALUE_DEFAULT)
+                            'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
+                            'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL)
                         )
                     ), 'List of grouping object. A grouping has a courseid, a name and a description.'
                 )
@@ -712,6 +729,11 @@ class core_group_external extends external_api {
                     $DB->count_records('groupings', array('courseid'=>$currentgrouping->courseid, 'name'=>$grouping->name))) {
                 throw new invalid_parameter_exception('A different grouping with the same name already exists in the course');
             }
+            // Check if the new modified grouping idnumber already exists.
+            if (!empty($grouping->idnumber) && $grouping->idnumber != $currentgrouping->idnumber &&
+                    $DB->count_records('groupings', array('idnumber' => $grouping->idnumber))) {
+                throw new invalid_parameter_exception('A different grouping with the same idnumber already exists');
+            }
 
             $grouping->courseid = $currentgrouping->courseid;
 
@@ -817,6 +839,7 @@ class core_group_external extends external_api {
                         $context->id, 'group', 'description', $grouprecord->groupid);
                         $groups[] = array('id' => $grouprecord->groupid,
                                           'name' => $grouprecord->name,
+                                          'idnumber' => $grouprecord->idnumber,
                                           'description' => $grouprecord->description,
                                           'descriptionformat' => $grouprecord->descriptionformat,
                                           'enrolmentkey' => $grouprecord->enrolmentkey,
@@ -847,6 +870,7 @@ class core_group_external extends external_api {
                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
                     'description' => new external_value(PARAM_RAW, 'grouping description text'),
                     'descriptionformat' => new external_format_value('description'),
+                    'idnumber' => new external_value(PARAM_RAW, 'id number'),
                     'groups' => new external_multiple_structure(
                         new external_single_structure(
                             array(
@@ -855,7 +879,8 @@ class core_group_external extends external_api {
                                 'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
                                 'description' => new external_value(PARAM_RAW, 'group description text'),
                                 'descriptionformat' => new external_format_value('description'),
-                                'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase')
+                                'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
+                                'idnumber' => new external_value(PARAM_RAW, 'id number')
                             )
                         ),
                     'optional groups', VALUE_OPTIONAL)
@@ -932,7 +957,8 @@ class core_group_external extends external_api {
                     'courseid' => new external_value(PARAM_INT, 'id of course'),
                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
                     'description' => new external_value(PARAM_RAW, 'grouping description text'),
-                    'descriptionformat' => new external_format_value('description')
+                    'descriptionformat' => new external_format_value('description'),
+                    'idnumber' => new external_value(PARAM_RAW, 'id number')
                 )
             )
         );
@@ -1222,7 +1248,7 @@ class core_group_external extends external_api {
 
         $usergroups = array();
         if (empty($warnings)) {
-            $groups = groups_get_all_groups($course->id, $user->id, 0, 'g.id, g.name, g.description, g.descriptionformat');
+            $groups = groups_get_all_groups($course->id, $user->id, 0, 'g.id, g.name, g.description, g.descriptionformat, g.idnumber');
 
             foreach ($groups as $group) {
                 list($group->description, $group->descriptionformat) =
@@ -1254,7 +1280,8 @@ class core_group_external extends external_api {
                             'id' => new external_value(PARAM_INT, 'group record id'),
                             'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
                             'description' => new external_value(PARAM_RAW, 'group description text'),
-                            'descriptionformat' => new external_format_value('description')
+                            'descriptionformat' => new external_format_value('description'),
+                            'idnumber' => new external_value(PARAM_RAW, 'id number')
                         )
                     )
                 ),
index a65d930..7dc9c65 100644 (file)
@@ -50,6 +50,7 @@ class core_group_externallib_testcase extends externallib_advanced_testcase {
         $group1['description'] = 'Group Test 1 description';
         $group1['descriptionformat'] = FORMAT_MOODLE;
         $group1['enrolmentkey'] = 'Test group enrol secret phrase';
+        $group1['idnumber'] = 'TEST1';
         $group2 = array();
         $group2['courseid'] = $course->id;
         $group2['name'] = 'Group Test 2';
@@ -58,6 +59,11 @@ class core_group_externallib_testcase extends externallib_advanced_testcase {
         $group3['courseid'] = $course->id;
         $group3['name'] = 'Group Test 3';
         $group3['description'] = 'Group Test 3 description';
+        $group3['idnumber'] = 'TEST1';
+        $group4 = array();
+        $group4['courseid'] = $course->id;
+        $group4['name'] = 'Group Test 4';
+        $group4['description'] = 'Group Test 4 description';
 
         // Set the required capabilities by the external function
         $context = context_course::instance($course->id);
@@ -80,6 +86,7 @@ class core_group_externallib_testcase extends externallib_advanced_testcase {
                     $groupcourseid = $group1['courseid'];
                     $this->assertEquals($dbgroup->descriptionformat, $group1['descriptionformat']);
                     $this->assertEquals($dbgroup->enrolmentkey, $group1['enrolmentkey']);
+                    $this->assertEquals($dbgroup->idnumber, $group1['idnumber']);
                     break;
                 case $group2['name']:
                     $groupdescription = $group2['description'];
@@ -93,10 +100,19 @@ class core_group_externallib_testcase extends externallib_advanced_testcase {
             $this->assertEquals($dbgroup->courseid, $groupcourseid);
         }
 
+        try {
+            $froups = core_group_external::create_groups(array($group3));
+            $this->fail('Exception expected due to already existing idnumber.');
+        } catch (moodle_exception $e) {
+            $this->assertInstanceOf('invalid_parameter_exception', $e);
+            $this->assertEquals('Invalid parameter value detected (Group with the same idnumber already exists)',
+                $e->getMessage());
+        }
+
         // Call without required capability
         $this->unassignUserCapability('moodle/course:managegroups', $context->id, $roleid);
         $this->setExpectedException('required_capability_exception');
-        $froups = core_group_external::create_groups(array($group3));
+        $froups = core_group_external::create_groups(array($group4));
     }
 
     /**
@@ -114,6 +130,7 @@ class core_group_externallib_testcase extends externallib_advanced_testcase {
         $group1data['description'] = 'Group Test 1 description';
         $group1data['descriptionformat'] = FORMAT_MOODLE;
         $group1data['enrolmentkey'] = 'Test group enrol secret phrase';
+        $group1data['idnumber'] = 'TEST1';
         $group2data = array();
         $group2data['courseid'] = $course->id;
         $group2data['name'] = 'Group Test 2';
@@ -142,6 +159,7 @@ class core_group_externallib_testcase extends externallib_advanced_testcase {
                     $groupcourseid = $group1->courseid;
                     $this->assertEquals($dbgroup->descriptionformat, $group1->descriptionformat);
                     $this->assertEquals($dbgroup->enrolmentkey, $group1->enrolmentkey);
+                    $this->assertEquals($dbgroup->idnumber, $group1->idnumber);
                     break;
                 case $group2->name:
                     $groupdescription = $group2->description;
@@ -209,6 +227,67 @@ class core_group_externallib_testcase extends externallib_advanced_testcase {
         $froups = core_group_external::delete_groups(array($group3->id));
     }
 
+    /**
+     * Test create and update groupings.
+     * @return void
+     */
+    public function test_create_update_groupings() {
+        global $DB;
+
+        $this->resetAfterTest(true);
+
+        $this->setAdminUser();
+
+        $course = self::getDataGenerator()->create_course();
+
+        $grouping1data = array();
+        $grouping1data['courseid'] = $course->id;
+        $grouping1data['name'] = 'Grouping 1 Test';
+        $grouping1data['description'] = 'Grouping 1 Test description';
+        $grouping1data['descriptionformat'] = FORMAT_MOODLE;
+        $grouping1data['idnumber'] = 'TEST';
+
+        $grouping1 = self::getDataGenerator()->create_grouping($grouping1data);
+
+        $grouping1data['name'] = 'Another group';
+
+        try {
+            $groupings = core_group_external::create_groupings(array($grouping1data));
+            $this->fail('Exception expected due to already existing idnumber.');
+        } catch (moodle_exception $e) {
+            $this->assertInstanceOf('invalid_parameter_exception', $e);
+            $this->assertEquals('Invalid parameter value detected (Grouping with the same idnumber already exists)',
+                $e->getMessage());
+        }
+
+        // No exception should be triggered.
+        $grouping1data['id'] = $grouping1->id;
+        $grouping1data['idnumber'] = 'CHANGED';
+        unset($grouping1data['courseid']);
+        core_group_external::update_groupings(array($grouping1data));
+
+        $grouping2data = array();
+        $grouping2data['courseid'] = $course->id;
+        $grouping2data['name'] = 'Grouping 2 Test';
+        $grouping2data['description'] = 'Grouping 2 Test description';
+        $grouping2data['descriptionformat'] = FORMAT_MOODLE;
+        $grouping2data['idnumber'] = 'TEST';
+
+        $grouping2 = self::getDataGenerator()->create_grouping($grouping2data);
+
+        $grouping2data['id'] = $grouping2->id;
+        $grouping2data['idnumber'] = 'CHANGED';
+        unset($grouping2data['courseid']);
+        try {
+            $groupings = core_group_external::update_groupings(array($grouping2data));
+            $this->fail('Exception expected due to already existing idnumber.');
+        } catch (moodle_exception $e) {
+            $this->assertInstanceOf('invalid_parameter_exception', $e);
+            $this->assertEquals('Invalid parameter value detected (A different grouping with the same idnumber already exists)',
+                $e->getMessage());
+        }
+    }
+
     /**
      * Test get_groupings
      */
@@ -313,6 +392,7 @@ class core_group_externallib_testcase extends externallib_advanced_testcase {
         $group1data['courseid'] = $course->id;
         $group1data['name'] = 'Group Test 1';
         $group1data['description'] = 'Group Test 1 description';
+        $group1data['idnumber'] = 'TEST1';
         $group2data = array();
         $group2data['courseid'] = $course->id;
         $group2data['name'] = 'Group Test 2';
@@ -339,6 +419,7 @@ class core_group_externallib_testcase extends externallib_advanced_testcase {
 
         $this->assertEquals($group1data['name'], $groups['groups'][0]['name']);
         $this->assertEquals($group1data['description'], $groups['groups'][0]['description']);
+        $this->assertEquals($group1data['idnumber'], $groups['groups'][0]['idnumber']);
 
         $this->setUser($teacher);
         $groups = core_group_external::get_course_user_groups($course->id, $student1->id);
@@ -372,5 +453,4 @@ class core_group_externallib_testcase extends externallib_advanced_testcase {
         $this->assertCount(1, $groups['warnings']);
 
     }
-
 }
index c3f320f..6430b18 100644 (file)
@@ -6,6 +6,15 @@ information provided here is intended especially for developers.
 * \core\progress\null is renamed to \core\progress\none for improved PHP7 compatibility as null is a reserved word (see MDL-50453).
 * \webservice_xmlrpc_client now respects proxy server settings. If your XMLRPC server is available on your local network and not via your proxy server, you may need to add it to the list of proxy
   server exceptions in $CFG->proxybypass. See MDL-39353 for details.
+* Group and groupings idnumbers can now be passed to and/or are returned from the following web services functions:
+  ** core_group_external::create_groups
+  ** core_group_external::get_groups
+  ** core_group_external::get_course_groups
+  ** core_group_external::create_groupings
+  ** core_group_external::update_groupings
+  ** core_group_external::get_groupings
+  ** core_group_external::get_course_groupings
+  ** core_group_external::get_course_user_groups
 
 === 2.9.1 ===