OneRoster files must be text files in CSV format, encoded in UTF-8. To generate these files, access your SIS data using its export tools, following your vendor’s instructions. Contact your SIS provider for guidance on extracting data into the OneRoster CSV format.
Brightspace supports the OneRoster v1.1 specification. Administrators can upload a OneRoster 1.1 compliant packages with the required roster data, such as schools, classes, users, and enrollments, and view the results in Brightspace.
OneRoster CSV supports the following files and processes them in the listed order:
- manifest.csv
- academicsessions.csv
- orgs.csv
- courses.csv
- classes.csv
- users.csv
- enrollments.csv
Using the OneRoster CSV files
The following sections provide a high-level description of the OneRoster CSV files. For more information, refer to OneRoster CSV data mappings.
Using the Manifest CSV file
You must include a Manifest file with each package. The manifest contains the version and the list of files that you are sending to Brightspace, and indicates if the roster data indicates if the package contains delta (only changes since the last update) or bulk (all files) content.
Using the AcademicSessions, Orgs, Courses, and Classes CSV files
The OneRoster CSV integration can create and update the org levels listed in the Understand the mapping of data types between OneRoster and Brightspace section of the Getting ready for OneRoster integration topic. You should manage any org levels that do not appear in the list outside the OneRoster integration.
Follow the naming conventions (Name/Code) defined in your SIS for Org Units. Brightspace accepts any number of Org Units, and you can include their names and codes in CSV files, provided they comply with Brightspace’s restrictions on illegal characters.
Send org levels at least once to specify which Org Units IPSIS can control. Resend Org Unit files only when you need to add or update them in the learning environment's org structure.
OneRoster CSV can:
- Create a new Org Unit if it does not exist
- Map to an existing Org Unit if it was created by a different source
- Update the name or code of an Org Unit that it controls
- Course Template: assign and update parent Schools based on the School code
- Course Offering: assign and update parent Schools based on the School code
- Course Offering: assign and update parent Course Template and Semester based on the parent code
- Course Offering: Update all course details including course offering name
- Update Org Unit codes
- Copy Course Content to New Course
- Delete an Org Unit if the delta file is sent with Status tobedeleted and the Org Unit has no enrollments
OneRoster CSV cannot do the following:
- Delete manually created Org Units unless they have been mapped with OneRoster CSV
- Delete an Org Unit if it has children linked to it (children must be deleted first)
Using the Users CSV file
Processing the user type creates, updates, or inactivates users in Brightspace. Send user data at least once to instruct IPSIS on which user profiles it can create, update, and manage enrollments for. Brightspace automatically enrolls users into the school.
OneRoster CSV can:
- Create a new user
- If a user exists with same OrgDefinedID or the same Username, then it can be mapped to an existing user
- Update First Name, Last Name, Password and Email
- Update the Org level role
- Activate or inactivate a user
- Update the Org Defined ID or Username
- Enroll or unenroll users from upper org units
OneRoster CSV does not :
Using the Enrollments CSV file
Processing the enrollment type enrolls or unenrolls users in Brightspace at the course section level. Send enrollments only when changes occur in your information system to keep Brightspace updated. Send an unenrollment only once, as resending it will generate warnings in the IPSIS log.
OneRoster CSV can:
- Enroll and unenroll users from course offerings and sections
OneRoster CSV cannot:
- Enroll users at other org levels (except using the user record as noted above)
Limitations and Assumptions
Unenrollments from upper org units
The term upper org unit refers to any org unit in the hierarchy above a course offering, such as the school where the course is offered. Users are typically enrolled in both the course offering and the corresponding school, which serves as the upper org unit.
- To enable unenrollments using the OneRoster integration, from the IPSIS Administration page and select Unenroll users from SIS Orgs if they're no longer associated with them in the SIS.
- The OneRoster integration cannot unenroll users from upper org units created before the June 2024/20.24.6 release or from enrollments created manually in Brightspace.
- Unenrolling a user with a cascading role from an upper org unit may remove their access to multiple child org units.
Unsupported Characters
The Org Unit Code comes from the following CSV fields:
- Academic Sessions: title
- Courses: title or courseCode
- Classes: title or classCode
- Orgs: name or identifier
The following characters are not currently supported for the Org Unit Code:
- \ (backward slash)
- : (colon)
- * (asterisk)
- ? (question mark)
- “ ” (opening and closing quotation marks)
- < > (less-than and greater-than signs)
- | (pipe)
- ‘ (apostrophe)
- # (hash / pound sign)
- , (comma)
- % (percent sign)
- & (ampersand)
All Org Unit Codes are truncated to a maximum length of 50 characters.
Processing CSV files
Zip CSV files before uploading them to Brightspace. You can upload the ZIP file:
- Manually: Drag and drop the file into the IPSIS Administration > Dashboard interface.
- Automatically: Upload the ZIP file to the SFTP site set up during your initial configuration. Brightspace checks the SFTP site every ten minutes.