How the sync engine works

Realsmart is two applications working together. This admin is where you manage users, groups and settings. A separate, headless service — realsmart-provisioning — takes what you manage here and pushes it out to Google Workspace, Microsoft Entra ID, Apple School Manager and on-prem Active Directory. It has no screens of its own; everything it does is visible here, in the Sync and Logs areas.

This page explains what that engine actually does, and when — so its behaviour is never a mystery.

The big picture: fetch → reconcile → apply

Every sync follows the same three-step shape:

1. Fetch — pull the source of truth. For MIS-connected schools that's your MIS via Wonde (students, staff, contacts, groups). This keeps Realsmart's own records current.
2. Reconcile — for each user and group, compare what Realsmart expects with what the platform actually has (the real Google/Entra account, its group memberships, Classroom rosters).
3. Apply — make only the changes needed to close the gap: create/update accounts, add missing memberships, remove ones no longer justified. Every change writes a log row as it happens.

Scheduled school syncs run from a central scheduler (one master server, so nothing runs twice), with the work spread across queue workers. Big schools are processed in slices so one school can't block another.

Change detection: why unchanged users are skipped

The engine does not push every user to Google every time. Each user carries a fingerprint of their desired state (their details, their synced group memberships and roles). If nothing in that fingerprint changed since the last confirmed successful push, the user is skipped without contacting Google at all — you'll see "skipped — no change" tallies in the logs. The fingerprint only advances when a push is confirmed successful, so a failed push is always retried on the next run.

This is why a change you make in the admin syncs, but an untouched user produces no traffic: the engine is delta-driven by design.

Adding vs removing (the reconciliation discipline)

• Adding is generous — if Realsmart expects a membership and the platform lacks it, it's added.
• Removing is careful — if a night would remove far more memberships than usual, removals are paused and shown on the Dashboard until the data is right or a school admin lets them go ahead (see Realsmart paused some changes to keep your groups safe). The sync also never changes groups through an address that belongs to someone else's Google account. Otherwise, a membership is only removed when nothing justifies it any more: not the user's own groups, not group-to-group mappings, and (on shared-domain trusts) not another school's claim — see below. Suspended/deleted users have their memberships stripped, again subject to those protections.

The provisioning window (the summer freeze)

Each school has a first and final provision date. Between them, MIS changes flow through to the platforms. From the final provision date, the school is frozen: MIS fetches and whole-school pushes stop, so summer MIS rollover chaos never reaches live accounts. Provisioning resumes on its own on your resume date (1 September by default): at 03:30 that morning the window is rolled forward, ahead of the day's Google and Entra syncs (see the End of year area, which manages exactly this).

While frozen, you can still create and edit users and groups in the admin, and everything is saved — but the engine's workers hold back every push to Google and Entra, including the changes you queue from the admin, until the window reopens. That's why the admin shows a Cloud sync is paused banner on the Users and Groups pages. Nothing is lost: at resume the whole-school sync rebuilds every user and group from the database. The ways through are Send now for one named person (see Cloud sync is paused) and Release early accounts for new staff and accepted pre-admission pupils (see Release early accounts during the freeze).

The manual MIS switch (a different mechanism)

Separately from the automatic window, School settings → Sync services → MIS sync is a deliberate master on/off for a school. Turning it off stops that school's MIS data being imported at all — new starters, leavers and group changes stop flowing to Realsmart, Google and Entra until it's turned back on (the next sync then reconciles what was missed). The MIS log shows IMPORT DISABLED for each import that finds it off. It's confirmation-gated and attributed in the logs, because turning it off is silent: nothing errors, changes just stop. The same card has a Mode: in Preview the fetch still reads your MIS but imports nothing, and the run shows as skipped (mis-preview) — see See what's coming from your MIS. On a planned move to a new MIS, Realsmart can also put a school into Preview on the switch-over day (the MIS log then reads MIS sync paused for the switch-over …). If sync seems held, check all of these: is the school past its final provision date (the freeze), is the MIS sync switch on, and is its mode Live? The admin screen shows which one is in effect.

Shared-domain trusts (one Google account, several schools)

When a trust shares one Google domain, the same person is one Google account but a separate record in each school. With the Shared Google domain (trust authority) setting on, removal decisions are made trust-wide: a group or Classroom membership is only removed when no school in the trust owns it. Protected removals appear in the logs as "Retained — owned by [school]". Full explanation: Shared Google domain trusts.

Google Classroom

Classroom courses are created from your teaching groups (each course is tied to its group and school year). The engine keeps rosters in step with group membership — teachers and students are added and removed as the group changes — and honours your end-of-term archiving policy (archive now / leave / archive next term). Guardians are only invited from the Classroom parents page (see Classroom parents), never automatically.

Adhoc syncs (the "sync now" path)

Alongside the scheduled runs there's a sync queue for immediacy. When you save a user, trigger a manual sync, or use "Add to sync queue", the admin places a message on the queue; the engine's workers pick it up within minutes and run the same reconcile logic for just those users or groups — for Google and Entra alike. Scheduled runs are the belt; the adhoc queue is the braces.

Logging and attribution (the glass)

Every action the engine takes writes a log row as it happens, attributed to:

• the school it ran for,
• the user it affected, and
• the group / classroom it acted on (membership changes carry both parties),
• with the real error detail when something fails (the actual API message, not a summary).

Runs themselves are tracked with start/end markers and counts, which is what the Sync status header and the Provisioning runs page (its Recent runs list) read. The whole-school Microsoft Entra sync isn't tracked as a run: its activity is in the Logs (Source: Microsoft Entra). The Logs area, the per-user and per-group log tabs, and the MAT User log trace all read this same stream — one record of truth. See Check sync status and read logs.

When things go wrong

• Transient platform errors (rate limits, timeouts) are retried automatically.
• Failed pushes don't advance the fingerprint, so the user is retried next run rather than silently forgotten.
• Errors are never silent — they land in the logs with the affected user/group and the platform's actual message, and surface in the Logs area's errors-first triage view.

Quick answers

• "I changed a user — when does it reach Google/Entra?" — Within minutes via the adhoc queue if the change queued one (saving a user does), otherwise on the next scheduled run. If your school is frozen for the summer, it waits until sync resumes.
• "Why did nothing sync for most users?" — Their fingerprints were unchanged; the engine deliberately skips them.
• "Why has syncing stopped entirely?" — Check the provisioning window (the school is frozen from its final provision date until its resume date) and the MIS sync card on School settings → Sync services (switched off, or set to Preview).
• "Who removed that membership?" — The Logs area shows the removal, attributed, with the reason; on shared-domain trusts you'll also see what was deliberately retained.