diff --git a/doc/errata/staging/ucs-school-umc-exam.yaml b/doc/errata/staging/ucs-school-umc-exam.yaml index 48f041e..1ee31f0 100644 --- a/doc/errata/staging/ucs-school-umc-exam.yaml +++ b/doc/errata/staging/ucs-school-umc-exam.yaml @@ -8,7 +8,7 @@ desc: | * It is now possible to run hooks on the DC master before the creation of exam users (Bug #44225). * Some UCR variables have not been cleaned up after the exam mode has been finished. - This problem has bow been fixed (Bug #44109). + This problem has been fixed (Bug #44109). * The time needed to create exam users has been reduced (Bug #43019). * The term "UCS@school" has been removed from some texts for branding purposes (Bug #44543). bug: [44225, 44109, 43019, 44543] diff --git a/doc/manual/ucsschool-import-handbuch-4.2.xml b/doc/manual/ucsschool-import-handbuch-4.2.xml index 48396c8..c8211be 100644 --- a/doc/manual/ucsschool-import-handbuch-4.2.xml +++ b/doc/manual/ucsschool-import-handbuch-4.2.xml @@ -64,7 +64,7 @@ Über eigene Python-Plugins kann die Schnittstelle erheblich erweitert werden. Dies - umfasst sowohl die Unterstützung für zusätzliche Dateiformat als auch die Implementierung von + umfasst sowohl die Unterstützung für zusätzliche Dateiformate als auch die Implementierung von zusätzlichen Automatismen, die während des Imports greifen. @@ -122,7 +122,7 @@ - Je nach Konfiguration werden die Werte des Eingabedatensatzes nach dem Einlesen automatisch geprüft, modifiziert und/oder erweitert. Darunter fällt z.B. auch die automatische Zuweisung eines eindeutigen Benutzernamens oder die Generierung einer Mail-Adresse. + Je nach Konfiguration werden die Werte des Eingabedatensatzes nach dem Einlesen automatisch geprüft, modifiziert und/oder erweitert. Darunter fällt z.B. auch die automatische Zuweisung eines eindeutigen Benutzernamens oder die Generierung einer E-Mail-Adresse. @@ -358,11 +358,9 @@ optional arguments: JSON-Konfigurationsformat Das JSON-Format erlaubt Daten in verschachtelten Strukturen zu speichern, und ist sowohl von Computern als auch Menschen zuverlässig zu lesen und zu schreiben. - Nach dem Editieren einer JSON-Datei kann ihre syntaktische Korrektheit mit Hilfe einer Webseite zur JSON Validierung (z.B. http://zaach.github.com/jsonlint/) oder eines Kommandozeilenprogramms überprüft werden: + Nach dem Editieren einer JSON-Datei kann ihre syntaktische Korrektheit mit Hilfe einer Webseite zur JSON Validierung oder eines Kommandozeilenprogramms überprüft werden: -univention-install libjson-xs-perl - -cat my_config.json | json_xs + python -m json.tool < my_config.json @@ -375,16 +373,16 @@ cat my_config.json | json_xs - Eine Kurzreferenz aller Konfigurationsschlüssel findet sich auf dem DC Master im Verzeichnis /usr/share/doc/ucs-school-import/. + Eine Kurzreferenz aller Konfigurationsschlüssel findet sich auf dem Domänencontroller Master im Verzeichnis /usr/share/doc/ucs-school-import/.
Globale Konfiguration - In den folgenden Tabellen kommt es layoutbedingt zu Freizeichen und Umbrüchen in Variablen- und Schlüsselnamen. + In den folgenden Tabellen kommt es layoutbedingt zu Leerzeichen und Umbrüchen in Variablen- und Schlüsselnamen. Diese müssen in den Konfigurationsdateien bzw. an der Kommandozeile entfernt werden. - Keines der Schlüsselwörter enthält ein Freizeichen oder einen Schrägstrich. + Keines der Schlüsselwörter enthält ein Leerzeichen oder einen Schrägstrich. @@ -533,7 +531,7 @@ cat my_config.json | json_xs csv:incell- \ delimiter - Dieses Objekt enthält Informationen darüber, welches Zeichen innerhalb einer Zelle zwei Daten trennt und kann Z.B. bei der Angabe von mehreren Telefonnummern verwendet werden. Es kann ein Standard (default) und pro &ucsUDM;-Attribut eine Konfiguration (mit dem Namen des Schlüssels in csv:mapping) definiert werden. + Dieses Objekt enthält Informationen darüber, welches Zeichen innerhalb einer Zelle zwei Daten trennt und kann z.B. bei der Angabe von mehreren Telefonnummern verwendet werden. Es kann ein Standard (default) und pro &ucsUDM;-Attribut eine Konfiguration (mit dem Namen des Schlüssels in csv:mapping) definiert werden. Standard (object): {"default": ..} @@ -566,6 +564,7 @@ cat my_config.json | json_xs scheme:email Schema aus dem die Email-Adresse erzeugt werden soll. + Standard (string): "<firstname>[0].<lastname>@<maildomain>" @@ -598,7 +597,7 @@ Zu den oben beschriebenen Ersetzungen kommen noch zwei weitere hinzu: [ scheme: \ username: \ default - Schema aus dem der Benutzername erzeugt werden soll, wenn kein Schema für speziell für diesen Benutzertyp existiert. + Schema aus dem der Benutzername erzeugt werden soll, wenn kein Schema speziell für diesen Benutzertyp existiert. Standard (string): "<:umlauts><firstname>[0].<lastname>[COUNTER2]" @@ -633,6 +632,7 @@ Zu den oben beschriebenen Ersetzungen kommen noch zwei weitere hinzu: [ Wenn auf true gesetzt, werden keine Benutzer gelöscht, oder nur solche für die es in den Eingabedaten explizit vermerkt ist. Dies kann genutzt werden, um eine Änderung an &ucsUAS;-Benutzern vorzunehmen, ohne einen vollständigen Soll-Zustand zu übergeben. + Standard (bool): false @@ -648,7 +648,7 @@ Zu den oben beschriebenen Ersetzungen kommen noch zwei weitere hinzu: [ output:new_ \ user_passwords - Diese Variable definiert den Pfad zur CSV-Datei, in die die Passwörter neuer Benutzer geschrieben werden. Auf den Dateinamen wird die Python-Funktion datetime.datetime.strftime() angewandt. Wenn ein Python-Format-StringPython Format-String Dokumentation: in ihm vorkommt, wird dieser umgewandelt (siehe Beispiel output:user_import_summary). + Diese Variable definiert den Pfad zur CSV-Datei, in die Passwörter neuer Benutzer geschrieben werden. Auf den Dateinamen wird die Python-Funktion datetime.datetime.strftime() angewandt. Wenn ein Python-Format-StringPython Format-String Dokumentation: in ihm vorkommt, wird dieser umgewandelt (siehe Beispiel output:user_import_summary). Standard (string): nicht gesetzt @@ -738,7 +738,7 @@ Muss zwingend entweder in einer Konfigurationsdatei oder an der Kommandozeile ge
- "default" Schlüssel + "default"-Schlüssel Einige Einstellungen erlauben das Setzen von verschiedenen Werten, je nach Rolle des Benutzers, der gerade importiert wird. In einem solchen Fall gibt es immer den Schlüssel default, der automatisch verwendet wird, wenn es keinen Schlüssel in der Konfiguration für die betroffene Benutzerrolle gibt. @@ -784,7 +784,7 @@ Muss zwingend entweder in einer Konfigurationsdatei oder an der Kommandozeile ge Anton geht also in die Klasse 1A der Schule Schule1 und in die Klasse 2B der Schule Schule2. - Die Namen der Schulen bzw. Klassen sind ohne Freizeichen und durch Komma getrennt, aufgelistet. + Die Namen der Schulen bzw. Klassen sind ohne Leerzeichen und durch Komma getrennt, aufgelistet. Als Trennzeichen innerhalb einer CSV-Zelle wird das Komma verwendet, da dies implizit aus der Standardeinstellung csv:incell-delimiter:default="," aus /usr/share/ucs-school-import/configs/user_import_defaults.json übernommen wurde. @@ -883,8 +883,8 @@ udm users/user - Bei der obigen, langen Ausgabe, handelt sich um die Beschreibung eines ImportUser Objektes. - Dieses zu kennen wird wichtig für der Programmierung von Hooks (siehe ), mit denen vor und nach dem Anlegen, Ändern oder Löschen von Benutzern noch Aktionen ausgeführt werden können. + Bei der obigen, langen Ausgabe handelt es sich um die Beschreibung eines ImportUser Objektes. + Dieses zu kennen wird wichtig für die Programmierung von Hooks (siehe ), mit denen vor und nach dem Anlegen, Ändern oder Löschen von Benutzern noch Aktionen ausgeführt werden können. Es existieren zwei "Sonderwerte" die in der Konfiguration der Zuordnung (mapping) verwendet werden können: __action und __ignore: @@ -900,11 +900,13 @@ udm users/user __ignore: Der Inhalt dieser Spalte wird ignoriert. + - Weitere, eigene Interpretationen von Eingabewerten können in einer abgeleiteten Klasse (siehe ) von ucsschool.importer.reader.csv_reader.CsvReader in der Methode handle_input() erzeugt werden. + Weitere, eigene Interpretationen von Eingabewerten können in einer von ucsschool.importer.reader.csv_reader.CsvReader abgeleiteten Klasse (siehe ) in der Methode handle_input() erzeugt werden. Als Beispiel kann handle_input() in ucsschool.importer.legacy.legacy_csv_reader.LegacyCsvReader dienen, welches für ein überholtes Tool den Sonderwert __activate (neue Benutzer de/aktivieren) hinzufügt. + Um Unterstützung für den Import von anderen Dateiformaten als CSV (JSON, XML etc) hinzuzufügen, kann von ucsschool.importer.reader.base_reader.BaseReader abgeleitet werden (siehe ). @@ -914,12 +916,13 @@ udm users/user
Formatierungsschema - Es kann wünschenswert – oder wie im Fall von Benutzername und E-Mail-Adresse notwendig – sein Attribute aus den Werten anderer Attribute zu erzeugen. - Zum Beispiel speichern und exportieren Schulverwaltungssoftware häufig keine Benutzernamen und E-Mail-Adressen die zur eingesetzten Infrastruktur passen. + Es kann wünschenswert – oder wie im Fall von Benutzername und E-Mail-Adresse notwendig – sein, Attribute aus den Werten anderer Attribute zu erzeugen. + Zum Beispiel speichern und exportieren Schulverwaltungssoftwares häufig keine Benutzernamen und E-Mail-Adressen, die zur eingesetzten Infrastruktur passen. Aus diesem Grund unterstützt die Importsoftware die Erzeugung von Attributen mit Hilfe von konfigurierbaren Schemata. Das Format ist das gleiche wie das bei den Benutzervorlagen eingesetzte (siehe ). + Es existieren dedizierte Konfigurationsschlüssel für die Attribute email, recordUID und username. Darüber hinaus können Schemata für beliebige &ucsUDM; Attribute (mit dem Namen des Attributs als Schlüssel) hinterlegt werden. @@ -940,7 +943,7 @@ udm users/user
Einmalige Benutzernamen - Benutzername müssen in der gesamten Domäne, nicht nur an einer Schule, einmalig sein. Darüber hinaus kann es die Anforderung geben, dass Benutzernamen auch "historisch einmalig" sind, sich also niemals wiederholen. + Benutzernamen müssen in der gesamten Domäne, nicht nur an einer Schule, einmalig sein. Darüber hinaus kann es die Anforderung geben, dass Benutzernamen auch "historisch einmalig" sind, sich also niemals wiederholen. Aus diesem Grund können zur Erzeugung von Benutzernamen, über die üblichen Variablen in Formatierungsschema (siehe ) hinaus, spezielle Zählervariablen verwendet werden. @@ -995,7 +998,7 @@ udm users/user Das Benutzerkonto wird nicht gelöscht, sondern deaktiviert und mit einem Verfallsdatum versehen. Dies entspricht dem Deaktivieren und Setzen eines Kontoablaufdatum im &ucsUMC;-Modul Benutzer. - Der Benutzer kann später final gelöscht werden. + Der Benutzer kann später endgültig gelöscht werden. Sollte der Benutzer kurze Zeit später erneut "angelegt" werden, wird das alte Benutzerkonto reaktiviert. Diese Variante wird ausgewählt durch die Konfiguration user_deletion:delete=false, user_deletion:expiration=3 (das Konto wird sofort deaktiviert, verfällt aber erst in drei Tagen). @@ -1141,7 +1144,7 @@ udm users/user dn string - DN des Benutzers im LDAP, wenn er jetzt gespeichert würde. + DN des Benutzer-Objekts im LDAP, wenn es jetzt gespeichert werden würde. entry_count @@ -1169,12 +1172,13 @@ udm users/user
Hooks - Hooks (engl. Haken) sind Stellen im Programmcode an die zusätzlicher Code "gehängt" werden kann. + Hooks (engl. Haken) sind Stellen im Programmcode, an die zusätzlicher Code "gehängt" werden kann. + Für den Benutzerimport sind acht Stellen vorgesehen: jeweils vor und nach dem Anlegen, Ändern, Löschen oder Verschieben von Benutzern. Zur Nutzung der Hook-Funktionalität muss eine eigene Python-Klasse erstellt werden, die von ucsschool.importer.utils.user_pyhook.UserPyHook ableitet. - In der Klasse können Methoden pre_create(), post_create() etc definiert werden, welche zum jeweiligen Zeitpunkt ausgeführt werden. + In der Klasse können Methoden pre_create(), post_create(), etc. definiert werden, welche zum jeweiligen Zeitpunkt ausgeführt werden. Der Name der Datei mit der eigenen Klasse muss auf .py enden und im Verzeichnis /usr/share/ucs-school-import/pyhooks abgespeichert werden. @@ -1257,7 +1261,7 @@ class MyHook(UserPyHook): Es handelt sich bei self.logger um eine Instanz eines Python logging ObjektsPython Dokumentation: . - In pre_remove() wird das Heimatverzeichnisses des Benutzers benötigt. + In pre_remove() wird das Heimatverzeichnis des Benutzers benötigt. Da dies nicht eines der direkt am Objekt stehenden Daten ist (siehe ), muss zuerst das gesamte Benutzerobjekt aus dem LDAP geladen werden. Dies tut user.get_udm_object(), welches als Argument ein LDAP-Verbindungsobjekt erwartet. Dieses ist im Hook-Objekt an self.lo gespeichert. @@ -1267,7 +1271,7 @@ class MyHook(UserPyHook): Falls das Benutzerobjekt in einem post-Hook geändert werden soll, so ist es möglich user.modify_without_hooks() auszuführen, aber generell sollte ein erneutes Modifizieren nach dem Speichern vermieden werden. - Die Methoden create(), modify() und remove() sollten in Hooks nie ausgeführt werden, da dies zu einer Rekursion führen kann. + Die Methoden create(), modify() und remove() des Benutzerobjekts sollten von Hook-Methoden nicht ausgeführt werden, da dies zu einer Rekursion führen kann.
@@ -1301,12 +1305,12 @@ class MyUsernameHandler(UsernameHandler): return new_number_str - In counter_variable_to_function() wird den existierenden beiden Variablen eine weitere hinzugefügt, und auf die neue Funktion verwiesen. - always_counter_with_zeros() verwendet always_counter() zur Erzeugung der nächsten freien Zahl, schreibt diese aber dann so um, dass sie immer vier Stellen lang ist (vorne wird mit Nullen aufgefüllt). + In counter_variable_to_function() wird den existierenden beiden Variablen eine weitere hinzugefügt und auf die neue Funktion verwiesen. + always_counter_with_zeros() verwendet always_counter() zur Erzeugung der nächsten freien Zahl, schreibt diese aber dann so um, dass sie immer vier Stellen lang ist (der Anfang wird mit Nullen aufgefüllt). Wird die Klasse unter /usr/local/lib/python2.7/dist-packages/usernames_with_zeros.py abgespeichert, so kann sie unter Python als usernames_with_zeros.MyUsernameHandler verwendet werden. - Evtl. muss zuvor das Verzeichnis angelegt werden: + Zuvor muss das Verzeichnis angelegt werden: mkdir -p /usr/local/lib/python2.7/dist-packages @@ -1335,15 +1339,16 @@ Anton0003 Es gibt jetzt zwar eine neue Klasse mit der neuen Funktionalität. Aber wie wird die Importsoftware nun dazu gebracht die neue Klasse zu verwenden? +
Abstract Factory - Für dieses immer wiederkehrende Problem gibt es verschiedene EntwurfsmusterWikipedia Entwurfsmuster: . - Für die Importsoftware wurde sich für das der Abstract FactoryWikipedia Abstrakte Fabrik: entschieden. + + Die Architektur der Importsoftware ist als Abstract FactoryWikipedia Abstrakte Fabrik: implementiert. In ihr wird die Erzeugung von Objekten zentralisiert. - Sie zeichnet sich u.a. dadurch aus, dass sie erlaubt das Auszutauschen mehrerer Komponenten einer Software konsistent zu halten. + Sie zeichnet sich u.a. dadurch aus, dass sie erlaubt das Austauschen mehrerer Komponenten einer Software konsistent zu halten. Im Fall der Importsoftware ist die abstract factory jedoch nicht Abstrakt, alle Methoden wurden implementiert. @@ -1369,6 +1374,7 @@ Anton0003 Welche Methode gewählt wird, hängt davon ab ob die Anpassungen nur punktuell sind, oder ob es sich um ein größeres Umschreiben der Importsoftware handelt. +
@@ -1405,7 +1411,7 @@ class MyUserImportFactory(DefaultUserImportFactory): - Wird diese Datei nun als /usr/local/lib/python2.7/dist-packages/my_userimport_factory.py abgespeichert, so kann sie in der Konfiguration zur Verwendung als factory for die Importsoftware folgendermaßen aktiviert werden: + Wird diese Datei nun als /usr/local/lib/python2.7/dist-packages/my_userimport_factory.py abgespeichert, so kann sie in der Konfiguration zur Verwendung als factory für die Importsoftware folgendermaßen aktiviert werden: { "factory": "my_userimport_factory.MyUserImportFactory"