10 Bedienungsanleitung JoSuA
In den folgenden Kapiteln erfahren Sie, wie Sie sich in JoSuA einloggen, wie man durch die JoSuA-Webschnittstelle navigiert, Aufträge einsendet und anschließend auf die Ergebnisse zugreift. Darüber hinaus finden Sie Hinweise, was Sie bei möglichen Problemen mit JoSuA tun können.
Aktuelle Antworten auf häufige Fragen zu JoSuA finden Sie auch auf der JoSuA-Seite der FDZ-Website. Dort finden Sie auch ein Video-Tutorial, dass Ihnen den Einstieg zur Nutzung von JoSuA erleichtern soll.
10.1 Login
Rufen Sie die Internetseite https://josua.iab.de/ auf. JoSuA kann nicht mit dem Internet Explorer verwendet werden.
Geben Sie im Login-Fenster die Zugangsinformationen ein, die Sie vom FDZ erhalten haben (siehe Kapitel 4.1). Jeder Nutzer bzw. jede Nutzerin erhält nach Abschluss eines Nutzungsvertrags eine Kennung für JoSuA. Sollten mehrere Projektverzeichnisse einer Person zugeschrieben sein, gilt diese Kennung für alle Projektzugänge.1
Falls Sie noch keine Zugangsdaten erhalten haben oder diese vergessen haben, setzen Sie sich mit dem FDZ in Verbindung (iab.fdz@iab.de).
Die Weitergabe des Passworts an Dritte ist nicht erlaubt, auch nicht innerhalb eines Projekts.
10.2 Start
Nach der erfolgreichen Anmeldung erscheint die Nutzeroberfläche. Das Hauptmenü besteht aus mehreren Reitern: Home, Projects, Submission und Transfers. Diese werden in den folgenden Kapiteln näher beschrieben. Zu Beginn ist der Reiter Home ausgewählt. In der oberen rechten Ecke können Sie Ihr Passwort ändern oder sich ausloggen.
10.3 Home
Der Reiter Home, der in Abbildung 2 dargestellt ist, zeigt eine Liste mit allen aktuellen Aufträgen, deren Status und, ob der Job erfolgreich durchgelaufen ist.
Folgende Statusinformationen, die den Stand des Jobs im Bearbeitungsprozess darstellen, sind möglich:
„running”: Der Job wird gerade ausgeführt.
„censoring”: Der Job befindet sich in der Zensierung (Presentation / Publication Modus) bzw. es werden die png-Dateien erzeugt (Internal Use Modus – siehe auch 10.10.2).
„released”: Der Job wurde freigegeben.
Folgende weitere Statusangaben können im letzten Feld der Übersicht erscheinen:
„success”: Der Job ist erfolgreich durchgelaufen.
„failed”: Der Job ist abgebrochen. In Ausnahmefällen erscheint der Status „failed”, obwohl der Job erfolgreich durchgelaufen ist.
„aborted”: Der Job wurde von den Nutzenden selbst vorzeitig gestoppt.
Klicken Sie auf die drei Punkte auf der rechten Seite, um Details des ausgewählten Auftrags anzusehen.
Neben einigen allgemeinen Informationen zu Ihrem Auftrag finden Sie in der Detailansicht (siehe Abbildung 3) unter Input alle hochgeladenen Dateien und unter Output alle verfügbaren Ergebnisdateien. Derzeit können pro Auftrag maximal 20 Ergebnisdateien generiert werden. Dabei werden alle Log-Files (inkl. einer etwaigen Dateiliste) und Grafiken mitgezählt. Log-Files werden automatisch abgeschnitten, wenn eine Dateigröße von 2 MB pro Datei oder alle Ergebnisdateien des Jobs zusammen 8 MB überschreiten. Die Darstellung der Ergebnisse ist abhängig vom Einsendemodus.
-
Input (Hochgeladene Dateien):
- Alle hochgeladenen Skripte für diesen Auftrag werden hier aufgelistet.
-
Output (Ergebnisdateien):
Internal Use: Sie können die Ergebnisse Ihres Auftrags per Klick auf das entsprechende Output-File (Log-File oder Grafik) oder das Icon auf der rechten Seite einsehen. Navigieren Sie mittels Klicken auf die Buttons rechts unten durch die Vorschaufenster. Bitte beachten Sie, dass die Ergebnisse nur solange zugänglich sind bis im gleichen Projekt ein neuer Auftrag im Presentation / Publication Modus hochgeladen wird.
Presentation / Publication: Nach der manuellen Datenschutzprüfung können alle geprüften Ergebnisse heruntergeladen werden. Der Link erscheint erst nach erfolgter Datenschutzprüfung. Um Dateien herunterzuladen, klicken Sie auf den Dateinamen oder auf den Pfeil auf der rechten Seite und speichern die Datei auf Ihrem Computer.
10.4 Projects: Projektübersicht
Im Reiter Projects (Projekte) sind alle Ihre laufenden Projekte aufgelistet (siehe Abbildung 4).
Durch einen Klick auf “View” gelangen Sie zu den Projektdetails des entsprechenden Projekts. In diesem Menü finden Sie drei Reiter:
Jobs: Hier finden Sie eine Liste der Aufträge aller Nutzenden des gewählten Projektes (siehe Abbildung 5). Zusätzlich zu generellen Informationen können Sie durch Anklicken der drei Punkte auf der rechten Seite dieselben Optionen aufrufen, die Sie auch unter Home finden (siehe Kapitel 10.3).
Resources: Diese Reiter dient der Übermittlung und Speicherung von zusätzlichen Befehlsbibliotheken, z. B. Stata-Ado-Paketen. Laden Sie hier nur Ado-Files für Ihr Projekt hoch (siehe Abbildung 6), wenn diese nicht über den Befehl
fdzinstallaus den am FDZ verfügbaren Paketen aus dem SSC-Archive installiert werden können (siehe Kapitel 2.2.1)! Alle Nutzenden eines Projekts können Dateien hinzufügen, die alle autorisierten Mitglieder für ihre Aufträge nutzen können. Falls dort schon von anderen Mitgliedern hochgeladene Dateien sind, können Sie diese hier sehen. Um neue Dateien hinzuzufügen klicken Sie auf “+” und ziehen Sie die gewünschte Datei in das Fenster oder klicken Sie in das Fenster, um die Datei von Ihrer Festplatte hochzuladen. Es ist nur möglich, einzelne Dateien hochzuladen. Falls bereits eine Datei mit gleichem Namen existiert, wird diese überschrieben (v.a. zu beachten bei sich ändernden Versionen von Ado-Files). Bitte beachten Sie, dass über Resources ausschließlich reine Textdateien hochgeladen werden können. Das Hochladen von anderen Formaten (wie beispielsweise .mlib oder .plugin) ist nicht möglich (siehe Kapitel 2.2.1). Nach dem Hochladen erscheint das Ado-File in der Liste mit der Statusangabe „new”. Sobald das Ado-File nach einer Datenschutzprüfung freigegeben wurde, wechselt der Status auf „accepted” und es steht dauerhaft im Projekt zur Nutzung innerhalb von JoSuA zur Verfügung. Wurde das Ado-File nicht freigegeben, erhält es den Status „dropped”. Um über RESOURCES hochgeladene Ado-Pakete auch für Gastaufenthalte verfügbar zu machen, müssen sie während des Gastaufenthalts einmalig heruntergeladen und im prog-Verzeichnis gespeichert werden.Transfers: Hier sind alle Skripte aufgelistet, die Sie vor oder nach einem Gastaufenthalt zum Transfer für dieses Projekt hochgeladen haben (siehe Abbildung 7). Nach Prüfung der Skripte durch das FDZ (censored) können Sie die Dateien für die weitere Bearbeitung zu Hause oder über Datenfernverarbeitung durch einen Klick auf den Dateinamen oder den Pfeil auf der rechten Seite herunterladen. Sie können durch einen Klick auf „+” auch neue Skripte hochladen. Ausführliche Informationen zu Transfers finden Sie in Kapitel 10.7.
10.5 Submission: Hochladen von Aufträgen
Ein Auftrag zur Datenfernverarbeitung wird übermittelt, indem die Skripte im Reiter Submission (Hochladen von Aufträgen) hochgeladen werden (siehe Abbildung 8). Es muss eine Master-Datei namens master.do enthalten sein. Bei jedem Auftrag müssen alle auszuführenden Skripte hochgeladen werden. Bitte verwenden Sie bei der Benennung der Skript-Dateien nur folgende Zeichen: 0-9, a-z, A-Z, -,_.
Auf der linken Seite wählen Sie im ersten Drop-Down-Menü bitte das Projekt aus, in welchem Sie den Job hochladen wollen (z. B. fdz2020). Im zweiten Drop-Down-Menü können Sie auswählen, ob der Auftrag im Internal Use Modus oder Presentation / Publication Modus eingeschickt werden soll (siehe Kapitel 4). Im dritten Drop-Down-Menü wählen Sie bitte das Software-Paket, das genutzt werden soll.
Im darunterliegenden Feld können Sie einen Kommentar eingeben, der relevante Details oder Erklärungen enthält. Verzichten Sie auf Umlaute und Sonderzeichen und verwenden Sie maximal 1.000 Zeichen.
Ziehen Sie anschließend Ihre Skripte in das Fenster auf der rechten Seite oder klicken Sie in das Fenster, um Skripte von Ihrer Festplatte in JoSuA hochzuladen. Bitte laden Sie pro Auftrag einschließlich der Master-Datei maximal 20 Skripte hoch. Die hochgeladenen Dateien werden aufgelistet. Sie können die Liste prüfen und einzelne Dateien entfernen. Wenn Sie mit dem Hochladen Ihrer Skripte fertig sind, klicken Sie auf Submit (Auftrag übermitteln), um Ihren Auftrag zu übersenden.
Sobald Sie einen Job im Presentation / Publication Modus hochgeladen haben, können Sie bis zu dessen Freigabe keine weiteren Jobs im Presentation / Publication Modus hochladen. Im Internal Use Modus ist es theoretisch möglich, mehrere Jobs parallel laufen zu lassen. Ebenso können, während ein Job im Presentation / Publication Modus läuft, weitere Jobs im Internal Use Modus gestartet werden. Das FDZ empfiehlt, diese Möglichkeiten nur in Ausnahmefällen zu nutzen, wenn z. B. ein Job im Presentation / Publication Modus mehrere Tage läuft. Bitte laden Sie im Normalfall erst dann einen neuen Job hoch, wenn der vorherige Job durchgelaufen ist.
10.6 Stoppen von Jobs
Falls ein laufender Job gestoppt werden soll, können Sie dies selbst vornehmen. Im Reiter „Home” sind Ihre Jobs aufgelistet. Beim entsprechenden Job befindet sich rechts eine Multifunktionsschaltfläche mit drei übereinander angeordneten Punkten. Damit öffnet sich das Kontextmenü des Jobs. Dort befindet sich wiederum rechts oben eine Multifunktionsschaltfläche mit drei übereinander angeordneten Punkten. Hinter dieser verbirgt sich die Funktion „Stop Job”. Wenn Sie diese Schaltfläche anklicken und den Sicherheitshinweis bestätigen, wird der Job gestoppt. Der Job hat nun den Status „aborted”. Jobs, die im Presentation / Publication Modus hochladen wurden, werden damit jedoch nicht automatisch gelöscht, sondern liegen zur Prüfung und Freigabe durch das FDZ bereit. Das FDZ löscht diese Jobs anschließend manuell. Dies bedeuten, dass bis zur endgültigen Löschung keine weiteren Jobs im Presentation / Publication Modus hochgeladen werden können.
10.7 Transfers: Übermittlung von Skripten vor oder nach dem Gastaufenthalt
Über den Reiter Transfers können Sie zu Hause vorbereitete Skripte für Ihren Gastaufenthalt hochladen (siehe Abbildung 9). Dies gilt neben Stata-Dofiles auch für Skripte anderer Programme wie z.B. R oder Octave. Sollten Sie nach Ihrem Gastaufenthalt die während des Gastaufenthalts erstellten Skripte zur weiteren Bearbeitung zu Hause oder über Datenfernverarbeitung benötigen, laden Sie diese bitte auch über die Funktion „Transfers” hoch. Laden Sie über „Transfers” keine Ado-Files oder andere Programm-Pakete hoch (siehe 2.2.1)
Ziehen Sie das gewünschte Skript hierzu in das Fenster auf der rechten Seite oder klicken Sie in dieses Fenster, um das Skript von Ihrer Festplatte hochzuladen. Alternativ können Sie auch über den Reiter Projects -> View -> TRANSFERS -> + gehen. JoSuA akzeptiert hier – im Gegensatz zum Hochladen von Dateien bei „Submission” - nur das Hochladen / Drag & Drop einzelner Dateien. Es ist aber möglich, mehrere Dateien in einer Archiv-Datei (.zip, .7z) hochzuladen.
Nach dem Hochladen erscheint das Skript in der Liste mit der Statusangabe „new”. Sobald das Skript nach einer Datenschutzprüfung freigegeben wurde, wechselt der Status auf „accepted”. Die Skripte stehen nun zum Herunterladen zur Verfügung. Sollten durch das FDZ Löschungen in den Skripten vorgenommen werden, erhalten die Dateien den Status „censored”. In der Regel finden Sie einen Hinweis zu den Löschungen am Anfang des Skripts. Vereinzelt erhalten Dateien jedoch auch den Status „censored”, obwohl keine Löschungen vorgenommen wurden. Dies ist technisch bedingt.
Unter dem Reiter Transfers sehen Sie alle bereits transferierten Skripte. Zudem haben Sie hier die Möglichkeit, die durch das FDZ-Team freigegebenen Skripte herunterzuladen. Klicken Sie hierzu auf den Skript-Namen oder den Pfeil auf der rechten Seite.
Damit eine Archiv-Datei freigegeben werden kann, müssen alle darin enthaltenen Dateien datenschutzrechtlich unbedenklich sein, ansonsten wird sie komplett gelöscht. Bitte beachten Sie, dass beim Erstellen einer Archiv-Datei an einem Rechner mit macOS automatisch Systemfiles/Metadaten erzeugt werden. Diese müssen von Ihnen gelöscht werden, bevor Sie die Archiv-Datei in JoSuA hochladen. Eine Löschung der Systemfiles, die für Sie selbst nicht sichtbar sind, kann mit folgendem Befehl über die Kommandozeile gelöscht werden: zip -r data.zip . -x ".*" -x "__MACOSX".
10.8 Technische Restriktionen in JoSuA
Bei der Nutzung von JoSuA gibt es einige Beschränkungen, die im Folgenden nochmals zusammengefasst dargestellt werden:
Unter „Submission” können einschließlich der Master-Datei maximal 20 Skripte pro Job hochgeladen werden.
Es können maximal 20 Ergebnisdateien pro Job ausgegeben werden. Hierzu zählt auch jede einzelne Grafik oder eine etwaige Dateiliste.2
Maximale Größe einer Ergebnisdatei: 2 MB. Sollte ein Log-File zu groß sein, wird die Datei abgeschnitten und ein entsprechender Hinweis in das Log-File geschrieben. Sollte eine Grafik-Datei zu groß sein, wird diese gelöscht und die Löschung in einem Log-File „lost-files.log” dokumentiert.
Maximale Größe aller Ergebnisdateien pro Job zusammen: 8 MB
Pro Projekt ist das Unterverzeichnis data auf die Größe von 30 GB beschränkt.
Es stehen maximal 30 GB Arbeitsspeicher zur Verfügung. Jobs, die zur Laufzeit mehr Arbeitsspeicher erfordern, brechen automatisch ab.
Pro Tag kann nur eine begrenze Anzahl an Jobs pro Projekt im Internal Use Modus bzw. im Presentation / Publication Modus hochgeladen werden. Die aktuell gültigen Limits finden Sie auf der FDZ-Website.
10.9 Hilfe bei Job-Abbrüchen in JoSuA
Sollte Ihr Job in JoSuA mit dem Status „failed” abbrechen, prüfen Sie bitte zunächst eigenständig folgende Aspekte:
Ist ein Job im Presentation / Publication Modus abgebrochen, beachten Sie bitte die Fehlermeldung im letzten Log-File bzw. einem etwaigen master.log sowie einen etwaigen User Comment des FDZ, um dem Problem auf den Grund zu gehen.
Überprüfen Sie Ihre Programme auf Programmierfehler.
Stellen Sie sicher, dass Sie alle Vorgaben zur Datennutzung – insbesondere die Pfadangaben betreffend – eingehalten haben.
Schlagen Sie in den FAQ zu JoSuA nach, ob Sie dort Hinweise zur Ursache bzw. zur Behebung des Abbruchs finden.
Erst wenn diese Maßnahmen zu keiner Lösung führen, wenden Sie sich bitte an das FDZ. Übermitteln Sie dazu bitte folgende Informationen:
Projektnummer, Jobnummer in JoSuA
Möglichst detaillierte Darstellung des Problems (z. B. Wortlaut der Fehlermeldung)
Übermitteln Sie bitte NIEMALS Ergebnisse, die im Internal Use Modus erstellt wurden oder sonstigen nicht vom FDZ-Team freigegebenen Output! Die Übermittlung von nicht freigegebenen Ergebnissen – auch an das FDZ – stellt eine Vertragsverletzung dar.
In Ausnahmefällen erscheint der Status „failed”, obwohl der Job erfolgreich durchgelaufen ist.
10.10 Fehlerbehebung in JoSuA
Im Folgenden werden häufige Fehler und deren Behebung beschrieben.
Bei Fragen kontaktieren Sie bitte das Forschungsdatenzentrum (iab.fdz@iab.de). Bitte geben Sie immer Ihre FDZ-Projektnummer (fdzXXXX) und ggf. die Job-ID aus JoSuA an.
10.10.1 Dateien können nicht hochgeladen werden
Unter "Transfers" und "RESOURCES" können Dateien nur einzeln hochgeladen werden (im Unterschied zu "Submission"). Beim Transferieren von Skripten vor ⁄ nach Gastaufenthalt ("Transfers") können Sie die einzelnen Dateien aber vorher packen (.zip, .7z).
10.10.2 Freigabe der Ergebnisse im Internal Use Modus dauert ungewöhnlich lang (Status „censoring”)
Üblicherweise erfolgt die Freigabe von Ergebnissen im Internal Use Modus innerhalb weniger Minuten. Bei hoher Beanspruchung von JoSuA kann es jedoch auch einige Stunden dauern. Bitte warten Sie mindestens 6 Stunden ab, bevor Sie das FDZ kontaktieren.
10.10.3 Ergebnisdateien fehlen
Nach Freigabe der Ergebnisse sind nicht alle im Job erzeugten Ergebnisdateien unter „Output” verfügbar. Hierfür kann es unterschiedliche Gründe geben:
Es wurden ganze Dateien im Rahmen der Datenschutzprüfung nicht freigegeben. In diesem Fall finden sich in der Regel Hinweise zu den Löschungen in den Kommentaren.
Pro Job wurden mehr als 20 Ergebnisdateien erzeugt. Hierzu zählen auch jede einzelne Grafik und eine etwaige Dateiliste. JoSuA gibt dann nur maximal 20 (zufällig ausgewählte) Ergebnisdateien aus.
Die maximale Größe von 2 MB pro Ergebnisdatei wurde überschritten. Sollte ein Log-File zu groß sein, wird die Datei abgeschnitten und ein entsprechender Hinweis in das Log-File geschrieben. Sollte eine Grafik-Datei zu groß sein, wird diese gelöscht und die Löschung in einem Log-File „lost-files.log” dokumentiert.
Im Internal Use Modus: Es gab einen Fehler bei der Umwandlung in png-Dateien. Bitte kontaktieren Sie in diesem Fall das FDZ unter Angabe der Projektnummer und der Job-ID.
10.10.4 Fehlermeldung im Log-File "File not found"
Diese Fehlermeldung tritt auf, wenn der Dateipfad nicht mit den vorgesehenen Globals $prog, $data, $orig oder $log angegeben wurde. Verwenden Sie bei jeder Pfadangabe die genannten Globals, da JoSuA sonst die Dateien nicht finden kann. Bitte achten Sie außerdem darauf, keine Umlaute, Leerzeichen oder Sonderzeichen in Dateinamen zu benutzen.
10.10.5 Log-File master.log ⁄ Fehlermeldung "log-file already open"
JoSuA legt automatisch eine Log-Datei namens master.log an. Bitte legen Sie nicht selbst ein master.log an. Verwenden Sie "cap log close", um das geöffnete Log-File zu schließen und legen Sie anschließend ein neues Log-File an. Hinweise zur Benennung von Skripten und Log-Files finden Sie in den Richtlinien.
10.10.6 Fehlermeldung "File not ok (suspicious mismatch between file suffix and actual file type)"
Diese Fehlermeldung erscheint beispielsweise, wenn das Log-File in Statas smcl-Format gespeichert wird. Bitte benutzen Sie nur Log-Files im reinen Text-Format. Dies erreichen Sie durch die Befehle "$log\logfile.log", replace" oder "log using "$log\logfile", text replace”.
10.10.7 Fehlermeldung "Error!"
Der Fehler tritt auf, wenn die Gesamtgröße aller generierten Output-Files eines Jobs größer als 8 MB ist. Bitte passen Sie Ihre Programme an, damit weniger Output generiert wird.