====== Schnittstelle zum Import von Schülerstammdaten in ASV ======
===== Status =====

**Updates:**
  * Beim Import mehrerer Schüler in eine Klasse, die in ASV //noch nicht// existiert, wird diese Klasse //mehrfach// angelegt. Workaround: Klasse und Klassengruppe, in die importiert werden soll, vorher anlegen. \\ -> **Fixed in Version 0.57**
  * Die Fortschrittsanzeige beim Schreiben in die Datenbank bewegt sich nicht proportional zur verstrichenen Zeit, sondern geht relativ schnell auf "100%" und verbleibt dann sehr lange dort, bis der Import abgeschlossen ist. \\ -> **Fixed in Version 0.57**
  * Die Anschrift des ersten Erziehungsberechtigten wird nicht übernommen \\ -> **Fixed in Version 0.6**
  * Die Herkunftsschule ist Pflichtfeld \\ -> **Fixed in Version 0.61**
  * ** Neues in Version 0.62:** 
    * Es gibt ein neues Element ''<anmeldedatum>'' (XML-Pfad: /schuelerstammdaten-import/schulen/schule/schuelerinnen/schuelerin/schullaufbahn/eintritt/anmeldedatum). Ist es nicht gesetzt, so wird Anmeldedatum = aktuelles Tagesdatum beim Import gesetzt, damit die entsprechende Maskenplausibilitätsprüfung im Schülermodul sicher nicht anschlägt (siehe [[https://forum.asv.bayern.de/beitraege/schuelerdaten/nach_update_verfaelschtes_eintrittsdatum_in_5_klasse/seite/1.html#pid5302|dieser Forumsbeitrag]].)
    * Das Feld "Im Schriftverkehrverteiler" bei den Anschriften der Erziehungsberechtigten wird automatisch vorbesetzt. Haben sie die selbe Anschrift, so ist es bei beiden gesetzt. Haben sie unterschiedliche Anschriften, so wird es nur beim 1. Erziehungsberechtigten gesetzt.
  * ** Neues in Version 0.63:**
    * Unterhalb des Elements <schuelerstammdaten> gibt es jetzt das Element <aufnahmeberechtigung> zum Import des gleichnamigen Attributs aus dem Reiter "Ein-/Austritt".
    * Unterhalb des Elements <schuelerstammdaten> gibt es jetzt das Element <zusaetzliche_ansprechpartner_liste> mit Unterelementen <zusaetzlicher_ansprechpartner> zur Erfassung der Zusätzlichen Ansprechpartner (gleichnamiger Reiter unter "Anschriften").
  * ** Neues in Version 0.64: (Rollout voraussichtlich Juli 2016)**
    * Unterhalb des Elements <anschriftreiterdaten> gibt es jetzt die optionalen Elemente <hauptansprechpartner>, <auskunftsberechtigt> und <imverteilerschriftverkehr> (Werte jeweils true oder false).
  * ** Neues in Version 0.65: (Rollout voraussichtlich September 2016):**
    * Das Element <austritt> ist kein Pflichtelement mehr.
  * ** Version 0.66: **
    * Es handelt sich um keine neue Schnittstellenversion. Verbessert wurde lediglich die Beispiel-Importdatei in den Entwicklermaterialien (siehe unten), da zwei Wertelistenschlüssel veraltet waren.
===== Aufruf/Bedienung in ASV =====
Hier finden Sie eine [[alle:schnittstellen:xml_sst:schuelerstammdatenimport:anleitung_fuer_schulen:start|Anleitung für die Schulen]] zur Benutzung der Schnittstelle in ASV.


====== Importformat ======
Die Schnittstelle erwartet eine XML-Datei mit festgelegtem Format. Hier finden Sie Details zur [[.versionshistorie|Versionshistorie]].

In der hier herunterladbaren 

{{ :alle:schnittstellen:xml_sst:schuelerstammdatenimport:doku_fuer_externe:schuelerstammdatenimport_0.66.zip |schuelerstammdatenimport_0.66.zip}} finden Sie
  * Die [[http://de.wikipedia.org/wiki/XSD|XSD-Datei]] Schülerstammdatenimport_xxx.xsd zur Beschreibung der akzeptierten Struktur
  * Ein Zip-Archiv Schuelerstammdatenimport_Wertelisten_xxx.zip mit allen benutzten Wertelisten im XML-Format
  * Eine Beispieldatei Schülerstammdatenimport(Beispieldaten)_xxx.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%>
Ab Version 0.57 akzeptiert die Schnittstelle 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>

<WRAP center round tip 60%>
Tipp: Die Wertelisten im XML-Format sind "flach", daher lassen sie sich über Datei->Öffnen ganz einfach in Excel öffnen und als übersichtliche Tabelle darstellen.
</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>

===== Das Element <anschriftreiterdaten> =====
Besondere Beachtung verdient das Element <anschriftreiterdaten>, da die Möglichkeiten, Anschriften für einen Schüler, seine Erziehungsberechtigten, weiteren Ansprechpartner usw. in ASV zu erfassen und miteinander zu verknüpfen, vielfältig sind. 

Hier finden Sie eine [[anschriftreiterdaten| genaue Beschreibung des Elements <anschriftreiterdaten>]].