Roster sync zip requirements

This guide helps administrators prepare and submit a compliant roster zip file for Roster Sync in Turnitin Feedback Studio. It explains the required file structure, encoding standards, and SFTP behavior so you can send roster data that processes successfully.

In this guide:

• Overview
• The zip file
• File encoding
• SFTP folders

Overview

When administrators configure Roster Sync, they must send a roster zip file (via SFTP) that follows the OneRoster v1.1 specification. Turnitin does not require every file or field defined in the full OneRoster standard; however, the roster zip must include the specific CSV files and property values that Roster Sync uses during processing.

Bulk vs delta

Roster Sync uses the manifest.csv file to understand how to interpret the data you send. In particular, it relies on the “bulk” and “delta” modes to determine whether each file represents a full snapshot of your data or a set of changes.

• Bulk means “this file represents the full current set of records.”
  If you omit classes, users, or enrollments from a bulk upload, those items may be treated as removed.
• Delta means “this file includes only changes since the last upload.”

The zip file

The name of the roster zip file can be anything, but the files inside it must use the exact required CSV names. Each roster zip must contain the specified files listed in this guide so Roster Sync can process the data correctly. 

Each roster zip must include the following files with the required property names and formats:

manifest.csv

The values will be different depending on the customer, but the property names must be present and correctly formatted.

propertyName,value
manifest.version, 1.0
oneroster.version, 1.1
file.academicSessions,bulk
file.categories,absent
file.classes,bulk
file.classResources,absent
file.courses,bulk
file.courseResources,absent
file.demographics,bulk
file.enrollments,bulk
file.lineItems,absent
file.orgs,bulk
file.resources,absent
file.results,absent
file.users,bulk
source.systemName, "OneRoster-Zipper"
source.systemCode,OneRoster-Zipper

orgs.csv

sourcedId,
status,
dateLastModified,
name

academicSessions.csv

sourcedId,
status,
dateLastModified,
title,
startDate,
endDate,
schoolYear

users.csv

sourcedId,
status,
dateLastModified,
enabledUser,
orgSourcedIds,
role,
username,
givenName,
familyName,
email

classes.csv

sourcedId,
status,
dateLastModified,
title,
courseSourcedId,
schoolSourcedId,
termSourcedIds

enrollments.csv

sourcedId,
status,
dateLastModified,
classSourcedId,
schoolSourcedId,
userSourcedId,
role,
primary

File encoding

All CSV files in the roster zip must be UTF-8 encoded. UTF-16 (and other encodings) can cause processing failures even if the file names and headers are correct.

SFTP folders

When a customer sends a roster zip via SFTP, they upload it to the /transfer folder.

After the file is received, Roster Sync is notified to begin processing. As part of that process, the roster zip is moved out of /transfer and into the /archive folder. The /archive folder stores previously processed uploads for up to 30 days, so if you don’t see a file in /transfer, check /archive.