Die Importsoftware kann gegenwärtig Daten nur aus CSV-Dateien^[1] einlesen. Wie eine Unterstützung für weitere Dateiformate (z.B. JSON, XML etc.) hinzugefügt werden kann, kann dem Kapitel 4 entnommen werden.

Das Tool ucs-school-user-import unterstützt den Import von Benutzerdaten aus mehreren Quellverzeichnissen. Um jeden UCS@school-Benutzer einem Benutzer in einer Quelldatenbank eindeutig zuordnen zu können, werden am UCS@school-Benutzerobjekt zwei zusätzliche Attribute gespeichert: sourceUID und recordUID.

Die sourceUID ist ein eindeutiger Bezeichner für die Quelldatenbank von der ein Benutzer importiert wurde. Der Bezeichner kann frei gewählt werden und muss für jede Quelldatenbank eindeutig sein. Er ist während des Imports auf der Kommandozeile bzw. in der Konfigurationsdatei für jede Quelldatenbank explizit mit anzugeben.

Die recordUID ist ein eindeutiger Bezeichner für den Benutzer in der Quelldatenbank. Als Bezeichner kann z.B. auf vorhandene Attribute innerhalb der Quelldatenbank, wie z.B. eine Schüler- oder Mitarbeiternummer, zurückgegriffen werden. Sollte kein eindeutig identifizierendes Attribut in der Quelldatenbank vorhanden sein, kann auch durch die Konkatenation von mehreren Attributen der Quelldatenbank ein ein eindeutiger Bezeichner generiert werden.

Durch die Kombination dieser beiden Bezeichner kann ein UCS@school-Benutzer genau einem Benutzer in einem bestimmten Quellverzeichnis zugeordnet werden.

Mit Hilfe der beiden Bezeichner sourceUID und recordUID wird versucht, jeden Eingabedatensatz genau einem UCS@school-Benutzer zuzuordnen:

# /usr/share/ucs-school-import/scripts/ucs-school-user-import --help
usage: ucs-school-user-import [-h] [-c CONFFILE] [-i INFILE]
                [-l LOGFILE] [-m] [-n] [-s SCHOOL]
                [--set [KEY=VALUE [KEY=VALUE ...]]]
                [--sourceUID sourceUID] [-u USER_ROLE] [-v]
optional arguments:
  -h, --help            show this help message and exit
  -c CONFFILE, --conffile CONFFILE
            Configuration file to use (see
            /usr/share/doc/ucs-school-import for an
            explanation on configuration file stacking).
  -i INFILE, --infile INFILE
            CSV file with users to import (shortcut for
            --set input:filename=...).
  -l LOGFILE, --logfile LOGFILE
            Write to additional logfile (shortcut for
            --set logfile=...).
  --set [KEY=VALUE [KEY=VALUE ...]]
            Overwrite setting(s) from the configuration file. Use ':' in
            key to set nested values (e.g. 'scheme:email=...').
  -m, --no-delete
            Only add/modify given user objects. User objects not
            mentioned within input files are not deleted/deactived
            (shortcut for --set no_delete=...) [default: False].
  -n, --dry-run
            Dry run - don't actually commit changes to LDAP (shortcut
            for --set dry_run=...) [default: False].
  --sourceUID sourceUID
            The ID of the source database (shortcut for
            --set sourceUID=...) [mandatory either here or in the
            configuration file].
  -s SCHOOL, --school SCHOOL
            Name of school. Set only, if the source data does not
            contain the name of the school and all users are from one
            school (shortcut for --set school=...) [default: None].
  -u USER_ROLE, --user_role USER_ROLE
            Set this, if the source data contains users with only one
            role <student|staff|teacher|teacher_and_staff>
            (shortcut for --set user_role=...) [default: None].
  -v, --verbose
            Enable debugging output on the console [default: False].

Nahezu alle Kommandozeilenparameter können auch in den Konfigurationsdateien angegeben werden. Um Variablen aus Konfigurationsdateien an der Kommandozeile zu setzen, kann --set verwendet werden. Geschachtelte Konfigurationsvariablen können mit dem Doppelpunkt angegeben werden.

Um z.B. "2" als die Anzahl der Kopfzeilen in einer CSV-Datei anzugeben, kann entweder in einer Konfigurationsdatei stehen:

{
    "csv": {
        "header_lines": 2
    }
}

oder es kann an der Kommandozeile der folgende Parameter verwendet werden:

--set csv:header_lines=2

Alle Zuweisungen für Variablen können leerzeichengetrennt hinter dem Kommandozeilenparameter --set aufgelistet werden. Dabei ist zu beachten, dass nur ein --set-Parameter an der Kommandozeile ausgewertet wird.

--set csv:header_lines=2 maildomain=univention.de no_delete=True

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:

univention-install libjson-xs-perl

cat my_config.json | json_xs

Im Folgenden werden alle Konfigurationsschlüssel und ihre möglichen Werte und Typen beschrieben.

Schlüssel sind immer als Zeichenketten (string) zu behandeln und müssen in doppelten Anführungszeichen stehen. Als Datentypen werden folgende Typen unterstützt: Wahrheitswerte (boolean: true / false), Ganzzahlen (int), Gleitkommazahlen (float), Listen (list: Werte die in [ und ] eingeschlossen sind) und Objekte (object: neue Verschachtelungsebene die in { und } eingeschlossen wird). Die Verschachtelungstiefe wird in den Schlüsseln wie oben beschrieben mit Doppelpunkten angezeigt.

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. Erlaubte Werte für die Benutzerrollen-Schlüssel sind student, staff, teacher und teacher_and_staff.

Es müssen nicht alle zwangsläufig Schlüssel für alle Benutzerrollen angegeben werden. Gilt für eine Einstellung z.B. das gleiche für Mitarbeiter und Lehrer und weicht nur der Wert für die Schüler-Benutzerrolle ab, so reicht es aus, default und student zu konfigurieren. In den Fällen staff, teacher und teacher_and_staff wird in Abwesenheit einer spezifischen Konfiguration automatisch auf default zurückgefallen:

{
    "scheme": {
        "username": {
            "default": "<:umlauts><firstname>[0].<lastname>[COUNTER2]",
            "student": "<:umlauts><firstname>.<lastname><:lower>[ALWAYSCOUNTER]"
        }
    }
}

Während des Imports aus einer CSV-Datei müssen die Daten einer Zeile, Attributen des anzulegenden bzw. zu ändernden Benutzerobjekts zugeordnet werden. Diese Zuordnung geschieht im Konfigurationsobjekt csv:mapping. In ihm stehen Schlüssel-Wert-Paare: CSV-Spalte → Benutzerattribut.

Folgendes Beispiel zeigt wie der Import von drei Schülern an zwei Schulen konfiguriert werden kann. Die Schulverwaltungssoftware hat folgendes CSV produziert:

"Schulen","Vorname","Nachname","Klassen","Mailadresse","phone"
"schule1,schule2","Anton","Meyer","schule1-1A,schule2-2B","anton@schule.local",""
"schule1,schule2","Bea","Schmidt","schule1-2B,schule2-1A","bea@schule.local","0421-1234567890"
"schule2","Daniel","Krause","schule2-1A","daniel@schule.local",""

Als erstes fällt auf, dass ein Schüler an zwei Schulen gleichzeitig eingeschrieben ist. Schulübergreifende Benutzerkonten wurden mit UCS@school 4.1R2 eingeführt^[3] und werden von der Importsoftware unterstützt. Entsprechend sind die Namen der Klassen so kodiert, dass sie eindeutig einer Schule zugeordnet werden können. 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. 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.

Folgende Konfiguration nutzt implizit die Standardeinstellung csv:header_lines=1 aus /usr/share/ucs-school-import/configs/user_import_defaults.json und verwendet damit die Spaltennamen aus der CSV-Kopfzeile als Schlüssel.

{
    "csv": {
        "mapping": {
            "Schulen": "schools",
            "Vorname": "firstname",
            "Nachname": "lastname",
            "Klassen": "school_classes",
            "Mailadresse": "email",
            "phone": "phone"
        }
    }
}

Um die Konfiguration zu überprüfen kann ein Testlauf mit --dry-run gestartet werden. Anschließend steht in /var/log/univention/ucs-school-import.log ein Protokoll das Debug-Ausgaben enthält. Hier findet sich:

2016-06-28 17:47:25 INFO  user_import.read_input:81  ------ Starting to read users from input data... ------
[..]
2016-06-28 17:47:25 DEBUG base_reader.next:73  Input 3: ['schule1', 'Bea', 'Schmidt', 'schule1-2B,schule2-1A',
'bea@schule.local', 'Sch\xc3\xbclerin mit Telefon', '0421-1234567890'] -> {u'Schulen': u'schule1',
u'Vorname': u'Bea', u'phone': u'0421-1234567890', u'Nachname': u'Schmidt', u'Klassen': u'schule1-2B,schule2-1A',
u'Mailadresse': u'bea@schule.local'}

Ab der zweiten Zeile ist dies folgendermaßen zu lesen:

Das Einlesen aus der CSV-Datei ist gelungen. Die Daten wurden den Schlüsseln aus der CSV-Kopfzeile zugeordnet. Da diese in csv:mapping verwendet werden, kann nun weiter unten, beim Anlegen der Benutzer, die Zuordnung der Daten zu Benutzerattributen beobachtet werden:

2016-06-28 17:47:25 INFO  user_import.create_and_modify_users:107  ------ Creating / modifying users... ------
[..]
2016-06-28 17:47:25 INFO  user_import.create_and_modify_users:128  Adding ImportStudent(name='B.Schmidt',
school='schule1', dn='uid=B.Schmidt,cn=schueler,cn=users,ou=schule1,dc=uni,dc=dtr', old_dn=None) (source_uid:NewDB
record_uid:bea@schule.local) attributes={'$dn$': 'uid=B.Schmidt,cn=schueler,cn=users,ou=schule1,dc=uni,dc=dtr',
'display_name': 'Bea Schmidt', 'record_uid': u'bea@schule.local', 'firstname': 'Bea',
'lastname': 'Schmidt', 'type_name': 'Student', 'school': 'schule1', 'name': 'B.Schmidt',
'disabled': 'none', 'email': u'bea@schule.local', 'birthday': None, 'type': 'importStudent', 'schools': ['schule1'],
'password': 'xxxxxxxxxx', 'source_uid': u'NewDB', 'school_classes': {'schule1': ['schule1-2B'],
'schule2': ['schule2-1A']}, 'objectType': 'users/user'} udm_properties={u'phone': [u'0421-1234567890'],
'overridePWHistory': '1', 'overridePWLength': '1'}...

Hier ist nun zu sehen, dass Daten umgewandelt und Attributen zugeordnet wurden, sowie dass einige Attribute aus anderen Daten generiert wurden:

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 Abschnitt 4.2), 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:

Weitere, eigene Interpretationen von Eingabewerten können in einer abgeleiteten Klasse (siehe Abschnitt 4.3) von ucsschool.importer.reader.csv_reader.CsvReader 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 Abschnitt 4.3).

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.

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 [ucs-handbuch]). Es existieren dedizierte Konfigurationsschlüssel für die Attribute email, recordUID und username. Darüber hinaus können Schemata für beliebige Univention Directory Manager Attribute (mit dem Namen des Attributs als Schlüssel) hinterlegt werden.

Im folgenden Beispiel würde allen aus den Eingabedaten übernommenen Telefonnummern die Ländervorwahl vorangestellt (und die führende 0 der Städtevorwahl entfernt), sowie die E-Mail-Adresse aus Vor- und Nachname berechnet:

{
    "scheme": {
        "email": "<firstname>[0].<lastname>@<maildomain>",
        "recordUID": "<email>",
        "phone": "+49-<phone>[1:]"
    }
}

Benutzername und Email-Adressen müssen in der gesamten Domäne, nicht nur an einer Schule, einmalig sein. Darüber hinaus kann es die Anforderung geben, dass Benutzernamen und Email-Adressen auch "historisch einmalig" sind, sich also niemals wiederholen.

Aus diesem Grund können zur Erzeugung von Benutzernamen und Email-Adressen, über die üblichen Variablen in Formatierungsschema (siehe Abschnitt 3.5) hinaus, spezielle Zählervariablen verwendet werden. Diese Variablen werden bei ihrer Verwendung automatisch hochgezählt. Ihr Wert wird pro Benutzername bzw. Email-Adresse gespeichert. Es existieren zwei Variablen, die sich darin unterscheiden wie die ersten Benutzer mit gleichem Benutzernamen bzw. Email-Adresse, benannt werden:

Im folgenden Beispiel würden für Bea Schmidt die Benutzernamen b.schmidt, b.schmidt2, b.schmidt3 sowie Email-Adressen bea.schmidt1@dom.ain, bea.schmidt2@dom.ain, bea.schmidt3@dom.ain erzeugt werden:

{
    "scheme": {
        "username": {
            "default": "<:umlauts><firstname>[0].<lastname><:lower>[COUNTER2]"
        },
        "email": "<firstname>.<lastname>[ALWAYSCOUNTER]@<maildomain>"
    },
	"maildomain": "dom.ain",
}

Um neue Zählervariablen hinzuzufügen, muss von der Klasse ucsschool.importer.utils.username_handler.UsernameHandler abgeleitet und die Methode counter_variable_to_function() überschrieben werden (siehe Abschnitt 4.3). Um Zählervariablen für Email-Adressen hinzuzufügen muss von der Klasse ucsschool.importer.utils.username_handler.EmailHandler abgeleitet werden.

Für das Löschen von Benutzern kann eine von drei Varianten konfiguriert werden:

Um eine der Löschvarianten zu ändern oder neue hinzuzufügen, muss von der Klasse ucsschool.importer.mass_import.user_import.UserImport abgeleitet und die Methode do_delete() überschrieben werden (siehe Abschnitt 4.3).

Die Klasse ImportUser wird verwendet um Daten von eingelesenen oder zu ändernden Benutzern zu speichern. An Objekten der ImportUser Klasse können folgende Attribute gesetzt werden:

Weitere interessante Attribute, die jedoch nur gelesen und nicht modifiziert werden sollten, sind:

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. Der Name der Datei mit der eigenen Klasse muss auf .py enden und im Verzeichnis /usr/share/ucs-school-import/pyhooks abgespeichert werden.

Die Methoden der Hook-Klasse bekommen als Argument das Benutzerobjekt übergeben, das aus dem LDAP geladen wurde bzw. im LDAP gespeichert werden soll. Veränderungen an diesem Objekt werden bei dessen Abspeicherung direkt ins LDAP übernommen.

Die Klasse definiert ein dictionary priority mit dessen Hilfe eine Reihenfolge definiert werden kann, sollten mehrere Hook-Klassen mit zum Einsatz kommen, die die gleichen Methoden definieren. Die Namen der Methoden die ausgeführt werden sollen sind die Schlüssel, Methoden mit höheren Zahlen werden zu erst ausgeführt. Ist der Wert None, wird die Methode deaktiviert.

Zur Erstellung einer eigenen Hook-Klasse kann das Beispiel in /usr/share/doc/ucs-school-import/hook_example.py kopiert und angepasst werden. Alle Funktionen die nicht ausgeführt werden sollen, sollten entweder gelöscht oder deaktiviert werden (indem ihr Wert in priority auf None gesetzt wird). Das könnte Beispielsweise so aussehen:

import datetime
import shutil

from ucsschool.importer.utils.user_pyhook import UserPyHook

class MyHook(UserPyHook):
    priority = {
        "pre_create": 1,
        "post_create": None,
        "pre_remove": 1
    }

    def pre_create(self, user):
        if user.birthday:
            bday = datetime.datetime.strptime(user.birthday,
                                              "%Y-%m-%d").date()
            if bday == datetime.date.today():
                self.logger.info("%s has birthday.", user)
                user.udm_properties["description"] = "Herzlichen \
                                                      Glückwunsch"

    def post_create(self, user):
        # Diese Function ist deaktiviert.
        self.logger.info("Running a post_create hook for %s.", user)

    def pre_remove(self, user):
        # backup users home directory
        self.logger.info("Backing up home directory of %s.", user)
        user_udm = user.get_udm_object(self.lo)
        homedir = user_udm["unixhome"]
        shutil.copy2(homedir, "/var/backup/{}".format(user.name))

In pre_create() wird in udm_properties an den Schlüssel description der Wert Herzlichen Glückwunsch geschrieben. Das explizite Abspeichern des user Objektes ist in dieser Funktion nicht nötig, da dies ja beim auf den Hook folgenden create geschieht.

In der Funktion wird außerdem mit self.logger.info() ein Text zu Protokoll gegeben. Es handelt sich bei self.logger um eine Instanz eines Python logging Objekts^[4].

In pre_remove() wird das Heimatverzeichnisses des Benutzers benötigt. Da dies nicht eines der direkt am Objekt stehenden Daten ist (siehe Abschnitt 4.1), 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.

Hooks erlauben das Ausführen von neuem Code zu bestimmten Zeitpunkten. Sie erlauben aber nicht bestehenden Code zu verändern. In einer objektorientierten Sprache wie Python wird dies üblicherweise getan, indem eine Klasse modifiziert wird. Soll für einen bestimmten Fall nur ein Teil der Klasse verändert werden, wird von ihr abgeleitet und nur dieser Teil verändert, der unveränderte Teil wird geerbt.

Folgendes Beispiel zeigt, wie der Klasse, welche die historisch einmaligen Benutzernamen erzeugt, eine weitere Variable hinzugefügt werden kann. Ein weiteres Beispiel ist in /usr/share/doc/ucs-school-import/subclassing_example.py zu finden.

from ucsschool.importer.utils.username_handler import UsernameHandler

class MyUsernameHandler(UsernameHandler):
    @property
    def counter_variable_to_function(self):
        name_function_mapping = super(MyUsernameHandler, self).counter_variable_to_function
        name_function_mapping["[ALWAYSWITHZEROS]"] = self.always_counter_with_zeros
        return name_function_mapping

    def always_counter_with_zeros(self, name_base):
        number_str = self.always_counter(name_base)
        number_int = int(number_str)
        new_number_str = "{:04}".format(number_int)
        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).

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:

mkdir -p /usr/local/lib/python2.7/dist-packages

Ob Python die Klasse findet, lässt sich testen mit:

python -c 'from usernames_with_zeros import MyUsernameHandler'

(Es sollte keine Ausgabe geben.)

Die neue Funktionalität lässt sich testen mit:

# python
>>> from usernames_with_zeros import MyUsernameHandler
>>> print MyUsernameHandler(15).format_username("Anton[ALWAYSCOUNTER]")
Anton1
>>> print MyUsernameHandler(15).format_username("Anton[ALWAYSWITHZEROS]")
Anton0002
>>> print MyUsernameHandler(15).format_username("Anton[ALWAYSWITHZEROS]")
Anton0003
>>> exit()

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?

{
    "classes": {
        "username_handler": "usernames_with_zeros.MyUsernameHandler"
    }
}

from ucsschool.importer.default_user_import_factory import DefaultUserImportFactory
from usernames_with_zeros import MyUsernameHandler

class MyUserImportFactory(DefaultUserImportFactory):
    def make_username_handler(self, max_length):
        return MyUsernameHandler(max_length)

{
    "factory": "my_userimport_factory.MyUserImportFactory"
}

Die folgenden Befehle müssen, mit angepassten Hostnamen und IP-Adressen, auf jedem Schulserver ausgeführt werden:

# UCR Variablen verfügbar machen
eval "$(ucr shell)"

# Name (Alias) des Servers auf dem das Heimatverzeichnis liegt
ucr set ucsschool/import/set/sambahome=schoolserver

# DNS-Eintrag schoolserver.$domainname -> IP des *jeweiligen* Schulservers
ucr set "connector/s4/mapping/dns/host_record/schoolserver.$domainname/static/ipv4"=172.16.3.12

# DNS-Eintrag aktivieren
invoke-rc.d univention-s4-connector restart

Folgendes muss auf dem DC Master ausgeführt werden:

# DNS Forward-Eintrag einrichten (school.local durch korrekte Domäne ersetzen,
# IP eines zentralen Server, z.B. des DC Master, verwenden)
udm dns/host_record create \
    --superordinate "zoneName=school.local,cn=dns,$ldap_base" \
    --set name=schoolserver \
    --set a=172.16.1.1

Der Befehl host schoolserver sollte nun auf allen Schulservern die IP des jeweiligen Schulservers liefern. Mit nslookup schoolserver können die gleiche DNS-Anfrage komfortabel an verschiedene DNS-Server geschickt werden.