Rostering Configuration Best Practices
When configuring rostering for your OneRoster integration, you should support both rostering service configurations and observe best practice guidelines.
Following best practice guidelines for your integration ensures correct rostering data transfers and removes enrollment correction guesswork.
Note: Instructure is a OneRoster Consumer. For OneRoster Consumer and Provider definitions, view the Introduction to OneRoster.
AcademicSessions/Terms
If your SIS uses a common term ID to group terms, include the common term ID in the API response. The common term ID can be used to identify terms if they need to be merged in Canvas.
Learn more about OneRoster academic session specifications.
| Example |
|---|
{ "title": "A 707 07/08", "sourcedId": "{hash}-{schoolId}-{termIdentifer}", ... } |
Available Dataset
Set your OneRoster data extraction endpoints for the current school year, including all historical and future data within the school year as defined by your system. Additionally, include all data objects in the data extract with necessary end dates to avoid undesired deletion of data in the target systems.
Learn more about OneRoster rostering endpoints and rostering endpoint compliance.
Duplicated Enrollment Records
If a user has multiple enrollment records for the same class, provide only the current enrollment record.
For example, if Student A in Class 123, is enrolled in the class, removed, and then re-enrolled, provide the most appropriate enrollment status at the time the API call is made instead of Student A’s multiple enrollment records.
Enrollment Start and End Dates
Every enrollment record must include both a startDate and endDate, even if those dates are the same as the term dates. By comparing enrollment and term dates, Canvas can maintain correct enrollment statuses.
getAllUsers/users
If your institution supports the use of the Canvas observer role (for parents, guardians, etc.), it is recommended that you include these user profiles in your implementation configuration.
Incremental Data Syncs
Instead of using full data pulls, you can configure incremental data syncs using a dateLastModified query filter.
Note: To reliably implement incremental data syncs, you must include the deleted status or end date for every enrollment record. Without this information, enrollment drops can only be calculated by diffing a new full data sync against a full data sync.
