UCS@school

Handbuch grafischer Benutzer-Import


Inhaltsverzeichnis

1. Zielgruppe
2. Einführung
3. Ablauf des Importvorgangs
4. Installation, Konfiguration und Dateiformat
4.1. Installation
4.2. Konfiguration
4.3. Datenformat
5. Test an der Kommandozeile

§Kapitel 1. Zielgruppe

Dieses Handbuch richtet sich an Mitarbeiter, die den grafischen Import von Benutzern durchführen, und ab Kapitel 4 an Administratoren, die ihn installieren und konfigurieren.

§Kapitel 2. Einführung

UCS@school bringt seit der Version 4.2 v6 ein UMC-Modul mit, das es ermöglicht, sicher und komfortabel Benutzerdaten aus CSV-Dateien zu importieren. Über ein flexibles Sicherheitskonzept kann einzelnen Benutzern oder ganzen Gruppen die Berechtigung gegeben werden, Importe für bestimmte Schulen durchführen und deren Ergebnisse einsehen zu können.

Technisch basiert das UMC-Modul Benutzerimport auf Komponenten der Software, die in UCS@school-Handbuch zur CLI-Import-Schnittstelle beschrieben sind. Die Konfiguration dieser Komponenten ist nicht Teil dieses Dokuments.

§Kapitel 3. Ablauf des Importvorgangs

Das UMC-Modul leitet den Anwender in mehreren Schritten durch den Import:

§

Abbildung 3.1. Schritte eines Importvorganges

Schritte eines Importvorganges


Ein neuer Import kann in der Übersichtsseite durch Klicken auf "Neuen Benutzerimport durchführen" gestartet werden. Wenn noch nie ein Import durchgeführt wurde, startet das UMC-Modul direkt mit den erstem Schritt für einen neuen Import. In allen anderen Fällen wird zunächst die Übersicht angezeigt.

Anmerkung

Sollte sich der Anwender per SAML (Single Sign-On) angemeldet haben, erscheint ein Fenster, das (u.U. mehrfach) zur Eingabe des eigenen Benutzerpasswortes auffordert.

§

Abbildung 3.2. Übersichtsseite

Übersichtsseite


  1. Zuerst muss der Typ der zu importierenden Benutzer ausgewählt werden.

    §

    Abbildung 3.3. Auswahl des Benutzertyps

    Auswahl des Benutzertyps


  2. Anschließend kann die CSV-Datei mit den Benutzerdaten ausgewählt werden.

    §

    Abbildung 3.4. Hochladen der CSV-Datei

    Hochladen der CSV-Datei


  3. Nun werden die Daten geprüft und es wird ein Test-Import durchgeführt, um mögliche Fehler vorab zu erkennen. Das Benutzerverzeichnis wird dabei nicht verändert.
  4. Je nach Menge der zu importierenden Daten, kann der Test-Import einige Zeit beanspruchen.

    • War die Simulation erfolgreich, kann nun der tatsächlich Import gestartet werden.

      §

      Abbildung 3.5. Simulation war erfolgreich

      Simulation war erfolgreich


    • Traten während des Test-Imports Fehler auf, wird eine Fehlermeldung angezeigt. Unterhalb der Fehlermeldung ist im Text ein Link. Durch Klicken auf diesen, wird eine E-Mail mit der Fehlermeldung an einen Administrator verfasst.

      §

      Abbildung 3.6. Simulation hatte Fehler

      Simulation hatte Fehler


  5. Nach dem Start des Imports kehrt das UMC-Modul zur Übersichtsseite zurück. Wenn der neue Import-Job noch nicht angezeigt wird, kann die Liste mit der Schaltfläche "Aktualisieren" neu geladen werden.

    §

    Abbildung 3.7. Übersichtsseite mit gestartetem Import

    Übersichtsseite mit gestartetem Import


§Kapitel 4. Installation, Konfiguration und Dateiformat

§4.1. Installation

Die Installation muss auf dem Domänencontroller Master stattfinden:

# univention-install ucs-school-umc-import

§4.2. Konfiguration

Das Setzen der Univention Configuration Registry-Variablen ucsschool/import/error/mail-address ist wichtig, damit Anwender beim Auftreten eines Fehlers, eine E-Mail an den Administrator schicken können, indem sie auf den oben beschriebenen Link klicken.

# ucr set ucsschool/import/error/mail-address=admin@ihre-schule.de

Technisch basiert der grafische Benutzer-Import auf Komponenten der Software die in Handbuch Import-Schnittstelle beschrieben sind. Deren Konfiguration erfolgt in einer JSON Datei. Die Datei /usr/share/ucs-school-import/configs/user_import_http-api.json sollte als Ausgangsbasis für eigene, angepasste Konfigurationen verwendet werden. Die Konfiguration wird aktiviert, indem sie an die richtige Position kopiert wird:

# cp /usr/share/ucs-school-import/configs/user_import_http-api.json \
	  /var/lib/ucs-school-import/configs/user_import.json

Das Sicherheitskonzept ermöglicht es Benutzern Rechte zu erteilen, um Importe nur an bestimmten Schulen und nur für bestimmte Benutzertypen durchführen, sowie die Ergebnisse dieser Import-Jobs einzusehen. Während der Installation wurde für jede Schule eine Gruppe $OU-import-all erstellt. An diesen Gruppen wurde die Option UCS@school Import-Berechtigungen aktiviert. In der UMC können für diese Gruppen auf der Karteikarte UCS@school Import-Berechtigungen festgelegt werden.

Eine Import-Berechtigung setzt sich zusammen aus einer Liste von Schulen (standardmäßig nur die Schule für die die Gruppe erzeugt wurde) und einer Liste von Benutzertypen (Rollen). Alle Benutzer die Mitglieder dieser Gruppe sind können Imports für die aufgelisteten Benutzertypen and den aufgelisteten Schulen durchführen. Verschachtelte Gruppen werden nicht unterstützt.

Sollen zusätzlich zu den automatisch erzeugten Gruppen neue angelegt werden, so muss an diesen zum einen die Option UCS@school Import-Berechtigungen aktiviert, und zum anderen die UMC-Richtlinie cn=schoolimport-all,cn=UMC,cn=policies,$LDAP_BASE zugewiesen werden.

Alle an einem Import-Job beteiligten, und von ihm erzeugten, Dateien finden sich unter /var/spool/ucs-school-import/jobs/$JAHR/$JOB-ID/: Konfigurationsdateien, Hooks, Logdateien, CSV-Dateien (Eingabedaten, Passwörter neuer Benutzer, Zusammenfassung).

§4.3. Datenformat

Das Format der CSV-Datei ist anpassbar. Generell gilt aber folgendes:

  • Die erste Zeile führt die Bezeichner der Spalten auf. Zum Beispiel:

    "Schule","Vorname","Nachname","Klassen","Beschreibung","Telefon","EMail"

  • Daten in Spalten sind in doppelten Anführungszeichen eingeschlossen.

  • Die Spalten sind durch Komma voneinander getrennt.

  • Es muss jeweils eine Spalte für die primäre Schule eines Benutzers, seinen Vor- und Nachnamen geben.

  • Mehrere Klassennamen werden durch Komma, ohne Freizeichen, getrennt aufgezählt (z.B. 1a,2b,3c). Klassennamen dürfen, aber brauchen nicht, den Namen der Schule (mit einem Bindestrich verbunden) vorangestellt haben (z.B. Scholl-1a,Scholl-2b,Scholl-3c). Wird der Name der Schule vorangestellt, muss dies der gleiche Wert sein wie in der Spalte für die Schule.

Beispieldaten für Testläufe können mit Hilfe eines Skripts erzeugt werden:

# /usr/share/ucs-school-import/scripts/ucs-school-testuser-import \
	  --httpapi \      # Format passend zu user_import_http-api.json erzeugen
	  --students 20 \  # Anzahl Benutzer, alternativ: --staff --teachers --staffteachers
	  --classes 2 \                   # Anzahl zu erzeugender Klassen
	  --create-email-addresses \      # E-Mail-Adressen erzeugen
	  SchuleEins                      # Schule (OU) in die importiert werden soll

Die erzeugte Datei heißt test_users_$DATUM_$UHRZEIT.csv und passt zur Konfiguration in /usr/share/ucs-school-import/configs/ucs-school-testuser-http-import.json.

Eine solche Datei sieht z.B. so aus:

"Schule","Vorname","Nachname","Klassen","Beschreibung","Telefon","EMail"
"SchuleEins","Jeanne","Oberbockstruck","1a","A student.","+24-165-622645","jeannem.oberbockstruck@example.de"
"SchuleEins","Jehanne","Obergöker","1b","A student.","+16-456-810331","jehannem.mobergoeker@example.de"
"SchuleEins","Çetin","Schrage","1a","A student.","+93-982-722661","cetinm.schrage@example.de"
"SchuleEins","Zwenna","Schomaker","1b","A student.","+39-504-246300","zwennam.schomakerm@example.de"

§Kapitel 5. Test an der Kommandozeile

Das Testen einer Konfiguration, insbesondere bei Änderungen am Spalten-Mapping, ist u.U. an der Kommandozeile schneller als in der UMC. Bei Verwendung der richtigen Kommandozeilenparameter wird beinahe der gleiche Importvorgang ausgeführt, wie wenn er vom UMC-Modul gestartet würde.

Das Skript, das Beispieldaten erzeugt, druckt am Ende die benötigten Kommandozeilenparameter exakt aus. Hier ein Beispiel:

--school 'SchuleEins' --user_role 'ROLE' --source_uid 'schuleeins-ROLE' \
--conffile '/usr/share/ucs-school-import/configs/ucs-school-testuser-http-import.json' \
--infile 'test_users_2018-07-04_12:31:46.csv'

'ROLE' muss mit student, staff, teacher oder teacher_and_staff ersetzt werden, und SchuleEins mit der entsprechenden OU (in 'schuleeins-ROLE' in Kleinbuchstaben).