OneRoster general information and readme

Begin here if you are starting to integrate with us using the OneRoster specification.

OneRoster package official reference

OneRoster CSV tables

1. According to the specifications, all one-roster files must be compressed into a single ZIP file. The CSV files should be located in the root directory of this ZIP file. This ZIP file is the final component you will need to upload to your FTP slot.

2. For your first attempt to send us a file, we want to validate your files before you upload them to your FTP slot. You will receive a Google Drive link where you can place your files for manual inspection. We will conduct visual and system checks in advance to spot common issues that might be in your file. Once we confirm the files meet the specifications, you will be able to send the files directly to your FTP slot.

3. Some cells like role, gender and so on are enumerations and accept only the listed values. Refer to Enumerated Vocabularies for more information.

4. All files must include a “sourcedId” column. The “sourcedId” serves as a unique identifier that should never change and must remain unique regardless of letter casing; for instance, "Hello" and "hello" are considered equal in a case-insensitive comparison. Currently, you need to submit a second version of the one-roster zip file. Ensure that you use the same “sourcedId” values as in the previous submission. Failing to use the same values may result in the removal or inactivation of records in our system. For example, if you change a student’s “sourcedId” in your second submission, that student will be disabled in our system, and a new record will be created, leading to data duplication.

5. DateTime fields should be sent in ISO format. Refer to Date and Time Formats for more information.

6. All columns specified in the one-roster documentation must be included in your CSV files. If a column is marked as optional, it means that while all cells can be left blank, the column itself must still be present in the file. If you fail to include a specified column, you will encounter validation errors. However, if the file itself is optional, you may choose not to send it and simply mark it as “absent” in the manifest file.

7. According to the OneRoster specification, if a file references another file, the corresponding value must be present in both files. For example, if a student entry in the users.csv file has the "orgSourcedIds" cell filled with "1234," then the orgs.csv file must contain an organization with the sourcedId "1234." This will be validated during the processing of your files.

8. The CSV files must adhere to standard CSV specifications.

   • Ensure that all rows in each file have the same number of columns. If the number of columns differs in any row, it can cause data misalignment, resulting in valid data being placed in incorrect columns.

   • Use a semicolon “;” as the separator for data within each cell. “;”.

   • It is crucial to follow the escaping rules outlined in the CSV specification, especially when dealing with special characters like newlines, commas, and quotes. If a cell is not properly formatted and escaped, it may be deemed invalid or lead to data shifts within the columns.

9. Our system processes files one at a time. This approach helps avoid false errors caused by incorrect dependent files, as we do not validate the entire zip file simultaneously.

10. Make sure that all file names are accurate and that the corresponding records in the manifest.csv file correctly indicate whether the file is absent, bulk, or delta. In most cases, files will either be absent or classified as bulk. Delta files can be sent, but they involve a more complex process. Please note that file names are always pluralized and case-sensitive.
    
    Each CSV file is linked to its detailed specifications.

    • academicSessions.csv

    • categories.csv

    • classes.csv

    • classResources.csv

    • courseResources.csv

    • courses.csv

    • demographics.csv

    • enrollments.csv

    • lineItems.csv

    • manifest.csv

    • orgs.csv

    • resources.csv

    • results.csv

    • users.csv

Example file packages

• Minimum for basic integration
  pc-oneroster-integration-example-minimum.zip (335 KB)

• Complete for full integration
  pc-oneroster-integration-example-complete.zip (675 KB)

Periodicity and location to send files

When you are ready to send files to production, you will receive an FTP location along with a randomly generated username and password from the Permission Click system. This FTP location is secure, using either explicit port 21 TLS or port 2222 for SSH.

The IT team is expected to upload the latest files once a day during working hours. These files will be validated and then synchronized with our databases overnight.

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 ( pc-oneroster-integration-example-minimum.zip (335 KB)).

2. As a suggestion, the sourcedId field for the “student” role can be your SIS student number. The sourcedId must be a unique identifier that never changes and must remain unique regardless of letter casing (i.e., it must be case-insensitively unique). For example, a case-insensitive comparison treats "Hello" and "hello" as equal.

3. Guardians, parents, and students are all included in the users.csv file.

   • To associate students with their guardians, each student’s row must contain the corresponding parent’s sourcedId in the “agentSourcedIds" cell.

   • Students without a listed guardian or parent cannot be added to a form.

   • It is crucial to fill in the “role” column according to the specifications.

   • Only active students and guardians will be imported, so ensure that the “enabledUser” column is set appropriately.

   • If a guardian or parent has a blank email address, their student can still be rostered to a form; however, a message won't be sent until the email is corrected.

   • In cases where a student has multiple guardians or parents, we follow this hierarchy to determine which record to use when rostering the student to a form:

     • Consider the latest imported guardian with a valid email, or the latest imported guardian with a blank email; if none, then.

     • Look for the latest imported relative with a valid email, or the latest imported relative with a blank email; if none, then.

     • The most recently imported parent with a valid email, or the most recently imported parent with a blank email; if none, then.

     • Use the latest imported proctor.

Send data to Form questions

To display or update data in a form by a guardian in Permission Click, you must include the metadata fields defined in the OneRoster specification.

• For each piece of information, a metadata column must be added to the users.csv file for students.

• For other types of users, such as guardians and parents, blank cells should be inserted.

• The column name in the header row should follow the format “metadata.[yourcolumnname]”. Remove all special characters and spaces from the column name.

• Ensure the column name is descriptive enough for administrators and teachers to understand its purpose when using the forms.

• When our system processes your file, minimal validation is performed on the data. Therefore, it is essential to sanitize the data to ensure it is suitable for display on a form. For example, if you send “NULL” as text instead of a blank cell when there is no information, “NULL” will appear on your form.

• DateTime fields should be sent in ISO format, according to the Date and Time Formats specified by http://w3.org . Be sure to include all the data you want in a form as a “metadata” column. Additionally, fields such as Phone, SMS, Grade, and Email can also be included in the form. Currently, data from the demographics.csv file is not supported.