How the sync engine (realsmart-provisioning) works

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 — 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. Once today passes 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 when the window is rolled forward for the new year (see the End of year area, which manages exactly this).

While frozen, admin-initiated actions you take deliberately in the admin still work — the freeze holds back the automated MIS-driven flow.

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 the provisioning fetch pulling that school's MIS data 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). It's confirmation-gated and attributed in the logs, because turning it off is silent: nothing errors, changes just stop. If sync seems held, check both: is the school past its final provision date (the freeze), and is the MIS sync switch on? 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 can be invited automatically where enabled.

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 dashboard and Recent runs views read. 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.
• "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: past the final provision date the school is frozen until the new-year dates are set.
• "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.