~~NOTOC~~
====== Allgemeine XML-Export-Schnittstelle ======
<WRAP round info>
Auf dieser Seite finden Sie technische Informationen zur **allgemeinen** XML-Exportschnittstelle, d.h. zum Schnittstellenframework. Informationen zu konkreten Schnittstellen**implementierungen**, insbesondere deren genaue Definition, finden Sie auf folgenden Seiten:
  * [[alle:schnittstellen:xml_sst:xmlexportnotenverwaltung:start|XML-Exportschnittstelle für Verfahren zur Notenverwaltung]]
  * [[alle:schnittstellen:xml_sst:xmlexportmehrarbeitsverguetung:start|Exportschnittstelle für Verfahren zur Mehrarbeitsvergütung]]

</WRAP>

==== Allgemein ====
Die allgemeine XML-Export-Schnittstelle ist ein Framework, das eine umfassende Baumstruktur beschreibt und in der Lage ist, beliebige Teilbäume daraus als gepackte und verschlüsselte XML-Datei zu exportieren.
==== Aufbau Exportdatei ====
  * Die exportierte Datei ist ein ZIP-Container. Dieser ist mit AES-256 verschlüsselt.
  * In der ZIP-Datei befindet sich eine einzelne XML-Datei namens ''export.xml''.
  * Der nähere Aufbau der ''export.xml'' wird für konkrete Instanzen eines XML-Exports (wie z. B. Notenverwaltung) jeweils dokumentiert durch
    * eine XML Schema Definition (XSD-Datei). Diese enthält auch Erläuterungen (aus Schema Spy übernommen) und beschreibt damit den Aufbau der exportierten XML-Dateien aus syntaktischer und semantischer Sicht.
    * eine ZIP-Datei, welche alle bei diesem Export tangierten Wertelisten als XML-Dateien enthält.\\ <wrap important>Bei den Wertelisten haben die sog. //Standardwertelisten// gleichen strukturellen Aufbau; einige sog. //spezielle Wertelisten// weichen jedoch davon ab.</wrap>

<WRAP round info>
== Das Tag <xml_id> ==
XML stellt bekanntlich nur baumartige Strukturen dar. Wo "Querreferenzen" im Baum notwendig werden, wird in referenzierten XML-Elementen eine ID mit dem Tag ''<xml_id>'' gesetzt; die Referenzen selbst lauten ''*_id'' (soll z. B. ein ''<lehrkraft>''-Element mit ''xml_id'' 1011 referenziert werden, geschieht dies mit ''<lehrkraft_id>1011</lehrkraft_id>'').

<wrap important>Die ''xml_id'' wird einzig innerhalb der XML-Struktur benutzt und kann sich bei jedem Export ändern. Für verbindliche IDs siehe nächsten Kasten.</wrap>
</WRAP>

<WRAP round info>
== Lokales Differenzierungsmerkmal für Lehrkräfte und Schüler ==
Bei Import-Vorgängen muss eine eindeutige Zuordnung zwischen zu importierenden und bestehenden Datensätzen geleistet werden; dies betrifft ASV selbst als auch andere Verfahren.

Zu diesem Zweck wird für die XML-Elemente ''<lehrkraftdaten_nicht_schulbezogen>'' und ''<schuelerin>'' jeweils ein eindeutiger Schlüssel namens ''<del><lfd_nr></del><lokales_differenzierungsmerkmal>'' ausgespielt.
Für dieses wird zugesichert:
  * Es identifiziert eine Lehrkraft bzw. einen Schüler eindeutig innerhalb der ASV-Datenbasis (d. h. je nach Installationsvariante schulweit, Schulzentrums-weit oder sogar Sachaufwandsträger-weit).
  * Es ist unveränderlich; sie bleibt insbesondere erhalten bei
    * Schuljahreswechsel und
    * Rückspielen von Datenbank-Backups.
  * Es wird nur einmal vergeben. Auch das "lokale Differenzierungsmerkmal" ausgetretener Personen wird nicht wieder an neu eintretende Personen vergeben.
</WRAP>

==== Benutzung ====
=== Installation des Exports in ASV ===
Der Notenverwaltungs-Export und weitere XML-Exporte wird von Seiten des StMBW in ASV integriert. Die einzelnen Schnittstellen werden über den Prozess "Anwendungsdaten aktualisieren" veröffentlicht.

=== Export in der ASV-GUI vornehmen ===
  * im Menü ''Datei->Verwaltung->Schnittstellen'' auswählen
  * im Navigator rechts den passenden Export (im Moment nur Notenverwaltung) auswählen
  * rechts unten Button ''Start...'' auswählen
  * Es startet ein Export-Assistent, in dem die zu exportierenden Schulen sowie Ausgabe-Pfad und -Dateiname ausgewählt werden können
  * Nach erfolgtem Export wird das Passwort zum Entschlüsseln der erzeugten Datei sowohl am Bildschirm angezeigt als auch in die Zwischenablage gelegt.

=== Transport der Export-Datei ===
Die Programme in der Schullandschaft, in die die Daten importiert werden sollen, sind sehr heterogen aufgestellt:
Möglicherweise...
  * läuft das Programm auf dem selben Rechner wie der exportierende ASV-Client
  * handelt es sich um zwei verschiedene Rechner innerhalb des Verwaltungsnetzes der Schule
  * wird die Export-Datei auf einem externen Datenträger (z. B. USB-Stick) transportiert
  * muss die Export-Datei auf einen Web-Server eines [[alle:datenschutz:auftragsdatenverarbeitung:start|Auftragsdaten-Verarbeiters]] geladen werden

=== Import in einem Schulverwaltungs-Programm ===
Idealerweise wird das importierende Schulverwaltungs-Programm die Schritte
  - Passwort vom Benutzer erfragen
  - ZIP-Datei auspacken
  - die enthaltene ''export.xml'' lesen und weiter verarbeiten
  - womöglich (z. B. beim Auspacken der ZIP-Datei) entstandene temporäre Dateien zuverlässig löschen

automatisiert vornehmen, so dass es dem Benutzer erspart bleibt, am Ziel-Rechner selbst mit ZIP-Programmen umgehen zu müssen.

<WRAP round info>
== Für Schritt 2 (ZIP-Datei auspacken) sehen wir folgende Implementierungs-Möglichkeiten, sortiert nach Präferenz (beste Lösung zuerst): ==
  - Benutzung einer Programmbibliothek, nach Möglichkeit in der benutzten Programmiersprache selbst. Beispiele für ZIP-Programmbibliotheken mit AES-Unterstützung:
    * **Zip4j** (für Java) [[http://www.lingala.net/zip4j/]]
    * **DotNetZip** (für .NET-Sprachen) [[http://dotnetzip.codeplex.com/]]
  - automatisierte Benutzung eines ZIP-Kommandozeilenprogramms durch das Schulverwaltungsprogramm. Gängige Programmiersprachen sollten Prozesse starten können, ohne dass ein Konsolen-Fenster "aufpoppt" (in vielen gängigen Programmiersprachen (.NET-Sprachen, Java) mittels einer ''Process''-Klasse). Beispiele für ZIP-Kommandozeilenprogramme mit AES-Unterstützung:
    * **7-Zip**s ''7z.exe'' (für Windows) [[http://www.7-zip.de/]]
    * **p7zip**s ''7z'' (für Posix-Systeme; in Linux Bestandteil vieler Distibutionen) [[http://sourceforge.net/projects/p7zip/]]
  - Der Benutzer muss auf dem Zielrechner manuell die ZIP-Datei mittels eines ZIP-Programms mit GUI auspacken :-(. Beispiele für GUI-ZIP-Programme mit AES-Unterstützung:
    * **7-Zip** [[http://www.7-zip.de/]]
    * **WinZip** [[http://www.winzip.de/]]
    * **WinRAR** [[http://www.winrar.de/]]
</WRAP>

<WRAP round important>Leider unterstützen viele ZIP-Programme und -Programmbibliotheken keine Verschlüsselung oder nur die ältere, unsicherere ZipCrypto-Verschlüsselung.</WRAP>

==== FAQ ====
[[alle:schnittstellen:xml_sst:xmlexport:faq|Häufig gestellte Fragen]] aus Sicht der Entwickler von Schulverwaltungsprogrammen
==== Kontakt ====
Für technische Unterstützung und Feedback stehen von Seiten des StMUK zur Verfügung:

  * Matthias Gold [[matthias.gold@stmuk.bayern.de]]
  * Leonhard Fellermayr [[leonhard.fellermayr@stmuk.bayern.de]]