Synergetic
The student information system common in Australian independent schools. The source of truth for who exists.
Plugboard reads Synergetic through a REST bridge the school runs: a small web service, set up by the school or its integrator, that reads Synergetic and answers Plugboard’s own bridge contract (below). Plugboard does not call Synergetic’s own APIs.
| Category | Student information |
| Authentication | Bearer key for the bridge |
| Reaches | Your Synergetic REST bridge, usually on your network |
| Needs an agent | Yes, on managed hosting, when the bridge is on your network |
| Demo mode | Yes |
Capabilities
Section titled “Capabilities”sis.getRoster, sis.lookupStudent, sis.getTutorGroup, sis.termDates
Which lights up:
- People, with names, year levels, tutor groups and student numbers, and staff start and leaving dates, department, position, manager and preferred name when the bridge sends them.
- Card numbers for the card checker and the kiosk.
- The tutor on file, used by the “ready for collection (tutor)” email.
- Term dates, which cost analytics uses to group spending by term.
The bridge contract
Section titled “The bridge contract”The bridge answers five routes, each with the bearer key in the
Authorization header. They are Plugboard’s contract, not Synergetic’s.
| Route | Answers |
|---|---|
GET /api/ping | Anything successful. Used by the connection test |
GET /api/roster | The whole roster: an array of people |
GET /api/students/lookup?q= | One student, or null |
GET /api/students/tutor?q= | The student’s tutor group, tutor name and tutor email, or null |
GET /api/term-dates?year= | That year’s terms |
The roster
Section titled “The roster”Each person in the array needs externalId, firstName, lastName, type
(STUDENT or STAFF) and active, a true or false the bridge states
outright. Plugboard never guesses whether someone is active, so a bridge that
leaves active out has its roster refused until it sends it.
Optional fields: email, username, yearLevel (1 to 13), tutorGroup and
cardNumber, and for staff startDate, endDate (both YYYY-MM-DD),
department, position, managerExternalId and preferredName. Anything
else the bridge sends is dropped.
The whole roster is refused, and nothing is applied, when it is malformed,
repeats an externalId, holds more than 50,000 people or 16 MiB, or takes
longer than 30 seconds. A refused roster is not retried until the next sync.
These checks prove the answer is well formed, not that it is the whole school.
Before you rely on the sync to deactivate leavers, confirm with whoever runs
the bridge that it returns every current student and staff member, and what
its active means.
Lookups, tutors and terms
Section titled “Lookups, tutors and terms”- Student lookup returns one
STUDENTrecord ornull. Plugboard keeps it only when itsexternalIdorcardNumbermatches the query exactly, or its username matches ignoring case. - Tutor returns
nullor an object with any oftutorGroup,tutorNameandtutorEmail. A tutor email must be a valid address. - Term dates return an array of
{ year, term, startDate, endDate }: term 1 to 6, dates within that year, each term starting after the one before ends, at most 24 terms.
Lookups and tutors are limited to 1 MiB and ten seconds, term dates to 64 KiB and ten seconds. None is retried, and no request follows a redirect away from the bridge.
The private network question
Section titled “The private network question”The bridge usually runs on the school network, so the connector is marked as reaching a private network.
Self-hosted on that network: reaches it directly. Nothing extra.
Managed hosting: needs a connector agent installed inside your network.
Getting the credentials
Section titled “Getting the credentials”What you need from whoever runs the bridge:
- The bridge URL. The address in front of the routes above.
- The bridge’s bearer key.
Ask for read-only access behind the bridge. Plugboard never writes to Synergetic, and a write-capable credential is a risk with no upside here.
Configuring it in Plugboard
Section titled “Configuring it in Plugboard”Settings, Connectors, then Synergetic under Add a service, and Continue to setup.
Settings
Section titled “Settings”| Field | Value |
|---|---|
baseUrl | The bridge URL |
demoMode | Return a small fictional roster instead of calling the bridge |
Credentials
Section titled “Credentials”| Field | Value |
|---|---|
apiKey | The bridge’s bearer key |
Save disabled & test. The test calls /api/ping, which proves the bridge answers,
not that its roster is complete. In demo mode the test reports “Synergetic
(demo mode)” without calling anything.
The roster sync
Section titled “The roster sync”The roster is synced on a schedule rather than looked up on demand, so a busy service desk is not making a call per lookup. A school whose people already came from another student system or a CSV import matches them first, with Match people. See the first sync of a student system.
What a person record carries
Section titled “What a person record carries”| Field | Notes |
|---|---|
| External id | The bridge’s identifier, used to match on later syncs |
| First and last name | |
| Username | Used at the kiosk when card entry is not available |
| Type | Student or staff |
| Year level | Students |
| Tutor group | Drives the tutor notification email |
| Card number | Used by the card checker and the kiosk |
| Active | Leavers stop appearing |
| Staff details | Start and leaving dates, department, position, manager and preferred name, when sent |
Try it in demo mode first
Section titled “Try it in demo mode first”The demo roster is four fictional people, and it is enough to exercise the whole pipeline: people appear, the kiosk recognises a card, a repair can be lodged against a person.
Doing that before the real credentials arrive means you find configuration problems in the parts you control rather than in the integration.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause |
|---|---|
| Connection refused or a timeout | A managed deployment with no agent, or an agent that cannot reach the bridge |
401 | Wrong bearer key |
| “The Synergetic REST bridge returned an invalid roster” | A person is missing a required field or an explicit active, a field is out of bounds, or the roster is too large |
| “The Synergetic REST bridge repeated a person identifier” | Two people share an externalId |
| “The Synergetic REST bridge returned invalid term dates” | A term is missing a field, falls outside its year or overlaps the one before |
| Test passes, no people appear | The sync has not run yet, or it is waiting for Match people |
| Four fictional people appear | demoMode is still on |
| Leavers still showing | The bridge still sends them as active, or the sync has not run since |
| Card taps not recognised | The bridge does not send cardNumber |
Alternatives
Section titled “Alternatives”Sentral, Compass Education and Wonde implement the same roster capability and return the same person shape, so the rest of the product does not care which you run.