Import-Format

Stammdaten kommen aus der Schulverwaltung. score nimmt sie im eigenen, kanonischen Format score-import entgegen – über die API, die Weboberfläche oder die Kommandozeile. Adapter für bestimmte Verwaltungsprogramme wandeln in dieses Format.

JSON

Eine Datei beschreibt den vollständigen Stand einer Einrichtung.

{
  "format": "score-import",
  "version": 1,
  "quelle": "demo",
  "einrichtung": "rs-am-hafen",
  "personen": [
    { "ref": "L-0001", "vorname": "Lena", "nachname": "Müller",
      "kennungen": [{ "idp": "idp-land", "subject": "lmueller" }] },
    { "ref": "S-0001", "vorname": "Mia", "nachname": "Neumann", "geburtsdatum": "2013-04-17" },
    { "ref": "E-0001", "vorname": "Paul", "nachname": "Neumann" }
  ],
  "mitgliedschaften": [
    { "person": "L-0001", "rolle": "fachlehrkraft" },
    { "person": "S-0001", "rolle": "schueler" },
    { "person": "E-0001", "rolle": "sorgeberechtigt" }
  ],
  "faecher": [{ "kuerzel": "DE", "name": "Deutsch" }],
  "klassen": [
    { "name": "7a", "jahrgang": 7, "bildungsgang": "mv.regionale-schule",
      "klassenleitung": "L-0001", "schueler": ["S-0001"] }
  ],
  "kurse": [
    { "ref": "DE-7a", "fach": "DE", "klasse": "7a", "name": "Deutsch 7a",
      "lehrkraefte": ["L-0001"], "teilnehmer": [{ "person": "S-0001", "anspruchsebene": "MR" }] }
  ],
  "sorgerechte": [{ "sorgeberechtigt": "E-0001", "schueler": "S-0001" }]
}

Feld	Inhalt
quelle	Quellsystem der Personenkennungen. Gleiche Quelle und gleiche ref an zwei Schulen ergeben dieselbe Person
einrichtung	Kennung der Einrichtung, deren Stand die Datei beschreibt
bereiche	optional: Datenarten, die die Datei führt (Bereichsabgleich, siehe unten); ohne Angabe Vollabgleich
personen	mit ref; optional geburtsdatum, kennungen (Identitätsanbieter und Subject) für die Anmeldung und vorhanden (quelle und ref derselben Person aus einem anderen Quellsystem)
mitgliedschaften	Person, Rolle, optional von/bis; Gastschüler mit stammschule (Schule derselben Installation) oder stammschule_extern (Kennung einer Schule auf einer anderen Installation; Noten gehen dann per Austauschdatei)
faecher	Kürzel, Name, optional Art und übergeordnetes Fach (Lernfelder als Baum)
klassen	Name, optional anzeigename (alternativer Klassenname für Übersichten), Jahrgang, bildungsgang (Kennung des Regelpakets), Klassenleitung, Schüler
kurse	Fach, optional Klasse, Kursart (LK/GK) und Halbjahr, Lehrkräfte, Teilnehmende mit Anspruchsebene oder klasse_belegen (alle Schüler der Klasse)
betriebe, ausbildungen	für die Berufsschule
sorgerechte	Sorgeberechtigte Person und Schüler

Verweise innerhalb der Datei laufen über ref, Fachkürzel und Klassennamen. Unbekannte Felder sind ein Fehler, und die Prüfung sammelt alle Fehler, statt beim ersten abzubrechen.

CSV

Ein Verzeichnis mit personen.csv und mitgliedschaften.csv (Pflicht), optional klassen.csv, klassen_schueler.csv und sorgerechte.csv. Semikolon als Trenner, Kopfzeile, Datum als JJJJ-MM-TT oder TT.MM.JJJJ. score-api csv2json <verzeichnis> wandelt in das JSON-Format.

Ablauf

1. Probelauf: Der Import läuft in einer Transaktion im Kontext genau dieser Einrichtung und wird am Ende zurückgerollt. Der Bericht ist deshalb identisch mit dem der Übernahme.
2. Bericht: je Objektart neu, geändert, unverändert, entfernt und „nicht im Import“, dazu die einzelnen Änderungen.
3. Übernahme: dieselbe Transaktion mit Commit, im Audit-Log als Massenvorgang vermerkt.

Abgleich

• Personen werden über (quelle, ref) zugeordnet, nie über Namen.
• Fehlende Mitgliedschaften enden gestern; fehlende Zuordnungen (Klasse, Kurs, Lehrauftrag, Sorgerecht) werden entfernt.
• Fehlende Fächer, Klassen, Kurse, Betriebe und Ausbildungen bleiben bestehen und erscheinen im Bericht als „nicht im Import“ – an ihnen können Noten hängen.
• Login-Kennungen werden nur ergänzt, nie entfernt.

Bereichsabgleich

Für Programme, die nur einen Teil der Stammdaten führen (Stundenplan, z. B. Untis): die Datei nennt in bereiche die Datenarten, für die sie maßgeblich ist.

Bereich	gleicht ab
mitgliedschaften	alle Mitgliedschaften
lehrkraefte	nur Mitgliedschaften mit Rolle fachlehrkraft
faecher, klassen, kurse, betriebe, ausbildungen	diese Objekte
klassenzugehoerigkeit, lehrauftraege, belegungen, sorgerechte, stundentafeln	diese Zuordnungen

• Entfernt oder beendet wird nur in den genannten Bereichen; alles andere bleibt unberührt.
• Jeder Abschnitt mit Daten muss als Bereich genannt sein, sonst ist die Datei ungültig.
• Leere optionale Felder (Jahrgang, Bildungsgang, Klassenleitung, Klasse eines Kurses, Kursart, Ort) überschreiben keine vorhandenen Werte.
• Kurse dürfen auf Fächer und Klassen im Bestand verweisen.
• Bestehende Personen werden nicht geändert; mit vorhanden wird eine Person verknüpft, die aus dem führenden System (z. B. der Schulverwaltung) schon bekannt ist.
• Zuordnungen (Klassenzugehörigkeit, Lehraufträge, Belegungen) gleicht der Import nur für die Klassen und Kurse der Datei ab; die anderer Kurse bleiben.

Untis

Auf der Seite Import unter „Aus Untis“ die GPU-Dateien hochladen; score wandelt sie um und zeigt den Probelauf, übernommen wird wie bei JSON erst nach Bestätigung. Auf der Kommandozeile: score-api untis2json -einrichtung <kennung> [-zuordnung lehrkraefte.csv] [-schueler-quelle <quelle>] <verzeichnis>. Gelesen werden GPU002 Unterricht, GPU003 Klassen, GPU004 Lehrer, GPU006 Fächer und mit Schülerquelle GPU010 Schüler und GPU015 Kurswahlen.

• Bereiche: Fächer, Klassen, Kurse, Lehraufträge, Belegungen und Lehrkräfte (Rolle fachlehrkraft). Schüler, Klassenzugehörigkeit und Klassenleitungen führt weiter die Schulverwaltung.
• Ein Kurs je Unterrichtsnummer und Klasse (untis-<Nummer>-<Klasse>); gekoppelte Lehrkräfte unterrichten ihn gemeinsam. Unterricht der ganzen Klasse (ohne Schülergruppe) belegen alle Schüler der Klasse.
• Kurswahlen (Schülergruppen, Oberstufe): mit -schueler-quelle bzw. dem Feld auf der Seite verknüpft score die Schüler über ihre Kennung in der Schulverwaltung (GPU010 Feld 15, Fremdschlüssel) und belegt die gewählten Kurse. Schüler ohne Kennung werden übergangen und im Hinweis gezählt; ohne Schülerquelle bleiben Gruppenkurse ohne Belegung.
• Nur genutzte Fächer, Klassen und Lehrkräfte; der Langname einer Klasse wird ihr Anzeigename.
• lehrkraefte.csv (kuerzel;quelle;ref) verknüpft Lehrerkürzel mit Personen aus der Schulverwaltung, sonst legt der Import die Lehrkräfte neu an.
• Trennzeichen Komma, Semikolon oder Tabulator, Zeichensatz UTF-8 oder Windows-1252 werden je Datei erkannt. Untis vergibt Unterrichtsnummern je Schuljahresdatei, ein neues Schuljahr ergibt neue Kurse.
• Ausprobieren ohne echten Export: score-api generate-untis [-einrichtung demo-gym-wall] [-variante standard|semikolon-utf8|tabulator] <verzeichnis> schreibt einen simulierten Export einer Demo-Schule samt lehrkraefte.csv; als Schülerquelle demo angeben.

Rechte

Über API und Oberfläche importieren Schuladmin und Schulleitung der jeweiligen Einrichtung. Die Kommandozeile (score-api import <datei> [-uebernehmen]) ist für den Betrieb gedacht.