Troubleshooting

Almost every question about the integration is answered in one of three places: the Test Connection result, the sync log, and the retry queue. Start there, then use the sections below for the specific symptom.

Quick Reference

Symptom

Likely cause

Fix

Connection failed (auth): Invalid token

The token was regenerated or deleted in Moodle.

Create a new token and save it on the instance.

Test Connection warns about missing functions

Functions were not added to the external service.

Add them in Moodle and test again.

Nothing syncs, no errors either

Auto Sync Enabled is off, or every toggle is off.

Enable the master switch and the entity toggles.

Every record is logged as skipped

The data has not changed since the last sync.

Normal. Clear the sync hash to force a resend.

Duplicate users or courses in Moodle

Mappings were lost before a push.

Rebuild the mappings, then remove the duplicates in Moodle.

Grades pulled but nowhere to be found

No mapping, no batch, or no exam module.

Check the sync log for the skip reason.

No attendance operations at all

The local_wsattendance plugin is missing.

Install it and add its functions to the service.

Background jobs stay pending

queue_job is not configured.

Set workers and channels in odoo.conf and restart.

One bad record blocks a whole batch

Moodle processes batches as one transaction.

Lower the batch size, fix the record, retry.

Connection Problems

Invalid token

The sync log shows errors of type auth and Test Connection reports an invalid token. The token no longer exists in Moodle or has expired.

  1. In Moodle, go to Site administration ‣ Server ‣ Web services ‣ Manage tokens.

  2. Delete the old entry and create a new token for the same service and user.

  3. In OpenEduCat, open the instance, paste the token into API Token and save.

  4. Click Test Connection.

Missing web service functions

Test Connection succeeds but lists missing functions. The service exists, but not every required function was added to it. Add the missing names to the openeducat_integration external service in Moodle and test again. The warning names exactly which ones are absent.

Moodle cannot be reached

Errors of type network or timeout mean the request never arrived.

  1. Confirm the Moodle URL — no trailing slash, no /webservice/rest/server.php suffix, and the same protocol the site actually serves.

  2. Confirm the OpenEduCat server can reach that host, allowing for firewalls and private networks.

  3. Open the URL in a browser to confirm the site itself is up.

Web services disabled

If every call fails and the response looks like a web page rather than data, web services or the REST protocol are switched off in Moodle. Re-check steps 1 and 2 of the prerequisites chapter.

Sync Problems

Nothing is synchronized

Work down this list:

  1. Auto Sync Enabled on the instance — while it is off, the scheduled jobs skip the instance entirely.

  2. Active on the instance — an archived instance is never processed.

  3. The entity toggles on the Sync Configuration tab — all of them start off.

  4. The scheduled actions in Settings ‣ Technical ‣ Automation ‣ Scheduled Actions.

  5. The sync log, to see whether the job ran and did nothing, or never ran at all.

Everything is skipped

Skipped means the stored hash matched, so nothing needed sending. This is the expected result for most records in a routine run. If a record genuinely needs re-sending — for example after it was changed directly in Moodle — clear the sync hash on its mapping and run the sync again.

Duplicates in Moodle

Duplicates appear when a push runs without the mappings that tell OpenEduCat the Moodle records already exist.

  1. Stop the scheduled synchronization by turning off Auto Sync Enabled.

  2. Open Moodle Integration ‣ Initial Import and click Rebuild Mappings to restore the links from the identifiers stored in Moodle.

  3. Remove the duplicate records in Moodle, keeping the ones that carry the oec_ identifier.

  4. Re-enable scheduled synchronization.

A batch fails because of one record

Moodle applies a batch as a single transaction, so one invalid record rejects the whole batch. The error message names the offending record — commonly an email address already in use, or a missing required field.

  1. Lower Batch Size on the instance to isolate the problem.

  2. Correct the data in OpenEduCat.

  3. Retry the item from the retry queue.

Role or permission errors

Enrollments that fail with a permission error usually mean the Student Role ID or Teacher Role ID does not match this Moodle site, or the token’s user lacks the rights to assign roles. Confirm the role IDs in Moodle, and confirm the service account can manage enrollments.

Grade Problems

Grades do not arrive

A grade is only written when the Moodle course is mapped to a subject, the Moodle user is mapped to a student, the program has at least one batch, and an exam or gradebook module is installed. The sync log records which condition failed.

  1. Check that the subject appears in Moodle Integration ‣ Mappings.

  2. Check that the student appears there too.

  3. Check that the program has a batch — the exam session cannot be created without one.

  4. Filter the sync log on the grade_pull operation for the detailed reason.

Grades arrive but students cannot see them

Imported grades follow the normal approval workflow. Until the gradebook is approved and published, the marks exist but stay invisible to students. Publish them, or review the Grade Publish Mode on the Advance Gradebook tab.

An exam is not in the right state

An exam must be advanced beyond the draft state before marks can be written to it. The integration attempts this automatically; where it cannot, the grade is skipped and the sync log says so. Advance the exam manually and re-run the pull.

Attendance Problems

No attendance operations appear in the log at all, even with Pull Attendance enabled. The standard Moodle attendance activity has no web service API — the local_wsattendance plugin is required.

  1. Install local_wsattendance in Moodle.

  2. Add mod_wsattendance_get_session and mod_wsattendance_update_user_status to the openeducat_integration service.

  3. Run Test Connection, then trigger an attendance sync.

If attendance data disagrees between the two systems, check Attendance Source on the Settings tab — it decides which side wins.

Background Job Problems

Jobs queued from the manual sync wizard never start, or the queue keeps growing. The queue_job module needs OpenEduCat to run with more than one worker:

workers = 4
server_wide_modules = base,web,queue_job

[queue_job]
channels = root:2,root.moodle:4

Restart the service after editing the file. Jobs can be inspected at Settings ‣ Technical ‣ Queue Jobs, where a failed job can be requeued.

Where to Look Next

Question

Where to look

Is the connection working?

Test Connection on the instance.

Did the sync run?

Reporting ‣ Sync Logs, filtered on Today.

What failed, and why?

The Errors smart button on the instance.

What is waiting to be retried?

Reporting ‣ Retry Queue.

Is this record linked to Moodle?

Moodle Integration ‣ Mappings.

Is the site healthy overall?

The health status on the instance, and Reporting ‣ Sync Dashboard.