In this guide, you'll learn how to manually set up rostering using the OneRoster 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 and prepare your OneRoster CSV files
OneRoster data can be exported from your SIS. You can also create files using our templates.
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 Twig Science.Use the tabs below to review requirements for each file and related setup.
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.
Recommendation
We recommend keeping a separate CSV file as a reference for all previously created users. This file is for your records only and should not be uploaded into the system.
Record the Sourceids and Usernames for all accounts (active or inactive). This will make it easier to check which IDs and usernames are already in use, and reduce the chance of errors from duplicates or incorrect entries when updating and uploading your OneRoster CSV files.
| 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:
|
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 |
| 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.
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. Permanent 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. Must be one grade from the CEDS grade list. | YES |
| courseSourcedId | A code for each course. Example: biology1290 | NO. NOT PROCESSED |
| classCode | A code for each class. Example: 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 e.g., Chem14 | NO. NOT PROCESSED |
| periods | 4 |
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: 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 |
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: 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.
Twig: Enabling Google SSO
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.
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: Choose your upload method
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.
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.
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.
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.
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]
If you need to download an SFTP client, we recommend FileZilla.
Your update will be processed overnight and you will receive an email to confirm that the update has been successful.
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 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 accordion 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.
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.
Each user needs a unique and consistent sourcedId. Reusing IDs for new staff or students, even if someone has left, can cause errors. Always archive old IDs and assign new ones to new users.
Watch out for typos in school or class names across your files. Inconsistent spelling can cause duplicate records or failed uploads. Also, make sure you’ve used the correct headers in all CSVs. Download template files.
Files must be named exactly: Any variation, even a capital letter, will stop the upload.