In this guide, you'll learn how to create, upload, and manage your TSF CSV files to ensure an error-free rostering process. Tailored specifically for District Admins, this guide is here to help you easily navigate all the ins and outs of rostering.
Step 1: Create your CSV files
We require a users.csv file and a classes.csv file to roster all users. Download the file templates to add your district information.
The sections below provide detailed guidance on how to fill out each CSV, including required fields, formatting tips, and important notes to help you avoid common errors. You must upload a users.csv and a classes.csv.
The users.csv file must include all users who need access to Twig Science; students, teachers and school administrators. Each time you upload, ensure the file contains a complete list of everyone who needs access. If a user is removed from future uploads, their account will be archived and their access revoked.
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 User_ID and Username 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 TSF CSV files.
Completing your users.csv file
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.
| Heading | Notes | Required |
|---|---|---|
| user_id | Each user must have a unique and permanent case-sensitive identifier. This user_id will be used in the classes.csv file as the teacher_id, student_id. | YES |
| first_name | First name | YES |
| last_name | Last name | YES |
| username | A unique and permanent identifier | NO |
| password | Data is optional, but the header must be present | NO |
| role |
Should contain one of the following values to specify
the user's role:
|
YES |
| Data is optional, but the header must be present | NO | |
| school_names | Data is optional; however, to ensure administrators have access to specific school reports, school_names should be included for any users with the administrator role. | NO |
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
If your district uses Google Workspace for Education, you will need to approve the Twig Science app in your Google Console first. Please read Google's guide: Control which third-party & internal apps access Google Workspace data
Your users.csv file should look something like this:
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.
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.
The classes.csv file should list the schools and classes each student and teacher belongs to. Every teacher and student referenced in the classes.csv file must also be listed in the users.csv file.
Be aware that any errors in the classes.csv file could result in teachers or students being rostered in the wrong school or class.
Completing your classes.csv file
Use this table to check the structure and required fields for your classes.csv file. Following the correct format helps prevent sync errors and ensures your data is processed correctly.
| Heading | Notes | Required |
|---|---|---|
| class_id | Should be a unique and permanent identifier for each class. | YES |
| class_name | The name of the class "Room 1" etc. | YES |
| school_name | YES | |
| teacher_id | This is the user_id of any teacher listed in the users.csv | YES |
| student_id | This is the user_id of any student listed in the users.csv | YES |
| grade | The grade associated with the class. Must be one grade from the CEDS grade list. | YES |
Your classes.csv file should look like this:
CSV Upload Checklist
This checklist is designed to help you finalize your data, and ensure your CSV is correctly formatted to avoid upload errors. Review each section carefully and complete all checks to prevent disruptions.
| Check | Details |
|---|---|
| Ensure there are no duplicated entries in the users.csv file. Top tip: Sort the column by alphabetical order to make it easier to spot duplicates. | |
| Every user should have a unique and permanent user_id If someone leaves, archive their ID. New users should always be provisioned with a new ID. | |
| Verify spelling of school and class names to prevent duplicates or errors. | |
| Confirm both files contain the required headers for proper processing. Download our file templates here which contain the correct headers. | |
| All users in classes.csv must also appear in users.csv. | |
| Files uploaded to the SFTP folder must be named exactly users.csv and classes.csv. This naming convention is mandatory. Files with incorrect names will cause errors and prevent successful rostering. |
Step 2: Choose your CSV 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.
- 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.
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 users.csv and classes.csv 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.
CSV upload via Twig Science Website Self-Service interactive guide
Follow our interactive, step-by-step guide to learn how to upload rostering files to Twig Science using our self-service dashboard.
Note
Access to our self-service dashboard requires a District Admin account. If you do not have one, please contact your CSM.
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 users.csv and classes.csv 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 the users.csv and classes.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.
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 user_id. 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 both CSVs. Download our CSV templates to avoid formatting issues.
Files must be named exactly:users.csv and classes.csv. Any variation, even a capital letter, will stop the upload.
Useful downloads and further reading
- Download CSV templates (.zip)
- Recommended SFTP client: FileZilla
- Twig: Enable Google SSO for Teachers, Students and Admin
- Twig: How do I upload rostering files for Twig Support?
- Twig: End of Year Rollover Process
- Twig: Available User Roles