{"id":19591893,"url":"https://github.com/catalyst/moodle-tool_dynamic_cohorts","last_synced_at":"2025-07-16T14:33:27.339Z","repository":{"id":225756933,"uuid":"766727186","full_name":"catalyst/moodle-tool_dynamic_cohorts","owner":"catalyst","description":"Moodle dynamic cohorts admin tool","archived":false,"fork":false,"pushed_at":"2025-05-12T12:43:39.000Z","size":261,"stargazers_count":5,"open_issues_count":28,"forks_count":4,"subscribers_count":15,"default_branch":"MOODLE_404_STABLE","last_synced_at":"2025-05-12T13:47:55.357Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://moodle.org/plugins/tool_dynamic_cohorts","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/catalyst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-04T02:18:33.000Z","updated_at":"2025-04-29T00:09:52.000Z","dependencies_parsed_at":"2024-03-25T04:33:02.592Z","dependency_job_id":"8e30d6bc-8f73-48d0-a09e-a338e2a0d9b9","html_url":"https://github.com/catalyst/moodle-tool_dynamic_cohorts","commit_stats":null,"previous_names":["catalyst/moodle-tool_dynamic_cohorts"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/catalyst/moodle-tool_dynamic_cohorts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-tool_dynamic_cohorts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-tool_dynamic_cohorts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-tool_dynamic_cohorts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-tool_dynamic_cohorts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catalyst","download_url":"https://codeload.github.com/catalyst/moodle-tool_dynamic_cohorts/tar.gz/refs/heads/MOODLE_404_STABLE","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-tool_dynamic_cohorts/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265518475,"owners_count":23780967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T08:31:34.472Z","updated_at":"2025-07-16T14:33:27.315Z","avatar_url":"https://github.com/catalyst.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"https://github.com/catalyst/moodle-tool_dynamic_cohorts/actions/workflows/ci.yml?query=branch%3AMOODLE_401_STABLE\"\u003e\n\u003cimg src=\"https://github.com/catalyst/moodle-tool_dynamic_cohorts/workflows/ci/badge.svg\"\u003e\n\u003c/a\u003e\n\n# Dynamic cohorts #\n\nDynamic cohorts plugin allows dynamically add and remove users from cohorts based on configured rules, which themselves are composed of conditions.\n\n# Versions and branches\n\n| Moodle Version   | Branch            | \n|------------------|-------------------|\n| Moodle 4.1 - 4.3 | MOODLE_401_STABLE | \n| Moodle 4.4+      | MOODLE_404_STABLE | \n\n\n## Installing via uploaded ZIP file ##\n\n1. Log in to your Moodle site as an admin and go to _Site administration \u003e\n   Plugins \u003e Install plugins_.\n2. Upload the ZIP file with the plugin code. You should only be prompted to add\n   extra details if your plugin type is not automatically detected.\n3. Check the plugin validation report and finish the installation.\n\n## Installing manually ##\n\nThe plugin can be also installed by putting the contents of this directory to\n\n    {your/moodle/dirroot}/admin/tool/dynamic_cohorts\n\nAfterwards, log in to your Moodle site as an admin and go to _Site administration \u003e\nNotifications_ to complete the installation.\n\nAlternatively, you can run\n\n    $ php admin/cli/upgrade.php\n\nto complete the installation from the command line.\n\n# Similar plugins\nThere are similar plugins that can add users to cohorts dynamically based on user profile fields.\n\n* Profile field based cohort membership https://moodle.org/plugins/local_profilecohort\n* Smart Cohort https://moodle.org/plugins/local_cnw_smartcohort\n* Auto-cohort plugin https://moodle.org/plugins/local_cohortauto\n\nHowever, \"Dynamic cohorts\" plugin gets this all to the next level as it provides an API for other plugins to implement pretty much any condition that can limit users from mdl_user table by SQL.\n\n# How does it work?\n\nThere are two concepts, rules and conditions.\n\n## Conditions\n\nConditions are simple predicates which assert something about a user in the system. Any plugin may specify a condition. As an example conditions related to user profile fields. These can be used to match users based on the value of a profile field.\n\n### Built-in conditions\n\n* Authentication method (Manual, SAML and etc)\n* Cohort fields (if a user is a member of cohort(s) matching specific cohort fields like cohort name, context, custom fields and etc)\n* Cohort membership (if a user is a member of cohort(s)).\n* Course completed (if a user has completed a course).\n* Course not completed (if a user has not completed a course).\n* User created time (time since a user was created).\n* User custom profile fields (text, menu, date and autocomplete types are supported).\n* User enrolment (if a user is enrolled into a course).\n* User last login (time since a user last logged in).\n* User role (if a user has a role in a given context)\n* User standard profile fields (e.g. first name, last name, username, auth method and etc).\n* User interests (if a user has a specific interest tagged on their profile).\n\n## Rules\n\nRules are what determine if a user will be added or removed from a cohort. A rule is defined by few things:\n\n1. A cohort\n2. A set of conditions\n3. A logical operator to be applied for conditions (OR/AND)\n\nFor users to be added to the cohort specified by a rule, they must match all of rule's conditions (logical operator AND) or any of rule's conditions (logical operator OR). \n\n**NB:** A cohort can be managed by _one and only one_ rule. This is to prevent rules competing over users in a cohort (e.g., to avoid situations where Rule A wants users a, b, c to be in a cohort, but Rule B wants to remove user c from the same cohort). \n\nRules can be processed by two mechanisms:\n\n1. By cron: When a rule is created or updated, there may be many users that need to be added or removed from a cohort. This process is handled by cron, and depending on how many users are matched by a rule, this process can take some time. For rules matching large sets of users, some [configuration options](#rule-processing-options) are provided which may be useful to server administrators.\n2. By event: rules may also listen to certain events. When one of these events triggers, appropriate rules will be checked and the user will be added to the appropriate cohort immediately. For example, the User standard profile field rule listens to the \"User created\" and \"User updated\" events.\n\n### Disabling realtime processing (processing on event)\n\nEach rule can be configured to be processed realtime (if any of the related conditions support processing on event).\n\nThere is also a global admin setting that allows administrator to enable or disable realtime rule processing globally overriding per rule configuration. \n\n# Configuration\n\n## Prerequisites\n1. At least one manually created cohort (See _Site administration \u003e Users \u003e Cohorts_)\n\n## Creating a rule\n1. Navigate to _Site administration \u003e Users \u003e Accounts \u003e Dynamic cohorts \u003e Manage rules_\n2. Press the \"Add a new rule\" button\n3. From this form you can specify the cohort users will be added to, and add any conditions available in your system. As metioned above, a user must match **all** conditions to be added to the cohort\n4. Press the \"Save changes\" button\n\nYou will be directed to the manage rules page where you can review your rule before enabling it by clicking the eye.\n\n**Note:** It is important to review your new rule to make sure it is configured properly. Consider carefully how many users are affected by the rule (displayed in the table) before enabling it. For rules operating on large sets of users see [rule processing options](#rule-processing-options)\n\nAny subsequent edits to a rule will disable it and require you to review and re-enable it.\n\n## Rule processing options\nRules are processed regularly by cron; by default cron will add each user to the specified cohort one by one. For large sets of users, this can take a long time and potentially block other cron tasks.\n\nTo mitigate this, an option is provided to process \"in bulk\" instead of adding them to a cohort one at a time. To enable it for a rule:\n\n1. Go to the rule edit table \n2. Check the \"Bulk processing\" checkbox\n3. Save the rule and review it before enabling\n\n# Technical details\n\n## Condition implementation\n\n### Quick start\n\nAny plugin can easily implement a condition by adding classes in the `\\local\\tool_dynamic_cohorts\\condition` namespace. Each condition must extend the [base_condition class](classes/condition_base.php). As an example, the itself provides some conditions; the directory structure is as follows:\n\n```\ntool_dynamic_cohorts\n└── classes\n    └── local\n       └── tool_dynamic_cohorts\n           └── condition\n               ├── auth_method.php\n               ├── cohort_membership.php\n               ├── user_custom_profile.php\n               └── user_profile.php\n```\n\nSee [cohort_membership.php](classes/local/tool_dynamic_cohorts/condition/cohort_membership.php) for an example implementation of a single rule. Any plugin wishing to add a rule must simply add similar class inside its own directory. tool_dynamic_cohorts will automatically discover new rules.  \n\n### Triggering on event\n\nAny condition can specify a list of events to listen to by overriding the `get_events` method. Simply return a list of events. See [user_custom_profile.php](classes/local/tool_dynamic_cohorts/condition/user_custom_profile.php) for an example.\n\n## Task processing\nTask processing is orchestrated by a simple mechanism:\n\n1. A scheduled task runs periodically which gets all enabled rules, then queues an ad-hoc task to process the rule (i.e., one ad-hoc task per rule)\n2. The ad-hoc task will either:\n   a) Iterate over all users, adding them to the cohort one at a time (via the cohort API)\n   b) If bulk processing is enabled, users will be inserted directly in to the DB in batches, bypassing the core API\n\n\n## Warm thanks ##\n\nPlugin funded by Murdoch University, Perth, Western Australia (https://www.murdoch.edu.au/) \n\n## License ##\n\n2024 Catalyst IT\n\nThis program is free software: you can redistribute it and/or modify it under\nthe terms of the GNU General Public License as published by the Free Software\nFoundation, either version 3 of the License, or (at your option) any later\nversion.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE.  See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with\nthis program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatalyst%2Fmoodle-tool_dynamic_cohorts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatalyst%2Fmoodle-tool_dynamic_cohorts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatalyst%2Fmoodle-tool_dynamic_cohorts/lists"}