Attachment #8831 for bug #41739

View | Details | Raw Unified | Return to bug 41739
Collapse All | Expand All

Lines 8-14 desc: \| Link Here

(-)a/doc/errata/staging/ucs-school-umc-exam.yaml (-1 / +1 lines)
8	* It is now possible to run hooks on the DC master before the creation	8	* It is now possible to run hooks on the DC master before the creation
9	of exam users (Bug #44225).	9	of exam users (Bug #44225).
10	* Some UCR variables have not been cleaned up after the exam mode has been finished.	10	* Some UCR variables have not been cleaned up after the exam mode has been finished.
11	This problem has bow been fixed (Bug #44109).	11	This problem has been fixed (Bug #44109).
12	* The time needed to create exam users has been reduced (Bug #43019).	12	* The time needed to create exam users has been reduced (Bug #43019).
13	* The term "UCS@school" has been removed from some texts for branding purposes (Bug #44543).	13	* The term "UCS@school" has been removed from some texts for branding purposes (Bug #44543).
14	bug: [44225, 44109, 43019, 44543]	14	bug: [44225, 44109, 43019, 44543]




		</para>
		<para>
			Über eigene Python-Plugins kann die Schnittstelle erheblich erweitert werden. Dies
			umfasst sowohl die Unterstützung für zusätzliche Dateiformate als auch die Implementierung von
			zusätzlichen Automatismen, die während des Imports greifen.
		</para>
		<para>

				</listitem>
				<listitem>
					<simpara>
						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.
					</simpara>
				</listitem>
				<listitem>

			<title>JSON-Konfigurationsformat</title>
			<para>
				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 oder eines Kommandozeilenprogramms überprüft werden:
				<programlisting>
					python -m json.tool < my_config.json

cat my_config.json | json_xs
				</programlisting>
			</para>
			<para>

			</para>
			<note>
				<simpara>
					Eine Kurzreferenz aller Konfigurationsschlüssel findet sich auf dem Domänencontroller Master im Verzeichnis <filename class="directory">/usr/share/doc/ucs-school-import/</filename>.
				</simpara>
			</note>
			<section id="configuration:json_format:global">
				<title>Globale Konfiguration</title>
				<caution>
					<simpara>
						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.
						<emphasis>Keines</emphasis> der Schlüsselwörter enthält ein Leerzeichen oder einen Schrägstrich.
					</simpara>
				</caution>
				<table id="table:global_configuration">

<!-- csv:incell-delimiter -->
							<row>
								<entry morerows="1"><varname>csv:incell- \ delimiter</varname></entry>
								<entry>Dieses Objekt enthält Informationen darüber, welches Zeichen <emphasis>innerhalb</emphasis> einer Zelle zwei Daten trennt und kann z.B. bei der Angabe von mehreren Telefonnummern verwendet werden. Es kann ein Standard (<literal>default</literal>) und  pro &ucsUDM;-Attribut eine Konfiguration (mit dem Namen des Schlüssels in <link linkend="configuration:json_format:userimport:csv:mapping"><literal>csv:mapping</literal></link>) definiert werden.</entry>
							</row>
							<row>
								<entry align="right">Standard (<classname>object</classname>): <literal>{"default": ..}</literal></entry>

							<row>
								<entry morerows="1"><varname>scheme:email</varname></entry>
								<entry>Schema aus dem die Email-Adresse erzeugt werden soll.</entry>
								<!-- TODO: Das "Schema"-Format sollte irgendwo erklärt werden. -->
							</row>
							<row>
								<entry align="right">Standard (<classname>string</classname>): <literal>"&lt;firstname&gt;[0].&lt;lastname&gt;@&lt;maildomain&gt;"</literal></entry>

<!-- scheme:username:default -->
							<row>
								<entry morerows="1"><varname>scheme: \ username: \ default</varname></entry>
								<entry>Schema aus dem der Benutzername erzeugt werden soll, wenn kein Schema speziell für diesen Benutzertyp existiert.</entry>
							</row>
							<row>
								<entry align="right">Standard (<classname>string</classname>): <literal>"&lt;:umlauts&gt;&lt;firstname&gt;[0].&lt;lastname&gt;[COUNTER2]"</literal></entry>

<option>-m</option>
<option>--no-delete</option></literallayout></entry>
								<entry>Wenn auf <literal>true</literal> gesetzt, werden keine Benutzer gelöscht, oder nur solche für die es in den Eingabedaten <emphasis>explizit</emphasis> vermerkt ist. Dies kann genutzt werden, um eine Änderung an &ucsUAS;-Benutzern vorzunehmen, ohne einen vollständigen Soll-Zustand zu übergeben.</entry>
								<!-- TODO: mention more explicit that this can be used to just add some users? -->
							</row>
							<row>
								<entry align="right">Standard (<classname>bool</classname>): <literal>false</literal></entry>

<!-- output:new_user_passwords -->
							<row>
								<entry morerows="1" id="configuration:json_format:userimport:output:new_user_passwords"><varname>output:new_ \ user_passwords</varname></entry>
								<entry>Diese Variable definiert den Pfad zur CSV-Datei, in die Passwörter neuer Benutzer geschrieben werden. Auf den Dateinamen wird die Python-Funktion <methodname>datetime.datetime.strftime()</methodname> angewandt. Wenn ein <foreignphrase>Python-Format-String</foreignphrase><footnote><para><foreignphrase>Python Format-String</foreignphrase> Dokumentation: <ulink url="https://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior"/></para></footnote> in ihm vorkommt, wird dieser umgewandelt (siehe Beispiel <link linkend="configuration:json_format:userimport:output:user_import_summary"><literal>output:user_import_summary</literal></link>).</entry>
							</row>
							<row>
								<entry align="right">Standard (<classname>string</classname>): nicht gesetzt</entry>

		</section>

		<section id="configuration:default_key">
			<title>"default"-Schlüssel</title>
			<para>
				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 <literal>default</literal>, der automatisch verwendet wird, wenn es keinen Schlüssel in der Konfiguration für die betroffene Benutzerrolle gibt.

				Anton geht also in die Klasse <literal>1A</literal> der Schule <literal>Schule1</literal> und in die Klasse <literal>2B</literal> der Schule <literal>Schule2</literal>.
			</para>
			<para>
				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 <link linkend="configuration:json_format:userimport:csv:incell-delimiter:default"><literal>csv:incell-delimiter:default=","</literal></link> aus <filename>/usr/share/ucs-school-import/configs/user_import_defaults.json</filename> übernommen wurde.
			</para>
			<para>

				</para>
			</note>
			<para>
				Bei der obigen, langen Ausgabe handelt es sich um die Beschreibung eines <link linkend="extending:import_user_class"><classname>ImportUser</classname></link> Objektes.
				Dieses zu kennen wird wichtig für die Programmierung von Hooks (siehe <xref linkend="extending:hooks"/>), mit denen vor und nach dem Anlegen, Ändern oder Löschen von Benutzern noch Aktionen ausgeführt werden können.
			</para>
			<para>
				Es existieren zwei "Sonderwerte" die in der Konfiguration der Zuordnung (<link linkend="configuration:json_format:userimport:csv:mapping"><varname>mapping</varname></link>) verwendet werden können: <literal>__action</literal> und <literal>__ignore</literal>:

					<listitem>
						<simpara>
							<literal>__ignore</literal>: Der Inhalt dieser Spalte wird ignoriert.
							<!-- TODO: das ist nicht verständlich -->
						</simpara>
					</listitem>
				</itemizedlist>
				Weitere, eigene Interpretationen von Eingabewerten können in einer von <classname>ucsschool.importer.reader.csv_reader.CsvReader</classname> abgeleiteten Klasse (siehe <xref linkend="extending:subclassing"/>) in der Methode <methodname>handle_input()</methodname> erzeugt werden.
				Als Beispiel kann <methodname>handle_input()</methodname> in <classname>ucsschool.importer.legacy.legacy_csv_reader.LegacyCsvReader</classname> dienen, welches für ein überholtes Tool den Sonderwert <literal>__activate</literal> (neue Benutzer de/aktivieren) hinzufügt.
				<!-- TODO: was heißt überholt? was heißt Sonderwert?-->
			</para>
			<para>
				Um Unterstützung für den Import von anderen Dateiformaten als CSV (JSON, XML etc) hinzuzufügen, kann von <classname>ucsschool.importer.reader.base_reader.BaseReader</classname> abgeleitet werden (siehe <xref linkend="extending:subclassing"/>).

		<section id="configuration:scheme_formatting">
			<title>Formatierungsschema</title>
			<para>
				Es kann wünschenswert &ndash; oder wie im Fall von Benutzername und E-Mail-Adresse notwendig &ndash; 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.
			</para>
			<para>
				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 <biblioref linkend="ucs-handbuch"/>).
				<!-- TODO: auf das direkte Kapitel verlinken?! -->
				Es existieren dedizierte Konfigurationsschlüssel für die Attribute <property>email</property>, <property>recordUID</property> und <property>username</property>.
				Darüber hinaus können Schemata für beliebige &ucsUDM; Attribute (mit dem Namen des Attributs als Schlüssel) hinterlegt werden.
			</para>

		<section id="configuration:unique_usernames">
			<title>Einmalige Benutzernamen</title>
			<para>
				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.
			</para>
			<para>
				Aus diesem Grund können zur Erzeugung von Benutzernamen, über die üblichen Variablen in Formatierungsschema (siehe <xref linkend="configuration:scheme_formatting"/>) hinaus, spezielle Zählervariablen verwendet werden.

						<simpara>
							Das Benutzerkonto wird nicht gelöscht, sondern deaktiviert und mit einem Verfallsdatum versehen.
							Dies entspricht dem Deaktivieren und Setzen eines Kontoablaufdatum im &ucsUMC;-Modul <guimenu>Benutzer</guimenu>.
							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 <literal>user_deletion:delete=false</literal>, <literal>user_deletion:expiration=3</literal> (das Konto wird sofort deaktiviert, verfällt aber erst in drei Tagen).
						</simpara>

							<row>
								<entry><varname>dn</varname></entry>
								<entry>string</entry>
								<entry>DN des Benutzer-Objekts im LDAP, wenn es jetzt gespeichert werden würde.</entry>
							</row>
							<row>
								<entry><varname>entry_count</varname></entry>

		<section id="extending:hooks">
			<title>Hooks</title>
			<para>
				Hooks (engl. Haken) sind Stellen im Programmcode, an die zusätzlicher Code "gehängt" werden kann.
				<!-- hmm, komische Beschreibung -->
				Für den Benutzerimport sind acht Stellen vorgesehen: jeweils vor und nach dem Anlegen, Ändern, Löschen oder Verschieben von Benutzern.
			</para>
			<para>
				Zur Nutzung der Hook-Funktionalität muss eine eigene Python-Klasse erstellt werden, die von <classname>ucsschool.importer.utils.user_pyhook.UserPyHook</classname> ableitet.
				In der Klasse können Methoden <methodname>pre_create()</methodname>, <methodname>post_create()</methodname>, etc. definiert werden, welche zum jeweiligen Zeitpunkt ausgeführt werden.
				Der Name der Datei mit der eigenen Klasse muss auf <filename>.py</filename> enden und im Verzeichnis <filename class="directory">/usr/share/ucs-school-import/pyhooks</filename> abgespeichert werden.
			</para>
			<note>

				Es handelt sich bei <property>self.logger</property> um eine Instanz eines Python <classname>logging</classname> Objekts<footnote><para>Python Dokumentation: <ulink url="https://docs.python.org/2/library/logging.html"/></para></footnote>.
			</para>
			<para>
				In <methodname>pre_remove()</methodname> wird das Heimatverzeichnis des Benutzers benötigt.
				Da dies nicht eines der direkt am Objekt stehenden Daten ist (siehe <xref linkend="extending:import_user_class"/>), muss zuerst das gesamte Benutzerobjekt aus dem LDAP geladen werden.
				Dies tut <methodname>user.get_udm_object()</methodname>, welches als Argument ein LDAP-Verbindungsobjekt erwartet.
				Dieses ist im <wordasword>Hook-Objekt</wordasword> an <property>self.lo</property> gespeichert.

					Falls das Benutzerobjekt in einem <foreignphrase>post-Hook</foreignphrase> geändert werden soll, so ist es möglich <methodname>user.modify_without_hooks()</methodname> auszuführen, aber generell sollte ein erneutes Modifizieren <emphasis>nach</emphasis> dem Speichern vermieden werden.
				</para>
				<para>
					Die Methoden <methodname>create()</methodname>, <methodname>modify()</methodname> und <methodname>remove()</methodname> des Benutzerobjekts sollten von Hook-Methoden nicht ausgeführt werden, da dies zu einer Rekursion führen kann.
				</para>
			</caution>
		  </section>

        return new_number_str
			</programlisting>
			<para>
				In <methodname>counter_variable_to_function()</methodname> wird den existierenden beiden Variablen eine weitere hinzugefügt und auf die neue Funktion verwiesen.
				<methodname>always_counter_with_zeros()</methodname> verwendet <methodname>always_counter()</methodname> 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).
			</para>
			<para>
				Wird die Klasse unter <filename class="directory">/usr/local/lib/python2.7/dist-packages/usernames_with_zeros.py</filename> abgespeichert, so kann sie unter Python als <classname>usernames_with_zeros.MyUsernameHandler</classname> verwendet werden.
				Zuvor muss das Verzeichnis angelegt werden:
				<programlisting>
mkdir -p /usr/local/lib/python2.7/dist-packages
				</programlisting>

			<para>
				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?
				<!-- rethorische Fragen in einer Dokumentation ist kein üblicher Stil! -->
			</para>

			<section id="extending:subclassing:abstract_factory">
				<title>Abstract Factory</title>
				<para>
					<!-- Hmm, eine Dokumentation sollte keine Herleitung sein, wie man den Lösungsansatz gefunden hat. -->
					Die Architektur der Importsoftware ist als <foreignphrase>Abstract Factory</foreignphrase><footnote><para>Wikipedia Abstrakte Fabrik: <ulink url="https://de.wikipedia.org/wiki/Abstrakte_Fabrik"/></para></footnote> implementiert.
					In ihr wird die Erzeugung von Objekten zentralisiert.
					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 <foreignphrase>abstract factory</foreignphrase> jedoch nicht Abstrakt, alle Methoden wurden implementiert.
				</para>
				<para>

				</para>
				<para>
					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.
					<!-- TODO: mir fehlt hier vor allem erstmal eine Übersicht aller Klassen und deren Methoden -->
				</para>
			</section>


					</programlisting>
				</para>
				<para>
					Wird diese Datei nun als <filename>/usr/local/lib/python2.7/dist-packages/my_userimport_factory.py</filename> abgespeichert, so kann sie in der Konfiguration zur Verwendung als <property>factory</property> für die Importsoftware folgendermaßen aktiviert werden:
					<programlisting>
{
    "factory": "my_userimport_factory.MyUserImportFactory"

Return to bug 41739