Template information for importing data into Apple School Manager
To add data to Apple School Manager, you can use .csv template files formatted by Apple or by OneRoster.
Apple .csv template names: Students, Staff, Courses, Classes, Rosters, Locations
OneRoster .csv template names: Users, Courses, Classes, Enrollments, Orgs
Apple filename | OneRoster filename | Contents | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Apple: Contains student account info. OneRoster: Contains student, instructor, and staff account info. | |||||||||||
N/A | Contains staff account info, such as instructors. | ||||||||||
Contains course info. | |||||||||||
Contains classes and instructor (staff) info. | |||||||||||
Contains class, student, and location (roster) info. | |||||||||||
Contains location (school or department) info. | |||||||||||
Templates and Managed Apple Accounts
If an optional field—such as person_number or sis_username—is part of your Managed Apple Account format, it then becomes a required field. If you leave it blank, the SFTP upload fails with the error MANAGED_ID_GENERATION_FAILED.
Prepare templates
When preparing a template, the following criteria must be met:
For the students.csv and staff.csv templates, person_id must be unique for all locations.
Important: If you use SFTP to upload a new user and the person_id you assign is already assigned to another user, the new user overwrites the existing user in Apple School Manager. After the overwrite is complete, you can update that user only through SFTP.
If you edit the templates, replace the example data with your own. Don’t change the contents of the header row in each file. Don’t create duplicate columns in any file. You can add columns to specific templates.
In every template, each row must represent a unique value. For example, within the students.csv file, each row must be a unique student. Certain values for that student can be empty. Literal values—for instance, a line break or quotation mark within a name—must be escaped with a backslash (\). Here’s an example: \". Any identifiers entered must be alphanumeric and can include a hyphen (-).
If your value contains a space ( ) or a comma (,), use straight quotation marks (") around it. If your value doesn’t have any of these special characters, don’t use quotation marks. If you don’t use quotes where they are needed, or you use curly quotes, you’ll get errors in the upload process.
The values in your files must be separated with commas (,) or semicolons (;), regardless of how you created the file. Don’t use spaces or tabs between a comma or semicolon and the next value. Each file must be encoded as UTF-8. To represent end of line, use the UNIX newline encoding \n.
If an entry from an earlier upload is missing, the user account is deactivated and automatically deleted after 120 days, unless:
The user has a role that has purchased apps or books in volume
The user is manually deleted before the 120-day limit
The names of the .csv files should match the original filename exactly.
All files must be compressed into one zipped (.zip) archive file to be uploaded.
No file may be placed within a folder in the zipped archive file.
All foreign-key references to other .csv files must be defined in the referenced file.
Character limits in .csv templates
Some fields in the .csv templates have limits on the number of characters allowed.
Attribute name | Templates | Character limit |
|---|---|---|
Apple: first_name OneRoster: givenName | Apple: Students, Staff OneRoster: Users | 32 |
Apple: middle_name OneRoster: middleName | Apple: Students, Staff OneRoster: Users | 32 |
Apple: last_name OneRoster: familyName | Apple: Students, Staff OneRoster: Users | 64 |
Apple: grade_level OneRoster: grades | Apple: Students OneRoster: Users | 64 |
Apple: email_address OneRoster: email | Apple: Students OneRoster: Users | 256 |
Apple: person_number OneRoster: identifier | Apple: Students, Staff OneRoster: Users | 64 |
Apple: person_id OneRoster: sourcedId | Apple: Students, Staff, Classes, Rosters OneRoster: Users, Classes, Enrollments | 256 |
Apple: sis_username OneRoster: username | Apple: Students, Staff OneRoster: Users | 256 |
Apple: class_id OneRoster: sourcedID | Apple: Classes, Rosters OneRoster: Classes, Enrollments | 256 |
Apple: class_number OneRoster: classCode | Apple: Students, Classes OneRoster: Classes | 64 |
Apple: course_id OneRoster: sourcedID | Apple: Courses, Classes OneRoster: Courses, Classes | 256 |
Apple: course_name OneRoster: title | Apple: Courses OneRoster: Courses | 128 |
Apple: course_number OneRoster: courseCode | Apple: Courses OneRoster: Courses | 64 |
Apple: location_name OneRoster: name | Apple: Locations OneRoster: Orgs | 256 |
Apple: location_id OneRoster: sourcedID | Apple: Students, Staff, Courses, Classes, Locations OneRoster: Users, Courses, Classes, Orgs | 256 |