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
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.
| 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.
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.
| 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 |
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 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 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 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 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. |
| 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 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. |
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.
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:
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.
