UCS@school - Handbuch zur CLI-Import-Schnittstelle

PDF herunterladen

JSON-Konfigurationsformat

2.3. 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 oder eines Kommandozeilenprogramms überprüft werden:

$ python3 -m json.tool < my_config.json

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.

    • Objekte: object - Neue Verschachtelungsebene die in { und } eingeschlossen wird. Die Verschachtelungstiefe wird in den Schlüsseln wie oben beschrieben mit Doppelpunkten angezeigt.

Bemerkung

Eine Kurzreferenz aller Konfigurationsschlüssel findet sich auf dem Primary Directory Node im Verzeichnis /usr/share/doc/ucs-school-import/.

2.3.1. Globale Konfiguration#

dry_run, -n, --dry-run#

Ob ein Testlauf gestartet werden soll. Es werden keine Änderungen vorgenommen.

Standard (boolean):

false

logfile, -l, --logfile#

Datei in die das ausführliche Protokoll geschrieben werden soll. Es wird außerdem eine Datei, die auf .info endet, mit weniger technischen Details, angelegt.

Standard (string)

/var/log/univention/ucs-school-import.log

verbose, -v, --verbose#

Ob ein ausführliches Protokoll auf die Kommandozeile geschrieben werden soll.

Standard (boolean)

true

2.3.2. Konfiguration des Benutzerimports#

classes#

Die Methoden der Klasse DefaultUserImportFactory können überschrieben werden, ohne die Klasse selbst zu ändern.

Die Namen der überschriebenen Methoden ohne vorangestelltes make_ sind die Schlüssel, der volle Python-Pfad der Wert.

Standardmäßig ist das Objekt leer und die Klasse DefaultUserImportFactory wird unverändert verwendet.

Ein Beispiel findet sich in Überschreiben einer Methode.

Standard (object)

{}

factory#

Voller Python-Pfad zu einer Python-Klasse, die von DefaultUserImportFactory abgeleitet ist. Wenn gesetzt, wird sie an ihrer Stelle verwendet (siehe Ersetzen durch eigene Klasse).

Standard (string)

ucsschool.importer.default_user_import_factory.DefaultUserImportFactory

input#

Objekt, welches Informationen über die Eingabedaten enthält.

Standard (object)

input:type#

Datenformat der angegebenen Eingabedatei. UCS@school unterstützt derzeit nur CSV als Datenformat.

Standard (string)

csv

input:filename, -i, --infile#

Einzulesende Datei.

Standard (string)

/var/lib/ucs-school-import/new-format-userimport.csv

activate_new_users#

Objekt, welches Konfigurationsmöglichkeiten zur Benutzeraktivierung enthält.

Standardmäßig ist im Objekt nur der Schlüssel default gesetzt.

Weitere Schlüssel student, staff, teacher, teacher_and_staff sind möglich (siehe default-Schlüssel).

Standard (object)

{"default": ..}

activate_new_users:default#

Diese Variable definiert, ob ein neuer Benutzer automatisch aktiviert werden soll. Ist false eingestellt, wird das Benutzerkonto beim Anlegen automatisch deaktiviert.

Standard (boolean)

true

csv#

Dieses Objekt enthält Informationen darüber, wie CSV-Eingabedaten interpretiert werden sollen.

Standard (object)

{"header_lines": .., "incell-delimiter": .., "mapping": ..}

csv:delimiter#

Diese Variable definiert das Trennzeichen zwischen zwei Spalten. Als Wert wird üblicherweise ein Komma, Semikolon oder Tabulator verwendet. Die Importschnittstelle versucht das Trennzeichen automatisch zu erkennen, wenn diese Variable nicht gesetzt ist.

Standard (string)

nicht gesetzt

csv:header_lines#

Diese Variable definiert, wie viele Zeilen der Eingabedaten übersprungen werden sollen, bevor die eigentlichen Benutzerdaten anfangen.

Wird der Wert 1 (Kopfdatensatz) verwendet, wird der Inhalt der ersten Zeile als Namen der einzelnen Spalten interpretiert. Die dort verwendeten Namen können dann in csv:mapping als Schlüssel verwendet werden.

Standard (int)

1

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 Univention Directory Manager-Attribut eine Konfiguration (mit dem Namen des Schlüssels in csv:mapping) definiert werden.

Standard (object)

{"default": ..}

csv:incell-delimiter:default#

Standard-Trennzeichen innerhalb einer Zelle, wenn kein spezieller Schlüssel für die Spalte existiert.

Standard (string)

,

csv:mapping#

Enthält Informationen über die Zuordnung von CSV-Spalten zum Benutzerobjekt. Ist standardmäßig leer. Siehe Zuordnung von Eingabedaten zu Benutzerattributen.

Standard (object)

{}

deletion_grace_period#

Dieses Objekt enthält Einstellungen zum Löschen von Benutzern.

Standard (object)

{"deactivation": .., "deletion": ..}

deletion_grace_period:deactivation#

Definiert in wie vielen Tagen ein Benutzer, der nicht mehr in den Eingabedaten enthalten ist, deaktiviert (nicht gelöscht) werden soll.

Wenn 0 gesetzt ist, wird das betroffene UCS@school-Benutzerkonto sofort deaktiviert.

Wenn deletion_grace_period:deletion auf einen kleineren oder den gleichen Wert gesetzt ist, wird das Benutzerobjekt gelöscht statt deaktiviert.

Standard (int)

0

deletion_grace_period:deletion#

Definiert die Anzahl der Tage, die nach dem Import vergehen sollen, bevor der Benutzer gelöscht aus dem Verzeichnisdienst wird.

Bei einem Wert von 0 wird der Benutzer sofort gelöscht.

Bei größeren Zahlen wird das geplante Löschdatum im Univention Directory Manager-Attribut ucsschoolPurgeTimestamp gesetzt. Ein Cron Job löscht automatisch Benutzer, deren geplanter Löschzeitpunkt erreicht ist.

Standard (int)

0

normalize:firstname#

Definiert, ob der in der CSV-Datei angegebene Wert für den Vornamen (i.d.R. UTF-8-kodiert) auf die Kodierung ASCII normalisiert wird. Umlaute und Sonderzeichen werden dabei ersetzt (ä wird zu ae) oder entfernt.

Standard (boolean)

false

normalize:lastname#

Definiert, ob der in der CSV-Datei angegebene Wert für den Vornamen (i.d.R. UTF-8-kodiert) auf die Kodierung ASCII normalisiert wird. Umlaute und Sonderzeichen werden dabei ersetzt (ä wird zu ae) oder entfernt.

Standard (boolean)

false

scheme#

Enthält Informationen über die Erzeugung von Werten aus anderen Werten und Regeln.

Es können Ersetzungen wie in den Benutzervorlagen verwendet werden sowie alle Schlüssel aus csv:mapping. Neben Formatvorlagen für email, record_uid und username können Konfigurationen für beliebige Univention Directory Manager-Attribute hinterlegt werden. [ALWAYSCOUNTER] und [COUNTER2] werden nur in scheme:email und scheme:username verarbeitet.

Standard (object)

{"email": .., "record_uid": .., "username": {..}}

scheme:email#

Schema, aus dem die E-Mailadresse erzeugt werden soll. Zusätzlich zu den in Formatierungsschema beschriebenen Ersetzungen kommen noch zwei weitere hinzu: [ALWAYSCOUNTER] und [COUNTER2] (siehe Einmalige Benutzernamen und E-Mailadressen).

Für die Verwendung des email-Schemas ist es erforderlich, dass maildomain oder die Univention Configuration Registry-Variable mail/hosteddomains gesetzt ist. Anderenfalls wird keine Mailadresse generiert.

Standard (string)

"<firstname>[0].<lastname>@<maildomain>"

scheme:record_uid#

Schema aus dem die eindeutige ID des Benutzers in der Quelldatenbank (Schulverwaltungssoftware) erzeugt werden soll.

Standard (string)

"<email>"

scheme:username#

Enthält Informationen über die Erzeugung von Benutzernamen. Standardmäßig enthält das Objekt nur den Schlüssel default.

Weitere Schlüssel student, staff, teacher, teacher_and_staff sind möglich (siehe default-Schlüssel).

Zusätzlich zu den in Formatierungsschema beschriebenen Ersetzungen kommen noch zwei weitere hinzu: [ALWAYSCOUNTER] und [COUNTER2] (siehe Einmalige Benutzernamen und E-Mailadressen).

Standard (object)

{"default": ..}

scheme:username:default#

Schema aus dem der Benutzername erzeugt werden soll, wenn kein Schema speziell für diesen Benutzertyp (scheme:username:teacher etc.) existiert.

Standard (string)

"<:umlauts><firstname>[0].<lastname>[COUNTER2]"

scheme:<udm attribute name>#

Univention Directory Manager-Attribute, die aus einem Schema erzeugt werden sollen. Der Schlüssel braucht nicht in csv:mapping vorzukommen.

Standard (string)

nicht gesetzt

maildomain#

Der Wert dieser Variable wird beim Formatieren mit einem Schema in die Variable <maildomain> eingesetzt.

Wenn nicht gesetzt, wird versucht <maildomain> durch Daten aus dem System zu füllen. Dafür wird die UCR-Variable mail/hosteddomains herangezogen. Sind maildomain und mail/hosteddomains nicht gesetzt, werden keine Mailadressen automatisch generiert.

Standard (string)

nicht gesetzt

mandatory_attributes#

Liste von Univention Directory Manager Attributen, die an jedem Benutzer gesetzt sein müssen.

Standard (list)

["firstname", "lastname", "name", "record_uid", "school", "source_uid"]

no_delete, -m, --no-delete#

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 UCS@school-Benutzern vorzunehmen, ohne einen vollständigen Soll-Zustand zu übergeben oder um neue Benutzer hinzuzufügen.

Standard (boolean)

false

output#

Dieses Objekt enthält Informationen über zu produzierende Dokumente.

Standard (object)

{"import_summary": ..}

output:new_user_passwords#

Diese Variable definiert den Pfad zu der 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-String in ihm vorkommt, wird dieser umgewandelt (siehe Beispiel output:user_import_summary).

Standard (string)

nicht gesetzt

output:user_import_summary#

Diese Variable definiert den Pfad zu der CSV-Datei, in die eine Zusammenfassung des Import-Vorganges geschrieben wird. Auf den Dateinamen wird, wie bei output:new_user_passwords, die Python-Funktion datetime.datetime.strftime() angewandt.

Standard (string)

"/var/lib/ucs-school-import/summary/%Y/%m/user_import_summary_%Y-%m-%d_%H:%M:%S.csv"

password_length#

Definiert die Länge des zufälligen Passwortes, das für neue Benutzer erzeugt wird.

Standard (int)

15

Abhängig vom Vorhandensein spezifischer Benutzerpasswörter in den Importdaten geht der Importvorgang wie folgt mit Passwörtern um:

Keine Passwörter definiert

In den Importdaten sind keine Passwörter definiert: Der Importvorgang erzeugt zufällige Benutzerpasswörter in der konfigurierten Passwortlänge.

Passwörter definiert

In den Importdaten sind Benutzerpasswörter definiert:

  1. Länge der Benutzerpasswörter < password_length: Der Importvorgang bricht ab mit folgender Meldung: ucsschool.importer.exceptions.BadPassword: Password is shorter than 15 characters.

  2. Länge der Benutzerpasswörter > password_length: Der Importvorgang wird durchgeführt. Die Benutzerpasswörter werden auf die Länge von password_length gekürzt.

Benutzer können zu jedem späteren Zeitpunkt ihr Passwort selbst setzen. Dabei greift die Passwortrichtlinie für Benutzer. Der Wert aus password_length hat keinen Einfluss auf die Passwortrichtlinie. Nur der Importvorgang verwendet den Wert aus password_length.

Siehe auch

Informationen über Passwortrichtlinien für Benutzer

Verwaltung der Benutzerpasswörter in Univention Corporate Server - Handbuch für Benutzer und Administratoren [1]

evaluate_password_policies#

Ab UCS@school Version 5.0 v3: Schaltet die Evaluierung von Passwort Richtlinien während des Imports neuer Benutzer ein.

Standard (boolean)

false

school, -s, --school#

Schulkürzel/OU-Name der Schule, für die der Import sein soll. Dieser Wert gilt für alle Benutzer in den Eingabedaten.

Vorsicht

Der Wert sollte nur gesetzt werden, wenn die Schule nicht über die Eingabedaten gesetzt wird.

Standard (string)

nicht gesetzt

source_uid, --source_uid#

Eindeutige und unveränderliche Kennzeichnung der Datenquelle. Muss zwingend entweder in einer Konfigurationsdatei oder an der Kommandozeile gesetzt werden.

Standard (string)

nicht gesetzt

tolerate_errors#

Definiert die Anzahl an für die Import-Software nicht-kritischen Fehlern, die toleriert werden sollen, bevor der Import abgebrochen wird.

Wird der Wert -1 verwendet, bricht der Import nicht ab und fährt mit dem nächsten Eingabedatensatz fort.

Standard (int)

0

user_deletion#

Veraltet ab Version 4.2: Bitte deletion_grace_period verwenden.

Standard (object)

nicht gesetzt

user_role, -u, --user_role#

Definiert die Benutzerrolle für alle Eingabedatensätze.

Vorsicht

Diese Variable sollte nur gesetzt werden, wenn die Benutzerrolle nicht in den Eingabedaten enthalten ist und die Eingabedatensätze homogen alle die gleiche Benutzerrolle verwenden sollen.

Erlaubte Werte sind student, staff, teacher und teacher_and_staff.

Standard (string)

nicht gesetzt

username#

Enthält Informationen über die Erzeugung von Benutzernamen.

Standard (object)

{"max_length": {..}

username:max_length#

Enthält Informationen über die Länge von Benutzernamen.

Standard (object)

{"default": .., "student": ..}

username:max_length:default#

Länge eines Benutzernamens, wenn keine Konfiguration speziell für diesen Benutzertyp (username:max_length:staff etc.) existiert.

Warnung

Benutzerkonten mit Benutzernamen über 20 Zeichen Länge sind vom Support für Samba, Samba 4 Connector und Active Directory Connector ausgeschlossen.

Für eine fehlerfreie Funktionalität von Windows-Clients in der Domäne dürfen Benutzernamen nicht über mehr als 20 Zeichen verfügen.

Der Wert darf den Wert der Univention Configuration Registry-Variablen ucsschool/username/max_length nicht überschreiten.

Der Wert von username:max_length:student wird automatisch berechnet, wenn nicht explizit gesetzt. Er muss um die Länge des exam-prefix (normalerweise exam-, also 5) niedriger sein, als der von username:max_length:default.

Standard (int)

20

username:allowed_special_chars#

Enthält die erlaubten Sonderzeichen in Benutzernamen. Außer dem Punkt (.) sind Bindestrich (-) und Unterstrich (_) erlaubt. Die Liste wird als ein string dargestellt und wäre für alle drei Zeichen: ".-_".

Standard (string)

"."

school_classes_invalid_character_replacement#

Unerlaubte Zeichen im Namen einer Schulklasse werden mit diesem Wert ersetzt. Erlaubt sind Zahlen, Buchstaben (keine Umlaute) und die Zeichen . -_.

Standard (string)

"-"

Auf dieser Seite