Bulk Roles Importer Moodle Plugin

The Bulk Roles Importer plugin allows Moodle administrators to efficiently import multiple role definitions from XML files. Roles can be imported either manually or automatically via integration with external repositories like GitHub or GitLab.

This plugin is ideal for Moodle sites managing custom roles across environments, supporting version control, or requiring regular role updates.

Features

Manual Import

• Upload a single XML file or a ZIP archive containing multiple XML files.
• Access the import interface via
  Site administration → Users → Permissions → Import roles from a file.
• Each file is validated to ensure it contains a valid <role> definition.

• Invalid files are skipped with detailed error logging.

Automatic Import

• Configure a GitHub or GitLab repository as the source of XML files.
  
• Define:
  • API URL
  • Repository path
  • Main branch
  • Access token
• Set up a scheduled task to fetch the latest roles automatically at regular intervals (e.g., daily).
• Each run:
  • Retrieves XML role files.
  • Compares timestamps.
  • Creates or updates roles.
  • Logs success, updates, or validation errors.

Admin Settings

Accessible via Site administration → Users → Permissions → Bulk Roles Importer settings:

• Select a role import source (GitHub or GitLab).
• Configure GitHub or GitLab integration details:
  • API URL
  • Access token
  • Project path
  • Branch name

• Link to Moodle’s Scheduled tasks interface to configure import frequency.

Access Tokens

To fetch role definitions from private or rate-limited Git repositories, access tokens are required:

• GitHub: Generate a token

• GitLab: Generate a project access token

Tokens must be added in plugin settings to enable automatic syncing from the repositories.

Example Role

A sample role XML file is included in the /samples directory for demonstration and testing purposes. This provides a simple example of valid XML structure with a few basic permissions.

Multilingual Support

• Plugin strings are translatable via Moodle’s standard language packs.

• The interface follows Moodle’s multilingual conventions for both UI and logs.

Installation

1. Clone or download the repository into the Moodle local/ directory:
   git clone https://github.com/AGILEDROP/moodle-local_bulk_roles_importer.git bulk_roles_importer

2. Visit Site administration → Notifications to complete the installation process.

Usage

• Configure repository access and schedule under plugin settings.

• Upload files manually through the import interface.

• View logs of import results, including newly created or updated roles and any invalid files.

Contribution

We welcome contributions to improve the Bulk Roles Importer plugin:

• Report Issues: Found a bug or have a feature request? Open an issue on GitHub.
• Submit Code: Fork the repository, implement changes, and submit a pull request.

• Translate: Contribute to translations via the Moodle AMOS system.