Import-Tool

Über den Befehl pa_client.exe import können Datentabellen oder Benutzer aus CSV-Dateien oder ODBC-Datenbanktabellen automatisiert importiert werden.

Konfiguriert wird der Import über die Konfigurations-Datei import.ini im config-Verzeichnis.

In dieser INI-Datei wird pro Sektion ein Import definiert, darüber hinaus gibt es noch eine besondere Sektion [DEFAULT], in der Vorgabe-Werte definiert werden, die für alle Sektionen gelten:

[DEFAULT]
URL = https://documents.example.com/
Token = mJVEFmvHJFGeqhsmPoWzRkVgHI6X8K9g

[Kunden]
Category = datatable
Type = odbc
Datatable = kunden
UseAlias = true
Clear = true

DSN = MYDSN
UID = phoenix
PWD = phnxqdrt

SQL = SELECT name, iban FROM kunden

[CSV]
Type = csv
FileMask = D:\Import\L*.csv|D:\Lieferanten\**\lieferant.csv
Datatable = kunden
Active = true
Decimal = ,
MoveCompleted = D:\Imported
Mapping = index

[CSV/Mapping]
name = 1
iban = 2

Die Basis-Einstellung einer Sektion sind:

URL: Die Basis-URL zum Server.
Token: Das Token des Dienstbenutzers, über den der Import durchgeführt wird.
Category: Mögliche Werte sind datatable (für einen Import in eine Datentabelle) und users (für Benutzer-Import). Wenn diese Option fehlt, ist datatable die Voreinstellung.
Type: Mögliche Werte sind csv für Importe aus lokalen CSV-Dateien oder odbc für einen dynamischen Import aus einer Datenbank über eine ODBC-Datenquelle.

Es ist sinnvoll, Optionen wie URL und Token in die Sektion [DEFAULT] zu schreiben, da diese in der Regel in allen Sektionen identisch sind. Es ist aber auch möglich, einzelne Imports zu einem anderen Documents-Server durchzuführen, indem die URL in einer Sektion überschrieben wird.

Es muss eine Datenquelle (CSV-Datei oder ODBC-Datenbank) mit einem Importer (Datentabelle oder Benutzer) verknüpft werden.

Datenquelle `csv`

Importiert eine oder mehrere CSV-Dateien, die in einer Sektion alle das gleiche, konfigurierbare Format haben müssen. Die Liste der zu importierenden Dateien wird in der Option FileMask angegeben, die eine Dateimaske spezifiziert. Durch | getrennt können mehrere Dateimasken angegeben werden, * ist ein Platzhalter für beliebige Zeichen.

FileMask = D:\Import\L*.csv|D:\Lieferanten\*\lieferant.csv

In diesem Beispiel werden alle mit „L“ beginnenden CSV-Datein im Verzeichnis D:\Import importiert und darüber hinaus alle Dateien mit dem Namen lieferant.csv, die in einem Unterzeichnis von D:\Lieferanten liegen (der *-Platzhalter kann auch für Unterverzeichnisse stehen).

Die nachfolgenden Optionen haben die gleiche Auswirkung wie beim manuellen CSV-Import einer Datentabelle und definieren das Format der CSV-Datei:

Delimiter: Feld-Trennzeichen. Vorgabe ist das Semikolon.
Quotechar: Textqualifizierer.
Mapping: Mögliche Werte sind index und title (siehe unten). Wenn diese Option nicht konfiguriert ist, werden die Spalten der CSV-Datei bei einer Datentabelle den Datenfeldern genau in der Reihenfolge zugeordnet, wie sie in der Datentabelle konfiguriert sind. Beim Benutzer-Import darf diese Option nicht weggelassen werden.
Module: Ein Python-Modul im Verzeichnis customisation\csv, mit dem der Import detailliert angepasst werden kann.
Skip: Gibt an, wie viele Zeilen am Anfang der CSV-Datei übersprungen werden sollen.
Limit: Limitiert den Import auf die ersten n Zeilen der CSV-Datei. Sinnvoll zum Debuggen, um die Import-Optionen von großen CSV-Dateien zu testen, ohne dass sofort viele Zeilen importiert werden.

Darüber hinaus gibt es zwei Optionen, die einstellen, was mit erfolgreich importieren CSV-Dateien passieren soll:

MoveCompleted: Gibt ein existierende Verzeichnis an, in das erfolgreich importierte CSV-Dateien verschoben werden soll.
DeleteCompleted: Wenn diese Option auf true eingestellt ist, werden erfolgreich importierte CSV-Dateien sofort gelöscht. Diese Option wird ignoriert, wenn MoveCompleted ebenfalls konfiguriert ist.

Zuordnung von Spalten aus der CSV-Datei

Wenn in der Sektion eines CSV-Import die Option Mapping konfiguriert ist, muss in einer Unter-Sektion [Sektionsname/Mapping] die Zuordnung konfiguriert werden.

Beispiel für die Option index:

[Lieferanten]
Type = csv
Mapping = index
...

[Lieferanten/Mapping]
name = 2
iban = 3

Hier werden die Werte aus der 2. Spalte der CSV in das Datenfeld mit dem Kurznamen name importiert und die aus der 3. Spalte in das Feld iban. Da für die erste Spalte keine Zurordnung konfiguriert, werden dessen Werte beim Import ignoriert. Bei Datentabellen muss im Mapping auf der linken Seite der Kurzname der Spalte angegeben werden und bei Benutzer fest definierte Felder.

Beispiel für die Option title:

[Lieferanten]
Type = csv
Mapping = title
...

[Lieferanten/Mapping]
name = Kunden-Name
iban = IBAN

Hier wird die erste Zeile der CSV dazu verwendet, die Zurordnung der Spalten anhand des Spalten-Titels automatisch zu ermitteln. Groß- und Kleinschreibung wird bei der Zurordnung des Titels ignoriert und nicht angegebene Spalten ignoriert.

Customisation-Skripte für CSV-Import

In der Option Module kann der Namen eines Python-Moduls angegeben werden, das sich im Verzeichnis customisation\csv befindet. Dieses Modul muss eine Klasse Transformer enthalten, die eine Methode transform enthält.

Die Klasse wird für eine Sektion nur einmal instantiiert, unabhängig von der Anzahl der Dateien. Die transform-Methode wird für die originale CSV-Zeile aufgerufen, bevor eine Zuordnung anhand der Mapping-Sektion durchgeführt wird.

class Transformer:
    def transform(self, row, context):
        # Gibt die Zeile unverändert zurück.
        return row

Der Parameter row enthält eine CSV-Zeile (als Liste). context ist ein Objekt, das folgende Attribute enthält:

line: Die aktuelle Zeilennummer (beginnend mit 1), um z.B. die erste Zeile gesondert zu behandeln.
filename: Den absoluten Pfad zur aktuell verarbeiteten CSV-Datei.

Die transform-Methode gibt eine Liste (die auch eine andere Länge haben kann) zurück, die die modifizierte Zeile enthält. Wenn der Wert None zurückgegeben wird, wird die aktuelle Zeile beim Import übersprungen.

Datenquelle `odbc`

Führt eine SQL-Abfrage über eine ODBC-Datenquelle aus.

Über die Parameter DSN (Pflichtfeld), UID, PWD, Server und Database wird die ODBC-Datenquelle konfiguriert. Werte, die bereits direkt in der DSN konfiguriert sind, müssen hier nicht noch zusätzlich angegeben werden. Auch diese Parameter können problemlos in der Sektion [DEFAULT] konfiguriert werden.

Ebenfalls Pflicht ist die Option SQL, die das aufzurufende SQL-Statement konfiguriert.

Die UseAlias bestimmt, wie das Resultat der SQL-Abfrage ausgewertet wird. Wenn diese Option fehlt, werden die Datenfelder in der Datentabelle genau in der Reihenfolge in der Ergebnismenge des SQL-Statements importiert: Angenommen, in einer Datentabelle in zwei Spalten mit den Kurznamen lieferant und iban in genau dieser Reihenfolge konfiguriert. Es gibt eine SQL-Datenbank Lieferanten, in der diese Felder aber Name und Konto heißen. Dann muss bei der Feldauswahl im SELECT genau die Reihenfolge der Datentabelle abfragt werden:

SELECT Name, Konto FROM Lieferanten

Das folgende Statement würde die Werte jedoch in die falschen Spalten importieren:

SELECT Konto, Name FROM Lieferanten

Wenn man nun UseAlias=true einstellt, ist die Reihenfolge im SQL-Statement egal, stattdessen muss für jede Spalte ein Alias angegeben werden, der dem Kurznamen in der Datentabelle entspricht. Bei einem Benutzer-Import ist UseAlias=true sogar Pflicht, weil es hier keine definierte Reihenfolge der einzelnen Benutzerdaten gibt.

SELECT Konto AS iban, Name AS lieferant FROM Lieferanten

Wenn ein Alias verwendet wird, der keinem Kurznamen einer Spalte in der Datentabelle entspricht, wird diese Spalte beim Import ignoriert.

Datentabellen-Import

Bei Category=datatable können in der Sektion noch folgende Optionen definiert werden:

Datatable: Der Kurzname der Datentabelle, in die Importiert wird. Diese Option ist Pflicht.

Folgende Optionen sind optional:

Active: Wenn dieser Wert auf false gesetzt wird, wird die Sektion beim Import übersprungen.
Clear: Wenn dieser Wert auf true gesetzt wird, werden existierende Daten beim Import aus der Datentabelle gelöscht. Das gilt pro Sektion, d.h. wenn bei einem CSV-Import mehrere CSV-Dateien in einer Sektion in die gleiche Datentabelle importiert werden, wird diese nur einmalig geleert und anschließend alle CSV-Dateien gelöscht.
Decimal: Dezimal-Trennzeichen (üblicherweise ein Komma für deutsche CSV-Dateien oder Punkt für englische). Vorgabe ist das Komma.
UpdateOn: Eine durch Kommas getrennte Liste von Spalten-Kurznamen, anhand derer Zeilen der Datentabelle aktualisiert werden. Wenn ein existierender Wert der Datentabellen in allen hier angegeben Spalten einen mit einer zu importierenden Zeile identischen Wert hat, wird die vorhandene Zeile aktualisiert und keine neue hinzugefügt.
OnRowError: Wenn bei einem Import einzelne Zeilen nicht importiert werden können (z.B. weil das Datumsformat falsch ist), bestimmt diese Option, was passieren soll: Beim Wert abort (Vorgabe) wird der gesamte Import abgebrochen und mit der nächsten Datei bzw. Sektion fortgefahren. Bei skip wird nur die fehlerhafte Zeile übersprungen.

Benutzer-Import

Bei Category=users können in der Sektion noch folgende Optionen definiert werden:

AdDomain: Der Name der Active-Directory-Domain, sofern der Benutzer als AD-Benutzer angelegt werden soll.
DryRun: Wenn man hier true einstellt, werden die Benutzer noch nicht tatsächlich importiert, sondern es wird nur ausgeben, mit welchen Daten sie angelegt werden würden.

Beim CSV-Import müssen die zu befüllenen Felder in der Mapping-Untersektion eintragen werden:

[Benutzer/Mapping]
fullname = Anwendername
username = Loginname
email = Email
roles = Rolle 1, "Rolle 2"
licensed = Lizenztyp

Dabei gibt es folgende Felder:

username: (Pflicht) Loginname des Benutzers.
fullname: (Pflicht) Name des Benutzers.
email: (Optional) E-Mail-Adresse.
password: (Optional) Das optionale Passwort wird nur bei neu angelegten Benutzer vergeben. Wenn kein Passwort angegeben wird, wird vom Server ein Zufallspasswort vergeben, in diesem Fall muss man später über die Administrations-Oberfläche erneut ein Passwort vergeben, um dem Benutzer eine Willkommens-E-Mail mit dem Zufallspasswort zuzusenden. Bei Active-Directory-Benutzern wird die Passwort-Option ignoriert.
addomain: (Optional) Name der Active-Directory-Domain, sofern der Benutzer als AD-Benutzer angelegt werden soll.
licensed: (Optional) Weist dem Benutzer eine Einzelbenutzer-Lizenz zu, wenn in der CSV-Datei „1“ oder „true“ in der Spalte steht.
roles: Eine kommagetrennte Liste von Spalten mit Rollennamen, die dem Anwender zugewiesen werden.

Wenn ein Benutzer bereits mit einem identischen Loginname existiert, wird er beim Import aktualisiert.

Rollenzuweisung

Rollen werden vom Import nicht automatisch angelegt und es werden bei der Rollenzuweisung nur diejenigen Rollen beachtet, die in der Untersektion Roles explizit aufgelistet sind:

[Benutzer/Roles]
; [Rolle in CSV-Datei] = [Rolle in Documents]
Buchhaltung = Buchhaltung
Entwickler = Entwicklung

Auf der linken Seite wird der Namen der Rolle angegeben, wie er in der CSV-Datei oder im ODBC-Ergebnis angegeben ist. Auf der rechten Seite steht der Name, wie er in Documents konfiguriert ist. Nur bei hier explizit angegebenen Rollen findet eine Zuweisung und auch ein Entfernen aus Rollen statt. Somit es ist möglich, auch weiterhin Rollen mit manueller Zuweisung zu haben.

Da ein Benutzer mehreren Rollen zugewiesen werden kann, gibt es zwei verschiedene Möglichkeiten, mehrere Rollen zu sammeln:

Es gibt mehrere Spalten in der CSV-Datei oder im SQL-Ergebnis, die jeweils genau einen Rollennamen enthalten und kommagetrennt im Mapping angegeben sind.
Es gibt mehrere Zeilen mit identischem Loginnamen, dann werden die aus allen Zeilen Rollen aufaddiert.