local_csv_user_sync is a Moodle local plugin that synchronizes users and manual course enrolments from a CSV source.

It supports user creation and updates, enrolment creation/update/removal, dry-run mode, detailed logging, and a secure onboarding email flow for new users.

• Imports users from CSV into Moodle.
• Updates existing users (optionally only when values changed).
• Synchronizes manual enrolments by course shortname and role shortname.
• Supports enrolment suspension and deletion flags.
• Can auto-create missing manual enrolment instances for courses.
• Supports CSV source from:
  • absolute file path, or
  • uploaded file in plugin settings.
• Supports configurable delimiter and encoding (UTF-8, ISO-8859-1, Windows-1252, auto).
• Validates CSV structure and required headers before processing.
• Supports Moodle custom profile fields from CSV.
• Provides downloadable CSV template (including custom profile fields).
• Includes dry-run mode (simulate actions without writing data).
• Uses task-level locking to prevent concurrent sync runs.
• Logs to both mtrace and plugin DB table (local_cus_log).
• Includes GDPR privacy provider for exported/deleted user-related log data.

• Moodle 4.5 branch or newer ($plugin->requires = 2024100700).
• Plugin component: local_csv_user_sync.

1. Copy the plugin into:
   • local/csv_user_sync
2. Visit:
   • Site administration -> Notifications
3. Complete database upgrade if prompted.

Path:

• Site administration -> Plugins -> Local plugins -> CSV User Sync

Configure only one source:

• CSV file path (absolute path), or
• CSV file upload (stored file area csvsource)

If both or neither are set, the task stops with a configuration error.

• File encoding: UTF-8, ISO-8859-1, Windows-1252, auto
• Delimiter: single character (default ;)

• Default authentication method: used when CSV auth is empty or invalid.
• Send credentials email: for newly created users.
• Email template: supports placeholders:
  • {{firstname}}
  • {{lastname}}
  • {{username}}
  • {{setpasswordurl}}
  • {{sitename}}
  • {{loginurl}}
• Legacy compatibility:
  • {{password}} is still accepted as an alias for {{setpasswordurl}}.

• Update only changed data
• Detailed logging
• Dry-run mode

Headers are normalized before matching:

• lowercase
• spaces/hyphens converted to _
• non [a-z0-9_] characters removed
• UTF-8 BOM removed from first header

Example:

• Course Shortname -> course_shortname

These headers must exist:

• username
• firstname
• lastname
• email

Enrolment headers must be paired:

• course_shortname and role_shortname must both be present if either is present.

• username
• firstname
• lastname
• email
• auth
• city
• country
• lang
• idnumber
• institution
• department
• phone1
• phone2
• address

• course_shortname
• role_shortname
• enrol_start_date (alias: start_date)
• enrol_end_date (alias: end_date)
• suspended (0 or 1, empty treated as 0)
• deleted (0 or 1, empty treated as 0)

Two ways are accepted:

• profile_field_<shortname>
• <shortname> (if it is not a reserved/system header and matches an existing profile field)

• Y-m-d (example 2026-02-18)
• d.m.Y (example 18.02.2026)
• d/m/Y (example 18/02/2026)
• YYYYMMDD (example 20260218)
• Unix timestamp (seconds, 10 digits)
• Unix timestamp (milliseconds, 13 digits)
• Empty value means 0 (no date)

For each row:

1. Validate mandatory user values.
2. Create or update user.
3. If course shortname is present, process enrolment.

Enrolment logic highlights:

• If deleted = 1: remove existing manual enrolment.
• If suspended = 1: set enrolment to suspended.
• If enrolment exists and start/end dates are empty: preserve existing dates.
• If role changes, plugin enforces exactly one manual role assignment for that instance.

If a manual enrolment instance is missing on a target course, the plugin creates one (unless dry-run).

• Template download endpoint requires:
  • authenticated session
  • valid sesskey
  • moodle/site:config capability
• Plugin file serving is restricted to system context and moodle/site:config.
• User data from CSV is sanitized before writes.
• New user:
  • It sends a one-time password setup/reset URL ({{setpasswordurl}}) when supported by user auth.
  • Falls back to login URL when reset links are not available.
• Exception messages are sanitized before persistent logging to reduce sensitive path leakage.

Logs are written to:

• mtrace output
• local_cus_log table (runid, level, rownum, userid, username, message, timecreated)

Privacy support:

• Plugin declares metadata and supports export/deletion for user-related records in local_cus_log.

Task class:

• \local_csv_user_sync\task\sync_task

Default schedule:

• random minute / random hour, daily (R R * * *)

Manual execution example:

php admin/cli/scheduled_task.php --execute="\\local_csv_user_sync\\task\\sync_task"

When enabled:

• no DB writes for users/enrolments
• actions are simulated and logged
• enrolment for newly "created" dry-run users is skipped because no real user ID exists

Common checks:

• Ensure exactly one CSV source is configured.
• Ensure delimiter is exactly one character.
• Ensure required headers exist.
• Ensure course_shortname and role_shortname are both present for enrolment imports.
• Ensure role shortnames and course shortnames exist in Moodle.
• Ensure uploaded file still exists in plugin file storage.