Managing Users with OneRoster® v1.1

Wriddle account administrators can create and update students, teachers, classes, and schools by uploading a ZIP file that contains comma-separated value (CSV) files that meet the OneRoster v1.1 specification. This ZIP file can be uploaded on wriddle.com through a web browser, or by using a secure FTP (SFTP) utility to upload the file to the Wriddle servers.

You can find the OneRoster specification on the IMS Global web site: OneRoster v1.1 Specification

CSV Overview

The first step in creating the necessary files for the Wriddle OneRoster files is determining the necessary data.

Wriddle requires a minimum of 7 files to provide all of the data that is needed to create teacher and student accounts, schools and classes.

The required files are:

Filename Description
manifest.csv Contains the list of files provided.
academicSessions.csv Contains the different time periods that are referenced in other files.
orgs.csv Contains the “organizations” that are referenced in other files. Generally, there will be a “District” organization and an organization for each school within the district.
courses.csv Contains the course offerings. These are sometimes referred to as “class templates” and are not assigned to teachers or students.
classes.csv Contains the classes that are being taught. These are sometimes referred to as “sections” and are assigned to teachers and students. They MUST be associated with a course and an org.
users.csv Contains all the users in the system. There will generally be one row for every student, teacher and administrator. The “username” column should match the user’s login credentials (for example, their Active Directory username or Google username).
enrollments.csv Contains the association between users and the classes they teach or take. Each row needs a unique identifier (sourcedId) and it is generally advised that the classSourcedId and the userSourcedId be combined to create a unique combination.
All filenames and field headers MUST be identical to those listed in the specs. All columns in the templates are required. The files must be at the root level of the zip archive, they MUST NOT be contained within an enclosing directory.

manifest.csv

The manifest file tells Wriddle what files are included with this set of data. The Wriddle OneRoster sync only processes bulk imports and requires that entire sets of data be provided. This means that an import MUST include all the rostering files and each file must contain all of the data.

Example:

Column 1 Column 2
propertyName value
source.systemName Manual
source.systemCode School District
manifest.version 1
oneroster.version 1.1
file.academicSessions bulk
file.orgs bulk
file.courses bulk
file.classes bulk
file.users bulk
file.enrollments bulk
file.demographics absent
file.resources absent
file.courseResources absent
file.classResources absent
file.categories absent
file.lineItems absent
file.results absent

academicSessions.csv

Academic Sessions represent time segments of your school year (i.e. semester, term, marking period). Generally, this file starts with a school year that is divided into terms. Although the IMS specification does allow for other units like semester, a term is what classes are assigned to, so it is the basic unit. You can, however, make a “term” and call it “Semester 2” if that is the appropriate word in your situation.

Column Field Header Required Description
sourcedId Yes SourcedId of this academicSession.
status No Must be blank
dateLastModified No Must be blank
title No Name or title of the academic session.
type No Options: “SchoolYear”, "semester", “Term”, “gradingPeriod” SchoolYear – to link all the terms together
Term – what you attach classes to
startDate Yes Inclusive start date for the academic session. Format: YYYY-MM-DD
endDate Yes Exclusive end date for the academic session. Format: YYYY-MM-DD
parentSourcedId No SourcedId of the parent of this academic session.
schoolYear No The school year for which the academic session contributes. This year should be that in which the school year ends. (Format is: YYYY). For the 2017-2018 SY use 2018

orgs.csv

Orgs represent the organizational structure of the school district. In general, this file will have one row to represent the district and one row to represent each school. Schools will reference the district’s sourcedId in the “parentSourcedId” column.

Column Field Header Required Description
sourcedId Yes Unique id for the organization. SourcedId is used in other files and must be unique across all organizations.
status No Must be blank
dateLastModified No Must be blank
name Yes Name of the organization.
type Yes Options: “school”, “district”
identifier Recommended NCES ID (National Center for Education Statistics) for the school/district.
parentSourcedId Yes for schools SourcedId of an Org representing the Parent organization.
For the identifier column, use the NCES ID for the school district. Go to https://nces.ed.gov/ccd/schoolsearch/

courses.csv

Courses are the different offerings for the district. These are not the actual representation that gets attached to students and teachers, but the overarching course that will generally be taught by different teachers in different classrooms/periods. These are sometimes referred to as "course templates" or "class templates" depending on your SIS.

Column Field Header Required Description
sourcedId Yes Unique ID for the course.
status No Must be blank
dateLastModified No Must be blank
schoolYearSourcedId No SourcedId of an AcademicSession with type of "schoolYear".
title Yes Name of the course.
courseCode No Human readable course code.
grades No Grade(s) for which the class is attended.
orgSourcedId Yes Set to orgId of the district.
subjects No Subject name(s) in human readable form.
subjectCodes No Must be blank

classes.csv

Classes represent the actual instance that is taught by a teacher. Later on, a teacher and students will be assigned directly to this instance. In some SISs these are referred to as "sections".

Column Field Header Required Description
sourcedId Yes Unique ID for the class. SourcedId is used in other files and must be unique across all classes.
status No Must be blank
dateLastModified No Must be blank
title Yes Name of this class.
grades No We recommend you populate the grades in courses.csv and leave this field blank.
courseSourcedId Yes SourcedId of the course of which this class is an instance.
classCode No Human readable code used to help identify this class.
classType No Options: “homeroom” or “scheduled”
location No Human readable description of where the class is physically located.
schoolSourcedId Yes SourcedId of the Org that teaches this class of OrgType "school".
termSourcedIds Yes SourcedId of the terms (the academicSessions) in which the class is taught.
subjects No We recommend you populate the subjects in courses.csv and leave this field blank.
subjectCodes No Must be blank
periods No The time slots in the day that the class will be given. If more than one period is needed, use double quotes, and separate with commas (per RFC 4180). Examples: 1; "1,3,5”

users.csv

Users represent all the different people that the system needs to manage. This includes all the teachers and students from the SIS and sometimes specialty teachers and school administrators as well. It is most important that all staff, teachers, and students are reflected here and that their username matches the name they use to log into the system.

Column Field Header Required Description
sourcedId Yes Unique ID for the user. SourcedId is used in other files and must be unique across all users.
status No Must be blank
dateLastModified No Must be blank
enabledUser Yes Boolean: { "true" | "false" }. 'false' denotes that the user is an active record but system access is curtailed according to the local administration rules.
orgSourcedIds Yes SourcedIds of the Orgs to which this user belongs. (Note in most in cases, it is expected that users will belong to a single school).
role Yes Student, teacher, or administrator. Admins will be assigned administrator privilidges at their organization level (school or district).
username Yes AD or Google username.
userIds No Used when mapping existing data to new OneRoster data. External machine-readable ID (e.g. LDAP id, LTI id) for this user. The ID must be accompanied by a type to indicate the nature of the Identifier. The Type and ID values are enclosed in '{}' with a colon used to separate the values. If more than one userId is needed, use double quotes, and separate with commas.
givenName Yes User's first name.
familyName Yes User's surname.
middleName No User's middle name (s). If more than one then they are separated by a space.
identifier Recommended We recommend adding the student/teacher id.
email Recommended We recommend adding email addresses for teachers.
sms No SMS address for the User.
phone No Phone number for the User.
agentSourcedIds No SourcedIds of the Users to which this user has a relationship. If multiple IDs are required then use double quotes and separate with commas. Note: In most cases this will be for indicating parental relationships.
grades Yes For students, the current grade for which classes are attended.
password Yes – if needed Passwords are required if Wriddle will handle user authentication on log in. If using LTI, SAML, LDAP, or Google for authentication then a password is not required.

enrollments.csv

Enrollments connect users to classes. The file contains references to the sourcedId of the user and the class as well as the org in which the class is taught. Each row in the file needs a unique identifier and in cases where the SIS does not provide one, it is the best practice to combine the sourcedId of the user and the class.

Column Field Header Required Description
sourcedId Yes Unique identifier of this enrollment.
status No Must be blank
dateLastModified No Must be blank
classSourcedId Yes SourcedId of the Class.
schoolSourcedId Yes SourcedId of an Org with type 'school'.
userSourcedId Yes SourcedId of the User.
role Yes Possible roles: student, teacher, administrator
primary No Applicable only to teachers. Only one teacher should be designated as the primary teacher for a class in the period defined by the begin/end dates. Boolean: { "true" | "false" }.
beginDate No The start date for the enrollment. This date must align with the associated academic session (term) identified in the class.
endDate No The end date for the enrollment (exclusive). This date must align with the associated academic session (term) identified for the class.

Adding, Updating, and Deleting Users

Each CSV file is a complete list of data. Each time the CSV file set is submitted, it must contain all the information for the entire organization (schools, classes, teachers, and students).

Wriddle does not support OneRoster delta changes to data.

For example, if a user exists in one CSV file but does not exist in the next CSV file, that user will be marked for deletion, will not be able to log in to their Wriddle account, and will be purged from the system after 30 days.

Processing OneRoster files

Once all of the CSV files are created, they must be combined into one ZIP file to be uploaded to Wriddle. The files must be at the root level of the zip archive, they MUST NOT be contained within an enclosing directory.

There are two steps to adding data to Wriddle:

  1. Upload the ZIP file - This can be done with your browser or using a secure FTP (SFTP) client.
  2. Processing the file - If a file is uploaded through a browser, it can be processed manually when the upload is complete. If it is not processed manually, or if it is uploaded using SFTP, the file will be processed at 2:30am Pacific Time (PT).

Upload Files Using SFTP

A ZIP file can be submitted through SFTP using a secure FTP (SFTP) client (such as Filezilla) and the organization's username and password.

SFTP access is granted to the top-level of an organization. If using a district level account, then the district Wriddle administrator will have SFTP access.

ZIP files are processed at 2:30am Pacific Time. Be sure you upload the file by 2:00am.

The ZIP file can have any name. Do not create a folder (directory) for the file - files in subdirectories will not be processed.

Wixie processes the most recent file every night. If the file is processed successfully, all files in the SFTP account will be deleted. If the file processing does not complete successfully (for example, if it is missing a required CSV file), Wixie will not delete any files in the account.

For best results, use the same file name every time.

Over 20 years serving education.
Download at the Apple App Store