OneRoster Roster Provisioning

This document explains how to set up the files to transfer information to ST Math using OneRoster provisioning.  In order to roster provision in ST Math, a district employee with direct access to your SIS data and an understanding of the data schema is required.  

 

To use OneRoster, CSV files must be prepared in accordance with OneRoster specifications found here: https://www.imsglobal.org/oneroster-v11-final-csv-tables#_Toc480293247 

OneRoster Template:   oneroster.zip
 

District Database Administrators:

• Will maintain ongoing roster uploads to reflect current information in the SIS to provide access to students and teachers as changes are made.
   
• Address and correct any errors reported in the automated roster file notification email, resubmitting files as needed.
• Must have the ability to automate SIS extracts and roster file uploads to the sftp site. 
• Should email ST Math Support at support@mindreseach.org regarding any changes to contact information for the district’s DBA.

Uploads must contain all 7 CSV files below with the following filenames.   Filenames ARE case sensitive and files must be uploaded as a zip file named OneRoster.zip

1. manifest.csv
2. users.csv
3. courses.csv
4. classes.csv
5. enrollments.csv
6. orgs.csv
7. academicSessions.csv

For Field Specifications, please check the IMS Global site regarding required fields and the order those fields must be in.  All fields must be included in the files but optional fields can be empty with the exception of grade designations on the users.cvs file for students.

http://www.imsglobal.org/oneroster-v11-final-csv-tables#_Toc480293252

Uploads:

• At a minimum, new files must be uploaded when there are SIS changes. Automated daily uploads are recommended. 
• Roster files must be uploaded to the “Home” folder on the SFTP site and maintain required file names.
• ST Math processes files each night. Files should be uploaded by 9 pm local time for your district to reflect changes the next day.
• Once processed, files will be appended with a date to the file name and should not be removed from the folder.

Roster Files:

• Use the comma separated values format (CSV) for all uploads to the Rostering SFTP server.
• CSV files should contain field values separated by commas, with line breaks between rows. Double quotes around fields are optional, except when the field value includes a comma, where they are required.
• CSV files should contain only active student data. For example, the users.csv file should contain only current staff and currently enrolled students.
• The users.csv file should only contain one row for each user.  You should put all the schools (org ids) that the teacher works with on the teacher's row in the users.csv file, separated by commas.
• Ingestion of historical or archived data is not supported.
• If provided, passwords must comply with your district's security policy. They must be unique, at least 6 characters long, and different from the username.

Please use the following specifications for all CSV files:

• CSV files must be prepared in accordance with OneRoster specifications found here: https://www.imsglobal.org/oneroster-v11-final-csv-tables#_Toc480293247 
• Only “BULK” processing CSV files are accepted and processed.
• CSV file names must match specification, including .csv suffix.
• The CSV files will be exchanged as a zip file. The encompassed files must be at the root level. i.e., they MUST NOT be contained within an enclosing directory. The zip file for the submission files MUST be named OneRoster.zip and it must have a file extension of 'zip'. The compression must conform to RFC 1951 [RFC1951].
• A header row is required. Headers must match the header names in the specification exactly. The Header fields for a file must be supplied in the same order as defined in the tables as described in specification. If metadata extension fields are used, then they must be added to the right of the defined data fields in the specification, as the last set of columns. This ensures that the sequence of the defined data fields remains fixed irrespective of the presence or not of metadata fields.
• Files that contain no data rows are NOT permitted and will stop rostering from processing any records.
• The support of ALL string-based data-types requires that a maximum length of at least 255 must be supported by implementations. If string lengths of greater than 255 are used then system may lose some part of the string without failing conformance.
• In BULK processing, the CSV files MUST NOT contain values in the "dateLastModified" and "status" fields. That is to say, for each row, there will be no data for either of these fields. Importing Systems MUST view this incoming data as the reference version of all data. That is to say, if records that were previously imported do not appear in this bulk CSV file, then the importing system should internally mark those records as 'Tobedeleted" with the "dateLastModified" value set to the time of the bulk files import processing. If said records subsequently appear in a future bulk file, then those records should be updated and made active. When a set of Bulk files are created they must be semantically complete i.e. every object referenced by another object MUST also be defined in the corresponding source CSV file and included with the manifest.csv file.
• Some fields are required - if they are not present, the row will not be processed.
• For fields that are required, the required column indicates this with the value: “Yes”.  Take care to ensure that all links (keys) connect to an ID existing in the upload.
• Some fields are optional - they may be left blank.
• All files must be present for upload to be processed. For example, a directory with only users.csv will not be processed.
• ID/value values ARE case sensitive. Example, nan2381 is NOT the same as NaN2381.
• The file format for each of the data files is a Comma Separated Values (CSV) format as specified in RFC 4180 with the extra restriction that carriage-returns are not permitted within a field. Fields containing commas and double-quotes must be enclosed in double-quotes. If double-quotes are used to enclose a field, then a double-quote appearing inside the field must be escaped by preceding it with another double-quote. https://tools.ietf.org/html/rfc4180.
• The CSV files must be UTF-8 encoded [RFC3629]. Importing processors must tolerate BOM (Byte Order Mark) prefixes and ignore them. In a UTF-8 encoded file with a BOM, the BOM will appear as the 3-byte sequence 'EF BB BF' at the beginning of the file. If present, the CSV header will begin at the 4th byte of the file; if not present, the CSV header will begin at the 1st byte of the file. http://en.wikipedia.org/wiki/UTF-8.

Related Articles and External Links:

• Setting Up and Accessing Your SFTP Account
• Rostering SFTP Server: https://sftp.stmath.com/ 
• SFTP General Help and Information: https://hostedftp.com/help/