Administrator

SIS Sync FAQs

  • Updated:
    info_outline
    Created:

Buzz supports the rostering of users, courses, enrollments, and observers through the IMS OneRoster specification. The sync makes rostering easy and automated.

What is OneRoster?

OneRoster is an IMS Global Learning Consortium specification for exchanging data between systems. Commonly, this exchange will happen between the student information system (SIS) and the learning management system (LMS). For these FAQs, Buzz learning platform is the LMS.

What version of OneRoster does Buzz support?

Buzz supports OneRoster 1.1.

What data exchange modes does Buzz support?

Buzz supports the CSV mode for Rostering Import Bulk.

What is the CSV mode?

The CSV mode is a collection of CSV files (packaged together as a OneRoster zip file). Once uploaded to Buzz, the CSV files are processed to create, update, and/or delete data from Buzz.

What CSV files are required in the OneRoster integration?
  • manifest.csv
  • academicSessions.csv
  • classes.csv
  • courses.csv
  • enrollments.csv
  • orgs.csv
  • users.csv
What header fields are required in the CSV files?

According to the OneRoster specification, every header field is required to be included in the CSV file. In addition, the header fields must be provided in the correct order and are case sensitive. Refer to CSV Format for more details.

Do all of the rows need to contain values for each header field?

No. However, you are expected to provide a value for each header field that is required according to the OneRoster specification. Refer to CSV Format for more details.

For example, in the academicSessions.csv you are required to include the header field (i.e., column) parentSourcedId, but you are not required to provide a value in the corresponding rows.

Example (displayed as a table for readability):

sourcedId title type startDate endDate parentSourcedId schoolYear
123456 Fall term 2020-09-01 2020-12-18   2021
234567 Winter term 2021-01-04 2021-03-26   2021
345678 Spring term 2021-03-29 2020-06-25   2021

 

How are the property values mapped between the OneRoster zip file and Buzz?
File Property Name Mapping
academicSessions.csv title Course term
startDate Course start date
endDate Course end date
schoolYear Base course title, Course term
classes.csv sourcedId Course external ID
title Course title
grades Course metadata
courseSourcedId Base course
classCode Course metadata
classType Course metadata
location Course metadata
schoolSourcedId Course domain
termSourceId First term listed is used to determine the course term, start date, and end date
subjects Course metadata
subjectCodes Course metadata
periods Course metadata
courses.csv title Base course title
courseCode Base course external ID
Base course title
enrollments.csv sourcedId Enrollment external ID
classSourcedId Enrollment course
schoolSourcedId Enrollment domain
userSourcedId Enrollment user
role Enrollment role
primary Enrollment metadata
The primary teacher is the one used to create teacher and term masters
orgs.csv sourcedId Domain external ID; only on domain creation
name Domain name; only on domain creation
type Domain metadata
identifier Domain metadata
parentSourcedId Domain parent; only on domain creation
users.csv sourcedId User external ID
enabledUser User metadata
orgSourcedIds First org listed is used to determine the user domain
role User metadata
Observer accounts
username User username
userIds User metadata
givenName User first name
familyName User last name
middleName User metadata
identifier User metadata
email User email
sms User metadata
phone User metadata
agentSourcedIds Observer accounts
grades User metadata
password User password; only on user creation
NOTE: If no password is provided for a new account, then the user’s password will have to be reset or the user will only be able to login through SSO.
How can I learn more about these CSV files?

Visit the IMS OneRoster: CSV Tables website.

Is there an example OneRoster zip file with the supported CSV files?

Yes, you can find an example OneRoster.zip file here. This zip file only includes the supported CSV files.

How does a user upload the OneRoster zip file to Buzz?

A Buzz Administrator can upload the OneRoster zip file through the Admin app or through FTPS.

What privileges does the administrator need to upload a OneRoster zip file to Buzz?

The Buzz Administrator uploading the OneRoster zip file must have the Administrator role (privileges value of -1) on the domain.

Does my SIS natively support exporting OneRoster CSV or zip files?

You can review the tools that have been certified to support OneRoster Rostering CSV Export Bulk. However, many other SIS support this functionality even though they are not certified. Reach out to your SIS administrator to learn if your SIS can export OneRoster files.

What actions does the OneRoster integration perform?

The OneRoster integration may create, update, and delete various entities shared with Buzz. Specifically, these entities include:

  • Users: Students, teachers, school and district admins
  • Courses: District, school, and teacher master courses; section courses
  • Enrollments: Student and teacher enrollments
  • Domains: Schools, districts, states, departments, etc.
  • Observers: Parents, guardians, and relatives
What data will be created in Buzz?

The OneRoster integration may create the user, courses, enrollments, domains, and observer associations for the data shared with Buzz via the OneRoster zip file.

What is a base course?

Buzz allows for multiple derivative courses to be managed (e.g., settings, content) from a base course. The derivative course receives updates from the base course as long as it was not explicitly changed in the derivative course. This workflow allows for efficient curriculum development and distribution while still allowing for teachers and schools to further enhance their course.

The OneRoster integration may create organization (e.g., state, district, school) base courses, a teacher base course, and academic session base course for every course that is taught. The classes (i.e., where student enrollments exist) will be created as derivative courses of the academic session base course, or the next available base course. This means that settings or content added to the state base course will be inherited by all organization base courses and subsequently the teacher/academic session base courses and the section courses.

In the example below, there is:

  • A state organization
  • Two school district organizations
  • Three school organizations
  • Three teachers
  • Two academic sessions per teacher
  • A total of ten section courses (or “classes”)

The higher in the hierarchy content or changes are made, the more derivative courses that would receive the change. For example, if a new assessment were to be added to the:

  • State organization base course, this assessment would appear in each distinct organization base course, school organization base course, teacher base course, academic session base course, and course section.
  • School base course, it would appear in each teacher base course, academic session base course, and section course.
  • Teacher base course, it would appear in each of that teacher’s academic session base courses section courses.
Base course example
Base course example. Click to view full size.

If the settings or content is supposed to be available to all students in the:

  • state, then it should be added to the state organization base course.
  • district, then it should be added to the district organization base course.
  • school, then it should be added to the school organization base course.
  • teacher’s courses for the current and future sections, then it should be added to the teacher base course.
  • teacher’s courses for a specific academic session, then it should be added to the teacher’s academic session base course.
  • specific section course, then it should be added to the section course.

See How do Base and Derivative Courses work?

Who is enrolled into the different types of courses?
  • Organization base course: Nobody. Buzz Administrators should manually enroll curriculum developers and other users, as necessary.
  • Teacher base course: The primary teacher of the particular course. Each teacher may get their own teacher base course for each unique course they teach.
  • Academic Session Base Course: The primary teacher of the particular course. Each teacher may get one or more Academic Session base course for each unique course they teach, and for each term that course is taught in.
  • Section course: The teacher(s) and students of the section course.
Will Buzz Administrator accounts be created automatically?

No, the OneRoster integration will not create Buzz Administrator accounts automatically.

Can I change information created by the OneRoster integration?

No. When you change some information that is managed by the integration, it will likely be reverted the next time the sync runs. For example, if you manually change a user’s first name in Buzz from “Bradley” to “Brad,” it will revert back to “Bradley” the next time the sync runs if the user’s first name is Bradley according to the OneRoster zip file.

Any changes should be managed in the organization’s SIS. Changes to these fields will automatically be reflected in Buzz upon the next sync.

How can I tell if the user, course, or enrollment is managed by the OneRoster integration?

If the user, course, enrollment, or domain has an external ID that is prefixed with “or-”, then it will be managed by the OneRoster integration. Buzz Administrators can review if the entity has an external ID by looking at the list of users, courses, enrollments, or domains in the Admin app.

Can I have users, courses, enrollments, and domains that are not managed by the OneRoster integration?

Yes. Administrators can create users, courses, and enrollments that are not managed by the OneRoster integration. If these are created, do not provide an external ID for the entity that has a prefix of “or-”. If you create one with an external ID that begins with “or-”, it will become managed by the OneRoster integration. If the user, course, or enrollment is not found in subsequently provided OneRoster zip files, it may be deleted.

However, if you manually create an entity and a comparable entity is also in the OneRoster zip file, there is a likelihood that you will have a duplicate entity. For example, a user created manually and by the OneRoster integration.

How often is the OneRoster integration sync run?

The OneRoster integration sync is run soon after a OneRoster zip file is sent to Buzz. It can be run as frequently as the organization desires. In general, we recommend not sending a OneRoster zip file to Buzz more frequently than every 12 hours.

Where in Buzz are users created?

Users are created in the domain that is associated with the first organization for the user in the user.csv file.

Where in Buzz are the courses created?

Organization base courses are created in the domain that is associated with the organization. Teacher base courses, academic session bases courses, and section courses are created in the domain associated with section courses (classes.csv).

If a teacher or admin creates a course outside of the OneRoster integration, will it be changed by the sync?

As long as the course external ID does not prefix with “or-”, it will not be modified by the OneRoster integration.

If a user, course, or enrollment is deleted from the SIS or no longer shared with Buzz via the OneRoster zip file, how will it impact Buzz?

If deleted from the SIS or no longer shared, by default, it will not be deleted from Buzz.

However, if the configuration option is set to delete any of these, then they will be deleted. If the exact same user or course is then reshared, Buzz will attempt to restore the user or course previously used. If the exact same enrollment is later reshared, Buzz will create a new enrollment.

How can I use an existing Buzz course as a OneRoster integration managed course?

There are times that you want to use an already existing Buzz course as a OneRoster integration managed course. For example, you created a course that you want to be used as a school organization base course. To do so:

  1. Identify the OneRoster integration managed school organization base course in Buzz.
  2. Update the manually created course to have the same external ID as the managed school organization master course.
  3. Delete the external ID from the undesired school organization base course.

The next time the sync runs, it will update all teacher base courses to point to the new school organization base course. Follow the same process for replacing any of the OneRoster integration managed courses with a manually created course.

What determines if base courses are created for a section course?

For a section course to have a base course, the section course (classes.csv) must have a course code with the associated course.csv in the OneRoster zip file.

What will happen to users, courses, and enrollments that exist in Buzz before the OneRoster integration?

Any user, course, enrollment, or domain that does not have a matching external ID will not be managed by the OneRoster integration.

What will happen to a user that is moved from one school to another in the OneRoster zip file?

If a user is moved from one school to another, whether due to a transfer or advancement, the OneRoster integration will move the user to the new school along with all of their past information. This will occur if the following conditions are met.

  • The user’s sourcedId did not change in the OneRoster zip file (users.csv).
  • The two school organizations exist in the same OneRoster zip file.
forum

Have a question or feedback? Let us know over in Discussions!