Merge pull request #847 from catalyst/add-user-step-and-find-step

add user step and find step

classes/local/step/connector_find.php

@@ -0,0 +1,92 @@
+<?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/>.
+
+namespace tool_dataflows\local\step;
+
+/**
+ * Find (a record from a collection)
+ *
+ * @package    tool_dataflows
+ * @author     Kevin Pham <kevinpham@catalyst-au.net>
+ * @copyright  Catalyst IT, 2022
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class connector_find extends connector_step {
+
+    /**
+     * Returns whether the step has a side effect.
+     *
+     * @return     bool whether or not this step has a side effect
+     * @link https://en.wikipedia.org/wiki/Side_effect_(computer_science)
+     */
+    public function has_side_effect(): bool {
+        return false;
+    }
+
+    /**
+     * Return the definition of the fields available in this form.
+     *
+     * @return array
+     */
+    public static function form_define_fields(): array {
+        return [
+            'collection' => ['type' => PARAM_TEXT, 'required' => true],
+            'condition' => ['type' => PARAM_TEXT, 'required' => true],
+        ];
+    }
+
+    /**
+     * Allows each step type to determine a list of optional/required form
+     * inputs for their configuration
+     *
+     * It's recommended you prefix the additional config related fields to avoid
+     * conflicts with any existing fields.
+     *
+     * @param \MoodleQuickForm $mform
+     */
+    public function form_add_custom_inputs(\MoodleQuickForm &$mform) {
+        $mform->addElement('text', 'config_collection', get_string('find:collection', 'tool_dataflows'));
+        $mform->addElement('static', 'config_collection_help', '', get_string('find:collection_help', 'tool_dataflows'));
+        $mform->addElement('text', 'config_condition', get_string('find:condition', 'tool_dataflows'));
+        $mform->addElement('static', 'config_condition_help', '', get_string('find:condition_help', 'tool_dataflows'));
+    }
+
+    /**
+     * Find based on the condition, and set the matching record given a record.
+     *
+     * If the message is empty, it will not log anything, which is useful for conditional logging.
+     *
+     * @param mixed|null $input
+     * @return mixed
+     */
+    public function execute($input = null) {
+        $variables = $this->get_variables();
+        $config = $variables->get('config');
+        $collection = $config->collection;
+
+        foreach ($collection as $item) {
+            $variables->set('record', $item);
+            $condition = $variables->evaluate('${{'.$config->condition.'}}');
+            if ($condition) {
+                $input = $item;
+                break;
+            }
+        }
+        $variables->set('match', $input);
+
+        return $input;
+    }
+}

classes/local/step/connector_update_user.php

@@ -0,0 +1,35 @@
+<?php
+// This file is part of Moodle - https://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/>.
+
+namespace tool_dataflows\local\step;
+
+/**
+ * Update user connector step
+ *
+ * @package   tool_dataflows
+ * @author    Kevin Pham <kevinpham@catalyst-au.net>
+ * @copyright Catalyst IT, 2023
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class connector_update_user extends connector_step {
+    use update_user_trait;
+
+    /** @var int[] number of output flows (min, max). */
+    protected $outputflows = [0, 1];
+
+    /** @var int[] number of output connectors (min, max). */
+    protected $outputconnectors = [0, 1];
+}

classes/local/step/flow_update_user.php

@@ -0,0 +1,35 @@
+<?php
+// This file is part of Moodle - https://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/>.
+
+namespace tool_dataflows\local\step;
+
+/**
+ * Update user flow step
+ *
+ * @package   tool_dataflows
+ * @author    Kevin Pham <kevinpham@catalyst-au.net>
+ * @copyright Catalyst IT, 2023
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class flow_update_user extends flow_step {
+    use update_user_trait;
+
+    /** @var int[] number of output flows (min, max). */
+    protected $outputflows = [0, 1];
+
+    /** @var int[] number of output connectors (min, max). */
+    protected $outputconnectors = [0, 1];
+}

classes/local/step/update_user_trait.php

@@ -0,0 +1,93 @@
+<?php
+// This file is part of Moodle - https://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/>.
+
+namespace tool_dataflows\local\step;
+
+/**
+ * Update user using core api
+ *
+ * @package   tool_dataflows
+ * @author    Kevin Pham <kevinpham@catalyst-au.net>
+ * @copyright Catalyst IT, 2023
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+trait update_user_trait {
+
+    /**
+     * Returns whether or not the step configured, has a side effect.
+     *
+     * @return     bool whether or not this step has a side effect
+     * @link https://en.wikipedia.org/wiki/Side_effect_(computer_science)
+     */
+    public function has_side_effect(): bool {
+        return true;
+    }
+
+    /**
+     * Return the definition of the fields available in this form.
+     *
+     * @return array
+     */
+    public static function form_define_fields(): array {
+        return [
+            'userid' => ['type' => PARAM_TEXT, 'required' => true],
+            'fields' => ['type' => PARAM_TEXT, 'required' => true, 'yaml' => true],
+        ];
+    }
+
+    /**
+     * Custom elements for editing the connector.
+     *
+     * @param \MoodleQuickForm $mform
+     */
+    public function form_add_custom_inputs(\MoodleQuickForm &$mform) {
+        $mform->addElement('text', 'config_userid', get_string('update_user:userid', 'tool_dataflows'));
+        $mform->addElement('static', 'config_userid_help', '', get_string('update_user:userid_help', 'tool_dataflows'));
+
+        $mform->addElement(
+            'textarea',
+            'config_fields',
+            get_string('update_user:fields', 'tool_dataflows'),
+            ['cols' => 60, 'rows' => 5]
+        );
+        $mform->addElement('static', 'config_fields_help', '', get_string('update_user:fields_help', 'tool_dataflows'));
+    }
+
+    /**
+     * Main execution method which updates the user's details.
+     *
+     * @param  mixed|null $input
+     * @return mixed
+     */
+    public function execute($input = null) {
+        $variables = $this->get_variables();
+        $config = $variables->get('config');
+        $userobject = (object) array_merge(
+            ['id' => $config->userid],
+            (array) $config->fields
+        );
+
+        // Some fields will not be updatable (intentionally).
+        unset($userobject->password);
+        unset($userobject->auth);
+
+        // Update user fields using core api.
+        user_update_user($userobject, false, false);
+        profile_save_data($userobject);
+
+        return $input;
+    }
+}

lang/en/tool_dataflows.php

@@ -622,3 +622,18 @@
 $string['log:level'] = 'Log Level';
 $string['log:level_help'] = 'Choose between 8 logging levels. Each level conveys a different meaning, and it is best practice to choose the most appropriate one for the log message.';
 $string['log:message'] = 'Message';
+
+// Find step.
+$string['step_name_connector_find'] = 'Find';
+$string['find:collection'] = 'Collection';
+$string['find:collection_help'] = 'A reference to a collection of items.';
+$string['find:condition'] = 'Condition';
+$string['find:condition_help'] = 'The expression checked against each item in the referenced collection. For each item in the collection, it can be referenced as "item.field"';
+
+// Update user step.
+$string['step_name_connector_update_user'] = 'Update user';
+$string['step_name_flow_update_user'] = 'Update user';
+$string['update_user:userid'] = 'User ID';
+$string['update_user:userid_help'] = 'The internal ID for this user.';
+$string['update_user:fields'] = 'Fields';
+$string['update_user:fields_help'] = 'Fields set here correspond to the fields available in the underlying user table. Custom user profile fields, must be prefixed with "profile_field_" followed by the shortname. Not all fields can be updated, such as password and auth';

lib.php

@@ -60,6 +60,7 @@ function tool_dataflows_step_types() {
         new step\connector_email,
         new step\connector_file_exists,
         new step\connector_file_put_content,
+        new step\connector_find,
         new step\connector_gpg,
         new step\connector_hash_file,
         new step\connector_log,
@@ -68,6 +69,7 @@ function tool_dataflows_step_types() {
         new step\connector_s3,
         new step\connector_set_variable,
         new step\connector_sftp,
+        new step\connector_update_user,
         new step\connector_sftp_directory_file_list,
         new step\connector_sns_notify,
         new step\connector_wait,
@@ -92,6 +94,7 @@ function tool_dataflows_step_types() {
         new step\flow_transformer_alter,
         new step\flow_transformer_filter,
         new step\flow_transformer_regex,
+        new step\flow_update_user,
         new step\flow_web_service,
         new step\reader_csv,
         new step\reader_directory_file_list,

version.php

@@ -25,8 +25,8 @@
 
 defined('MOODLE_INTERNAL') || die();
 
-$plugin->version = 2023101600;
-$plugin->release = 2023101600;
+$plugin->version = 2023110900;
+$plugin->release = 2023110900;
 $plugin->requires = 2017051500;    // Our lowest supported Moodle (3.3.0).
 $plugin->supported = [35, 401];    // Available as of Moodle 3.9.0 or later.
 // TODO $plugin->incompatible = ;  // Available as of Moodle 3.9.0 or later.