Twig: Rostering with OneRoster Format CSV

In this guide, you'll learn how to manually set up rostering using the One Roster CSV format. Tailored specifically for District Admins, this guide is here to help you easily navigate all the ins and outs of rostering.

Step 1: Export OneRoster CSV files

OneRoster data cam be exported from your SIS. You can also create files by using our templates.  Click on the sections below to find out more.

Export OneRoster data

The CSV file format we accept is OneRoster standard specification v1.1: https://www.imsglobal.org/oneroster-v11-final-csv-tables

Most SIS systems can export files in OneRoster CSV format.

To successfully sync your roster, please ensure you export and upload the following CSV files:

Read on to see which data is required for the Twig Science.

 

Required data for users.csv

This table outlines the required structure for your users.csv file. Be sure to include all required fields and follow the formatting notes to ensure an error free upload.

 Caution

When updating your roster via CSV uploads, ensure that all active users remain listed in the users.csv file. Any users omitted from this file during an upload will be automatically removed from the Twig Science platform. To maintain user access and data integrity, always include all currently active users in each users.csv upload.

Heading Notes Required
sourcedId A unique identifier for each user. This is a permanent identifier and should not be changed. After use each sourcedId should be archived and not used again. YES
status The status could be one of the following: active, tobedeleted, inactive NO. NOT PROCESSED

dateLastModified

Date format should be: ISO-8601 NO. NOT PROCESSED

enabledUser

The status should be one of the following:

true, false

YES

orgSourcedIds

Values must match sourcedId values in orgs.csv. Examples: "10239845,10239846,10239849,10239889" YES
role

Should be one of the following roles:

  • student
  • teacher
  • administrator
YES
username Should only contain: letters, numbers, and the characters @+-_ YES

userIds

Should only contain: letters, numbers, and the characters @+-_ NO. NOT PROCESSED
givenName First name NO. NOT PROCESSED
familyName Surname NO. NOT PROCESSED
middleName Middle name NO. NOT PROCESSED
identifier A unique and permanent id for each user NO. NOT PROCESSED
email Example: mrodriguez@gmail.com NOT REQUIRED. EMAIL WILL BE PROCESSED IF PROVIDED AND CAN BE USED FOR GOOGLE SSO
sms   NO. NOT PROCESSED
phone   NO. NOT PROCESSED

agentSourcedIds

  NO. NOT PROCESSED
grades The grade associated with the class. Must be one grade from the CEDS grade list NO
password Should be a secure password NO

 Caution

Important: Do Not Reuse User IDs

Each user_id must be unique and permanently assigned to a single user. These IDs should never be reused or reassigned—even if a student has left the school or district, or after a school year rollover. Reusing IDs can lead to serious issues with data integrity, user accounts, and access within the Twig Science platform. Our system does not support ID reuse under any circumstance.

Required data for classes.csv

This table outlines the required structure for your classes.csv file. Be sure to include all required fields and follow the formatting notes to ensure an error free upload.

Heading Notes Required
sourcedId A unique identifier for each class. This is a permanent identifier and should not be changed. After use each sourcedId should be archived and not used again.  YES
status active, tobedeleted, inactive NO. NOT PROCESSED
dateLastModified Date format should be in: ISO-8601 NO. NOT PROCESSED
title Class name or identifier: Science class 1A YES
grade Grade associated with class. The grade associated with the class. Must be one grade from the CEDS grade list. YES
courseSourcedId A code for each course. Example would be: biology1290 NO. NOT PROCESSED
classCode A code for each class. Example would be: Class2b NO. NOT PROCESSED
classType Name of class, for example: Science NO. NOT PROCESSED
location Name of room or location, for example: Room 36 NO. NOT PROCESSED
schoolSourcedId Name of school, for example: Small Town Elementary YES
termSourcedId Term, for example: 2023/2024 NO. NOT PROCESSED
subjects Name of subject, for example: Chemistry NO. NOT PROCESSED
subjectCodes Code for subject for example: Chem14 NO. NOT PROCESSED
periods   4
Required data for orgs.csv

This table outlines the required structure for your orgs.csv file. Be sure to include all required fields and follow the formatting notes to ensure an error free upload.

Heading Notes Required
sourcedId

A unique identifier for each user. This is a permanent identifier and should not be changed. After use each sourcedId should be archived and not used again. 

YES
status The status could be one of the following: active, tobedeleted, inactive NO. NOT PROCESSED
dateLastModified Date format should be: ISO-8601 NO. NOT PROCESSED
title Class name or identifier: Science class 1A YES
name School name YES
type This could be: department, school, district, local, state ONLY PROCESSED IF SCHOOL IS DATA VALUE
identifier   NO. NOT PROCESSED
parentSourcedId   NO. NOT PROCESSED
Required data for enrollments.csv

This table outlines the required structure for your enrollments.csv file. Be sure to include all required fields and follow the formatting notes to ensure an error free upload.

Heading Notes Required
sourcedId A unique identifier for each user. This is a permanent identifier and should not be changed. After use each sourcedId should be archived and not used again.  YES
status The status could be one of the following: active, tobedeleted, inactive NO. NOT PROCESSED
dateLastModified Date format should be: ISO-8601 NO. NOT PROCESSED
classSourcedId This should be the sourcedId referenced in your classes.csv file. YES
schoolSourcedId A unique, permanent identifier for each school YES
userSourcedId This should be the sourcedId referenced in the users.csv file YES
role administrator, teacher, student YES
primary Signifies who is the main teacher for each class. Data input should be true or false NO
beginDate Date format should be: ISO-8601 NO
endDate Date format should be: ISO-8601 NO
Assigning roles in OneRoster

Roles are assigned within two different files when using OneRoster format. The role of a user is assigned in the user.csv and the enrollments.csv.

Learn more about rostering roles and assigning teachers and co-teachers in our article, Twig: Available User Roles.

Enabling Google Classroom Single Sign On

You can enable users to sign in with their Google credentials by including their Google email addresses in your users.csv file.

To log in using single sign-on (SSO), users should visit login.twigscience.com and click Log in with Google.

rtaImage.jpeg

Note: Google Workspace for Education

If your district uses Google Workspace for Education, you will need to approve the Twig Science app on your Google Console first. Please read Google's guide: Control which third-party & internal apps access Google Workspace data

Step 2: Upload OneRoster files

You can upload your rostering files using one of two methods: Twig Science Website Self-Service or SFTP Upload. Each option offers a different level of flexibility and setup depending on your district’s needs.

  • Website Self-Service is our recommended method. It’s fast, user-friendly, and provides instant feedback so you can resolve issues right away.
  • SFTP Upload is best suited for districts with existing secure file transfer processes and automated workflows.

The sections below walk you through how each method works, what you’ll need to get started, and how to ensure your uploads are successful.

 

Website Self-Service

This is the easiest and most flexible way to upload and manage your rostering files.

How it works:

  • Use your District Admin login details to access the Twig Science Admin Dashboard (contact your Customer Success Manager if you need your username or password).
  • Upload your CSV files directly through the dashboard.
  • Access real-time updates and error messages through the import log.
  • Check the status of your upload and resolve any issues promptly.

Why we recommend this option: 

It’s fast and flexible, with no need for SFTP setup, and provides immediate feedback to reduce sync delays, making it easy to troubleshoot and re-upload without waiting.

 

 Note

District admin accounts are provided by us, and the term administrator in this document refers to a school administrator account. For more information on available user roles, please refer to Twig Available User Roles.

Interactive Self Rostering Guide

Follow our interactive step-by-step guide to learn how to upload OneRoster files to Twig Science using our self-service dashboard.

SFTP Upload Guide

This method is suitable for districts with established SFTP workflows.

How it works:

  • Ensure your SFTP client is configured correctly with the provided credentials.
  • Upload your CSV files to the designated SFTP folder.
  • Monitor the upload status and check for any error messages.

Uploading the CSV files to our SFTP server

After you create the CSV files in the required Twig Science format, please upload them to the Twig Science SFTP account. Credentials will be supplied during initial setup with your CSM, and will look like the following:

  • Hostname: sftp-rostering.twigscience.com
  • Port: 22
  • Username: [district specific]
  • Password: [district specific]
  • Folder path: [not required]

 

Step 3: Sync and Test

After each upload, you’ll receive a sync confirmation, either through the admin dashboard or by email (if using SFTP). If there are any issues, you can check the import log on the dashboard or contact support@twigeducation.com.

You can update your district data at any time using your chosen upload method. SFTP uploads are processed nightly, and you’ll receive an email once the overnight sync is complete.

Once the sync is complete, the rostering database will be updated based on the contents of the your CSV files:

  • New records in the CSV will result in new users being created.

  • Missing records (compared to the previous upload) will result in those users being archived. Archived users can be reactivated by including their original ID in a future upload.

  • Existing records with updated information will modify the corresponding user accounts.

After syncing, you can log in as a teacher or student to verify the updates. Credentials will be listed in your users.csv file.

Troubleshooting sync errors

Having trouble with your upload? It’s usually something simple. Use the tabs below to spot and fix common issues like duplicate users or file name mistakes. If you're still stuck, reach out to your CSM for help.

Duplicate Users User ID Issues Typos & Headers File Naming & References

Duplicates in your users.csv file can prevent proper syncing. To check for these quickly, sort your file by name or email. Removing any repeated entries should help resolve the issue.

How do users log in after syncing?

All users can log in at app.twigscience.com/login using:

  • Google SSO

  • Twig username or email and password (specified in users.csv)

Useful downloads and further reading

 

Back to Top