OneRoster General Information & Readme

Start here if you're starting off on integrating with us via the OneRoster specification.

OneRoster Package

Official Reference

https://www.imsglobal.org/oneroster-v11-final-csv-tables

  1. As per the spec, all one-roster files must be zipped in a single file, and the CSV files must be in the root of the zip file. This zip file is the final piece you will need to push in your FTP slot.
  2. For your very first attempt to send us a file, we would like to validate your files before you send it to your FTP slot. You will be provided with a Google Drive location to place files for manual inspection. We will perform some visual and system validation in advance to identify some common problems that may exist within your file. Once we find the files are following the specifications, then you will be able to send the files directly to your FTP slot.
  3. Some cells like role, gender, etc. are enumerations and accept only the listed values. The enumerations for each type can be found here: https://www.imsglobal.org/oneroster-v11-final-specification#_Toc480452020
  4. All files have a sourcedId column. The sourcedId must be a unique id that will never change. At the moment you need to send us a second version of the one-roster zip file, make sure you are using the same sourcedId values as before. Failing to send the same value may result in removal or inactivation of the record on our system. For example, if you change the student’s sourcedId in your second push, that student will be disabled in our system and a new one will be created, resulting in data duplication.
  5. DateTime fields should be sent in ISO format, see Date and Time Formats (w3.org)
  6. All columns spec'd in one-roster documentation must be included in your CSV files. If the column is optional, it means that all cells can be blank, but the column itself must be present. Failing to send a spec’d column will result in validation errors. However, if the file itself is optional, then you can simply not send it and mark it as “absent” in the manifest file.
  7. As per the OneRoster spec, if a file has a relation to another file, the corresponding value must be present. For example, if a student in users.csv has the cell “orgSourcedIds” filled in with “1234”, the orgs.csv file must have an organization with sourcedId filled in with “1234”. This will be validated while processing your files.
  8. The CSV files must follow regular CSV specs: https://tools.ietf.org/html/rfc4180.
    1. Make sure all rows in each file have the same number of columns. Wrong amounts of columns in a row might shift column data, sending valid data to the incorrect spots.
    2. The separator for data inside of a field cell must be a semicolon ‘;’.
    3. It is important to follow the escaping rules in the CSV specification, in case you have any data with special characters like newlines, commas, and quotes. If a cell is not properly formatted and escaped, it might be considered invalid, or shift column cells depending on the content.
  9. Our system processes your files in a sequential fashion. That means we are not validating the entire zip file at once. This is to avoid false errors due to incorrect dependent files.
  10. Ensure that all file names are correct and the matching record in the manifest.csv file is correct regarding if the file is absent, bulk or delta. In most of the cases files will be absent or bulk. You can send delta files, but this is a more complex scenario. Note: file names are all pluralized and case sensitive.

    Each CSV file is linked to its detailed specifications.
    1. academicSessions.csv
    2. categories.csv
    3. classes.csv
    4. classResources.csv
    5. courseResources.csv
    6. courses.csv
    7. demographics.csv
    8. enrollments.csv
    9. lineItems.csv
    10. manifest.csv
    11. orgs.csv
    12. resources.csv
    13. results.csv
    14. users.csv

Example File Packages

Periodicity & Location to Send Files

Once you are ready to send files to production, you will be provided a FTP location with a random username and password generated by the Permission Click system. The FTP location is secure with either port 21 TLS explicit or port 2222 SSH.

It is expected that your IT team will send up-to-date files once a day during working hours, to be validated and then synchronized to our databases overnight.

How to Send Student Data

Basic Integration

  1. The minimum files needed for a basic integration are manifest.csv, orgs.csv, and users.csv. Only students and corresponding parents/guardians are needed (example files for basic integration - ZIP archive, 336 KB).
  2. As a suggestion, the sourcedId field for the “student” role can be your SIS student number given that the value is unique for each student and won’t change over time.
  3. Guardians, parents, and students (at a minimum) all go into the users.csv file.
    1. To correlate students and guardians, a student row must have the parent sourcedId listed in the cell agentSourcedIds.
    2. Students with no guardian/parent listed can’t be added to a form.
    3. It is important to fill the “role” column according to the spec.
    4. Only active students and guardians will be imported, so make sure the “enabledUser” column is set accordingly.
    5. If a guardian/parent has a blank email address, their student can be rostered to a form, but a message won’t be sent until the email is corrected.
    6. If a student has multiple guardians/parents associated with, this is how we choose the record when rostering a student to a form:
      1. Latest imported parent with valid email or latest imported parent with blank email; if none, then
      2. Latest imported guardian with valid email or latest imported guardian with blank email; if none, then
      3. Latest imported relative with valid email or latest imported relative with blank email; if none then
      4. Latest imported proctor

Sending Data to Show in Form Questions

To include data that will be shown or updatable in a form by a guardian in Permission Click, you will need to include the metadata fields available in OneRoster spec.

  1. For each piece of information, a metadata column must be added to the users.csv file for the student.
  2. Blank cells must be inserted for other types of users (guardians, parents, etc.).
  3. The column name must be “metadata.[yourcolumnname]” in the header row.
    1. Remove all special characters and spaces from the column name.
  4. Ensure the column name is descriptive enough that your admins and teachers will understand what the field is when using them on their forms.
  5. When our system runs over your file, little to no validation is made on your data, so make sure your data is sanitized and good to be shown on a form. For example: If you send “NULL” as a text instead of a blank cell when you have no information, “NULL” will be shown on your form.
  6. DateTime fields should be sent in ISO format, see Date and Time Formats (w3.org)
  7. Make sure you include as a “metadata” column all the data you want in a form. In addition to metadata fields, Phone, SMS, Grade, and Email can also be added to a form. Currently demographics.csv file data is not supported.