Add cli script to install webservice, user and role.

CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
 
+## Version 1.2.5 (XXXXXXXXXX)
+
+- Add an automatic plugin configuration feature, to simplify the setup process (#15 - Thanks to @melanietreitinger)
+- Display a welcome message with setup instructions during plugin installation
+- Add support for automated configuration using a CLI script
+- Add error message during job creation, when plugin is not fully configured yet
+
+
 ## Version 1.2.4 (2024021901)
 
 - Fix image inlining for Moodle instances that reside in subdirectories (e.g., `https://your.domain/moodle`)

README.md

@@ -128,7 +128,7 @@ permissions, setup a webservice for the archive worker, and set configuration
 options for the Moodle plugin.
 
 
-### 1. Prerequisites
+### Prerequisites
 
 Installation of the additional [quiz archive worker service](https://github.com/ngandrass/moodle-quiz-archive-worker)
 is mandatory for this plugin to work.
@@ -137,7 +137,81 @@ is mandatory for this plugin to work.
 [Quiz Archive Worker: Installation](https://github.com/ngandrass/moodle-quiz-archive-worker#installation)**
 
 
-### 2. Create Moodle User and Role
+### Automatic Configuration
+
+Creation of the dedicated Moodle user and role, as well as the setup of the
+webservice for the archive worker, can be done automatically.
+
+The easiest way is to use the automatic configuration feature provided via the
+Moodle admin interface.
+
+1. Navigate to _Site Administration_ > _Plugins_ (1) > _Activity modules_ >
+   _Quiz_ > _Quiz Archiver_ (2)
+2. Click the _Automatic configuration_ button (3)
+3. Enter the URL under which the quit archive worker can be reached (4)
+4. (Optional) Change the configuration defaults (5)
+5. Execute the automatic configuration (6)
+6. Close the window (7)
+7. (Optional) Adjust the default plugin setting on the plugin settings page
+
+[![Screenshot: Configuration - Automatic Configuration 1](doc/configuration/configuration_plugin_settings_1_thumb.png)](doc/configuration/configuration_plugin_settings_1.png)
+[![Screenshot: Configuration - Automatic Configuration 2](doc/configuration/configuration_plugin_autoinstall_2_thumb.png)](doc/configuration/configuration_plugin_autoinstall_2.png)
+[![Screenshot: Configuration - Automatic Configuration 3](doc/configuration/configuration_plugin_autoinstall_3_thumb.png)](doc/configuration/configuration_plugin_autoinstall_3.png)
+[![Screenshot: Configuration - Automatic Configuration 4](doc/configuration/configuration_plugin_autoinstall_4_thumb.png)](doc/configuration/configuration_plugin_autoinstall_4.png)
+
+
+#### Using the Command Line Interface (CLI)
+
+<details>
+<summary><b>Expand here to show CLI configuration instructions</b></summary>
+
+If you want to configure this plugin in an automated fashion, you can use the
+provided CLI script. The script is located at
+`{$CFG->wwwroot}/mod/quiz/report/archiver/cli/autoinstall.php`.
+
+To execute the script:
+
+1. Open a terminal and navigate to the quiz archiver CLI directory:
+   ```bash
+   cd /path/to/moodle/mod/quiz/report/archiver/cli
+   ```
+2. Execute the CLI script using PHP:
+    ```bash
+    php autoinstall.php --help
+    ```
+
+Usage:
+```text
+Automatically configures Moodle for use with the quiz archiver plugin.
+
+ATTENTION: This CLI script ...
+- Enables web services and REST protocol
+- Creates a quiz archiver service role and a corresponding user
+- Creates a new web service with all required webservice functions
+- Authorises the user to use the webservice.
+
+Usage:
+    $ php autoinstall.php
+    $ php autoinstall.php --username="my-custom-archive-user"
+    $ php autoinstall.php [--help|-h]
+
+Options:
+    --help, -h          Show this help message
+    --force, -f         Force the autoinstall, regardless of the current state of the system
+    --workerurl=<value> Sets the URL of the worker (default: http://localhost:8080)
+    --wsname=<value>    Sets a custom name for the web service (default: quiz_archiver_webservice)
+    --rolename=<value>  Sets a custom name for the web service role (default: quiz_archiver)
+    --username=<value>  Sets a custom username for the web service user (default: quiz_archiver_serviceaccount)
+```
+</details>
+
+
+### Manual Configuration
+
+<details>
+<summary><b>Expand here to show manual configuration instructions</b></summary>
+
+### 1. Create Moodle User and Role
 
 1. Create a designated Moodle user for the quiz archiver webservice
    1. Navigate to _Site Administration_ > _Users_ (1) > _Accounts_ > _Add a new user_ (2)
@@ -174,8 +248,7 @@ is mandatory for this plugin to work.
    [![Screenshot: Configuration - Assign Role 2](doc/configuration/configuration_assign_role_2_thumb.png)](doc/configuration/configuration_assign_role_2.png)
    [![Screenshot: Configuration - Assign Role 3](doc/configuration/configuration_assign_role_3_thumb.png)](doc/configuration/configuration_assign_role_3.png)
 
-
-### 3. Setup Webservice
+### 2. Setup Webservice
 
 1. Enable webservices globally
    1. Navigate to _Site Administration_ > _Server_ (1) > _Web services_ > _Overview_ (2)
@@ -215,7 +288,7 @@ is mandatory for this plugin to work.
    [![Screenshot: Configuration - Assign Webservice Functions 4](doc/configuration/configuration_assign_webservice_functions_4_thumb.png)](doc/configuration/configuration_assign_webservice_functions_4.png)
 
 
-### 4. Configure Plugin Settings
+### 3. Configure Plugin Settings
 
 1. Navigate to _Site Administration_ > _Plugins_ (1) > _Activity modules_ >
    _Quiz_ > _Quiz Archiver_ (2)
@@ -238,6 +311,7 @@ is mandatory for this plugin to work.
 [![Screenshot: Configuration - Plugin Settings 1](doc/configuration/configuration_plugin_settings_1_thumb.png)](doc/configuration/configuration_plugin_settings_1.png)
 [![Screenshot: Configuration - Plugin Settings 2](doc/configuration/configuration_plugin_settings_2_thumb.png)](doc/configuration/configuration_plugin_settings_2.png)
 
+</details>
 
 ### Known Pitfalls
 

adminui/autoinstall.php

@@ -0,0 +1,94 @@
+<?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/>.
+
+/**
+ * Handler for autoinstall feature from the admin UI of the quiz archiver plugin.
+ *
+ * @package   quiz_archiver
+ * @copyright 2024 Niels Gandraß <niels@gandrass.de>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or late
+ */
+
+/** @var bool Disables output buffering */
+const NO_OUTPUT_BUFFERING = true;
+
+require_once(__DIR__.'/../../../../../config.php');
+require_once("{$CFG->libdir}/moodlelib.php");
+require_once("{$CFG->dirroot}/mod/quiz/report/archiver/classes/form/autoinstall_form.php");
+
+use quiz_archiver\form\autoinstall_form;
+use quiz_archiver\local\autoinstall;
+
+// Ensure user has permissions
+require_login();
+$ctx = context_system::instance();
+require_capability('moodle/site:config', $ctx);
+
+// Setup page
+$PAGE->set_context($ctx);
+$PAGE->set_url('/mod/quiz/report/archiver/adminui/autoinstall.php');
+$title = get_string('autoinstall_plugin', 'quiz_archiver');
+$PAGE->set_title($title);
+
+$returnlink = html_writer::link(
+    new moodle_url('/admin/settings.php', ['section' => 'quiz_archiver_settings']),
+    get_string('back')
+);
+
+echo $OUTPUT->header();
+echo $OUTPUT->heading($title);
+
+// Content
+if (autoinstall::plugin_is_unconfigured()) {
+    $form = new autoinstall_form();
+
+    if ($form->is_cancelled()) {
+        // Cancelled
+        echo $OUTPUT->paragraph(get_string('autoinstall_cancelled', 'quiz_archiver'));
+        echo $OUTPUT->paragraph($returnlink);
+    } else if ($data = $form->get_data()) {
+        // Perform autoinstall
+        list($success, $log) = autoinstall::execute(
+            $data->workerurl,
+            $data->wsname,
+            $data->rolename,
+            $data->username
+        );
+
+        // Show result
+        echo $OUTPUT->paragraph(get_string('autoinstall_started', 'quiz_archiver'));
+        echo $OUTPUT->paragraph(get_string('logs'));
+        echo "<pre>{$log}</pre><br/>";
+
+        if ($success) {
+            echo $OUTPUT->paragraph(get_string('autoinstall_success', 'quiz_archiver'));
+        } else {
+            echo $OUTPUT->paragraph(get_string('autoinstall_failure', 'quiz_archiver'));
+        }
+
+        echo $OUTPUT->paragraph($returnlink);
+    } else {
+        echo $OUTPUT->paragraph(get_string('autoinstall_explanation', 'quiz_archiver'));
+        echo $OUTPUT->paragraph(get_string('autoinstall_explanation_details', 'quiz_archiver'));
+        $form->display();
+    }
+} else {
+    echo $OUTPUT->paragraph(get_string('autoinstall_already_configured_long', 'quiz_archiver'));
+    echo $OUTPUT->paragraph($returnlink);
+}
+
+// End page
+echo $OUTPUT->footer();

classes/form/autoinstall_form.php

@@ -0,0 +1,76 @@
+<?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/>.
+
+/**
+ * Defines the editing form for artifacts
+ *
+ * @package    quiz_archiver
+ * @copyright  2024 Niels Gandraß <niels@gandrass.de>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace quiz_archiver\form;
+
+use quiz_archiver\local\autoinstall;
+
+defined('MOODLE_INTERNAL') || die();
+
+require_once($CFG->dirroot.'/lib/formslib.php');
+require_once($CFG->dirroot.'/mod/quiz/report/archiver/classes/local/autoinstall.php');
+
+
+/**
+ * Form to trigger automatic installation of the quiz archiver plugin
+ */
+class autoinstall_form extends \moodleform {
+
+    /**
+     * Form definiton.
+     *
+     * @throws \dml_exception
+     * @throws \coding_exception
+     * @throws \moodle_exception
+     */
+    public function definition() {
+        $mform = $this->_form;
+        $mform->addElement('header', 'header', get_string('settings', 'plugin'));
+
+        // Add configuration options
+        $mform->addElement('text', 'workerurl', get_string('setting_worker_url', 'quiz_archiver'), ['size' => 50]);
+        $mform->addElement('static', 'workerurl_help', '', get_string('setting_worker_url_desc', 'quiz_archiver'));
+        $mform->setType('workerurl', PARAM_TEXT);
+        $mform->addRule('workerurl', null, 'required', null, 'client');
+
+        $mform->addElement('text', 'wsname', get_string('autoinstall_wsname', 'quiz_archiver'), ['size' => 50]);
+        $mform->setDefault('wsname', autoinstall::DEFAULT_WSNAME);
+        $mform->setType('wsname', PARAM_TEXT);
+        $mform->addRule('wsname', null, 'required', null, 'client');
+
+        $mform->addElement('text', 'rolename', get_string('autoinstall_rolename', 'quiz_archiver'), ['size' => 50]);
+        $mform->setDefault('rolename', autoinstall::DEFAULT_ROLESHORTNAME);
+        $mform->setType('rolename', PARAM_TEXT);
+        $mform->addRule('rolename', null, 'required', null, 'client');
+
+        $mform->addElement('text', 'username', get_string('autoinstall_username', 'quiz_archiver'), ['size' => 50]);
+        $mform->setDefault('username', autoinstall::DEFAULT_USERNAME);
+        $mform->setType('username', PARAM_TEXT);
+        $mform->addRule('username', null, 'required', null, 'client');
+
+        // Action buttons
+        $this->add_action_buttons(true, get_string('confirm', 'moodle'));
+    }
+
+}