4. Synchronization

A synchronization run reads the school data from the LDAP directory, writes it to CSV files, packs the files into a ZIP archive, and uploads the archive to Apple School Manager. This chapter describes the run itself and the data that it transfers.

4.1. Run the synchronization

Three things start a synchronization run:

• The cron job from Schedule the synchronization.

• Saving the app settings, if you enabled asm/run_on_appsetting_save.

• The command asm-upload on the command line.

Listing 4.1 Start a synchronization run manually

$ /usr/sbin/asm-upload

The command writes progress messages to the terminal and a more detailed log to /var/log/univention/asm.log. It exits with a non-zero status if the credentials are missing or if the upload to any account fails.

4.1.1. What happens during a run

1. The connector reads the settings file /etc/asm-connections.json, as described in Settings file. A missing or invalid entry stops the run, and so does a school that doesn’t exist in the LDAP directory.

2. The connector collects the schools, classes, work groups, teachers, and students from the LDAP directory, restricted to the schools of the account and by the LDAP filters from Select users with an LDAP filter.

3. The connector writes the six CSV files from The CSV files to a temporary directory.

4. The connector packs the CSV files into /var/lib/asm/asm_TIMESTAMP.zip and removes the temporary directory. TIMESTAMP is the time the connector created the archive, in ISO 8601 format, for example 2026-10-01T03:00:12.345678.

5. The connector opens an SFTP connection to upload.appleschoolcontent.com and uploads the archive as archive.zip. It verifies the host key against /etc/asm_public_key.

6. The connector sets asm/last_upload and asm/last_upload/ACCOUNT to the current time and deletes the archive, unless you enabled asm/store_zip.

With several accounts, the connector repeats the steps 2 to 6 for each account.

Every run transfers the complete data set. The connector doesn’t track what changed since the last run.

4.1.2. How Apple School Manager applies the data

Apple School Manager compares the uploaded data with the accounts that it holds:

• A user who appears for the first time gets a new account.

• A user who is no longer in the upload is deactivated immediately and deleted after 30 days.

• A user whose attributes changed keeps the account, as long as the person_id column is unchanged. See Identification of users.

4.2. The CSV files

The archive contains the following six files. Apple documents their format in Apple Inc. [4]. The connector sorts the rows of each file by school and then by user or class name.

Table 4.1 Files in the uploaded archive

File	Content
locations.csv	One row per school.
courses.csv	One row per school class and work group.
classes.csv	One row per school class and work group, with the teachers of that class.
staff.csv	One row per teacher.
students.csv	One row per student.
rosters.csv	One row per membership of a student in a school class or work group.

4.2.1. Locations

Table 4.2 Columns of locations.csv

Column	Source in UCS@school
location_id	Name of the school, for example gym123.
location_name	Display name of the school. Falls back to the name if the school has no display name.

4.2.2. Courses

Apple School Manager requires every class to belong to a course. UCS@school only has the school class or work group, so the connector exports each of them twice: once as a course in courses.csv and once as a class of that course in classes.csv. Both rows use the name of the group as their ID, so each course has exactly one class.

Table 4.3 Columns of courses.csv

Column	Source in UCS@school
course_id	Name of the school class or work group, including the school prefix, for example gym123-1a.
course_number	Same value as course_id.
course_name	Built from course_name_pattern. See Names of courses and classes.
location_id	Name of the school.

4.2.3. Classes

Table 4.4 Columns of classes.csv

Column	Source in UCS@school
class_id	Name of the school class or work group.
class_number	Empty by default. See class_number_empty in Names of courses and classes.
course_id	Name of the school class or work group.
instructor_id, instructor_id_2, instructor_id_3	The person_id of the first three teachers of the class.
instructor_id_4 to instructor_id_15	The person_id of the remaining teachers. The connector only writes as many columns as it needs.
location_id	Name of the school.

Note

Apple School Manager supports at most 15 teachers per class. If a class has more, the connector synchronizes the first 15 and writes a warning to the log file.

4.2.4. Staff

Table 4.5 Columns of staff.csv

Column	Source in UCS@school
person_id	The attribute from staff.person_id_attribute, entryUUID by default.
person_number	Same value as person_id.
first_name	First name of the teacher.
middle_name	First value of middleName, initials, or oxMiddleName.
last_name	Last name of the teacher.
email_address	Primary email address, modified by email_prepend_domain.
sis_username	User name of the teacher.
location_id	Primary school of the teacher.
location_id_2 and following	The other schools of the teacher, in alphabetical order.

The file holds teachers and teachers with an additional staff role. Staff members without a teacher role aren’t part of the export.

4.2.5. Students

Table 4.6 Columns of students.csv

Column	Source in UCS@school
person_id	The attribute from student.person_id_attribute, entryUUID by default.
person_number	Same value as person_id.
first_name	First name of the student.
middle_name	First value of middleName, initials, or oxMiddleName.
last_name	Last name of the student.
grade_level	The attribute from student.grade_level_attribute. Empty if the key is unset.
email_address	Primary email address, modified by email_prepend_domain.
sis_username	User name of the student.
password_policy	The value of student.password_policy. See Password policy for students.
location_id	Primary school of the student.
location_id_2 and following	The other schools of the student, in alphabetical order.

Exam users aren’t part of the export.

4.2.6. Rosters

Table 4.7 Columns of rosters.csv

Column	Source in UCS@school
roster_id	The class name and the person_id of the student, joined with a hyphen.
class_id	Name of the school class or work group.
student_id	The person_id of the student.

The file only holds students. Teachers reach a class through the instructor_id columns of classes.csv.

4.3. Inspect the uploaded data

To look at what the connector uploads, enable asm/store_zip in the app settings and run the synchronization. The connector then keeps the archive in /var/lib/asm/.

Listing 4.2 List the archives and unpack the newest one

$ ls -l /var/lib/asm/
$ unzip -d /var/tmp/asm "$(ls -t /var/lib/asm/*.zip | head -1)"

Caution

The archives contain personal data. Delete them when you no longer need them, and turn asm/store_zip off again.