ST Math Roster Provisioning (OneRoster)

Rostering is a service for transferring school information in a secure manner from a school’s database to the ST Math application. This document explains how to set up the files to transfer school information to ST Math using the OneRoster process.

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.

The OneRoster specification from IMS Global Learning Consortium can be found here: https://www.imsglobal.org/oneroster-v11-final-csv-tables#_Toc480293252

Rostering Requirements:

• Name and contact information for District Database Administrator(s) responsible for preparing and uploading roster files. If the district DBA changes, inform MIND.
• Student Information System (SIS) managed by district DBA with ability to export and format required information for roster file uploads. Export may need to be pared down to reflect licensing purchased.
• District DBA will maintain ongoing roster uploads to reflect current information in the SIS.
• District DBA must have the ability to automate SIS extracts and roster file uploads to the sftp site. At a minimum, new files must be submitted when there are SIS changes. Files should be uploaded as frequently as possible but no more often than once daily.

• Roster files must contain all active student data.  Any data removed from the roster files will also be removed in ST Math.

• Roster files must be uploaded to the “Home” folder on the sftp site and maintain required file names.
• All required fields must be included in all roster file uploads as stated in the roster provisioning instructions.
• Any errors reported in the automated roster file notification emails must be addressed and corrected by the district DBA.

Download the templates here: oneroster.zip

General SFTP Setup

The Rostering SFTP Server is located at:

https://sftp.stmath.com

Need help connecting?

https://hostedftp.com/help/

Username and password for the SFTP Server are unique to each account. You can retrieve your credentials from your ST Math account representative or by going to the login screen above and click on Forgot your password? Click here.

Once logged in, click on "Setup" to change your password and add a recovery email address.

Files should be uploaded to your account’s home directory (username/home) as frequently as possible but no more often than daily. Rostering processes files nightly and will append a date to the file name once the file is processed. These files will only be kept for 30 days on the Rostering SFTP server.

Roster Files

Details of the file formats are provided in the following section.

• 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.
• user.csv file should only contain one row for each user.
• Ingestion of historical or archived data is not supported.

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;
• 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 NOT case sensitive. Example, nan2381 is 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.

The required files are listed below:

Uploads MUST contain all the below files, with the following filenames:

Note: filenames ARE case sensitive

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

The above files must be zipped into a zip file named OneRoster.zip (this is case sensitive) and uploaded to username/home folder on the sftp server.

Grade Mapping