moodle-an-hochschulen · mfprimo · Oct 5, 2022 · Oct 5, 2022 · Oct 6, 2022
diff --git a/CHANGES.md b/CHANGES.md
@@ -4,6 +4,10 @@ moodle-local_bulkenrol
 Changes
 -------
 
+### v4.0-r3
+
+* 2022-10-06 - Lets Teachers choose different fields other than email to enrol users by.
+
 ### v4.0-r2
 
 * 2022-07-12 - Fix README description how this plugin works in Moodle 4.0

diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@ moodle-local_bulkenrol
 
 [![Moodle Plugin CI](https://github.com/moodle-an-hochschulen/moodle-local_bulkenrol/workflows/Moodle%20Plugin%20CI/badge.svg?branch=master)](https://github.com/moodle-an-hochschulen/moodle-local_bulkenrol/actions?query=workflow%3A%22Moodle+Plugin+CI%22+branch%3Amaster)
 
-Moodle plugin which provides the possibility to bulk enrol a list of users who are identified by their e-mail adresses into a course.
+Moodle plugin which provides the possibility to bulk enrol a list of users who are identified by their e-mail adresses, username or idnumber into a course.
 
 
 Requirements
@@ -20,7 +20,7 @@ In some organizations or some teaching scenarios, manually enrolling students in
 To ease the life of teachers, there is the need for a bulk enrolment tool. There are already plugins out there which provide this functionality, so this is just another one. The goal of this bulk enrolment implementation is not to fulfil everybody's needs, but to do one thing and to do this well.
 
 So, the key features of this plugin are:
-1. to let teachers submit a line-separated list of email addresses to enrol them into a course,
+1. to let teachers submit a line-separated list of email addresses, username or idnumber to enrol them into a course,
 2. to let teachers submit this list to a textarea within their course instead of requiring them to create and upload a CSV file first.
 
 
@@ -41,11 +41,19 @@ After installing the plugin, it does not do anything to Moodle yet.
 To configure the plugin and its behaviour, please visit:
 Site administration -> Plugins -> Enrolments -> User bulk enrolment
 
-There, you find only one setting:
+There, you find three settings:
 
 ### 1. Enrolment plugin
 The enrolment method to be used to bulk enrol the users. If the configured enrolment method is not active / added in the course when the users are bulk-enrolled, it is automatically added / activated.
 
+### 2. Role
+The role assigned to the bulk enrolled users.
+
+### 3. Field options
+The key fields available to the teachers to identify the users to enroll. If no field is enabled, the plugin will be disabled.
+The plugin supports custom field defined with "forceunique" set to on.
+Please note that e-mail address uniqueness can be disabled by the adminstrator.
+Morover, Moodle doesn't enforce idnumber uniqueness. 
 
 Capabilities
 ------------
@@ -61,7 +69,7 @@ How this plugin works
 
 Teachers (rather users who have been granted the capability which is described in the "Capabilities" section above) will find an additional "User bulk enrolment" menu item within the jump menu on the course's participants page.
 
-To enrol existing Moodle users into the course, the teacher will then have to add a list of e-mail adresses to the form on this page, one user / e-mail adress per line.
+To enrol existing Moodle users into the course, the teacher will then have to add a list of e-mail adresses, username or idnumber to the form on this page, one user / key identifier per line.
 
 Example:
 ```
@@ -85,7 +93,7 @@ [email protected]
 Limitations
 -----------
 
-This plugin currently only accepts a list of e-mail adresses to be enrolled into a course. It does especially not accept lists of user names, matriculation IDs or something else.
+This plugin currently only accepts a list of e-mail addresses, username or idnumber to be enrolled into a course. It does not accept any other field because only these are managed as key in Moodle.
 
 Additionally, this plugin only enrols users who already exist in Moodle. It won't create Moodle user accounts on-the-fly.
 
@@ -192,3 +200,7 @@ Communication and Information Centre (kiz)\
 Alexander Bias
 
 It was contributed to the Moodle an Hochschulen e.V. plugin catalogue in 2022.
+
+This plugin contains contributes from:
+- University of Münster, Learnweb by ZHLdigital
+- University of Genoa, AulaWeb staff
diff --git a/classes/bulkenrol_form.php b/classes/bulkenrol_form.php
@@ -50,24 +50,62 @@ protected function definition() {
 
         $mform = $this->_form;
 
+        // Selector for database field to match list to.
+        $availablefieldsstring = get_config('local_bulkenrol', 'fieldoptions');
+        $availablefieldsarray = explode(',', $availablefieldsstring);
+        if (count($availablefieldsarray) < 1 or $availablefieldsarray[0] == '') {
+            print_error(get_string('error_no_options_available', 'local_bulkenrol'));
+        }
+
+        $selectoptions = [];
+        foreach ($availablefieldsarray as $fieldoption) {
+            $selectoptions[$fieldoption] = $this->get_fieldname($fieldoption);
+        }
+
+        // Format CSV, replace last , with 'or' and add spaces after remaining.
+        $fieldnamestring = implode(', ', $selectoptions);
+        $formattedfieldnamestring = $this->str_last_replace(', ', ' ' . get_string('or', 'local_bulkenrol') . ' ', $fieldnamestring);
+
         // Infotext.
-        $msg = get_string('bulkenrol_form_intro', 'local_bulkenrol');
+        $msg = get_string('bulkenrol_form_intro', 'local_bulkenrol', $formattedfieldnamestring);
         $mform->addElement('html', '<div id="intro">'.$msg.'</div>');
 
-        // Textarea for Emails.
-        $mform->addElement('textarea', 'usermails',
-                get_string('usermails', 'local_bulkenrol'), 'wrap="virtual" rows="10" cols="80"');
-        $mform->addRule('usermails', null, 'required');
-        $mform->addHelpButton('usermails', 'usermails', 'local_bulkenrol');
+        // Helptext.
+        if ($availablefieldsarray[0] == 'u_username') {
+            $helpstringidentifier = 'userlist_username';
+        } else if ($availablefieldsarray[0] == 'u_idnumber') {
+            $helpstringidentifier = 'userlist_idnumber';
+        } else {
+            $helpstringidentifier = 'userlist_email';
+        }
+
+        $singleoption = count($availablefieldsarray) == 1;
+        if (!$singleoption) {
+            $mform->addElement('select', 'dbfield', get_string('choose_field', 'local_bulkenrol'), $selectoptions);
+            $listfieldtitle = get_string('userlist', 'local_bulkenrol');
+        } else {
+            $field = $availablefieldsarray[0];
+            $mform->addElement('hidden', 'dbfield');
+            $mform->setType('dbfield', PARAM_TEXT);
+            $mform->setDefault('dbfield', $field);
+            $listfieldtitle = get_string('userlist_singleoption', 'local_bulkenrol', $this->get_fieldname($field));
+        }
+        // Textarea for uservalues.
+        $mform->addElement('textarea', 'uservalues',
+                $listfieldtitle, 'wrap="virtual" rows="10" cols="80"');
+        $mform->addRule('uservalues', null, 'required');
+        $mform->addHelpButton('uservalues', $helpstringidentifier, 'local_bulkenrol');
 
         // Add form content if the user came back to check his input.
         $localbulkenroleditlist = optional_param('editlist', 0, PARAM_ALPHANUMEXT);
         if (!empty($localbulkenroleditlist)) {
             $localbulkenroldata = $localbulkenroleditlist.'_data';
             if (!empty($localbulkenroldata) && !empty($SESSION->local_bulkenrol_inputs) &&
                     array_key_exists($localbulkenroldata, $SESSION->local_bulkenrol_inputs)) {
-                $formdatatmp = $SESSION->local_bulkenrol_inputs[$localbulkenroldata];
-                $mform->setDefault('usermails', $formdatatmp);
+                $formdatatmp = $SESSION->local_bulkenrol_inputs[$localbulkenroldata]['users'];
+                $dbfield = $SESSION->local_bulkenrol_inputs[$localbulkenroldata]['dbfield'];
+                $mform->setDefault('uservalues', $formdatatmp);
+                $mform->setDefault('dbfield', $dbfield);
             }
         }
 
@@ -89,10 +127,47 @@ protected function definition() {
     public function validation($data, $files) {
         $retval = array();
 
-        if (empty($data['usermails'])) {
-            $retval['usermails'] = get_string('error_usermails_empty', 'local_bulkenrol');
+        if (empty($data['uservalues'])) {
+            $retval['uservalues'] = get_string('error_list_empty', 'local_bulkenrol');
         }
 
         return $retval;
     }
+
+    /**
+     * Returns the name of a fieldoption without its table prefix
+     * @param string $fieldoption fieldname with type prefix
+     * @return string name of field without type prefix
+     * @throws \UnexpectedValueException Field is not prefixed by c_ or u_
+     * @throws \dml_exception Database connection error
+     */
+    private function get_fieldname($fieldoption) {
+        global $DB;
+        $fieldinfo = explode("_", $fieldoption, 2);
+        switch ($fieldinfo[0]) {
+            case "u":
+                return $fieldinfo[1];
+            case "c":
+                return $DB->get_field('user_info_field', 'name', array("id" => intval($fieldinfo[1])));
+            default:
+                throw new \UnexpectedValueException("field is not from usertable (u_) or customfield (c_)");
+        }
+    }
+
+    /**
+     * Replaces the last occurence of the needle in a string.
+     * @param string $search needle to search for
+     * @param string $replace string replacement for needle
+     * @param string $subject string subject string to search
+     * @return string subject string with the last occurence of the needle replaced
+     */
+    private function str_last_replace($search, $replace, $subject) {
+        $pos = strrpos($subject, $search);
+
+        if ($pos !== false) {
+            $subject = substr_replace($subject, $replace, $pos, strlen($search));
+        }
+
+        return $subject;
+    }
 }
diff --git a/db/upgrade.php b/db/upgrade.php
@@ -0,0 +1,43 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * bulkenrol plugin upgrade code
+ *
+ * @package     local_bulkenrol
+ * @copyright   2022 Marco Ferrante, University of Genoa (I) <[email protected]>
+ * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Function to upgrade bulkenrol.
+ * @param int $oldversion the version we are upgrading from
+ * @return bool result
+ */
+function xmldb_local_bulkenrol_upgrade($oldversion) {
+    global $CFG, $DB;
+
+    if ($oldversion < 2022100600) {
+        // Enable e-mail address as key field if unique
+        if (empty($CFG->allowaccountssameemail)) {
+            set_config('fieldoptions', ["u_email"], 'local_bulkenrol');
+            upgrade_plugin_savepoint(true, 2022100600, 'local', 'bulkenrol');
+        }
+    }
+
+    return true;
+}
diff --git a/index.php b/index.php
@@ -59,25 +59,32 @@
 if (empty($localbulkenrolkey)) {
     $form = new bulkenrol_form(null, array('courseid' => $id));
     if ($formdata = $form->get_data()) {
-        $emails = $formdata->usermails;
+        $datafield = $formdata->dbfield;
+        $uservalues = $formdata->uservalues;
         $courseid = $formdata->id;
 
-        $checkedmails = local_bulkenrol_check_user_mails($emails, $courseid);
+        $availablefieldsstring = get_config('local_bulkenrol', 'fieldoptions');
+        $availablefieldsarray = explode(',', $availablefieldsstring);
+        if (!in_array($datafield, $availablefieldsarray)) {
+            print_error('The provided datafield has not been approved by the administrator.', 'local_bulkenrol');
+        }
+
+        $checkedusers = local_bulkenrol_check_user_data($uservalues, $courseid, $datafield);
 
         // Create local_bulkenrol array in Session.
         if (!isset($SESSION->local_bulkenrol)) {
             $SESSION->local_bulkenrol = array();
         }
         // Save data in Session.
         $localbulkenrolkey = $courseid.'_'.time();
-        $SESSION->local_bulkenrol[$localbulkenrolkey] = $checkedmails;
+        $SESSION->local_bulkenrol[$localbulkenrolkey] = $checkedusers;
 
         // Create local_bulkenrol_inputs array in session.
         if (!isset($SESSION->local_bulkenrol_inputs)) {
             $SESSION->local_bulkenrol_inputs = array();
         }
         $localbulkenroldata = $localbulkenrolkey.'_data';
-        $SESSION->local_bulkenrol_inputs[$localbulkenroldata] = $emails;
+        $SESSION->local_bulkenrol_inputs[$localbulkenroldata] = array('users' => $uservalues, 'dbfield' => $datafield);
     } else if ($form->is_cancelled()) {
         if (!empty($id)) {
             redirect($CFG->wwwroot .'/course/view.php?id='.$id, '', 0);
@@ -130,13 +137,13 @@
         }
 
         // Show notification if there aren't any valid email addresses to enrol.
-        if (!empty($localbulkenroldata) && isset($localbulkenroldata->validemailfound) &&
-                empty($localbulkenroldata->validemailfound)) {
+        if (!empty($localbulkenroldata) && isset($localbulkenroldata->validusersfound) &&
+                empty($localbulkenroldata->validusersfound)) {
             $a = new stdClass();
             $url = new moodle_url('/local/bulkenrol/index.php', array('id' => $id, 'editlist' => $localbulkenrolkey));
             $a->url = $url->out();
             $notification = new \core\output\notification(
-                    get_string('error_no_valid_email_in_list', 'local_bulkenrol', $a),
+                    get_string('error_no_valid_data_in_list', 'local_bulkenrol', $a),
                     \core\output\notification::NOTIFY_WARNING);
             $notification->set_show_closebutton(false);
             echo $OUTPUT->render($notification);