======Datei-Upload======

Der Datei-Upload, der in Zusammenarbeit mit der Universität Göttingen implementiert wurde, soll es Studenten ermöglichen Abgaben vollständig über die Studenten-Schnittstelle (FN2SSS) abwickeln zu können. Eine erste Iteration wurde im Februar 2019 abgeschlossen und ermöglicht den eigentlichen Upload von Dokumenten, sowie deren rudimentäre Verwaltung durch FN2SSS und das PA-Modul.

Gesteuert wird der Datei-Upload letztlich durch das Feld ''hochladen'' in der Tabelle ''teilprf'', das im PO-Modul für jede Teilprüfung gesetzt werden kann.

=====Nötige Version, Felder und Einträge=====

Der Datei-Upload wird in FN2WEB ab Version 2.04.02.000 und in den fn2Modulen ab dem Release vom 18.02.2019 (Version 2.0.6988.25824) unterstützt.

<wrap important>Bis Release 2.04.09:</wrap>\\
Seitens der Datenbank werden die Tabellen DATEI_UPLOAD und PRFSTD_ENDGUELTIG benötigt.

<wrap important>Ab Release 2.04.10:</wrap>\\
Seitens der Datenbank werden die Tabellen UPLOAD, PRFSTD_UPLOAD und PRFSTD_ENDGUELTIG benötigt.

Zudem werden die Spalten END_TIMESTAMP und ENDGUELTIG in der Tabelle PRFSTD und die Spalte HOCHLADEN in der Tabelle TEILPRF erwartet. Falls diese nicht vorhanden sind, bitte nochmal die veröffentlichten SQL-Skripte aus dem Zeitraum November 2018 bis Februar 2019 durchgehen.

Folgend werden die nötigen Konfigurationsparameter mit **beispielhaften** Werten aufgelistet. Auf deren Bedeutung wird im Abschnitt [[datei-upload#Konfiguration]] näher eingegangen.

====context.xml====

In die tomcat context.xml müssen in dem Abschnitt für allgemeine Parameter

    <Parameter description="Pfad fuer Datei-Uploads" name="DATEIUPLOADPATH" value="${catalina.base}/temp/uploads/"/>

und in dem Abschnitt für FN2SSS

    <!-- Datei-Upload -->
    <Parameter description="Valide MIME-Typen fuer den FileUpload in der SSS, mit Doppelpunkt trennen" name="FN2SSS.UPLOAD_MIME" value="application/pdf"/>
    <Parameter description="Suffix fuer den Pfad von FileUploads in der SSS" name="FN2SSS.UPLOAD_SUFFIX" value="SSS/"/>
    <!-- Datei-Upload --> 

ergänzt werden.
====FN2SSS/WEB-INF/web.xml====

In der web.xml von FN2SSS werden die <init-param>

	<init-param>
		<description>Maximalgröße für POST-Requests über die SSS in byte</description>
		<param-name>REQUEST_SIZE_LIMIT</param-name>
		<param-value>51200</param-value>
	</init-param>
	<init-param>
		<description>Maximalgröße für einzelne, hochgeladene Dateien in byte</description>
		<param-name>UPLOAD_MAX_FILE_SIZE</param-name>
		<param-value>104857600</param-value>
	</init-param>

erwartet.

Falls der Menüpunkt zum Hochladen von Arbeiten in FN2SSS ausgeblendet ist, muss aus dem Value des Init-Parameters 'NAV_CONFIG' der Eintrag 'datei_upload' entfernt werden.

====FN2XML/WEB-INF/web.xml====

Die web.xml von FN2XML sollte um den Eintrag

  <load-on-startup>1</load-on-startup>

innerhalb des XML-Tags <servlet> ergänzt werden (auf gleicher Ebene wie <servlet-class> und <servlet-name>).

=====Konfiguration=====

Viele Aspekte des Datei-Uploads lassen sich, meist über die im vorhergehenden Abschnitt vorgestellten Parameter, konfigurieren.

====Speicherort====

<WRAP center round alert 60%>
**FlexNow ist kein Datei-Verwaltungssystem.**
</WRAP>
 
Der Datei-Upload ist lediglich zum logischen Handling und Weiterreichen von Dateien an ein dediziertes System gedacht, wobei die für uns interessanten Daten in der Datenbank gespeichert werden und zusätzlich Funktionen von uns bereit gestellt werden.

Der Speicherort setzt sich aus
  DATEIUPLOADPATH + FN2SSS.UPLOAD_SUFFIX
zusammen. Zum Beispiel würde sich mit DATEIUPLOADPATH=''"${catalina.base}/temp/uploads/"'' und FN2SSS.UPLOAD_SUFFIX=''"SSS/"'' der Pfad ''${catalina.base}/temp/uploads/SSS/'' ergeben. In den Parametern werden also Strings erwartet, die letztlich auf ein Verzeichnis deuten (bitte auf die '/' achten).

Beachtet werden muss, dass
  * das Verzeichnis vorhanden ist (es wird nicht erstellt)
  * der Nutzer, unter dem der Tomcat-Server läuft, dort Schreibrechte hat

====MIME-Typ====

Mit dem Parameter FN2SSS.UPLOAD_MIME müssen für den Upload zulässige MIME-Typen nach [[https://tools.ietf.org/html/rfc2046|RFC2046]] hinterlegt werden. Wie schon in der Beschreibung erklärt, müssen die einzelnen Typen mit Doppelpunkten getrennt werden, z.B. würde ein value von
  application/pdf:text/plain
für .pdf und .txt (und Ähnliche) stehen. Eine Liste mit den gängigsten MIME-Typen ist [[https://wiki.selfhtml.org/wiki/MIME-Type/Übersicht|hier]] zu finden.

Mit fn2Web-Release [[releasenotes:fn2web2.04.10|2.04.10]] und folgend, werden die hochgeladenen Dateien genauer analysiert um ihren Datei-Typ zu bestimmen. Eine vollständige Liste der unterstützten Typen kann [[https://tika.apache.org/2.4.1/formats.html#Full_list_of_Supported_Formats_in_standard_artifacts|hier]] gefunden werden.
====Begrenzung der Datei/Upload-Größe====

Die maximale Datei- bzw. Uploadgröße ist über die Parameter UPLOAD_MAX_FILE_SIZE und REQUEST_SIZE_LIMIT einstellbar. Wie der Name schon sagt wird in UPLOAD_MAX_FILE_SIZE die max. Größe einzelner Dateien in Byte angegeben. REQUEST_SIZE_LIMIT begrenzt die Größe des kompletten Requests (auch für nicht-Uploads).

Ist für UPLOAD_MAX_FILE_SIZE ein valider Zahlenwert gesetzt, dann wird REQUEST_SIZE_LIMIT bei Uploads ignoriert.

Falls keiner der beiden Parameter gesetzt ist, wird für REQUEST_SIZE_LIMIT ein Default von 50 kB angenommen.

Die maximal Anzahl an hochladbaren Dateien wird in der Tabelle TEILPRF in der Spalte HOCHLADEN für jede Teilprüfung separat angegeben.

Die Parameter UPLOAD_MAX_FILE_SIZE und REQUEST_SIZE_LIMIT gelten auch für andere Uploads (z.B. Teilnehmerlisten im CSV-Format in FN2LM). Sie müssen in der jeweiligen web.xml eingetragen werden.

Zur Erinnerung:
  1 kB = 2^10 B = 1024 B
  1 MB = 2^20 B = 1048576 B

=====Optionale Einträge in context.xml=====
<wrap important>**Gilt ab Release** [[releasenotes:fn2web2.04.11|2.04.11]]:</wrap>

  <Parameter description="Sollen bei finaler Abgabe Mails an den Dozenten verschickt werden? (true/false)" name="FN2SSS.SEND_MAIL_FINALE_ABGABE_DOZENT" value="true"/>
  <Parameter description="Sollen bei finaler Abgabe Mails an den Studenten verschickt werden? (true/false)" name="FN2SSS.SEND_MAIL_FINALE_ABGABE_STUDI" value="true"/>

Wenn die Parameter vorhanden sind und auf 'true' steht, werden bei endgültiger Abgabe [[mail:start|Mails]] an die verantwortlichen Dozenten (mail=503) und den bzw. die betroffenen Studenten (mail=504) verschickt. Die Mails müssen im PO-Modul [[mail:start|konfiguriert]] werden.

<wrap important>**Gilt ab Version** [[releasenotes:fn2web2.04.08|2.04.08.007]]:</wrap>

Optional kann der Zeitpunkt angegeben werden, zu dem täglich nach abgabefälligen Uploads gesucht wird.

  <Parameter description="Uhrzeit, zu der täglich nach verstrichenen Abgabe-Fristen gesucht wird. Format 'HH:mm'" name="FN2SSS.DATEI_UPLOAD_CHECK_TIME" value="00:00"/>
  
Der Zeitpunkt defaultet auf 00:00 Uhr, wenn der Parameter nicht vorhanden ist oder nicht im richtigen Format ('HH:mm') hinterlegt wurde.


<wrap important>**Gilt bis Version** [[releasenotes:fn2web2.04.08|2.04.08.006]]:</wrap>

Optional kann das Intervall angegeben werden, in dem nach abgabefälligen Uploads gesucht wird.

    <Parameter description="Intervall mit dem nach abgabefälligen Uploads gesucht wird in Sekunden" name="FN2SSS.DATEI_UPLOAD_CHECK_INTERVALL" value="10800"/> 

Das Intervall hat einen Default-Wert von einer Stunde (wenn der Parameter nicht vorhanden ist) und einen Minimal-Wert von einer halben Stunde.

=====Deckblatt einfügen=====
Auf Wunsch kann den in FN2SSS hochgeladenen PDF-Dateien ein via XSLT generiertes Deckblatt beigefügt werden. dafür muss in der web.xml von FN2SSS der Init-Parameter 'ATTACH_PAGE_TO_UPLOAD' vorhanden und auf 'true' stehen:
  <init-param>
      <description>Soll ein Deckblatt den Uploads vorangestellt werden? (true/false)</description>
      <param-name>ATTACH_PAGE_TO_UPLOAD</param-name>
      <param-value>true</param-value>
  </init-param>
Zudem wird eine XSL-Datei 'Upload_Deckblatt.xsl' im XSL-Verzeichnis von FN2XML erwartet ('FN2XML.XSLPATH' in der context.xml). Bei Interesse kann eine Liste der Übergabeparameter bei uns erfragt werden.

=====Überschriften und Texte=====
Mit fn2Web-Release [[releasenotes:fn2web2.04.10|2.04.10]] und folgend, werden die zugehörigen Textschnippsel, Überschriften, etc. von Custvalues auf .properties-Dateien umgestellt. Die aktuellen Beispiele für den Datei-Upload, upload_de.properties und upload_en.properties, befinden sich unter .../Konfigurationsdateien/FN2SSS/WEB-INF/classes/de/ihb/flexnow/ss/properties (siehe auch die zugehörigen Patchnotes).

Die Umarbeitung der Lokalisierung via Properties ist im Moment work in progress. Wir bitten die damit verbundenen Unannehmlichkeiten zu entschuldigen.

=====Automatische Abgabe von Dateien=====
Mit fn2Web-Release [[releasenotes:fn2web2.04.11|2.04.11]] wurde die automatische Abgabe von Dateien von FN2XML nach FN2Service ausgelagert um die zugehörigen Benachrichtigungen via Mail besser technisch umsetzen zu können. Die zugehörigen SQL-Statements sind in den Skripten mit den Ids 1238 und 1253 zu finden.

In der web.xml von FN2Service kann, für den Fall, dass FN2Service nicht auf dem gleichen Server läuft wie FN2SSS, optional ein Parameter mit dem Pfad zu den gespeicherten, hochgeladenen Dateien angegeben werden. Der dort hinterlegte Pfad überschreibt dann die Kombination aus DATEIUPLOADPATH und FN2SSS.UPLOAD_SUFFIX. Befinden sich FN2SSS und FN2Service auf dem gleichen Server, kann der Parameter ignoriert werden.

  <init-param>
    <description>Optionaler Pfad für Uploads</description>
    <param-name>PATH_UPLOADS_OPTIONAL</param-name>
    <param-value>/optionaler/pfad/falls/FN2Service/auf/anderem/server/</param-value>
  </init-param>

=====Download der Dateien in FN2LM=====

Die jeweils zugehörigen Prüfer können hochgeladene Dateien über den Menüpunkt "Arbeiten herunterladen" in FN2LM zur Korrektur herunterladen. Dazu muss im Init-Parameter 'NAV_CONFIG' in der web.xml von FN2LM der Eintrag "abschlussarbeiten" aus dem Value entfernt werden, bzw. im Init-Parameter 'NAV_ROLE_CONFIG' bei einer gewünschten Rolle hinzugefügt werden, z.B.:
  <init-param>
    <description>
      In diesem Parameter kann angegeben in Abhängigkeit der Rolle eines Benutzers angegeben werden welche Menüpunkte dem Benutzer angezeigt werden:
      rolle1:menüpunkt1,menüpunkt2;rolle2:menüpunkt2
    </description>
    <param-name>NAV_ROLE_CONFIG</param-name>
    <param-value>2:abschlussarbeiten,prf,prf-zentral,studentendaten</param-value>
  </init-param>

In FN2LM werden die hochgeladenen Dateien dann nach den zugehörigen Prüfungen sortiert zum Download aufgelistet. Es können einzelne Dateien oder mehrere gezip heruntergeladen werden. Der ZIP-Datei wird eine Übersichtstabelle in CSV-Format beigelegt, die auf Wunsch auch anonymisiert erstellt wird.

{{ :fn2:arbeiten_herunterladen_lm.png |}}
===== Download von Arbeiten im PA-Modul =====

Ab [[releasenotes:fn2web2.04.11|Release 2.04.11]] können hochgeladene Arbeiten über das PA-Modul herunterlegaden und eingesehen werden:
{{ :fn2:pa_download-abgabe.png?direct |}}
Diese Funktion ist auf PDF-Dateien beschränkt und soll hauptsächlich der Kontrolle des Arbeitstitels, der beteiligten Prüfer u.Ä. dienen.

Hierfür wurde mit [[releasenotes:fn2web2.04.11|Release 2.04.11]] eine neue Rolle 'FN2ServiceIntern' eingeführt, die einem Benutzer zugeordnet werden muss (siehe SQL-Skript 1265). Zudem müssen folgende Einträge in der Setup-Tabelle vorhanden und sinnvoll gefüllt sein:
^ Parameter        ^    Wert    ^               Erklärung                 ^
| PA_UPLOAD_ANZEIGEN | true/false | schaltet die Funktion an oder aus |
| INTERN_USER | Kennung | Die Kennung des FN2ServiceIntern-Nutzers |
| INTERN_PASS | Passwort | Das Passwort des FN2ServiceIntern-Nutzers |
| INTERN_SERVER | URL | Die Adresse der FN2Service-Web-App |
| INTERN_VERZEICHNIS | Dateipfad | Der Pfad (vom fn2Module-Verzeichnis ausgehend) in dem die heruntergeladenen PDFs zwischengespeichert werden sollen |
Da das Passwort im Klartext abgelegt wird (analog zum Druck-User), raten wir dringends hierfür einen eigenen Nutzer anzulegen und diesem keine weiteren Rollen zuzuweisen.

Falls im FN2AUTH Parameter 'ROLLENERLAUBT' (in der web.xml) die Rolle 7 (allgemeiner Nutzer) nicht erlaubt ist, muss dort wenigsten die im SQL-Skript 1238 angelegte Rolle 49 (FN2ServiceIntern) gestattet werden. Siehe auch den Wiki-Eintrag zu [[fn2:service_intern|FN2Service]].
======Klausur-Upload======
Da der Klausur-Upload weitestgehend die gleiche Infrastruktur wie der Datei-Upload nutzt, können die zugehörigen Parameter größtenteils abgeleitet werden:

Die Parameter-Benamung bleibt gleich, es müssen lediglich die 
  * Einträge in der in FN2SSS-web.xml statt dessen in die FN2LM-web.xml
  * Einträge in der context.xml statt dessen mit 'FN2LM' beginnen

Selbstverständlich müssen die Werte sinnvoll gewählt werden, z.B. sollte FN2LM.UPLOAD_SUFFIX den Wert "LM/" oder ähnlich haben.

Da für Klausur-Uploads eine Fächer/Prüfungsspezifische Begrenzung der Anzahl nur wenig Sinn macht, kann die maximale Anzahl der hochladbaren Dateien global in der FN2LM-web.xml mit dem Init-Parameter 'UPLOAD_LIMIT' eingestellt werden:

  <init-param>
      <description>Anzahl der max. Klausuren, die pro Prüfungszeitraum hoch geladen werden dürfen</description>
      <param-name>UPLOAD_LIMIT</param-name>
      <param-value>3</param-value>
  </init-param>

Ist der Wert negativ, nicht vorhanden oder nicht als Zahl interpretierbar, können beliebig viele Uploads durchgeführt werden.

=====Verschlüsselung=====
Wenn gewünscht, können die hochgeladenen Klausuren zusätzlich verschlüsselt werden. Dazu muss in der FN2LM-web.xml ein Init-Parameter ENCRYPT_KLAUSUREN mit dem Wert true hinterlegt werden:
  <init-param>
       <description>Sollen hochgeladene Klausuren verschlüsselt werden? (true/false)</description>
       <param-name>ENCRYPT_KLAUSUREN</param-name>
       <param-value>true</param-value>
  </init-param>

Das verwendete Verfahren kann ebenfalls über Init-Parameter gewählt werden.

Für die verwendete Transformation der Parameter CIPHER:
  <init-param>
       <description>Welche Transformation soll verwendet werden?</description>
       <param-name>CIPHER</param-name>
       <param-value>############</param-value>
  </init-param>

Für den verwendeten Schlüssel der Parameter CIPHER_KEY:
  <init-param>
       <description>Verwendeter Schlüssel</description>
       <param-name>CIPHER_KEY</param-name>
       <param-value>############</param-value>
  </init-param>

Valide Werte können [[https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#impl|hier]] entnommen werden, sind jedoch nicht alle implementiert. Bei Bedarf bitte bei uns nachfragen.

Die Parameter sind **alle optional**. Wenn sie nicht vorhanden sind, werden folgende Defaults genutzt:
^ Parameter        ^    Default-Wert    ^ Effekt                      ^
| ENCRYPT_KLAUSUREN|       false        | Klausuren werden nicht verschlüsselt |
| CIPHER           |AES/CBC/PKCS5Padding|     AES mit CBC und PKCS5-Padding    |
| CIPHER_KEY       |     #########      |       Bitte bei Bedarf erfragen      |
======Feedback-Upload======
Ab dem  FN2WEB-Release [[releasenotes:fn2web2024-04|2024-04]] ist der Feedback-Upload für Dozenten in FN2LM möglich, mit dessen Hilfe ein direktes Feedback, zu von den Studenten hochgeladenen Prfstd-Uploads ermöglicht wird.

Damit die Funktion verwendet werden kann, muss in der context.xml des Tomcats der Parameter **"FN2LM.UPLOAD_FEEDBACK"** hinzugefügt und **value="all"** oder **value="PA"** gesetzt werden.
  * **Value="all"** bedeutet, dass Feedback-Dateien **sowohl in der Studierendenschnittstelle, als auch im PA-Modul sichtbar sind.** 
  * **Value="PA"** bedeutet, dass Feedback-Dateien **nur im PA-Modul sichtbar sind.**
  * **Value="false"**, bzw. das Nichtsetzen des Parameters bedeutet, dass das Feature komplett nicht verwendet werden kann.

  <Parameter description="Schalter, der bestimmt, ob Feedback-Dateien von den Lehrenden hochgeladen werden können (all/PA/false). all=Anzeige PA + SSS, PA=Anzeige nur PA, false=Deaktivieren des Features" name="FN2LM.UPLOAD_FEEDBACK" value="all"/>
  
Zusätzlich dazu werden noch die beiden Parameter 'FN2LM.UPLOAD_SUFFIX' und FN2LM.UPLOAD_MIME benötigt.

  <Parameter description="Suffix fuer den Pfad von FileUploads im LM" name="FN2LM.UPLOAD_SUFFIX" value="LM/"/>

  <Parameter description="Valide MIME-Typen fuer den KlausurUpload/Feedbackupload im LM, mit Doppelpunkt trennen" name="FN2LM.UPLOAD_MIME" value="application/pdf:text/plain"/>

Damit im PA-Modul die Feedback-Uploads der Dozenten angezeigt werden, muss in der Tabelle Setup der **param "PA_FEEDBACK_ANZEIGEN"** hinzugefügt und der dazugehörige **value auf "TRUE"** gesetzt werden.
  
Zusätzlich benötigt werden die Datenbankskripte mit den Ids: 1308 (neue Tabelle prfstd_feedback), 1309 (neue Rechte, die für den Feedbackupload benötigt werden) und 1310 (neue Flog-Typen, Log-Elemente/Schlüssel für den Feedbackupload).

Beim ersten Aufruf wird die Seite folgendermaßen aussehen:

{{:fn2:ersteraufruf.png|}}

Durch den Klick auf "Feedback hochladen" erscheint eine Upload-Formular. Durch das Auswählen einer Datei und das Klicken auf "Datei auswählen", erscheint folgende Übersicht, bei der mehrere Möglichkeiten zur Auswahl stehen:

  * Durch das Auswählen einer weiteren Datei lassen sich weitere Dateien auswählen 
  * Ausgewählte Dateien können wieder entfernt werden
  * Durch das Klicken auf "Dateien hochladen" werden die Datei(en) hochgeladen.

{{:fn2:uploaddialog.png|}}

Sobald die Datei(en) (bisher Stand: [[releasenotes:fn2web2024-04|2024-04]] gibt es keine Begrenzung der Anzahl) hochgeladen wurde(n), erscheint unter den Uploads der Studenten ein Balken mit den Überschriften "Feedback Dateiname: Zum Umschalten bitte klicken:", "Datum" und "Löschen". Dieser zeigt an, dass Feedback-Uploads existieren. Damit diese angezeigt werden, muss auf den Balken geklickt werden. Dadurch entsteht folgende Ansicht:

{{:fn2:aufrufmitfeedback.png|}}

Es besteht die Möglichkeit, die Feedback-Uploads nochmal zu löschen, oder sich diese, durch einen Klick auf den Dateinamen, anzeigen zu lassen.

===== Download von Feedback-Dateien in FN2SSS =====
Sobald das Feedback vom Dozenten hochgeladen wurde, ist es auch für den Studenten in der Studierendenschnittstelle sichtbar. Sobald dieser in dem Bereich für Datei-Uploads die Prüfung auswählt, erscheint dem Studierenden folgende Übersicht:

{{:fn2:ansichtstudent.png|}}

Durch einen Klick auf den Dateinamen wird die Datei runtergeladen.

Die Sichtbarkeit des Bereiches nach einer Verbuchung wird durch das bereits existierende Custvalue "anzeigeDauerErgebnisse" des Projektes "FN2SSS" und dem Korrekturdatum der Prüfung geregelt. Die Anzeige der Prüfungen in FN2LM nach einer Verbuchung wird auf die gleiche Weise geregelt.

===== Löschen des Feedback-Uploads durch den Dozenten =====
Die Löschbarkeit eines Feedback-Uploads wird je nach value des Parameters "FN2LM.UPLOAD_FEEDBACK" unterschiedlich eingeschränkt:
  * **Value="all"**: Sobald ein Student das Feedback heruntergeladen hat, kann es nicht mehr gelöscht werden.
  * **Value="PA"**: Das Löschen wird anhand des neuen Parameters **"FEEDBACK_LOESCHEN_NACH_FREIGABE"**, der in die **web.xml** des Projektes **FN2LM** eingetragen werden soll, und dem freigabedatum der Prüfung (Feld freigabedatum in der Tabelle prfstd) geregelt. Das **param-value soll eine Ganzzahl** sein. Diese steht für die Anzahl der Tage, in denen der Feedback-Upload nach der Freigabe einer  Prüfung gelöscht werden kann. Falls der Parameter nicht vorhanden ist, oder keinen gültigen Ganzzahlenwert besitzt, wird mit der Zahl 10 (Tage) anstelle des Parameters gerechnet.

  <init-param>
		<description>Falls nur eine Anzeige des Feedbacks im PA vorgesehen ist, wird die
				Löschbarkeit des Feedbacks anhand des Parameters bestimmt
				((aktuelles Datum - param-value (Zahlenwert entspricht Tagen))&lt;&#061;<!-- <= -->  freigabedatum).	
				Falls ein ungültiger Wert eingetragen wird, wird als Standard der Wert 10 (Tage) für die Rechnung genommen</description>
		<param-name>FEEDBACK_LOESCHEN_NACH_FREIGABE</param-name>
		<param-value>10</param-value>
	</init-param>