Use SFTP to upload student, staff and class data to Apple School Manager

If your Student Information System (SIS) isn’t currently supported by Apple School Manager or you don’t have a student information system, you can upload student, staff and class data to Apple School Manager using SFTP.

When you set up SFTP in the SIS/SFTP Assistant, Apple School Manager gives you CSV template files and access information for a private SFTP server. You can export data from your SIS or create the files in a spreadsheet application such as Numbers.

SFTP upload requires a third-party application on macOS. If you don’t have an SFTP client installed, you can find one in the Mac App Store.

Use the buttons below to get help with setting up your SFTP files. If you haven't used SFTP to upload data into Apple School Manager, you should start with the Set up your first SFTP upload section.

Set up your first SFTP upload

  1. Sign in to Apple School Manager as an Admin, Site Manager or People Manager.
  2. Click Settings in the bottom left-hand corner, choose Data Source, then click Connect. You must verify a domain before you can set up SFTP.
  3. Click Find Students, Staff and Classes.
  4. Click Set Up SFTP.
  5. Apple School Manager generates a URL, user name and password to use when uploading files. Use this information to configure your SFTP client.
  6. Click Download Templates.
  7. Read the instructions for using templates in the "Filling In Data Files" section.
  8. After your data files have been filled in, create a zip archive of all six files. In the Finder, select the files, then go to the File menu and choose Compress 6 Items. It doesn't matter what you call the zip archive.
  9. Upload the zip file to Apple School Manager. Use an SFTP client to connect to the URL shown in the SIS/SFTP Assistant. When asked for sign-in information, use the user name and password you received when you clicked Set Up SFTP. Copy the zip file to the Dropbox directory.
  10. Click Continue in the SIS/SFTP Assistant. If your upload contains errors, you can review a log that identifies the files and lines that contain errors. Correct any errors in the data files, then repeat steps 8 and 9. You don't need to remove the previous file from the SFTP server.
  11. When the SFTP import has finished, click Review SFTP Data. If you find any errors, click Cancel. Correct any errors in the data files, then repeat the upload process. If the data is accurate and complete, click Continue.
  12. Under Create Accounts and Classes, choose a Managed Apple ID format for students, instructors and staff. Click Preview Accounts and Classes. When the IDs are in the correct format, click Create Accounts and Classes. Only verified domains can be used in the Managed Apple ID format.
  13. After the accounts have been created, distribute sign-in information to users and assign roles to staff.

Fill in your data files

The template download includes six comma-separated value (CSV) files for Classes, Courses, Locations, Registers, Students and Staff. If the templates are not available in Apple School Manager or if you've lost a copy of the original templates, you can download them again.

You can use your SIS to export data in the format described by the templates and this article, or you can edit the templates in a spreadsheet program such as Numbers.

Use the tables in this article to make sure you enter the correct information, then save each file without changing its name.

Format your values

If you edit the templates, replace the example data with your own. Don't change the contents of the header cells in each file. Don't add columns in any file, except as described below.

In every template, each row must represent a unique value. For example, within the students.csv, each row must be a unique student. Certain values for that student can be empty. Literal values within a name, such as a line break or quotation mark character, must be escaped with a backslash (\), such as (\”). Any identifiers that are entered must be alphanumeric and can include a "-".

If your value contains a space ( ) or 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 will encounter errors during 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 and use Unix new-lines (\n). 

If an otherwise optional field such as person_number or sis_username is part of your Managed Apple ID format, it will become a required field. If you leave it blank, the upload will fail with the error MANAGED_ID_GENERATION_FAILED.

Locations file

location_id A unique identifier consisting of numbers and/or letters that contains no spaces. Required
location_name The name of the location.  Required

You must define at least one location in the Locations file. You can't use SFTP to create student or staff accounts in the main "headquarters" location.

Students file

If you use SFTP to upload a new person, and the person_id you assign already exists in Apple School Manager, your new person will overwrite the existing user in Apple School Manager. After the overwrite has been completed, you can only update that user via SFTP. 

 

person_id

The unique identifier for a specific student. This person_id should match the unique identifier in your SIS, if available. This person_id is the unique identifier for the student in Apple School Manager. Use this value to refer to the student in the Registers file and instructors in the Classes file. 

Required
person_number Another value that can be used to identify a student in your school. This could be a student identification number.  Optional
first_name The student's first name. Required
middle_name The student's middle name. Optional
last_name The student's surname. Required
grade_level The student's attainment level. Optional
email_address* An email address for the student. Optional
sis_username The user name for the student in your SIS.  Optional
password_policy Use the password_policy field to specify a password policy for each specific student. The password_policy field must have the number 4, the number 6, the number 8 or be left blank. If you select 8, this will be a standard password policy (8+ alphanumeric characters). This value overrides the location password policy and any password policy you had previously set for that student. If you leave password_policy blank, the default password policy for the location will be used for any new student and no changes will be made to existing students. Optional
location_id The location_id for the student. This must correspond with a location_id in the Locations file. If this entry doesn't match an entry in the Locations file, you will experience issues during the upload process. Required

* If federated authentication has been enabled, an email address will be required. If the email address is in a federated domain, the user account will be federated.

Assign multiple locations

You can assign more than one location to a student by adding more location columns to the Students file. You can add up to 998 more location columns named location_id_2, location_id_3, up to location_id_999. For each student, you have the option of entering another location_id in each of these columns. This must correspond with a location_id in the Locations file. If this entry doesn't match an entry in the Locations file, you will experience issues during the upload process.

Staff file

If you use SFTP to upload a new person, and the person_id you assign already exists in Apple School Manager, your new person will overwrite the existing user in Apple School Manager. After the overwrite has been completed, you can only update that user via SFTP. All staff will receive the standard password policy (8+ alphanumeric characters).

person_id

The unique identifier for a specific staff member. This person_id should match the unique identifier in your SIS, if available. This person_id is the unique identifier for the staff member in Apple School Manager. Use this value to refer to instructors in the Classes file. 

Required
person_number Another value that can be used to identify a staff member in your school. This could be a staff badge number.  Optional
first_name The staff member's first name. Required
middle_name The staff member's middle name. Optional
last_name The staff member's surname. Required
email_address* An email address for this staff member.  Optional
sis_username The user name for the staff member in your SIS. Optional
location_id The location_id for the staff member. This should correspond with a location_id in the Locations file. If this entry doesn't match an entry in the Locations file, you will experience issues during the upload process. Required

* If federated authentication has been enabled, an email address will be required. If the email address is in a federated domain, the user account will be federated.

Assign multiple locations

You can assign more than one location to a staff member by adding more location columns to the Staff file. You can add up to 998 more location columns named location_id_2, location_id_3, up to location_id_999. For each staff member, you have the option of entering another location_id in each of these columns. This must correspond with a location_id in the Locations file. If this entry doesn't match an entry in the Locations file, you will experience issues during the upload process.

Courses file

course_id A unique identifier for the course. This must match the corresponding course_id used in the Classes file.   Required
course_number A number for the course. This number could be the course number in your SIS or your curriculum guide. Optional
course_name The name of your course. Optional
location_id The location_id for the course. This should correspond with a location_id in the Locations file. If this entry doesn't match an entry in the Locations file, you will experience issues during the upload process.
Required

Classes file

class_id A unique identifier for the class.    Required
class_number A number or code that identifies this class in your organisation. Unlike class_id, class_number isn't used to refer to this class in CSV registers.  Optional
course_id The course_id of the course this class belongs to. This must match a course_id in the Courses file. Required
instructor_id The person_id for the instructor. This must match the person_id used in the Staff file. Optional
instructor_id_2 The person_id for the instructor. This must match the person_id used in the Staff file. Optional
instructor_id_3 The person_id for the instructor. This must match the person_id used in the Staff file. Optional
location_id The location_id for the class. This should correspond with the location_id in the Locations file. If this entry doesn't match an entry in the Locations file, you will experience issues during the upload process. Required

Assign multiple instructors

You can assign more than three instructors to a class by adding more instructor columns to the Classes file. You can add up to 12 more instructor columns named instructor_id_4, instructor_id_5, up to instructor_id_15. For each class, you have the option of entering another person_id for the instructor. This must match the person_id used in the Staff file.

Registers file

roster_id A unique identifier for the register in your SIS or other course database (if available).  Required
class_id A unique alphanumeric identifier for the class. This must match a class_id in the Class file.
Required
student_id A person_id for one student.  Required

The Registers file is used to add students to their classes. Each line in the file must have a unique roster_id and contain only one class_id and one person_id.

Update your files

When you want to add or edit students, staff and classes, edit your data files and upload the new copies. Whenever you upload files, you must upload all six files and each file must contain the complete list of each category, not just the items you intend to add. You can check SFTP account information by choosing Settings > Data Source.

If you disconnect your SFTP connection within Apple School Manager accidentally, your accounts will change to manual and will be deactivated. You can resolve this by restoring your SFTP connection and performing a new upload to reactivate accounts without creating duplicates.

After the first upload, new accounts and classes will be created automatically when you upload. If there are any errors, Apple School Manager will send you an email.

If an entry from an earlier upload is missing

If an entry from an earlier upload is missing, its source changes to Manual in Apple School Manager. Additional effects of the removal may vary. If students or staff are removed from the upload, their accounts will be deactivated and deleted automatically after 30 days, unless the account has purchased volume content.

If a course or a class is removed

If a course or a class is removed from the upload, students will be removed from the class and the source will change to Manual. If courses were in use in iTunes U or Schoolwork, the register will be removed and a new course must be created for re-enrolment. If classes were in use in Schoolwork, progress data will be deleted automatically and will no longer be available to the teacher or student.

Courses and classes with a manual source will continue to sync with your MDM solution, but may no longer appear in the Classroom app. Manual classes can be deleted in Apple School Manager if you want to stop them from syncing.

Information about products not manufactured by Apple, or independent websites not controlled or tested by Apple, is provided without recommendation or endorsement. Apple assumes no responsibility with regard to the selection, performance or use of third-party websites or products. Apple makes no representations regarding third-party website accuracy or reliability. Contact the vendor for additional information.

Published Date: