Rostering for multiple schools via SFTP (automated CSV rostering using oneRoster)

I. Overview

Literably rosters are to be uploaded as a series of CSV files via SFTP. These CSV files can be generated as an export from your student information system. Your school or district will be rerostered based on the most recent CSV files uploaded. We encourage you to upload these files in an automated fashion (such as via a nightly script) if possible, but you may also upload them via an SFTP client such as WinSCP or Cyberduck.

II. Upload process

The Literably SFTP server address is: sftp://sftp.literably.com (Port 22). The username and password should have been provided to whomever was identified as a rosterer for your school or district. Typically, the rosterer(s) are members of the school or district technology staff. If you are a rosterer, the SFTP credentials can also be found by logging in to Literably, clicking on your username in the top right, and clicking Rostering. Upload the files to the /home/username directory.

There are several types of common errors that can prevent roster files from working properly— for example, typos in the names of the field names. Once you have uploaded your first batch of files, we encourage you to click the Validate button in the Rostering dialog box. This will provide you with immediate feedback on some of the most common issues in drafting these CSV files.

When any single instance of rostering is complete, Literably will send an automated email to your Literably subscription’s rosterers with the results of the process. This email will indicate whether the upload failed, partially succeeded due to certain rows not being processed, or completely succeeded. It will also indicate, for each CSV file, the counts of rows that were successfully processed, successfully processed with problems, and unable to be processed.

III. CSV Filenames and Formatting

oneRoster is an industry-standard rostering scheme used by schools to format roster data for educational applications. Literably roster uploads are based on the oneRoster v1.1 specification, available at https://www.imsglobal.org/oneroster-v11-final-csv-tables. There are 14 CSV files in oneRoster, but only five that are required by Literably (links to blank CSV shells in parentheses):

• orgs.csv (https://s3.amazonaws.com/literably-assets/blank-rosters-oneroster/orgs.csv)
• users.csv (https://s3.amazonaws.com/literably-assets/blank-rosters-oneroster/users.csv)
• classes.csv (https://s3.amazonaws.com/literably-assets/blank-rostersoneroster/classes.csv)
• courses.csv (https://s3.amazonaws.com/literably-assets/blank-rostersoneroster/courses.csv)
• enrollments.csv (https://s3.amazonaws.com/literably-assets/blank-rosters-oneroster/ enrollments.csv)

Each file must be complete (i.e. “bulk” processing). If incomplete file(s) are uploaded, Literably will infer that users not found in these files have left the school or district. Uploading an incomplete file will disrupt users’ access to Literably.

These files should be in standard CSV (not Excel) format with UTF-8 encoding and commas as delimiters. They should have exactly these filenames. Quoting is required where there are commas in a field’s text, but is otherwise optional. The first row should be a header row with field names.

You may upload the files in a single ZIP file (as described in the oneRoster specification) or simply to the SFTP folder.

Fields shaded yellow are not part of the official oneRoster specification, but are requested.

IV. CSV File Specification

orgs.csv:

field header	required	format	description
sourcedId	Yes	string	unique id for the organization. SourcedId is used in other files and must be unique across all organizations. (For example –schools in your district).
status	No	String	Leave blank
dateLastModified	No	Date	Leave Blank
name	Yes	String	name of the organization
type	Yes	String	“school” | “local” | “state” | “national”
identifier	No	String	NCES ID National Center for Education Statistics) for the school / district
metadata.classification	No	String	“charter” | “private” | “public”
metadata.gender	No	String	“female” | “male” | “mixed”
metadata.boarding	No	Boolean	True if school is boarding school
parentSourcedId	No	String	SourcedId of the Parent organization

 

users.csv:

field header	required	format	description
sourcedId	Yes	String	Unique ID for the user. SourcedId is used in other files and must be unique across all users
status	No	String	Leave blank
dateLastModified	No	Date	Leave blank
orgSourcedIds	Yes	String	SourcedIds of the Organizations to which this user belongs. If multiple Ids are required then use double quotes and separate with commas. (Note in most in cases, it is expected that users will belong to a single school).
role	Yes	String	“teacher”, “student”, “parent”, “guardian”, “relative”, “aide”, “administrator”
username	No	String	Used for students but ignored for teachers; need to be unique
password	Yes (for non-students)	String
grades	Yes (for students)	String	Grade of student. Should be in {KG, 01, 02, 03…}
metadata.literably.ELL	No	Boolean	True if student is classified as an English language learner; False otherwise
metadata.literably.homeLanguage	No	String	Student’s home language code. Literably is designed to accept California state home language codes. (Haitian Creole is not included in this list, but is recognized by Literably. If a student's home language is Haitian Creole, enter "Haitian Creole.")
metadata.literably.initialLevel	No	String	Student’s initial reading level, in DRA, F&P, PM Benchmarks, or STEP levels (format auto-detected). Must use the same format for all students.
metadata.literably.levelImputed	No	Boolean	If True, the student’s initial reading level will be treated as a “guess” and she will be permitted to float below her initially specified level.
userId	No	String	Used to identify users for single sign-on
givenName	Yes	String	User's first name
familyName	Yes	String	User's surname
identifier	No	String	Not currently used
email	Yes (for non-students)	String	Email address for the user

 

courses.csv:

field header	required	format	description
sourcedId	Yes	String	Unique ID for the course. SourcedId is used in other files and must be unique across all courses.
status	No	String	Leave Blank
dateLastModified	No	Date	Leave Blank
schoolYearId	No	String	Not currently used
metadata.duration	No	String	Description of how long the course runs for (e.g. two weeks, one semester)
title	Yes	String	Name of the course
courseCode	No	String	Human readable course code
grade	No	String	Grade (i.e., 9 or range 9-12)
orgSourcedId	No	String	SourcedId of the org to which this course belongs. This may be a district level org Id.
subjects	No	String	Subject name(s). If more than one subject is needed, use double quotes, and separate with commas (per RFC 4180): Examples: “chemistry, physics” physics “music, drama, poetry”

 

classes.csv:

field header	required	format	description
sourcedId	Yes	String	Unique ID for the class. SourcedId is used in other files and must be unique across all classes.
status	No	String	Leave blank
dateLastModified	No	Date	Leave blank
title	Yes	String	Name of this class
grade	No	String	Grade (i.e., 9 or range 9-12)
courseSourcedId	No	String	SourcedId of the course of which this class is an instance
classCode	No	String	Human readable code used to help identify this class
classType	Yes	String	“homeroom”, “scheduled”
location	No	String	Human readable description of where the class is physically located
schoolSourcedId	Yes	String	SourcedId of the organization which teaches this class
termSourcedId	No	String	SourcedId of the academicSessions(s) in which the class is taught. If more than one term is needed, use double quotes and delimit with commas, (per RFC 4180) Examples: “1,2” 1 “1,4,8” Not currently used
subjects	No	String	Subject name(s). If more than one subject is needed, use double quotes, and delimit with commas (per RFC 4180): Examples: “chemistry, physics” physics “music, drama, poetry”

 

enrollments.csv:

field header	required	format	description
sourcedId	Yes	String	Id of this enrollment
classSourcedId	Yes	String	Id of the class
schoolSourcedId	Yes	String	Id of the school
userSourcedId	Yes	String	Id of the user (teacher or student)
role	Yes	String	“student” | “teacher” | “parent” | “guardian” | “relative” | “aide”, “administrator”
status	No	String	Leave blank
dateLastModified	No	Date	Leave blank
primary	No	Boolean	MUST only be set to true for ONE teacher for a class.

Here are some additional notes to be aware of:

• Usernames are case-insensitive.
• If your SIS requires separate extracts for different roles, you may include up to three users CSV files and we will automatically concatenate them. Use the filenames users.csv, users2.csv, and users3.csv. You may also include up to two enrollments files, as enrollments.csv and enrollments2.csv.
• Files with duplicate usernames or student IDs will be rejected. Rows missing required fields will not be processed.
• To classify a user as a school administrator, set her role to “administrator” and make sure that the organization IDs of the school(s) in orgs.csv she needs access to appear in her orgSourcedIds field. To classify a user as a district administrator, set her role as "administrator” and make sure that her district ID is listed in both her orgSourcedIds and as a “local” organization in orgs.csv.
• If a teacher account doesn’t exist with a given ID, but does exist with that email, the existing teacher account will be matched with the teacher account in the roster file and enriched with the information in the roster file.
• Teacher and student credentials will be rewritten whenever these roster files are uploaded, even if these accounts already exist. The only exception is that we will not rewrite a teacher’s password (since sometimes teachers change them deliberately.)
• Students and teachers enrolled in a class must be associated with the school hosting that class, which must match the school listed in the enrollments file for the class.

V. FAQs

If a student switches classes, do their Literably assessment records move with them?

• All assessment data is stored/anchored to the student's sourcedId on the users.csv.  As long as this sourcedId does not change, the student's assessment data will be preserved if they move classes, schools, etc.

How can I make sure students' assessment records are preserved if we are switching to OneRoster from a different rostering system?

• If transitioning from manual CSV uploads: If you want your students' Literably assessment data to be preserved when you transition to OneRoster rostering, it is required that each user's (students, teachers, admins) sourcedid from your district's OneRoster files (located on your district's users.csv(s)) is identical to their "Student ID" and "Teacher ID" found on your most recent Literably CSV files.
• If transitioning from Clever: if you want your students' Literably assessment data to be preserved when you transition to OneRoster rostering, it is required that each user's (students, teachers, admins) sourcedid from your district's OneRoster files (located on your district's users.csv(s)) is the same as the SIS_ID that was associated with the user on Clever.

Other questions? Email us anytime at [e-mail].