OneRoster (preview)
Available from 0.20.0 as a preview. Automated tests use synthetic provider responses, including 100,000 users. The connector has not been validated against a live school SIS or certified by 1EdTech. Complete a school-provider pilot before relying on scheduled synchronisation.
| Category | Student information system (SIS) |
| Capability | sis.getRoster only |
| Authentication | OAuth 2 client credentials with HTTP Basic client authentication |
| API versions | OneRoster 1.1 and 1.2 REST bindings |
| Access | Read-only student and staff people records |
| Endpoints | Public HTTPS roster and OAuth token services |
This connector does not provision accounts, write to the SIS, or import classes, enrolments, grades or family relationships. A person’s SIS role does not grant a Plugboard technician account or administrator permissions.
Before connecting
Section titled “Before connecting”Ask the SIS administrator or provider for a dedicated OAuth client and restrict its feed to the intended school or campus. Plugboard does not infer campus assignment from OneRoster organisations. Configure the connector instance’s campus coverage deliberately, using separate scoped feeds where needed.
Request only the scope for the chosen API version:
| Version | Read-only scope |
|---|---|
| 1.2 | https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.readonly |
| 1.1 | https://purl.imsglobal.org/spec/or/v1p1/scope/roster-core.readonly |
Providers requiring OAuth 1.0a, custom scopes, client credentials in a JSON body, private-network endpoints or custom role extensions need a reviewed adapter change. Selecting OneRoster does not make those variants compatible.
Configure the instance
Section titled “Configure the instance”Open Admin, Connectors, add OneRoster, and enter the provider’s values. See configuring connector instances.
| Setting | Value |
|---|---|
baseUrl |
Full HTTPS roster service URL, without /users; a typical 1.2 path ends in /ims/oneroster/rostering/v1p2, and a typical 1.1 path ends in /ims/oneroster/v1p1 |
tokenUrl |
HTTPS OAuth token endpoint supplied by the provider |
version |
1.2 by default, or 1.1 to match the provider |
clientId |
The dedicated client’s ID |
maxRecords |
Maximum provider users per pull, including excluded family roles; default 250000, configurable from 1000 to 1000000 |
clientSecret |
Put the secret in the dedicated secret field, which the platform seals |
Use the provider’s actual URLs. Endpoint URLs cannot contain credentials, query parameters or fragments. Do not put a secret in ordinary configuration.
Save and test. The connection test exchanges the credentials for a token and reads one user page. It confirms reachability and response compatibility, not that the complete school’s roster has been returned.
Mapping and lifecycle
Section titled “Mapping and lifecycle”| Source | Plugboard |
|---|---|
sourcedId |
Source identifier |
givenName, familyName |
First and last name |
username, email |
Username and email, when supplied |
Current student role |
Student person |
| Recognised school staff role | Staff person |
| Deleted status, disabled user or no current school role | Inactive person |
Version 1.1 uses role; version 1.2 uses roles and optional role dates. Dates
use the current UTC date, with the end date excluded. A current student role
takes precedence when a person is both student and staff.
Family-only parent, guardian and relative records are discarded. Passwords, phone numbers, relatives, agents, demographics, pronouns, grades and class memberships are not returned to the roster-sync pipeline. The connector does not request demographics or assessment endpoints.
Existing source ownership, manual-field protection and departure safeguards continue to apply. An incomplete pull does not start applying people changes.
First school pilot and large rosters
Section titled “First school pilot and large rosters”- Compare an independently exported SIS student/staff count with the first complete sync. Provider totals may also include family-only users excluded by Plugboard.
- Inspect inactive users, people with multiple roles, role dates and campus assignment before enabling scheduled updates.
- Prefer a stable export window. OneRoster supplies no snapshot token; a provider changing during pagination can omit a record without detection if it repeats no ID and reports no changed total.
The connector requests up to 1,000 users per page, sorted by source ID, and
continues until an empty page. A smaller provider page size is supported.
Malformed users, duplicate IDs, unsupported roles, failed pages, inconsistent
reported totals or exceeding maxRecords refuse the complete pull. Reaching
the exact ceiling triggers one final request to check for further records.
Tokens are confined to the current operation, so another tenant, connector instance or credential rotation cannot reuse them. Token expiry during a pull fails that pull without applying earlier pages. Cross-origin redirects do not carry credentials to another service.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause and next step |
|---|---|
| Token request fails | Check client ID, secret, token URL, selected version’s scope and HTTP Basic client authentication with the provider |
| Test passes but full sync fails | The test reads only one page; inspect later-page errors, duplicate IDs, role extensions, changing totals or token expiry |
| Unknown role or malformed user | Ask the provider to correct its response or request an adapter review; the incomplete population is deliberately refused |
| Record limit reached | Compare the provider population, including family-only records, with maxRecords; do not reduce the feed blindly |
| People are assigned to the wrong campus | Correct the provider feed and connector instance coverage; organisation fields do not automatically map campuses |
| Parents are missing | Family-only roles and family relationships are outside this connector’s scope |
See people and roster synchronisation and the generated connector reference.