Moodle plugin

The local_ssea plugin is the bridge between your Moodle and SoftSys Edu Analytics. It observes 15 standard Moodle events, queues them, and resiliently sends them to the SSEA backend.

Prerequisites

• Moodle 4.1 or higher (4.5+ recommended).
• PHP 7.4+ (aligned with Moodle 4.x requirements).
• Administrator access in Moodle.
• Tenant credentials provided by SoftSys Solutions:
  • Tenant ID (UUID)
  • API key (format ssea_ + 32 hex characters)
• HTTPS egress allowed from your Moodle server to ingest.softsysanalytics.com and api.softsysanalytics.com.

Installation

Option A — ZIP (recommended)

1. Download the latest local_ssea.zip from the release channel agreed with SoftSys Solutions (customers receive access to the package through the support channel).

2. In Moodle, go to Site administration → Plugins → Install plugins.

3. Upload the ZIP file.

4. Follow the installation wizard.

5. When finished, complete the initial configuration (next section).

Option B — Manual

1. Copy the plugin directory inside <moodle_root>/local/ssea/.

   Caution

   The directory must be named exactly ssea, not local_ssea. The final path must be <moodle_root>/local/ssea/.

2. Adjust permissions to the web-server user (typical on Debian/Ubuntu):

   sudo chown -R www-data:www-data <moodle_root>/local/ssea

3. Visit https://<your_moodle>/admin/index.php — Moodle detects the plugin and runs the database migration.

4. Complete the initial configuration.

Configuration

After install, go to:

Site administration → Plugins → Local plugins → SSEA Analytics

Or directly: /admin/settings.php?section=local_ssea

Required settings

Setting	Description	Example
Enabled	Plugin master switch	Yes
Server URL	SSEA ingest endpoint	https://ingest.softsysanalytics.com
API key	Tenant API key	ssea_abc123...
Tenant ID	UUID assigned by SoftSys	f47ac10b-58cc-...

Optional settings

Setting	Default	Description
Delivery mode	batch	sync (immediate), async (adhoc task), batch (DB queue)
Batch size	50	Events per batch (1–500)
Request timeout	5 s	HTTP timeout
SSL verify	Yes	Only disable on local dev with invalid certificates
Debug logging	No	Verbose log to Moodle debug log
Do not send IP (no_ip)	No	Exclude IP from the payload before sending — useful for strict internal policies

Delivery modes

The plugin supports three modes for sending events to ingest:

Batch (default, recommended)

Events are written to the local_ssea_queue table and sent in batches every 5 minutes by the process_queue_task scheduled task. Best performance and resilience: if the ingest is temporarily down, events accumulate safely and are sent once it recovers.

Async (adhoc task)

Each event is queued as a Moodle adhoc task and delivered when Moodle’s task runner (cron.php) processes it. Better UX than sync mode (no per-page latency), but depends on the Moodle cron frequency.

Sync (immediate)

Events are sent directly during the Moodle HTTP request. Simple but adds latency to every page that triggers an event. Recommended only for very low-traffic sites or for debugging.

Tip

For production, always use batch. It has the best balance of performance, resilience, and operational simplicity.

Captured events

The plugin observes 15 standard Moodle events: session, enrollment, course navigation, resource views, quiz attempts and submissions, assignment submissions, forum posts, grading, and completion.

See the full catalog in Event types.

Plugin capabilities

The plugin declares four Moodle capabilities to control access to its views:

Capability	Description	Typical roles
local/ssea:viewlearnerreport	View the personal learner report	Student, Teacher, Manager
local/ssea:viewinstructorreport	View instructor reports	Teacher, Manager
local/ssea:managesettings	Manage plugin configuration	Manager
local/ssea:viewreports	View aggregated admin reports	Manager

Scheduled tasks

The plugin registers two Moodle scheduled tasks:

Task	Class	Default frequency
SSEA: Process event queue	\local_ssea\task\process_queue_task	Every 5 minutes (*/5 * * * *)
SSEA: Migrate Moodle data	\local_ssea\task\migrate_data_task	Daily (disabled by default — see below)

The data migration task syncs the current state of users, courses, enrollments, activities, and grades to the backend. Useful to pre-populate the dashboard with existing history when you install the plugin on a Moodle with content. It is disabled by default — enable it when you want to run the initial sync.

To enable it:

Site administration → Server → Scheduled tasks → SSEA Migrate Data → Edit → Enable

Troubleshooting

No events reaching SSEA

1. Confirm the plugin is enabled: Site administration → Plugins → SSEA → “Enabled: Yes”.

2. Test the connection: the plugin settings page has a “Test connection” button.

3. Check the queue: run (from the Moodle UI or the DB):

   SELECT COUNT(*) FROM mdl_local_ssea_queue WHERE status = 'pending';

4. Verify Moodle cron is running. Without cron, the process_queue_task never runs and events pile up. From the shell:

   php admin/cli/cron.php

   Or check your crontab / systemd unit.

5. Check errors: Moodle debug log, and if the plugin has an errors table:

   SELECT * FROM mdl_local_ssea_errors ORDER BY created_at DESC LIMIT 20;

401 error (API key rejected)

• Verify the API key starts with ssea_ and has the correct length.
• Verify the Tenant ID matches what SoftSys Solutions provisioned.
• If you suspect the key was revoked, contact the support team to issue a new one.

402 error (plan quota exceeded)

Your tenant has exceeded its plan’s daily event quota. Options:

• Wait for the UTC midnight reset.
• Upgrade to a higher-quota plan. See Plans & limits.

SSL errors on on-premise Moodle

If your Moodle server has an outdated CA bundle, TLS verification may fail against Cloudflare. Update the system CA bundle:

sudo apt-get update && sudo apt-get install --only-upgrade ca-certificates

Only as a last resort in internal environments can you disable SSL verify in the plugin settings. Never in public production.

Queue grows indefinitely

1. Verify process_queue_task is running: Site administration → Scheduled tasks.
2. Check errors: SELECT * FROM mdl_local_ssea_errors WHERE error_type = 'delivery_failed' LIMIT 10;
3. If the ingest is temporarily down, events accumulate safely — they will flush once the ingest recovers.

The plugin doesn’t appear in settings

Verify the plugin directory is named exactly ssea (not local_ssea):

<moodle_root>/local/ssea/    ← correct
<moodle_root>/local/local_ssea/  ← wrong

Plugin upgrade

1. Download the new ZIP or copy the new files into <moodle_root>/local/ssea/.
2. Visit /admin/index.php — Moodle detects the new version and runs DB upgrades (they are incremental, no data loss).
3. Existing settings are preserved.

Uninstall

Site administration → Plugins → Local plugins → SSEA → Uninstall

Uninstalling:

• Removes the plugin’s local tables (queue, errors, metadata).
• Does not remove the data already sent to SSEA (lives in the tenant’s backend).
• Stops generating events immediately.

If you also want to delete the tenant’s data from the backend, contact the support team — see Data retention.

Privacy

The plugin implements Moodle’s standard Privacy API provider (classes/privacy/provider.php):

• When Moodle deletes a user, the plugin immediately stops generating events for that user_id.
• Moodle’s standard export / right-to-be-forgotten flows include the plugin’s data.
• The plugin API key is stored in Moodle’s config and is never logged in plaintext.
• Events do not include the content of activities (quiz answers, forum bodies, uploaded files). Only metadata.

See Security & privacy for the full model.

Related

• Quick start
• Event types
• API — Event ingestion
• Data retention
• Security & privacy