4. Synchronisation

Ein Synchronisationslauf liest die Schuldaten aus dem LDAP-Verzeichnis, schreibt sie in CSV-Dateien, packt die Dateien in ein ZIP-Archiv und lädt das Archiv zu Apple School Manager hoch. Dieses Kapitel beschreibt den Lauf selbst und die Daten, die er überträgt.

4.1. Synchronisation ausführen

Drei Auslöser starten einen Synchronisationslauf:

• Der Cron-Job aus Synchronisation zeitlich planen.

• Das Speichern der App-Einstellungen, wenn Sie asm/run_on_appsetting_save aktiviert haben.

• Der Befehl asm-upload auf der Kommandozeile.

Quellcode 4.1 Synchronisationslauf manuell starten

$ /usr/sbin/asm-upload

Der Befehl gibt Fortschrittsmeldungen im Terminal aus und schreibt ein ausführlicheres Log nach /var/log/univention/asm.log. Er endet mit einem Exit-Status ungleich null, wenn die Zugangsdaten fehlen oder der Upload in ein Konto fehlschlägt.

4.1.1. Ablauf eines Synchronisationslaufs

1. Der Connector liest die Einstellungsdatei /etc/asm-connections.json, wie in Einstellungsdatei beschrieben. Ein fehlender oder ungültiger Eintrag bricht den Lauf ab, ebenso eine Schule, die es im LDAP-Verzeichnis nicht gibt.

2. Der Connector sammelt die Schulen, Schulklassen, Arbeitsgruppen, Lehrer und Schüler aus dem LDAP-Verzeichnis, beschränkt auf die Schulen des Kontos und durch die LDAP-Filter aus Benutzer mit einem LDAP-Filter auswählen.

3. Der Connector schreibt die sechs CSV-Dateien aus Die CSV-Dateien in ein temporäres Verzeichnis.

4. Der Connector packt die CSV-Dateien in /var/lib/asm/asm_TIMESTAMP.zip und entfernt das temporäre Verzeichnis. TIMESTAMP ist der Zeitpunkt, zu dem der Connector das Archiv erstellt hat, im Format ISO 8601, zum Beispiel 2026-10-01T03:00:12.345678.

5. Der Connector öffnet eine SFTP-Verbindung zu upload.appleschoolcontent.com und lädt das Archiv als archive.zip hoch. Den Host-Schlüssel prüft er gegen /etc/asm_public_key.

6. Der Connector setzt asm/last_upload und asm/last_upload/ACCOUNT auf die aktuelle Uhrzeit und löscht das Archiv, sofern Sie asm/store_zip nicht aktiviert haben.

Bei mehreren Konten wiederholt der Connector die Schritte 2 bis 6 für jedes Konto.

Jeder Lauf überträgt den vollständigen Datenbestand. Der Connector verfolgt nicht, was sich seit dem letzten Lauf geändert hat.

4.1.2. Wie Apple School Manager die Daten übernimmt

Apple School Manager vergleicht die hochgeladenen Daten mit den Konten, die es verwaltet:

• Ein Benutzer, der zum ersten Mal auftaucht, erhält ein neues Konto.

• Ein Benutzer, der nicht mehr im Upload enthalten ist, wird sofort deaktiviert und nach 30 Tagen gelöscht.

• Ein Benutzer, dessen Attribute sich geändert haben, behält sein Konto, solange die Spalte person_id unverändert bleibt. Siehe Identifikation von Benutzern.

4.2. Die CSV-Dateien

Das Archiv enthält die folgenden sechs Dateien. Apple dokumentiert ihr Format in Apple Inc. [4]. Der Connector sortiert die Zeilen jeder Datei nach Schule und anschließend nach Benutzer- oder Klassenname.

Tab. 4.1 Dateien im hochgeladenen Archiv

Datei	Inhalt
locations.csv	Eine Zeile pro Schule.
courses.csv	Eine Zeile pro Schulklasse und Arbeitsgruppe.
classes.csv	Eine Zeile pro Schulklasse und Arbeitsgruppe, mit den Lehrern dieser Klasse.
staff.csv	Eine Zeile pro Lehrer.
students.csv	Eine Zeile pro Schüler.
rosters.csv	Eine Zeile pro Mitgliedschaft eines Schülers in einer Schulklasse oder Arbeitsgruppe.

4.2.1. Standorte

Tab. 4.2 Spalten von locations.csv

Spalte	Quelle in UCS@school
location_id	Name der Schule, zum Beispiel gym123.
location_name	Anzeigename der Schule. Hat die Schule keinen Anzeigenamen, verwendet der Connector stattdessen den Namen.

4.2.2. Kurse

Apple School Manager verlangt, dass jede Klasse zu einem Kurs gehört. UCS@school kennt nur die Schulklasse oder Arbeitsgruppe, daher exportiert der Connector jede davon zweimal: einmal als Kurs in courses.csv und einmal als Klasse dieses Kurses in classes.csv. Beide Zeilen verwenden den Namen der Gruppe als ID, sodass jeder Kurs genau eine Klasse hat.

Tab. 4.3 Spalten von courses.csv

Spalte	Quelle in UCS@school
course_id	Name der Schulklasse oder Arbeitsgruppe einschließlich des Schulpräfixes, zum Beispiel gym123-1a.
course_number	Derselbe Wert wie course_id.
course_name	Gebildet aus course_name_pattern. Siehe Namen von Kursen und Klassen.
location_id	Name der Schule.

4.2.3. Klassen

Tab. 4.4 Spalten von classes.csv

Spalte	Quelle in UCS@school
class_id	Name der Schulklasse oder Arbeitsgruppe.
class_number	Standardmäßig leer. Siehe class_number_empty in Namen von Kursen und Klassen.
course_id	Name der Schulklasse oder Arbeitsgruppe.
instructor_id, instructor_id_2, instructor_id_3	Die person_id der ersten drei Lehrer der Klasse.
instructor_id_4 bis instructor_id_15	Die person_id der übrigen Lehrer. Der Connector schreibt nur so viele Spalten, wie er benötigt.
location_id	Name der Schule.

Bemerkung

Apple School Manager unterstützt höchstens 15 Lehrer pro Klasse. Hat eine Klasse mehr, synchronisiert der Connector die ersten 15 und schreibt eine Warnung in die Logdatei.

4.2.4. Mitarbeiter

Tab. 4.5 Spalten von staff.csv

Spalte	Quelle in UCS@school
person_id	Das Attribut aus staff.person_id_attribute, standardmäßig entryUUID.
person_number	Derselbe Wert wie person_id.
first_name	Vorname des Lehrers.
middle_name	Erster Wert von middleName, initials oder oxMiddleName.
last_name	Nachname des Lehrers.
email_address	Primäre E-Mail-Adresse, angepasst durch email_prepend_domain.
sis_username	Benutzername des Lehrers.
location_id	Primäre Schule des Lehrers.
location_id_2 und folgende	Die weiteren Schulen des Lehrers, in alphabetischer Reihenfolge.

Die Datei enthält Lehrer sowie Lehrer mit zusätzlicher Mitarbeiterrolle. Mitarbeiter ohne Lehrerrolle sind nicht Teil des Exports.

4.2.5. Schüler

Tab. 4.6 Spalten von students.csv

Spalte	Quelle in UCS@school
person_id	Das Attribut aus student.person_id_attribute, standardmäßig entryUUID.
person_number	Derselbe Wert wie person_id.
first_name	Vorname des Schülers.
middle_name	Erster Wert von middleName, initials oder oxMiddleName.
last_name	Nachname des Schülers.
grade_level	Das Attribut aus student.grade_level_attribute. Leer, wenn der Schlüssel nicht gesetzt ist.
email_address	Primäre E-Mail-Adresse, angepasst durch email_prepend_domain.
sis_username	Benutzername des Schülers.
password_policy	Der Wert von student.password_policy. Siehe Passwortrichtlinie für Schüler.
location_id	Primäre Schule des Schülers.
location_id_2 und folgende	Die weiteren Schulen des Schülers, in alphabetischer Reihenfolge.

Prüfungsbenutzer sind nicht Teil des Exports.

4.2.6. Roster

Tab. 4.7 Spalten von rosters.csv

Spalte	Quelle in UCS@school
roster_id	Der Klassenname und die person_id des Schülers, verbunden durch einen Bindestrich.
class_id	Name der Schulklasse oder Arbeitsgruppe.
student_id	Die person_id des Schülers.

Die Datei enthält nur Schüler. Lehrer werden einer Klasse über die Spalten instructor_id von classes.csv zugeordnet.

4.3. Hochgeladene Daten prüfen

Um zu sehen, was der Connector hochlädt, aktivieren Sie asm/store_zip in den App-Einstellungen und führen Sie die Synchronisation aus. Der Connector behält das Archiv dann in /var/lib/asm/.

Quellcode 4.2 Archive auflisten und das neueste entpacken

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

Vorsicht

Die Archive enthalten personenbezogene Daten. Löschen Sie sie, sobald Sie sie nicht mehr benötigen, und deaktivieren Sie asm/store_zip wieder.