Importmodul IV: Importprofil

Aufbau der Profildatei

Eine recotech Profildatei ist logisch in vier Bereiche unterteilt:

    • globale Einstellungen
    • Deklaration der Datenquellen
    • Deklaration der Datensenken
    • Makroanweisungen

Die globalen Einstellungen definieren die speziellen Strings für boolesche Werte, die Sonderwerte (Autowert, Null etc.) und die Anweisungen (Einfügung, Änderung etc.) sowie das verwendete Zahlformat.

Die Deklaration der Datenquellen besteht aus der Aufzählung der zu verwendenden Dateien und ihrer Spalten sowie der Angabe wie sie zu lesen sind (die Kodierung, das Spaltentrennzeichen und das Zitatzeichen).

Die Deklaration der Datensenken besteht aus der Zuordnung von Quellspalten zu Eigenschaften von Importobjekten (d.h. Spalten in den Importtabellen).

Die Makroanweisungen definieren Aktionen im Importmodul, die nach der erfolgreichen Erfassung der Importdaten ausgeführt werden sollen.

Die meisten Zeilen bestehen aus einem Schlüssel - Wert Paar. Alle Schlüssel sind fest definierte Zeichenketten und fangen mit einem Dollarzeichen an. Das Importmodul erwartet nach einem Schlüssel Leer- oder Tabulatorzeichen. Den Rest der Zeile liest es als Wert.

Bei Aufzählungen wie zum Beispiel den Spaltendeklarationen einer Datei gibt es keine Schlüssel. Solche Aufzählungen werden mit einem definierten Schlüssel eingeleitet und enden mit der ersten Leerzeile oder der ersten Zeile mit einem Schlüssel.

Alle Zeilen, die weder mit einem Dollarzeichen beginnen, noch aufgrund ihrer Position Teil einer Aufzählung sind, werden ignoriert. Kommentare brauchen also nicht besonders gekennzeichnet werden. Sie müssen allerdings in eigenen Zeilen stehen.


Globale Profil Einstellungen

Beispiel:

$Profile


$NumberCulture

de-DE

$UseGroupSeperator

false

$EmptyString

$WildCardString

*

$AutoString

?

$NullString

null

$GeoString

geo

$InsertString

Einfügung

$UpdateString

Änderung

$InsertOrUpdateString

Einfügung oder Änderung

$DeleteString

Löschung

$TrueString

ja

$FalseString

nein


Zum besseren Verständnis sind in diesem Dokument im obigen und allen weiteren Beispielen die Schlüsselwörter und -zeichen in roter Schrift, die vom Benutzer wählbaren Werte in schwarzer Schrift gehalten.


$Profile: Dieser Schlüssel leitet die Deklaration der globalen Profileinstellungen ein, ihm ist selbst kein Wert zugeordnet. In den folgenden Zeilen erwartet der Parser genau die im Beispiel angegebenen Schlüssel in beliebiger Reihenfolge und gegebenenfalls Kommentare.

$NumberCulture: Definiert das Zahlformat in Form eines Kulturkürzels.

$UseGroupSeperator: Gibt an, ob Tausendertrennzeichen verwendet werden sollen. Nur die Werte 'true', 'false', 'True' und 'False' sind gültig.


Tausender Trennzeichen

Es wird dringend empfohlen, Tausendertrennzeichen nur dann zuzulassen, wenn dies absolut notwendig ist, insbesondere beim Einsatz von CSV Dateien, die zu irgendeinem Zeitpunkt mit Excel bearbeitet wurden. Im Zahlformat 'de-DE' wird ansonsten '123.456' ohne Warnung oder Fehler als 123456 interpretiert, obwohl wahrscheinlich 123,456 gemeint war.


Leere Felder und Spezialwerte

Die Spezialwerte dienen der Lückenbehandlung. Das Datenimportmodul erwartet nicht, dass eine Datenquelle für jedes Feld in den Importtabellen einen Wert bereitstellt. Wenn die Datenquelle für eine Spalte keine Entsprechung hat oder eine Quellspalte teilweise leer ist, müssen dem Datenimportmodul Hinweise gegeben werden, wie mit diesen Lücken zu verfahren ist.

Es gibt fünf mögliche Gründe, warum ein Feld zu diesem Zeitpunkt leer sein kann:

  1. Das entsprechende Attribut soll keinen Wert haben, also null sein, aber die Datenquelle kann das nicht anders als durch eine leere Zeichenkette ausdrücken.
  2. Das entsprechende Attribut ist in der Datenquelle gar nicht vorhanden oder soll sich nicht ändern.
  3. Der Wert soll tatsächlich eine leere Zeichenkette sein.
  4. Die Datenquelle hat auf die Angabe verzichtet, weil das Attribut redundant ist und sich rein logisch aus anderen Angaben ergibt.
  5. Der Wert kann und soll aufgrund anderer Angaben geometrisch berechnet werden.

Für jede dieser Interpretationen steht ein Spezialwert. Bei Zielspalten, für die in den Quelldaten keine Informationen enthalten sind, kann statt einer Quellspalte ein solcher als Wert angegeben werden. Bei Quellspalten, die teilweise leer sind, kann einer dieser Spezialwerte als Standard deklariert werden.
Deklarationen entsprechender Ersetzungsanweisungen bewirken das Gleiche. Mit diesen können allerdings pro Verwendung einer Quellspalte unterschiedliche Werte eingesetzt werden.

$EmptyString: Der reservierte Spezialwert für die leere Zeichenkette. Der Wert muss sich von den Spezialwerten für Wildcard, Autowert, null und der geometrischen Berechnung unterscheiden und darf nur alphanumerische Zeichen sowie den Unterstrich enthalten.

$WildCardString: Der reservierte Spezialwert für die Wildcard. Dieser befiehlt dem Importmodul, den entsprechenden Wert nicht zu ändern. Der Wert muss sich von den Spezialwerten für die leere Zeichenkette, den Autowert, null und der geometrische Berechnung unterscheiden und darf nur alphanumerische Zeichen sowie den Unterstrich enthalten.

$AutoString: Der reservierte Spezialwert für den Autowert. Dieser Wert befiehlt dem Importmodul den entsprechenden Wert aus anderen Angaben unter Berücksichtigung aller vorhandenen Informationen zu ermitteln. Der Wert muss sich von den Spezialwerten für die leere Zeichenkette, der Wildcard, null und der geometrischen Berechnung unterscheiden und darf nur alphanumerische Zeichen sowie den Unterstrich enthalten.

$NullString: Der reservierte Spezialwert für den Wert null (wie in NullPointerException). Dieser bedeutet, dass das Feld keinen Wert hat. Der Wert muss sich von den Spezialwerten für die leere Zeichenkette, der Wildcard, dem Autowert und der geometrischen Berechnung unterscheiden und darf nur alphanumerische Zeichen sowie den Unterstrich enthalten.

$GeoString: Der reservierte Spezialwert für die geometrische Berechnung. Dieser befiehlt dem Importmodul, den Wert des Feldes geometrisch zu errechnen. Der Wert muss sich von den Spezialwerten für die leere Zeichenkette, der Wildcard, dem Autowert und null unterscheiden und darf nur alphanumerische Zeichen sowie den Unterstrich enthalten.

$InsertString: Der reservierte Spezialwert für den Befehl, ein entsprechendes Objekt zu erzeugen. Er muss sich von den anderen Anweisungsbefehlen unterscheiden und darf nur alphanumerische Zeichen sowie den Unterstrich enthalten.

$InsertOrUpdateString: Der reservierte Spezialwert für den Befehl, ein entsprechendes Objekt zu erzeugen oder zu ändern, je nachdem ob es schon existiert oder nicht.  Er muss sich von den anderen Anweisungsbefehlen unterscheiden und darf nur alphanumerische Zeichen sowie den Unterstrich enthalten.

$UpdateString: Der reservierte Spezialwert für den Befehl, ein existierendes Objekt zu ändern.  Er muss sich von den anderen Anweisungsbefehlen unterscheiden und darf nur alphanumerische Zeichen sowie den Unterstrich enthalten.

$DeleteString: Der reservierte Spezialwert für den Befehl, ein existierendes Objekt zu löschen.  Er muss sich von den anderen Anweisungsbefehlen unterscheiden und darf nur alphanumerische Zeichen sowie den Unterstrich enthalten.

Anweisungsbefehle

Es ist selten der Fall, dass aus Quelldaten ersichtlich ist, ob ein Datensatz ein für recotech neues Objekt darstellt oder ob es ein schon bestehendes nur ändert. Noch seltener ist eine vollständige Löschhistorie, aus der hervorgeht, welche bestehenden recotech Objekte entfernt werden sollen. Dementsprechend oft stellen die Quelldaten für die Anweisungsspalte keinerlei Informationen bereit.

Das Anweisungsfeld in allen Tabellen kann auf die konditionalen Anweisungen "Erzeugen oder Ändern" gesetzt werden. Im Laufe der Verarbeitung wird das Importmodul anhand der XIds oder der identifizierenden Attribute feststellen, welche Objekte neu sind und welche nur geändert werden.
Die Löschung aller nicht mehr erwähnten Objekte kann per Makroanweisung in das Profil kodiert werden.

$TrueString: Der reservierte Spezialwert für den positiven booleschen Wert. Er muss sich vom FalseString unterscheiden und darf nur alphanumerische Zeichen sowie den Unterstring enthalten.

$FalseString: Der reservierte Spezialwert für den negativen booleschen Wert. Er muss sich vom TrueString unterscheiden und darf nur alphanumerische Zeichen sowie den Unterstring enthalten.

Globale Definition und Ersetzung

Die hier definierten Spezialwerte gelten global für den gesamten Import. Es ist durchaus möglich, dass verschiedene Quelldateien verschiedene Zahlformate und/oder Darstellungen für die beiden booleschen Werte verwenden. Um die Nachbearbeitung der Quelldateien zu vermeiden, können im Importprofil für die betroffenen Spalten systematische Ersetzungen definiert werden.
So können zum Beispiel für Spalten mit "Ja/Nein"-Information die Werte '1', 'wahr', 'Wahr', 'true', 'True', 'Ja' und 'ja' alle durch einen Wert ersetzt werden, der als der Wert des TrueString definiert wurde.

Dateideklaration

Beispiel:

$File

Person.csv

$Alias

Personen

$Headline

True

$ColumnNumber

15

$ColumnSeperator

;

$QuoteChar

"

$Encoding

UTF-7


In diesem und allen weiteren Beispielen zeigt kursive Schrift optionale Werte an.

$File: Dieser Schlüssel leitet eine Dateideklaration ein, sein Wert ist der Name der Datei. Das Importmodul erwartet eine Datei mit diesem Namen im gleichen Ordner, in dem die Profildatei abgelegt ist. Dieser Wert wird nur für den Dateizugriff benötigt und darf auch Leer- und Sonderzeichen enthalten, sofern das Betriebssystem diese zulässt. In den nächsten Zeilen erwartet das Importmodul genau die im Beispiel angegebenen weiteren Schlüssel sowie die Aufzählung der Spalten (siehe unten).

$Alias: Ein frei wählbarer Bezeichner für diese Datei, der nur alphanumerische Zeichen sowie den Unterstrich enthalten darf. In allen weiteren Definitionen und Deklarationen innerhalb der Profildatei wird immer nur dieser Alias verwendet, um die Datei zu spezifizieren.

$Headline: Gibt an, ob die deklarierte Datei eine Kopfzeile hat, ob also die erste Zeile Daten enthält oder nicht. Nur die Werte 'true', 'false', 'True' und 'False' sind gültig. Die Werte einer Kopfzeile, also die Spaltenüberschriften in der Datei selbst, werden nie verwendet. Diese Angabe hier bewirkt nur, dass die erste Zeile gegebenenfalls ignoriert wird.

$ColumnNumber: Die Anzahl der Spalten in der Datei. Diese Angabe dient zur Kontrolle der korrekten Spaltentrennung. Nicht alle Spalten einer Datei müssen auch verwendet werden und nur die zu verwendenden müssen im Detail deklariert werden.

$ColumnSeperator: Dies ist das in der Datei verwendete Spaltentrennzeichen. Außer den Zeichen für Zeilenende ('\n') und Zeilenumbruch ('\r') sind alle Zeichen möglich, es muss sich aber vom Textmarkierungszeichen unterscheiden. Der Standard beim CSV Format ist das Semikolon. Tabulatoren werden durch '\t' bezeichnet.

$QuoteChar: Dies ist das in der Datei verwendete Textmarkierungszeichen. Außer den Zeichen für Zeilenende ('\n') und Zeilenumbruch ('\r') sind alle Zeichen möglich, es muss sich aber vom Spaltentrennzeichen unterscheiden. Der Standard beim CSV Format ist das doppelte Hochkomma.

$Encoding: Hier wird die verwendete Kodierung der Quelldatei angegeben. Sie kann als Nummer (Code Page) oder durch ihren Namen (Web Name) angegeben werden. Ist diesem Schlüssel kein Wert zugeordnet, wird die Standarteinstellung des Betriebssystems verwendet.

Kodierung und Zeichensätze

Die Angabe eine Kodierung bzw. eines Zeichensatzes ist notwendig für die korrekte Darstellung und Auswertung einer Textdatei. Technisch gesehen sind Textdateien nur Abfolgen von ganzen Zahlen und die Kodierung bestimmt, welche Zahl welches Zeichen repräsentiert. Streng gesehen sind es noch nicht einmal Zahlen, sondern Abfolgen von Nullen und Einsen, so dass ohne weitere Angabe noch nicht einmal klar ist, wie viele Zeichen eine Textdatei enthält.

Zum Beispiel existieren die für Darstellung von deutschem Text notwendigen Umlaute und das 'ß' nur in manchen Zeichensätzen. Die sie repräsentierenden Zahlen stehen in anderen Zeichensätzen für Sonderzeichen oder sogar chinesische Zeichen.

Im Gegensatz zu HTML Dateien enthält eine Textdatei keine Information darüber, mit welchem Zeichensatz sie geschrieben wurde. Der Benutzer muss es entweder wissen oder erraten. Die Verwendung einer unpassenden Kodierung sorgt im Extremfall dafür, dass noch nicht einmal die Spaltenerkennung funktioniert. Dieser Fehler wird vom System erkannt, weil die Anzahl der zu erwartenden Spalten mit der Anzahl der gefundenen nicht übereinstimmt.
Zur Sicherheit sollte der Benutzer aber die Dateivorschau nutzen und die korrekte Darstellung kritischer Sonderzeichen überprüfen. Die folgenden Screenshots der Dateivorschau des Importmoduls zeigen mögliche Kodierungsprobleme bei Einlesen derselben Datei.

Beispiel für eine korrekte Kodierungsangabe:

Beispiel für eine falsche Kodierungsangabe. Die Umlaute sind inkorrekt dargestellt.

Beispiel für eine völlig falsche Kodierungsangabe. Kein einziges Zeichen wird korrekt dargestellt und sogar die Spaltentrennung schlägt fehl. Weil das Importmodul nur eine Spalte erkennen kann, aber mehr als eine angekündigt wurden, wird dies als Fehler ausgewiesen.

Spaltendeklaration

Beispiel:

$Columns


 Personalnummer

0


 Vorname

4

EmptyString

 Nachname

3

EmptyString

 Kommentar

7

"Bitte nachtragen"


In diesem und allen weiteren Beispielen steht grüne Schriftfarbe für Angaben, die zuvor definiert wurden und dementsprechend interpretiert werden.

$Columns: Dieser Schlüssel leitet die Auflistung der Spaltendeklaration ein, ihm ist kein Wert zugeordnet. Alle folgenden nicht leeren Zeilen ohne Schlüssel werden als Spaltendeklarationen interpretiert. Die Spalten werden in der Datei gesucht, unter deren Deklaration sich dieser Block befindet.

Eine Spaltendeklaration besteht aus zwei bis drei Teilen, dem Spalten-Alias, der Nummer und einem optionalen Standartwert. Die Spalten Aliase dürfen nur alphanumerische Zeichen und den Unterstrich enthalten. Keine zwei Spalten in einer Datei dürfen mit den gleichen Aliasen bezeichnet werden. In der Profildatei wird für alle weiteren Definitionen und Deklarationen die durch Punkt getrennte Kombination aus Datei-Alias und dem Spalten-Alias verwendet, um eine bestimmte Spalte zu bezeichnen.
Die Nummer ist die der Spalte in der Datei. Diese Angabe ist nullbasiert, d.h. die erste Spalte einer Datei hat die Nummer 0, die zweite die 1 usw.
Der optionale Standartwert wird immer dann verwendet, wenn ein Feld in dieser Spalte leer ist. Gültige Werte sind hier alle Schlüssel der Spezialwerte sowie beliebige Zeichenketten in Anführungsstrichen.

Spaltennummern und Spaltennamen

Wenn in den Quelldateien Kopfzeilen mit Spaltennamen vorhanden sind und diese den Regeln für Aliase entsprechen, bietet es sich an, diese Spaltennamen als Spalten Aliase zu verwenden. Dabei ist aber zu beachten, dass beim Dateizugriff die entscheidende Angabe die Spaltennummer und nicht der Alias ist. Mit den obigen Beispieldeklarationen würde die 5. Spalte der Datei Personen.csv mit 'Personen.Vorname' bezeichnet. Und zwar selbst dann, wenn in der Kopfzeile der Datei dort etwas anderes steht.

Deklaration der Zielspalten und Spaltenzuordnungen

Beispiel:

$Type XPerson


$TargetColumn XId

Personen.Personalnummer


$TargetColumn FirstName

Personen.Vorname


$TargetColumn LastName

Personen.Nachname


$TargetColumn Comment

Personen.Kommentar


$TargetColumn Command

InsertString

$Type: Dieser Schlüssel leitet die Deklaration der Zuordnungen für einen recotech Datentyp ein. Gültige Werte sind nur die fest definierten Bezeichner dieser Datentypen. Diese Deklarationsblöcke werden durch den nächsten $Type oder das Dateiende beendet.
Die Typbezeichner sind die intern verwendeten Klassennamen und werden als solche nicht übersetzt. Im Anhang befindet sich eine Übersetzungstabelle mit den in der Programmoberfläche verwendeten Temini. Solche Deklarationsblöcke müssen nur für die Typen existieren, die importiert werden sollen.

$TargetColumn: Dieser Schlüssel leitet eine Zielspalten-Deklaration ein. Gültige Werte sind nur die intern verwendeten Attributs Namen des entsprechenden recotech-Objektes. Im Anhang befindet sich eine Übersetzungstabelle.
Das Importmodul erwartet für jedes Attribut eine solche Deklaration. Alle Zeilen nach der $TargetColumn Zeile bis zur ersten Leerzeile oder der nächsten $TargetColumn Zeile werden als Datenquellen Deklarationen interpretiert, dürfen also keine Kommentarzeilen enthalten.
Zwei mögliche Deklarationen von Datenquellen sind im obigen Beispiel verwendet: Die Angabe des Schlüssels eines Spezialwertes und die Angabe der Spalte einer Datei in Form von Datei-Alias und Spalten-Alias, die mit einem Punkt verbunden sind. Eine dritte einfache mögliche Deklarationsart ist eine beliebige Zeichenkette in doppelten Anführungsstrichen. Komplexere Möglichkeiten, Datenquellen zu definieren werden weiter unter beschrieben.
Um in die Spalten einer Importtabelle mehrere Quellspalten untereinander zu schreiben, werden die entsprechenden Quellspalten in aufeinanderfolgenden Zeilen aufgelistet:

$Type XPerson


$TargetColumn XId

PersonalHamburg.Personalnummer

PersonalBerlin.Personalnummer


$TargetColumn FirstName

PersonalHamburg.Vorname

PersonalBerlin.Vorname


$TargetColumn LastName

PersonalHamburg.Nachname

PersonalBerlin.Nachname


$TargetColumn Comment

"bitte nachtragen"

PersonalBerlin.Kommentar


$TargetColumn Command

InsertString

InsertString

Das Importmodul erwartet für alle Zielspalten die gleiche Anzahl an Datenquellen. Dies gilt auch für die Angabe eines Spezialwertes als Datenquelle und wird bereits beim Einlesen der Profildatei überprüft. Dass darüber hinaus die Anzahl der Datensätze in den Datensätzen zueinander passt, wird erst nach dem Einlesen der Quelldateien überprüft.

Falls die Quelldaten keine XId bereitstellen, muss dort der Autowert verwendet werden. Im Fall einer Einfüge-Anweisung wird dieser durch eine neue GUID ersetzt und es wird ein neues recotech-Objekt erzeugt. Bei Änderungen und Löschungen muss das gemeinte Objekt anhand inhaltlicher Übereinstimmung gefunden werden. Dazu ist die Kennzeichnung der zur Identifizierung verwendeten Attribute notwendig:

$Type XPerson


$TargetColumn XId

AutoString


$TargetColumn FirstName (Identifying)

Personen.Vorname


$TargetColumn LastName (Identifying)

Personen.Nachname


$TargetColumn Comment

Personen.Kommentar


$TargetColumn Command

InsertOrUpdateString

Diese Angabe beeinflusst nur die Ersetzung von Autowerten in der XId Spalte. Sollten die Werte der identifizierenden Attribute Änderungen unterliegen, wird die Identifizierung scheitern oder möglicherweise sogar fehlerhaft ausfallen.