====== Datenverbund Client (DVUH Client) ======
FH Complete stellt einen Client für die Anbindung zum Datenverbund zur Verfügung. DVUH steht für "Datenverbund der Universitäten und Hochschulen" und ermöglicht das Melden von Studierendendaten. Es ist eine Vorstufe zur Bismeldung. Schnittstellendokumentation: [[https://stubei-q.portal.at/rws/swagger-ui.html
]].
==== DVUH Extension installieren und konfigurieren ====
Die Schnittstelle zu DVUH wird über die DVUH Extension zur Verfügung gestellt:
[[https://github.com/FH-Complete/FHC-Core-DVUH.git]]

Zur Installation und Inbetriebnahme der Extension sind folgende Schritte nötig:

  * Installieren der FHC-Core-DVUH Extension wie in [[developer:extensions|Extensions]] beschrieben
  * Angeben der korrekten Verbindungsdaten (portal, username, password) in der configdatei config/DVUHClient.php. Diese können auch als Konstanten in der vilesci.config.inc.php angelegt und in der Extension config referenziert werden. (DVB_PORTAL, DVB_USERNAME, DVB_PASSWORD). 
  * Angeben weiterer Konfigurationsdaten: //fhc_dvuh_be_code// zur Identifikation der Bildungseinrichtung (z.B. "FT" für Technikum Wien, DVB_BILDUNGSEINRICHTUNG_CODE), //fhc_dvuh_path// für die Umgebung (Teil der Aufruf-URL, für die sandbox-Testunmgebung z.B. 'sandbox')
  * Cronjobs aktivieren damit Meldungen an den Datenverbund laufend durchgeführt werden (siehe DVUH Jobs starten)

==== Weitere Konfiguration (optional) ====
DVUHSync.php Konfigurationdatei: 
  * //fhc_dvuh_log_infos// - wenn auf true gesetzt, werden neben Fehlern und Warnungen auch Infomeldungen (z.B. erfolgreiche Speicherung von Daten) ausgegeben (kann zu vielen Einträgen in der Logtabelle führen!)
  * //fhc_dvuh_status_kurzbz// - Angabe (mehrerer) Status pro Jobtyp, welche berücksichtigt werden. So kann z.B. der Job sendStudyData Studenten ab dem Status "Student" an DVUH schicken, sendCharge aber schon ab "Aufgenommener". 
  * //fhc_dvuh_buchungstyp// zur Identifikation der bei der Zahlungsvorschreibung zu berücksichtigenden Buchungstypen.
  * //fhc_dvuh_oe_kurzbz// - Einschränkung der Studierenden nach Organisationseinheit (bzw Studiengang). Studierende, die der angegebenen Organisationseinheit oder einer Organisationseinheit unterhalb der angegeben Organisationseinheit zugeordnet sind (über ihren Studiengang), werden berücksichtigt.
  * //fhc_dvuh_sync_days_valutadatum//, //fhc_dvuh_sync_days_valutadatumnachfrist// - Zahlungsfrist in Tagen ab Buchungsdatum der Vorschreibung. Wenn innerhalb dieser Zeitspanne + Nachfrist (config Eintrag //fhc_dvuh_sync_days_valutadatumnachfrist//) bezahlt wird, wird die Zahlung von DVUH als rechtzeitig bezahlt angesehen und ein entsprechender Bezahlstatus vergeben.
  * //fhc_dvuh_studiensemester_meldezeitraum// - definiert alle Semester, für welche Studierende standardmässig an den Datenverbund geschickt werden. Pro Semester wird ein "von"- und ein "bis"-Datum in Array-Form angegeben. Fällt der Tag des Jobaufrufs in die Zeitspanne eines Semesters, so werden Studierende dieses Semesters mit synchronisiert. Trifft das für mehrere Studiensemester zu, werden die älteren Semester zuerst abgearbeitet. Beispiel für drei aufeinanderfolgende Studiensemester:

  $config['fhc_dvuh_studiensemester_meldezeitraum'] = array(
	  'SS2021' => array(
		  'von' => '2021-01-01', // SS from 01.01
		  'bis' => '2021-05-31' // SS to 31.05
	  ),
	  'WS2021' => array(
		  'von' => '2021-06-01', // WS from 01.06
		  'bis' => '2022-03-31' // WS to 31.03
	  ),
	  'SS2022' => array(
		  'von' => '2022-01-01', // SS from 01.01
		  'bis' => '2022-05-31' // SS to 31.05
	  )
  );

==== DVUH Jobs starten ====
Es werden eine Reihe von Jobs unterstützt, die laufend von FH Complete holen und an den DVUH senden, und in manchen Fällen Daten in FH Complete speichern. Zum Starten der Jobs sind 2 Schritte notwendig:

  - Starten des Schedulers, welcher die an den DVUH zu sendenden Daten bestimmt und die Ids für diese Daten in einer "Jobsqueue" (Tabelle system.tbl_jobsqueue) ablegt.
  - Starten des eigentlichen Jobs ("Worker"), welcher die vom Scheduler gespeicherten Ids ausliest, für die entsprechenden Daten Aktionen durchführt und mit dem DVUH interagiert. 

Pro Job gibt es demnach zwei Aufrufe, den Scheduler- und den Workeraufruf:


**requestMatrikelnummer**

  * Scheduler: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/JQMScheduler/requestMatrikelnummer/SS2021''
  * Worker: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/DVUHManagement/requestMatrikelnummer''

**sendCharge**

  * Scheduler: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/JQMScheduler/sendCharge/SS2021''
  * Worker: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/DVUHManagement/sendCharge''

**sendPayment**

  * Scheduler: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/JQMScheduler/sendPayment/SS2021''
  * Worker: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/DVUHManagement/sendPayment''

**sendStudyData**

  * Scheduler: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/JQMScheduler/sendStudyData/SS2021''
  * Worker: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/DVUHManagement/sendStudyData
''
**
requestBpk**

  * Scheduler: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/JQMScheduler/requestBpk/SS2021''
  * Worker: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/DVUHManagement/requestBpk''

**sendPruefungsaktivitaeten**

  * Scheduler: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/JQMScheduler/sendPruefungsaktivitaeten/SS2021''
  * Worker: ''php index.ci.php extensions/FHC-Core-DVUH/jobs/DVUHManagement/sendPruefungsaktivitaeten''


Diese Aufrufe sollten von Cronjobs in festgelegten Zeitabständen ausgeführt werden. Die Meldungen erfolgen für ein als Parameter angegebenes Studiensemester (oben SS2021). Wenn der Studiensemester Parameter weggelassen wird, werden die Studiensemester aus der config Datei DVUHSync.php herangezogen (siehe Konfiguration //fhc_dvuh_studiensemester_meldezeitraum//). 

==== DVUH Jobs Beschreibung ====
Alle Jobs werden für ein bestimmtes Studiensemester aufgerufen.

**requestMatrikelnummer**
  * Input: person Ids von aufgenommenen Studierenden mit validem Prestudentstatus im Studiensemester, für welche
    * keine Matrikelnummer existiert
  * Ablauf: 
    - Prüfen, ob Matrikelnummer in DVUH vorhanden ist (matrikelpruefung.xml).
    - Wenn Matrikelnummer in DVUH vorhanden, wird diese in FH Complete übernommen und auf aktiv gesetzt
    - Wenn keine Matrikelnummer in DVUH vorhanden ist, wird eine neue Matrikelnr reserviert (matrikelreservierung.xml) und in FH Complete als inaktiv (noch nicht scharfgeschalten) gespeichert
    - Abschließend wird eine Stammdatenmeldung (stammdaten.xml) mit der neuen Matrikelnummer durchgeführt.
  * Resultat:
     * Gespeicherte Stammdaten in DVUH (inkl. Zahlungsvorschreibung wenn vorhanden)
     * Matrikelnummer in FH Complete

**sendCharge**
  * Input: person Ids von aufgenommenen Studierenden mit validem Prestudentstatus im Studiensemester, für welche
    * in dem Studiensemester noch keine Stammdaten gemeldet wurden ODER
    * eine Zahlungsvorschreibung in FH Complete, aber nicht in DVUH gespeichert ist ODER
    * seit der letzten Stammdatenmeldung eine Datenänderung erfolgt ist
  * Ablauf: 
    - Es wird eine Stammdatenmeldung (stammdaten.xml) durchgeführt.
  * Resultat: 
    * Gespeicherte Stammdaten in DVUH (inkl. Zahlungsvorschreibung wenn vorhanden)
**sendPayment**
  * Input: person Ids von aufgenommenen Studierenden mit validem Prestudentstatus im Studiensemester, für welche
    * eine Zahlungsbuchung in FH Complete vorhanden ist UND
    * in dem Studiensemester noch keine Zahlungen für diese Buchung an den DVUH gemeldet wurden
  * Ablauf: 
    - Es wird eine Zahlungsmeldung (zahlung.xml) pro relevante Buchung durchgeführt.
  * Resultat: 
    * Gespeicherte Zahlungen in DVUH

**sendStudyData**
  * Input: person Ids von Studierenden (mind. Status "Student") mit validem Prestudentstatus im Studiensemester, für welche
    * in dem Studiensemester eine Zahlungsvorschreibung an den DVUH gesendet (Ausnahme: Abbrecher, Unterbrecher, Absolvent) wurde UND
    * in dem Studiensemester noch keine Studiumsmeldung durchgeführt wurde ODER es Datenänderungen seit der letzten Studiumsmeldung gab
  * Ablauf: 
    - Es wird eine Studiumsmeldung (studium.xml) durchgeführt.
    - Bei erfolgreicher Studiumsmeldung wird die Matrikelnummer in FH Complete scharfgeschalten (matr_aktiv = true)
  * Resultat: 
    * Gespeicherte Studiumsmeldung in DVUH
    * Scharfgeschaltene Matrikelnummer in FH Complete

**requestBpk**
  * Input: person Ids von aufgenommenen Studierenden mit validem Prestudentstatus im Studiensemester, für welche keine Bpk existiert
  * Ablauf: 
    - Es wird geprüft, ob eine Bpk im DVUH existiert (pruefebpk.xml). Hierzu werden Vorname, Nachname, Geburtsdatum und Geschlecht der studierenden Person übermittelt.
    - Falls mehrere Bpks zurückkommen, erfolgt eine weitere pruefebpk.xml Abfrage, ergänzt um Strasse und Plz.
    -  Wenn eine Bpk ermittelt wurde, wird diese in FH Complete gespeichert.
  * Resultat: 
    * In FH Complete gespeicherte Bpk

**sendPruefungsaktivitaeten**
  * Input: person Ids von aufgenommenen Studierenden mit validem Prestudentstatus im Studiensemester, für welche
    * die Summe der absolvierten ECTS eines der Person zugeordneten Prestudenten von der bei der letzten Meldung gesendeten Summe der ECTS (oder von 0 wenn noch nicht gesendet) abweicht 
  * Ablauf: 
    - Alle validen ECTS (aktiv, offiziell, positiv, zeugnis müssen true sein) von Noten von abgeschlossenen Lehrveranstaltungen einer Person werden gemeldet (pruefungsaktivitaeten.xml)
  * Resultat: 
    * In DVUH gespeicherte Prüfungsaktivitäten


**Weitere Hinweise:**
  * "valider Prestudentstatus" ist ein Status (valide Statustypen können je nach Job in mit der Konfigurationsoption //fhc_dvuh_status_kurzbz// festgelegt werden) im beim Aufruf angegebenen Semester mit bismelden = true und bismelderelevantem Studiengang
  * "aufgenommen" bedeutet einen Prestudentstatus im Studierendenlebenszyklus ab "Aufgenommener"
  * "relevante" Buchungen sind Buchungen mit einem in der Konfigurationsdatei DVUHSync.php (fhc_dvuh_buchungstyp) festgelegten Buchungstyp. I.d.R. sind dies ÖH-Beitrag und Studiengebühr. 
  * Wenn bei einer Stammdatenmeldung eine Zahlungsvorschreibung bereits an einer anderen Bildungseinrichtung beglichen ist (aber nicht in FH Complete gegengebucht), kann die Zahlungsvorschreibung mit 0 an den DVUH gesendet und in FH Complete die Vorschreibungsbuchung auf 0 gesetzt werden.
  * Jede Stammdaten-, Zahlungs- und Studiumsdatenmeldung wird mit Datum in FH Complete in einer Tabelle im sync Schema mitgeloggt. So können noch nicht gemeldete Daten identifiziert und neue Datenänderungen nachverfolgt werden.
  * Für Incoming, Outgoing und ausserordentliche Studierende werden abweichende Studiumsmeldungen mit weniger Daten durchgeführt (z.B. Entfall der Orgform, kein Zulassungsdatum)

==== DVUH Client GUI ====
FH Complete stellt eine grafische Benutzeroberfläche zur Durchführung einzelner Aktionen im DVUH zur Verfügung.
Dies betrifft das Auslesen von Daten im DVUH sowie das Senden bestimmter Daten an den DVUH. So können u.a. Stammdaten, Studiumsdaten ausgelesen und gemeldet werden, Zahlungen durchgeführt sowie Kontostände, Matrikelnummern und Bpks geprüft werden.
Aktionen, die sowohl im Rahmen der Jobs als auch mit der GUI ausgeführt werden können, decken sich. So werden z.B. auch bei Stammdaten-, Zahlungsdaten- sowie Studiumsdatenmeldungen über die GUI die Meldungsinformationen im Sync Schema geloggt und die Matrikelnummer aktiviert.

Die GUI stellt Funktionalitäten aus 4 Bereichen zur Verfügung: Matrikelnummermanagement, Stammdatenmanagement, Zahlungsmanagement und Studiumsdatenmanagement. 

Bei Klick auf eine Option erscheint eine Eingabemaske für Daten, die an DVUH geschickt werden sollen. Beispiel für die Zahlungseingangseingabemaske, Option "Zahlungseingang melden":

{{:admin:dvuh_gui_eingabemaskezahlungseingang.png?900|}}

Bei Senden von mit einer Person verknüpften Daten (z.B. Stammdaten-, Studiumsdatenmeldung) ist nur die Eingabe einer Person Id notwendig, die dazugehörigen weiteren Daten werden automatisch aus FH Complete bezogen. Zur besseren Nachvollziehbarkeit der zu sendenden Daten ist für Speicherzugriffe mit umfangreicheren Daten eine Vorschaufunktion verfügbar, Button "Zu sendende Daten anzeigen", wie z.B. bei der Stammdatenmeldung:

{{:admin:dvuh_gui_datenanzeigen.png?900|}}

Die Daten werden im XML-Format angezeigt, so wie sie an den DVUH geschickt werden. Wo möglich, werden Datenprüfungen seitens FH Complete noch vor der DVUH-Anfrage durchgeführt. Dies wird schon bei der Vorschau als Fehler (rot) oder Warnung (gelb) angezeigt:

{{:admin:dvuh_gui_stammdatenmeldungvorschaufehler.png?900|}}

Nach Klick auf "Absenden" wird dann der Response so wie er von der DVUH Schnittstelle zurückkommt im XML Format angezeigt. Meldungen (grün), erkannte Fehler (rot) und Warnungen (gelb) werden oberhalb des XML angezeigt:

{{:admin:dvuh_gui_stammdatenmeldungabsenden.png?900|}}

Lesezugriffe funktionieren ähnlich, nach Eingabe der Daten und Klick auf den "Absenden" Button wird der XML response mit den angefragten Daten angezeigt, wie z.B. bei Abfrage der Studiendaten:

{{:admin:dvuh_gui_studiumsdatenabfrage.png?900|}}