====== Importschnittstelle für Zeugnisnoten - Dokumentation für externe Entwickler ======
===== Anpassungen April 2024 =====
In der Version **0.25** der Importschnittstelle wird das Element <belegart> als Unterelement des XML Knoten <Note> hinzugefügt. Wenn Zeugnisnoten importiert werden und keine Belegart vorhanden ist, wird der Defaultwert der Datenbank (13 entspricht Pflichtunterricht) eingebucht. Durch diese Erweiterung ist es nun möglich, unter anderem die Noten des Projekt-Seminars zur beruflichen Orientierung (11. Jahrgangsstufe) am Gymnasium über die Importschnittstelle zu importieren.

===== Aufruf/Bedienung in ASV =====
Hier finden Sie eine [[alle:schnittstellen:xml_sst:zeugnisnotenimport:anleitung_fuer_schulen:start|Anleitung für die Schulen]] zur Benutzung der Schnittstelle in ASV.

===== 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]]

===== Vorgehen der Schnittstelle beim Import =====
  * In der Importdatei können Noten zu beliebig vielen Zeugnisarten beliebig vieler Schüler beliebig vieler Schulen enthalten sein. 
  * Zu jedem Zeugnis können auch Informationen zum Erreichen des Ziels der Jahrgangsstufe und zur Gefährdung (Zwischenzeugnis!) in der Importdatei enthalten sein.
  * Die Identifikation der Schüler geschieht entweder (vorzugsweise!) über Angabe des lokalen Differenzierungsmerkmals oder über gleichzeitige die Angabe folgender vier Merkmale des Schülers:
    * Familienname
    * Rufname
    * Geburtsdatum
    * Geschlecht
  * Kann die Schnittstelle einen Schüler und die angegebene Zeugnisart identifizieren, so löscht sie zunächst alle Noten des Schülers zur angegebenen Zeugnisart und schreibt dann die in der Importdatei angegebenen Noten in die Datenbank.
====== Importformat ======
Die Schnittstelle erwartet eine XML-Datei mit festgelegtem Format. In der hier herunterladbaren {{alle:schnittstellen:xml_sst:zeugnisnotenimport:doku_fuer_externe:zeugnisnotenimport_entwicklerdokumentation_0.25.zip|Entwicklerdokumentation, Stand 29.04.2024}} finden Sie
  * Die [[http://de.wikipedia.org/wiki/XSD|XSD-Datei]] Zeugnisnotenimport_xxx.xsd zur Beschreibung der akzeptierten Struktur
  * Ein Zip-Archiv Zeugnisnotenimport_Wertelisten_xxx.zip mit allen benutzten Wertelisten im HTML-Format
  * Eine Beispieldatei Schülerstammdatenimport Beispiel-Importdatei_Zeugnisnoten.xml, die schulisch zwar keinen Anspruch auf Korrektheit erhebt, aber auf einfache Art klärt, wie Header/Kodierung/Struktur einer zulässigen XML-Datei aussehen könnten.

<WRAP center round tip 80%>
Die Schnittstelle akzeptiert auch in Zip-Archive **gepackte** und per AES **verschlüsselte** Dateien (Dateiendung: .zip). Innerhalb des Zip-Archivs muss sich eine XML-Datei (Endung: .xml) befinden, die die Importdaten enthält. \\
Erfolgreich getestet wurden bereits Archive, die mit 
  * [[http://www.7-zip.org/|7-zip]]
  * [[http://www.lingala.net/zip4j/| Zip4j]]
erstellt wurden. \\

Falls sich das Passwort für das Zip-Archiv in der Zwischenablage befindet, erkennt dies die Importschnittstelle und verzichtet auf die Passwortabfrage. \\
\\
Im Interesse des praktischen Datenschutzes möchten wir Sie nachdrücklich darum bitten, nur verschlüsselte zip-Archive zu exportieren. Die Passwörter sollten zufällig generiert und am Bildschirm angezeigt werden. Falls sie zudem automatisch in die Zwischenablage kopiert werden, vereinfacht dies das Vorgehen für die Programmbenutzer (vorausgesetzt, der ASV-Client und die exportierende Software befinden sich auf einem Rechner).</WRAP>
===== Kardinalität/Pflichtelemente =====
Die Kardinalität der XML-Elemente ersehen Sie in der XSD-Datei durch die Angaben ''minOccurs'' und ''maxOccurs'', beispielsweise
<code XML>
<element name="schule" minOccurs="0" maxOccurs="unbounded">
</code>
Insbesondere werden **Pflichtelemente** gekennzeichnet durch ''minOccurs="1"''.

===== Datentypen =====
Die in der XML-Datei akzeptierten Datentypen werden als ''<restriction>''-Elemente im XSD formuliert, beispielsweise
<code XML>
<restriction base="string">
   <pattern value="\d\d\d\d"></pattern>
</restriction>
</code>
für eine vierstellige Schulnummer, 
<code XML>
<restriction base="string">
   <maxLength value="32"></maxLength>
</restriction>
</code>
für längenbeschränkten Text,
<code XML>
<restriction base="string">
   <pattern value="(true|false)"></pattern>
</restriction>
</code>
für einen booleschen Wert oder
<code XML>
<restriction base="string">
   <pattern value="(0[1-9]|[12][0-9]|3[01])\.(0[1-9]|1[012])\.(19|20)\d\d"></pattern>
</restriction>
</code>
für einen Datumswert.

===== Referenzen auf Werte aus ASV-Wertelisten =====
Referenzen auf Werte aus ASV-Wertelisten haben in der XSD-Datei folgende Form:
<code XML>
  <element name="ziel_jgst_vorjahr" minOccurs="0" maxOccurs="1">
	<annotation>
	  <appinfo>
		<werteliste plkey="2185">Klassenziel</werteliste>
	  </appinfo>
	  <documentation><![CDATA[Information über das Erreichen des Ziels der Jahrgangsstufe im Vorjahr]]></documentation>
	</annotation>
	<simpleType>
	  <restriction base="string">
		<maxLength value="40"></maxLength>
	  </restriction>
	</simpleType>
  </element>
</code>
Hieraus ist ersichtlich, dass in der Importdatei ein Wert aus der Werteliste ''Klassenziel'' (Wertelistennummer: ''2185'') erwartet wird. Sie finden die vollständige Werteliste im Wertelistenverzeichnis (''Schuelerstammdatenimport_Wertelisten_xxx.zip'') in der Datei ''Klassenziel_(2185).xml''. 

Ein Beispieleintrag in der **Werteliste** (//nicht in der Importdatei!//) sieht so aus:
<code XML>
  <eintrag>
    <schluessel><![CDATA[50]]></schluessel>
    <kurzform><![CDATA[e]]></kurzform>
    <anzeigeform><![CDATA[Klassenziel erreicht]]></anzeigeform>
    <langform><![CDATA[Ziel der Jahrgangsstufe erreicht]]></langform>
    <bemerkung><![CDATA[#kuerzel_alt=50#nicht BS/BSF]]></bemerkung>
    <schulart_schluessel><![CDATA[04]]></schulart_schluessel>
    <schulart_kurzform><![CDATA[GY]]></schulart_kurzform>
    <schulart_anzeigeform><![CDATA[Gymnasium]]></schulart_anzeigeform>
  </eintrag>
</code>
<WRAP center round important 60%>
In der XML-Importdatei wird von diesem Eintrag nur der Wert des Feldes ''schluessel'' erwartet.
</WRAP>

Ein gültiges Element für die **Importdatei** wäre also
<code XML>
<ziel_jgst_vorjahr>50</ziel_jgst_vorjahr>
</code>

<WRAP center round important 60%>
Bitte achten Sie darauf, nur Werte zu übermitteln, die zur Schulart der importierenden Schule passen. Der obige Wert ''50'' in der Werteliste ''Klassenziel'' passt beispielsweise zur Schulart Gymnasium (siehe obigen Eintrag). 
\\ 
//Natürlich kann ein Schlüsselwert zu mehreren Schularten passen. Zu welchen, ersehen Sie aus der XML-Datei, die die Werteliste enthält.//
</WRAP>
===== Dokumentation zur schulfachlichen Semantik der Elemente =====
Schulfachliche Dokumentation ist in der XSD-Datei in ''<documentation>''-Elementen abgelegt, beispielsweise
<code XML>
  <element name="auswaertige_unterbringung" minOccurs="0" maxOccurs="1">
	<annotation>
	  <documentation><![CDATA[Gastschulverhätlnis: auswärtige Unterbringung 
             notwendig? Nur anzugeben für Gastschüler bzw. Umschüler! Für den Besuch 
             der Berufsschule ist eine auswärtige Unterbringung gemäß Art. 10 Abs.8, 
             Art. 20 Abs. 1 oder Art. 37 BaySchFG notwendig .]]>
          </documentation>
	</annotation>
	<simpleType>
	  <restriction base="string">
		<pattern value="(true|false)"></pattern>
	  </restriction>
	</simpleType>
  </element>
</code>