Nutzerimport-Planung

Die Funktion „Nutzerimport-Planung“ dient dazu, CSV-Batch-Importaufträge für Nutzerdateien zu konfigurieren und direkt in der GUI auf Importprotokolle zuzugreifen. Es lassen sich mehrere mandantenspezifische Importaufträge anlegen, die geplant oder manuell verarbeitet werden und auf das Erstellen und/oder Aktualisieren von Nutzern beschränkt sein können.

Die Funktion ist über den Menüpfad „Admin > Nutzer > Nutzerverwaltung“ erreichbar. Sie enthält die zwei Registerkarten „Nutzerimporte“ und „Protokolldatei“.

Die Funktion ist für Scheer IMC Beratende gedacht. Auch Teile der Kundschaft, die mit Batch-Datei-Schnittstellen vertraut sind, nutzen sie erfolgreich. Mit der Funktion lassen sich Importaufträge erstellen, bearbeiten und löschen sowie Protokolldateien aufrufen. Die folgenden Abschnitte erläutern die Optionen im Detail.

Funktionen der Nutzerimport-Planung

Erstellung eines Nutzerimport-Auftrags

Ein neuer Nutzerimport-Auftrag ist schnell angelegt, wenn die erforderlichen Nutzerattribute bereits konfiguriert sind. Dazu auf das Symbol „Erstellen“ klicken. Daraufhin öffnet sich ein neuer Browser-Tab. Für die Konfiguration sind neun Felder auszufüllen, darunter der Upload einer XML-Zuordnungsdatei.

Die folgenden Felder und Einstellungen befinden sich auf der Registerkarte „Beschreibung“:

• Identifikator: Eindeutiger Name des Importauftrags. Er entspricht nicht dem Namen der CSV-Datei.

• Mandant: Der festgelegte Mandant wird zum „Stamm-Mandanten“ der importierten Nutzer, sofern die Geschäftsregeln nichts anderes vorgeben. In einem Multi-Mandanten-System ist der Nutzerimport nur für Nutzende innerhalb des Mandanten sichtbar, der einen manuellen Nutzerimport in der Funktion „Nutzer“ durchführt.

• Attribut-Mapping: Dieses Upload-Feld erwartet eine XML-Datei, die die Spaltennamen der CSV-Datei den Namen der Nutzerattribute in der Datenbank zuordnet. Details stehen im Abschnitt zur XML-Zuordnungsdatei.

• Importdateien: Name der CSV-Datei, die verwendet wird, wenn der Importauftrag „Täglich“, „Wöchentlich“ oder „Monatlich“ geplant ist. Bei der Planung „Manuell“ wird der Dateiname beim Import nicht erzwungen.

• Trennzeichen für Importdaten: Das Spaltentrennzeichen ist TAB, Semikolon, Komma oder Pipe. Die Datei muss beim Import dazu passen. Eine Pipe wird empfohlen, wenn das Quellsystem die CSV-Datei mit diesem Trennzeichen erzeugen kann.

• Checkboxen:

  • Synchronisierung des Imports: Die Option kommt vor allem zum Einsatz, wenn ein Quellsystem keinen Beendigungsstatus senden kann, weil es nur aktive Datensätze liefert. Diese Option wird bei der Kundschaft häufig genutzt.

  • Verschlüsselung benutzen: Für zusätzliche Sicherheit lassen sich Importdateien mit PGP verschlüsseln. Bei aktivierter Option muss eine verschlüsselte Datei geliefert werden, die den Einstellungen in der Funktion „Konfiguration > Schlüsselverwaltung“ entspricht.

  • Deaktivierung nicht eindeutiger Nutzer: Alle Nutzer, die in der CSV-Datei zweimal vorkommen, werden deaktiviert. Das gilt nur für Nutzer, die mit demselben Import erstellt wurden (prüfbar über das Nutzerattribut „Import-ID“).

• Import-Einschränkungen: Ein Importauftrag lässt sich auf das Erstellen oder auf das Aktualisieren von Nutzern beschränken. Der Standardwert „Keine“ bedeutet, dass keine Einschränkung aktiv ist. Der Auftrag erstellt dann neue Nutzerdatensätze und aktualisiert bestehende.

  • Nur einfügen: Unbekannte IDs erstellen neue Nutzer, bekannte IDs werden ignoriert.

  • Nur aktualisieren: Unbekannte IDs werden ignoriert, bekannte IDs aktualisieren bestehende Nutzer.

  • Keine: Unbekannte IDs erstellen neue Nutzer, bekannte IDs aktualisieren bestehende Nutzer.

• Ausführen als Nutzer: Wählt einen Nutzer in der imc Learning Suite (LMS) aus, in dessen Namen der Import verarbeitet und die Protokolldateien gesendet werden.

• Terminierung: Einzelauswahl, die festlegt, wie und wann der Importauftrag verarbeitet wird.

  • Inaktiv: Der Importauftrag steht weder für manuelle noch für automatische Läufe zur Verfügung.

  • Manuell: Der Importauftrag ist beim Import in der GUI über das Menü „Nutzer“ auswählbar.

  • Täglich: Der Importauftrag läuft täglich zu der im Cron-Job festgelegten Zeit. Die CSV-Datei muss vorher auf einen SFTP-Server hochgeladen sein.

  • Wöchentlich: Der Importauftrag läuft wöchentlich zu der im Cron-Job festgelegten Zeit. Die CSV-Datei muss vorher auf einen SFTP-Server hochgeladen sein.

  • Monatlich: Der Importauftrag läuft monatlich zu der im Cron-Job festgelegten Zeit. Die CSV-Datei muss vorher auf einen SFTP-Server hochgeladen sein.

Erstellung einer XML-Zuordnungsdatei

Die .xml-Zuordnungsdatei wird verwendet, um die Struktur der .csv-Datei zu definieren, einschließlich der Zuordnung von Spaltennamen zu Namen in der Datenbank für persönliche Attribute. Die Benutzerimportdatei muss mindestens die obligatorischen persönlichen Attribute in LMS enthalten, wie unten gezeigt, aber die Anzahl der Spalten, die persönlichen Attributen zugeordnet sind, ist normalerweise viel höher. Um einen neuen Nutzer anzulegen, müssen die folgenden obligatorischen Standardattribute im System enthalten sein:

• LOGIN (Generator kann verwendet werden)

• VORNAME

• NACHNAME

• E-MAIL

• EXT_ID_CSV (obligatorische eindeutige Kennung für CSV-Importe)

Es gibt viele Tools zum Erstellen von XML-Dateien, darunter das frei verfügbare Notepad++. Das Format einer einfachen XML-Zuordnungsdatei, die die oben genannten obligatorischen Attribute enthält, würde wie folgt aussehen:

<CSV>

<attributeMapping>

<mapping sourceField="Benutzername" clixField="LOGIN"/>

<mapping sourceField="Vorname" clixField="FIRSTNAME"/>

<mapping sourceField="Nachname" clixField="LASTNAME"/>

<mapping sourceField="E-Mail" clixField="EMAIL"/>

<mapping sourceField="ID" clixField="EXT_ID_CSV"/>

</attributeMapping>

</CSV>

Erweiterte Mapping-Einstellungen

Die .xml-Zuordnung kann einige fortgeschrittene Funktionen unterstützen, wie zum Beispiel:

• ignoreUnmappedFields - Ignoriert alle Spalten in der CSV-Datei, die nicht zugeordnet sind.

• ignoreEmptyField - Konfiguriert pro Zuordnungszeile, wobei „false“ einen ausgefüllten Wert durch einen leeren Wert überschreiben kann und „true“ einen ausgefüllten Wert nicht durch einen leeren Wert überschreibt.

• hashident - Bezieht sich auf einen Hash-Tabellen-Identifikator, bei dem es sich um eine Konvertierungstabelle in den Registrierungsgeschäftsregeln (siehe unten) handelt. Wird häufig für den Import anhand von Auswahllisten verwendet, um diese anstelle der Scheer IMC-ID oder mit Datumsfeldformatkonvertierungen zu verwenden.

Ein Beispiel für eine komplexere Zuordnung:

<attributeMapping ignoreUnmappedFields="true">

<mapping sourceField="Benutzername" clixField="LOGIN"/>

<mapping sourceField="Vorname" clixField="FIRSTNAME"/>

<mapping sourceField="Nachname" clixField="LASTNAME"/>

<mapping sourceField="E-Mail" clixField="EMAIL"/>

<mapping sourceField="ID" clixField="EXT_ID_CSV"/>

<mapping sourceField="Zugangsvoraussetzungen" clixField="ACCESS_REQ" ignoreEmptyField="false"/>

<mapping sourceField="Stelle" clixField="POSITION" hashident="POSITIONHASHTABLE"/>

</attributeMapping>

Einrichtung des SFTP-Servers

Sind Importaufträge für die automatische tägliche, wöchentliche oder monatliche Verarbeitung geplant, organisiert eine Scheer IMC Beratung den Zugriff auf einen von Scheer IMC bereitgestellten SFTP-Server. Die Kundschaft lädt die vereinbarte CSV-Datei zum vereinbarten Zeitpunkt hoch. Ein Transferauftrag überträgt die Datei vom SFTP-Server an einen festgelegten Ort auf dem Inhaltsserver des LMS (z. B. \data\person\personimport\src\staff).

Das Hosting-Team von Scheer IMC (ECMT) verwaltet den SFTP-Server, weil aus Sicherheitsgründen kein direkter Zugriff auf die von Scheer IMC gehosteten LMS-Server besteht. Es stellt der Kundschaft eindeutige Zugangsdaten für das SFTP-Konto bereit. Bei Bedarf lässt sich der Zugriff per IP-Whitelist einschränken.

Cron-Jobs und ihre Konfiguration

Ein Cron-Job ist ein automatischer, zeitgesteuerter Job, der so konfiguriert werden kann, dass er zu gewünschten Zeiten ausgeführt wird. Im LMS stehen viele Cron-Jobs zur Verfügung, darunter „UserImport“. Die Cron-Jobs wurden traditionell von Scheer IMC-Beratern programmiert. Ab 2022 besteht die Möglichkeit, sie über eine neue Funktion „Cron-Jobs“ direkt in der GUI zu konfigurieren. Bei der Cron-Konfiguration ist die zeitliche Abfolge der Aufgaben wichtig, um sicherzustellen, dass die Daten so aktuell wie möglich sind. So muss beispielsweise der Cron „UserImport“ nach der Übertragung der Datei durch SFTP ausgeführt werden und sollte vor den Aufgaben „TargetGroupPersonAssignment“ und „ParticipantAutomaticRegistration“ ausgeführt werden. Bei Cron-Jobs verwendet Scheer imc den Quartz-Cron-Standard. Die Datums-/Zeitformate sind hier beschrieben: https://www.freeformatter.com/cron-expression-generator-quartz.html. Im folgenden Beispiel würde der Import täglich um 23 Uhr ausgeführt werden.

Verschlüsselung von CSV-Dateien

Für CSV-Nutzerimportdateien unterstützt Scheer IMC die PGP-Verschlüsselung. Die Kundschaft kann verschlüsselte Dateien für zusätzliche Sicherheit auf den SFTP-Server laden. Sie verwaltet den privaten Schlüssel und teilt Scheer IMC einen öffentlichen Schlüssel mit, mit dem die Dateien beim Import entschlüsselt werden können. Beratende von Scheer IMC konfigurieren diese Jobs. Sie lassen sich mandantenspezifisch einrichten, sodass nicht jeder Nutzerimport-Auftrag betroffen ist.

Registrierungs- und Geschäftsregeln

Werden Nutzer lokal in der GUI oder per Import erstellt oder aktualisiert, löst das System eine Reihe von Geschäftsregeln aus. Beratende von Scheer IMC schreiben diese Regeln in XML-Code. Sie führen auf Basis von Nutzerattributwerten unter anderem folgende Aufgaben aus:

• Zuweisung von Nutzern zu Gruppen (Rollen oder Organisationseinheiten) oder Mandanten

• Zuweisung von Jobprofilen

• Erteilung von Freigaben auf Nutzer für Administratorengruppen

• Füllen von Einstellungen wie Spracheinstellungen oder Zeitzonen

• Bestimmung des Authentifizierungsstatus

• Weitere fortgeschrittene Regeln wie Umwandlungen

Geschäftsregeln werden in der Regel von Beratenden während der Implementierungsprojekte geschrieben. Sie lassen sich jederzeit direkt in der GUI aktualisieren, entweder global für alle Mandanten (Funktion „Konfiguration“) oder mandantenspezifisch (Funktion „Mandant“).

Zugriff auf Importprotokolle und deren Auswertung

Protokolldateien werden normalerweise automatisch per E-Mail an den Nutzer gesendet, der im Feld „Ausführen als Nutzer“ festgelegt ist, sobald ein Import abgeschlossen ist. Zusätzlich sind sie direkt in der Funktion „Nutzerimport-Planung“ auf der Registerkarte „Protokolldatei“ abrufbar. Dort zeigt eine Übersicht jeden Import in zeitlicher Reihenfolge mit Status, Anzahl der Datensätze und vor allem der Anzahl der fehlerhaften Datensätze, die zu bearbeiten sind.

Eine detaillierte CSV-Protokolldatei lässt sich als ZIP-Datei herunterladen. Dazu das gewünschte Importdatum markieren und auf die Schaltfläche „Herunterladen“ klicken. Die in der ZIP-Datei enthaltene CSV-Datei beginnt erneut mit einer Übersicht. Darunter folgt für jeden Nutzerdatensatz der Nutzerdatendatei eine Zeile mit dem Importstatus.

Bei Fehlern mit „Strg + F“ nach dem Wort „Fehler“ suchen, um alle nicht importierten Datensätze zu finden. Anschließend in jeder betroffenen Zeile die zugehörige Spalte anklicken, um die Beschreibung des Fehlers einschließlich des Fehlercodes zu sehen. Die häufigsten Fehler betreffen:

• Login-Konflikte

• Fehlende Pflichtattribute wie E-Mail

• Falsche E-Mail-Formate

• Falsche Datumsformate (bei Datumsattributen)

• Doppelte Einträge in der Spalte EXT_ID_CSV

Eine Beispielfehlermeldung für ein doppeltes Login lautet: „Fehler, leider ist der von Ihnen eingegebene Login-Name bereits einem anderen Benutzer zugewiesen. Bitte wählen Sie einen anderen Login-Namen. [Fehlercode:PRS0126]“.

Tipps zum Troubleshooting bei Importfehlern

Bei Importfehlern helfen folgende Prüfungen:

• Prüfen, ob die erforderlichen Attribute in der Zuordnung und in der CSV-Datei enthalten sind.

• Die in der Datei „mapping.xml“ definierten Werte für Kodierung und fieldSeparator sowie die angewendete Einstellung in der CSV-Datei prüfen.

• Die Spaltennamen und die Attributnamen prüfen, die in der Datei „mapping.xml“, in der CSV-Datei und im LMS definiert sind.

• Die Registrierungsregeln, die korrekte Schreibweise der Attributnamen und gegebenenfalls Hashtable-Verweise prüfen.

Tipps & Tricks

• Für die Konfiguration komplexer Importe, etwa mit Geschäftsregeln und automatischer Terminierung, empfiehlt sich der Kontakt zum Scheer IMC Consulting-Team.

• Bei einem geplanten Import ohne Synchronisierung ist ein manueller Import mit denselben Zuordnungen und Einstellungen sinnvoll. Er eignet sich zum Testen und als Notlösung, falls der geplante Import ausfällt.

• Bei einem Komma als Trennzeichen kommt ein Komma innerhalb eines Werts oft vor. In diesem Fall das Komma in Anführungszeichen setzen, um Fehler bei der Spaltenverarbeitung zu vermeiden.

• Lässt sich eine Aufgabe logisch aus Attributdaten ableiten, ist unter Umständen eine Registrierungs-/Geschäftsregel möglich. Dafür empfiehlt es sich, mit einer erfahrenen Beratung von Scheer IMC zu sprechen und ein Level-2-Support-Ticket zu erstellen.