Flat Adapter

Verwendung

Flatfiles sind Dateien, die Datensätze ohne explizite Informationen über ihre Strukturen enthalten. Mithilfe eines Flat Adapters werden Flatfiles in XML-Dateien bzw. XML-Dateien in Flatfiles konvertiert.

Für die Konvertierung werden XML-basierte Regeln verwendet. Für jeden Nachrichtentyp muss eine spezifische Regel erstellt werden, die dann für beide Konvertierungsrichtungen verwendet werden kann. In der Regel wird festgelegt, wie die Flatfile-Elemente auf Flat-XML-Elemente abgebildet werden.

Siehe EDI Adapter

Wenn Sie Flatfile-Eingangsnachrichten nach XML konvertieren, die das Zeichen 0x00 enthalten, dann werden Ausgangsnachrichten mit einer ungültigen Entity-Referenz erzeugt! Ersetzen Sie das Zeichen 0x00 vor der Konvertierung mit einem Data Stream Modifier durch ein anderes Zeichen, das in Ihren Eingangsnachrichten nicht vorkommt.

Siehe Data Stream Modifier

Funktionsprinzip des Flat Adapters

Ein Flatfile hat eine nicht-hierarchische Struktur aus einem oder mehreren Segmenten, die jeweils ein oder mehrere Elemente enthalten. Implizite Segment- und Elementeigenschaften wie z.B. die Häufigkeit eines Elements in einem Segment werden im XML entweder

explizit als Attributwert der betreffenden XML-Elemente notiert, z.B. loop=3
oder beim Anlegen des Flat Adapter als Adapter-Eigenschaft konfiguriert, wie z.B. das Trennzeichen, welches das Segmentende signalisiert.

Die folgende Tabelle zeigt, wie Segmente und Elemente auf XML-Elemente abgebildet werden.

Hierarchiestufe Struktur im Flatfile Struktur im Flat-XML

Hierarchiestufe	Struktur im Flatfile	Struktur im Flat-XML
1	kein root-Element	root-Element `<Flatfile>` Name nicht änderbar!
2	Segmente	XML-Element `<Segment>`
Eigenschaften	Attribute
kein Segmentname	ID und xml-Tag Mögliche Werte: Buchstaben (a-z, A-Z, keine Sonderzeichen) Ziffern 0-9 Das erste Zeichen muss ein Buchstabe sein.
ein oder mehrere Segmente Häufigkeit des Vorkommens ist festgelegt	loop=n\|[Anzahl]
Pflichtsegment oder optional	required=C(onditional)\|M(andatory)
jedes Segment kann ein oder mehrere Elemente enthalten	kann über ein XML Schema für das Template festgelegt werden
Elemente sind durch Trennzeichen getrennt oder ohne Unterbrechung aufeinander folgend	Angabe beim Konfigurieren des Adapters
3	Elemente	XML-Element <Element>
Eigenschaften	Eigenschaften analog zu Segment
kein Elementname	ID und xml-Tag Mögliche Werte: Buchstaben (a-z, A-Z, keine Sonderzeichen) Ziffern 0-9 Das erste Zeichen muss ein Buchstabe sein.
festgelegte Länge	Längenangabe über Anfangs- und Endposition
festgelegte Position Beispiel: Die Angabe {n 15-23} bedeutet, dass es sich um einen numerischen Wert handelt, der in Position 15 beginnt und in Position 23 endet.	z.B. posStart=1, posEnd=14
nicht vorhandene Zeichen
festgelegter Datentyp	`type=(AN\|N\|QL\|D\|B)`
Pflichtelement oder optionales Element	required=C(onditional)\|M(andatory)

kein root-Element

root-Element <Flatfile> Name nicht änderbar!

Segmente

XML-Element <Segment>

Eigenschaften

Attribute

kein Segmentname

ID und xml-Tag

Mögliche Werte:

Buchstaben (a-z, A-Z, keine Sonderzeichen)
Ziffern 0-9

Das erste Zeichen muss ein Buchstabe sein.

ein oder mehrere Segmente Häufigkeit des Vorkommens ist festgelegt

loop=n|[Anzahl]

Pflichtsegment oder optional

required=C(onditional)|M(andatory)

jedes Segment kann ein oder mehrere Elemente enthalten

kann über ein XML Schema für das Template festgelegt werden

Elemente sind durch Trennzeichen getrennt oder ohne Unterbrechung aufeinander folgend

Angabe beim Konfigurieren des Adapters

Elemente

XML-Element <Element>

Eigenschaften

Eigenschaften analog zu Segment

kein Elementname

ID und xml-Tag

Mögliche Werte:

Buchstaben (a-z, A-Z, keine Sonderzeichen)
Ziffern 0-9

Das erste Zeichen muss ein Buchstabe sein.

festgelegte Länge

Längenangabe über Anfangs- und Endposition

festgelegte Position

Beispiel: Die Angabe {n 15-23} bedeutet, dass es sich um einen numerischen Wert handelt, der in Position 15 beginnt und in Position 23 endet.

z.B. posStart=1, posEnd=14

nicht vorhandene Zeichen

festgelegter Datentyp

type=(AN|N|QL|D|B)

Pflichtelement oder optionales Element

required=C(onditional)|M(andatory)

Beispiel

Die folgende Abbildung zeigt ein Flatfile (im Hintergrund) und die daraus erstellte Flat-XML-Nachricht (Vordergrund):

Das Flatfile (im Hintergrund) besteht aus mehreren Segmenten, die durch einen Zeilenumbruch (nicht sichtbar) getrennt sind.

In der Flat-XML-Nachricht wurde das Root-Element <Flatfile> hinzugefügt. Für jedes Flatfile-Element wurde ein XML-Element erzeugt und entsprechend der Konvention D_n+1 (D_01, D_02…) benannt. Bei den Elementwerten wurden führende Nullen entfernt: aus dem zweiten Element 01 im Flatfile wird im Flat-XML-File das Element D_02 mit dem Wert 1.

Die folgende Abbildung zeigt einen Ausschnitt aus einer Regel, die zum Konvertieren der oben abgebildeten Dateien verwendet wurde:

Dieser Ausschnitt zeigt, dass

obligatorisch das root-Element <Flatfile> eingefügt worden ist
das erste Segment vorhanden sein muss (M in der Baumdarstellung)
es unbegrenzt oft vorkommen kann ([1…n] in der Baumdarstellung)
es aus einer Reihe von Elementen besteht, u.a. aus dem Element 01, das ebenfalls obligatorisch ist (M), einen alphanumerischen Datentyp hat, in Position 1 beginnt und in Position 3 endet ({an 1-3} in der Baumdarstellung).

Regel-Editor - Oberfläche

Im Flat Rule Editor erstellen Sie Regeln.

Der Editor besteht aus folgenden Bereichen:

Hilfsregelbereich

Initial nicht sichtbar. Einzublenden über > Hilfsregel-Ansicht.

In diesen Bereich können Sie eine zusätzliche Regel laden und als Vorlage für Ihre neue Regel verwenden. Sie können per Drag’n’Drop Elemente und Segmente aus der Hilfsregel in den Regel-Bereich ziehen und damit eine neue Regel erstellen.
Regelbereich

Zum Erstellen einer neuen Regel.

Zum Einfügen, Verschieben und Löschen von Segmenten/Elementen nutzten Sie das Kontextmenü des Baums.

Um die Darstellung des Baums zu ändern, wählen Sie > Regeldarstellung.
Eigenschaftenbereich

Zeigt die Eigenschaften des Elements/Segments an, welches in der Regel markiert ist.

Menüleiste

In der Menüleiste des Editors gibt es folgende Befehle:

: Öffnet ein Eingabefenster für Zeichenketten, die im Regelbaum gesucht werden können.
: Öffnet ein Menü mit folgenden Befehlen:
- Neu: Erzeugt eine neue Regeldatei mit dem root-Element <Flatfile>.
- Öffnen: Zum Anzeigen einer im Dateisystem gespeicherten Regel.
- Speichern: Speichert die aktuell angezeigte Regel.
- Drucken
  
  Öffnet einen Drucken-Dialog, mit dem Sie die aktuell angezeigte Regel an Ihren Standarddrucker senden.
- Regelstruktur validieren
  
  Startet die Validierung der Regel gegen eine interne XML Schema-Datei.
- Mapping-Template generieren
  
  Öffnet den Assistenten zum Erzeugen einer Flat-XML-Vorlage, die alle Strukturinformationen der aktuell angezeigten Regel enthält. Diese Vorlage kann im XSLT-Converter als Zieldatei geladen werden.
  
  Alternativ verwenden Sie im XSLT-Converter den Regeldatei-Explorer, der das Erzeugen, Speichern und Laden der Regel für Sie übernimmt.
- XML-Schema generieren
  
  Erzeugt aus der Regel ein XML-Schema, das Sie z.B. zum Validieren von Eingangsnachrichten nutzen können. Für die Validierung können Sie einen XML Validator nutzen oder die Schemaprüfung aktivieren.
  
  Siehe XML Validator
- Excel-Report generieren
  
  Öffnet einen Assistenten, in dem Sie detailliert festlegen, welche Informationen aus der Regel in den Excel-Report exportiert werden sollen. Neben dem Export ins xls-Format, können Sie auch eine Option wählen, mit der die Regeldateien nach CSV exportiert werden.
Regeldarstellung

Zum Ändern der Regel-Ansicht:
- Attribut id: ID, entspricht im Eigenschaftenbereich der Eingabe im Feld ID.
- Attribut xmlTag: XML-Elementname, entspricht im Eigenschaftenbereich der Eingabe im Feld XML-Tag.
- Elementtyp: Standardname des Regelknotens, z.B. Segment.
- Beschreibung
  
  Zeigt im Baum neben jedem Element dessen Beschreibung an, entspricht im Eigenschaftenbereich der Eingabe im Feld Beschreibung.
- Bedingte Option
  
  Zeigt im Baum an, ob ein Element optional (C für engl. conditional) oder erforderlich ist (M für engl. mandatory).
- Wiederholung
  
  Zeigt im Baum die Häufigkeit des Vorkommens von Elementen an, z.B. [0…n].
- Länge (oder Position des Elements)
  
  Zeigt im Baum den Typ und die Länge bzw. Position von Elementen an, z.B. {an 1-7}.
Hilfsregel-Ansicht

Blendet einen zusätzlichen Bereich ein, in den eine weitere Regel als Vorlage für die neu zu erstellende Regel geladen werden kann.

Regeldatei vor dem Publizieren überprüfen

Menü Bearbeiten

Wenn aktiviert, dann wird jede Regel vor dem Publizieren gegen ein internes XML-Schema validiert, welches die Regelstruktur beschreibt. Wenn die Option XML‑Validierung markiert ist, dann müssen alle Regeldateien dieser Struktur entsprechen, sonst kann das Modul nicht publiziert werden.

Siehe Dialog Syntax und Validierung

Neue Regel erstellen - Flat Adapter

Zum Erstellen einer Konvertierungsregel benötigen Sie detaillierte Informationen über die Struktur der Nachrichten, die Sie mit dem Adapter verarbeiten möchten!

So gehen Sie vor

Hilfsregel laden (wenn nötig)

Hilfsregeln sind normale Regeln, die Sie zuvor erstellt haben oder die Ihnen zur Verfügung gestellt wurden. Standardmäßig werden mit der INUBIT-Software keine Regeln ausgeliefert.
1. Klicken Sie im Regelbereich auf den -Button und wählen Sie Hilfsregel-Ansicht. Der Hilfsregel-Bereich wird links vom Regel-Bereich eingeblendet.
2. Klicken Sie in dem leeren Bereich auf den -Button und wählen Sie Öffnen. Sie können Dateien aus dem Dateisystem, dem Repository und aus der Zwischenablage laden.
3. Navigieren Sie zu der Regel, die Sie als Hilfsregel anzeigen möchten und wählen Sie diese aus. Die Regel wird angezeigt.
Neue Regel erzeugen

Klicken Sie im Regelbereich auf den -Button und wählen Sie Neu > Regel. Eine neue Regel mit dem Root-Element Flatfile wird angezeigt.
Neue Regel bearbeiten

Sie haben folgende Möglichkeiten:
- Im Regelbereich Mithilfe des Kontextmenüs Segmente und Elemente hinzufügen
- Per Drag’n’Drop Segmente und Elemente aus der Hilfsregel verwenden

Die Regel wird automatisch zusammen mit dem Adapter gespeichert.

Dialogbeschreibung: Flat-XML-/XML-Flat Adaptereigenschaften

Namen der XML-Elemente

Attribut id verwenden

Wenn markiert, enthält die XML-Nachricht Elemente mit abgekürzten Bezeichnern (S_<ID> bzw. D_<ID>).
Attribut xmlTag verwenden

Wenn markiert, dann wird die Nachricht mit sprechenden Elementnamen ausgegeben, entsprechend dem Wert für XML Tag in der Konvertierungsregel.

Sprechende Elementnamen verbessern die Lesbarkeit der Nachricht, erhöhen aber die Dateigröße und beeinflussen damit die Performance.

Formatierung der Flat-Nachricht

Segmenttrennzeichen (Eingabe)

Wählen Sie einen Wert aus der Liste aus, um anzugeben, wie die Segmente in den Eingangsnachrichten voneinander getrennt sind.
Dezimaltrennzeichen (Eingabe)

Geben Sie an, durch welches Zeichen (Punkt oder Komma) Dezimalzahlen mit Nachkommastellen getrennt sind.
Dezimaltrennzeichen (Ausgabe)

Das Dezimaltrennzeichen kann bei der Konvertierung ersetzt werden. Legen Sie fest, welches Zeichen verwendet werden soll (Punkt oder Komma).
Zeichensatzkodierung

Zeichensatz der Eingangsnachrichten. Mit der Angabe stellen Sie sicher, dass die Eingangsnachricht korrekt konvertiert wird und z.B. Umlaute richtig dargestellt werden.

Standardmäßig ist der Zeichensatz ISO-8859-1 ausgewählt, der alle Zeichen der gebräuchlichen westeuropäischen Sprachen und deren Sonderzeichen enthält.

Formatierung der XML-Nachricht (nur Flat-XML Adapter)

Entferne führende Nullen, die zum Auffüllen von numerischen Feldern eingefügt wurden

Der Name der Option ist sprechend.
Leere Elemente nicht erzeugen

Wenn diese Option markiert ist, dann werden für Flatfile Elemente, die nur Whitespaces enthalten, keine XML-Elemente erzeugt. Dadurch werden die Ausgangsnachrichten kleiner und XSLT-Stylesheets für die evtl. anschließende Verarbeitung sind besser zu pflegen.

Leerzeichen

XML-Ausgabe bleibt unverändert

Der Name der Option ist sprechend.
Führende und nachfolgende Leerzeichen entfernen

Der Name der Option ist sprechend.
Alle Leerzeichen und Zeilenumbrüche werden aus der XML-Ausgabe entfernt

Der Name der Option ist sprechend.

Analyse

Regeldatei cachen

Wenn markiert, dann bleibt die Regeldatei während der Ausführung des gesamten Workflows im Speicher.

Diese Einstellung ist sinnvoll, um viele Nachrichten hintereinander zu konvertieren, weil der Konvertierungsprozess schneller ist, wenn die Regeldatei nicht immer wieder neu geladen werden muss. Caching ist sinnvoll bei Nachrichten ab einer Größe von 300 KByte.

Berücksichtigen Sie bei der Dimensionierung des Arbeitsspeichers, dass das Cachen zusätzlich Arbeitsspeicher kostet.
Syntaxfehler in der Eingangsnachricht ignorieren

Wenn Sie diese Option auswählen, wird die Konvertierung im Fehlerfall nicht abgebrochen. Stattdessen werden fehlerhafte Bereiche in der Nachricht übergangen.

Wenn die Option deaktiviert ist, dann wird im Fehlerfall eine Fehlermeldung angezeigt und die Verarbeitung abgebrochen. Deaktivieren Sie diese Option zum Testen einer Regel, damit Sie eventuelle Fehler darin finden können.
- Fehlerinformationen zur Ausgabe XML-Nachricht hinzufügen (nur Flat-XML Adapter)
  
  Fügt die Originalsegment- und Elementdaten in die Flat XML Ausgangsnachrichten ein.

Validierung

XML-Validierung

Wenn aktiviert, dann werden die Ausgangsnachrichten (Flat-XML Adapter) bzw. Eingangsnachrichten (XML-Flat Adapter) gegen ein XML Schema validiert, das aus der Konvertierungsregel erzeugt wurde. Bei der Validierung werden auch der Elementtyp und die Qualifierlisten überprüft, anders als bei der standardmäßig immer durchgeführten automatischen Syntaxprüfung.

Aktivieren Sie die Option Syntaxfehler in der Eingangsnachricht ignorieren, wenn Sie die XML Validierung nutzen. Dann werden alle Prüfungen gegen das XML Schema durchgeführt und im Fehlerfall wird nur ein Fehlertyp ausgegeben.

Wenn die Option deaktiviert ist, dann erzeugt eine fehlerhafte Nachricht mit einem zu langen Element einen anderen Fehlertyp als eine Nachricht mit einem falschen Qualifier.

Bei fehlerhafter Schema-Validierung Fehlerausgang verwenden

Wenn diese Option aktiviert ist, dann wird die Ausführung des Workflows abgebrochen, sobald die Schema-Validierung fehlschlägt. Die Nachricht wird an den Fehlerausgang weitergeleitet.