Beispielkonfiguration: Szenariokonfiguration
Das Beispiel-Szenario example_scenarioConfig.json beschränkt sich auf Dateisystemeingaben und Dateisystemausgaben. Auf diese Weise müssen keine externen Systeme angebunden werden. Die XML-Datei wird eingelesen und neu generierte XML-Dateien mit verändertem Aufbau werden ausgegeben.
Input
In der Beispielkonfiguration ist eine XML-Eingabedatei mit dem Namen example_inputData.xml enthalten. Diese Datei wird zunächst über das allgemeine Eingabesystem "InputSystem" vom Typ "File" als beliebige Datei eingelesen.
Eine erste inhaltliche Interpretation als XML-Datei findet beim Eingabeformat "InputFormat" vom Typ "Xml" statt. Die Datei enthält 2 Dokumente. Die Eingabedaten werden in einen Stapel mit diesen beiden Dokumenten strukturiert. Über die Eigenschaft .DocNode ist vorgegeben, auf Ebene welches XML-Knotens jeweils ein separates Dokument beginnt. Die Dokumente werden später einzeln ausgegeben, d.h. der gemeinsame Stapel bleibt nicht erhalten.
Als weitere Funktion des Eingabeformatlesers werden die Dateianlagen extrahiert. Die Dateianlagen sind in diesem Fall direkt als Binärdaten eingebettet und über .AttachFileMode definiert. In .AttachFileNode ist hinterlegt, an welchem Knoten die Binärdaten und der zugehörige Dateiname zu finden sind.
Über Input.TrackingIdMacro und Input.TrackingKeyMacro werden exemplarisch Tracking-Werte generiert. Diese Werte werden vorwiegend im Zusammenspiel mit anderen xSuite-Anwendungen verwendet. Für die Generierung der Werte werden Makrofunktionen genutzt, die eine eindeutige UUID (GetUuid()) oder einen in der Datenbank verwalteten Zählerwert (GetDbCounter()) erzeugen.
Process
Im "Process"-Schritt werden über den Indexdatenleser "ProcessReadIndex" vom Typ "Xml" die Indexwerte aus den Dokumenten extrahiert. Als Filter für die jeweilige Indexdatei kann hier nicht *.xml verwendet werden, weil das auch die ursprüngliche XML-Datei einbeziehen würde. Die ursprüngliche Datei wurde bei der Eingabeformatverarbeitung in dokumentspezifische Dateien aufgetrennt, die den Zusatz split im Dateinamen erhalten haben. Auf diesen Zusatz im Dateinamen wird nun gefiltert.
Beispielhaft werden einige Werte unterschiedlichen Datentyps eingelesen. Die Zielfelder dafür sind im Feldkatalog (FieldCatalog) definiert. Die Zuordnung von den Quellfeldern zu den Zielfeldern erfolgt in der Auflistung .Field des Indexdatenlesers. Die Namen der Quellfelder (.InputName) sind in XPath-Syntax angegeben. Diese Syntax beschreibt den Pfad zu dem jeweiligen Knoten in der XML-Datei. Alle Werte werden zunächst in Textform eingelesen. Für den Datumswert ist daher explizit definiert, wie dieser Wert als Datum interpretiert werden soll (.InputFormat). Bei dem numerischen Wert ist eine Formatangabe nicht zwingend erforderlich, da dieser Wert implizit korrekt interpretiert wird. Voraussetzung für die implizite Erkennung ist, dass der Wert im Feldkatalog als Zahlenwert deklariert ist (.InitType). Wenn der Zahlenwert im Feldkatalog nicht als solcher deklariert ist, wird der Wert als reiner Textwert übernommen, was bei späteren Rechenoperationen nachteilig ist.
Im Fall von tabellarischen Positionsdatenfelder ist über die Eigenschaft .ItemNode des Indexdatenlesers explizit vorgegeben, unter welchem XML-Knoten sich die Daten einer Positionsdatenzeile befinden. Wenn diese Angabe fehlt, wird über alle Auftrittsstellen eines Feldes in der XML-Datei gesucht. Dies kann zu falschen Positionszuordnungen führen, wenn ein Feld nicht in allen Zeilen vorhanden ist, weil das Feld z. B. aufgrund eines leeren Wertes weggelassen wurde.
In der Eigenschaft .InitMacro der Feldkatalog-Felder ist anhand der ersten beiden Felder definiert, wie diese Felder per Feldmakroausdruck mit einem Initialwert belegt werden können, wenn die Feldwerte nicht aus den Eingabedaten gelesen werden sollen. Außerdem ist in dieser Eigenschaft definiert, wie ein gelesener Eingabewert im Nachhinein verändert werden kann. Im ersten Fall wird der Wert der internen Tracking-ID-Eigenschaft in Form der entsprechenden Dokumentvariable einem Feld zugewiesen, wodurch dieser Wert später in die Ausgabedatei übernommen werden kann. Im Normalfall ist das nicht erforderlich, weil die Übergabe der Tracking-Werte bei xSuite-Systemen, die diese Werte unterstützen, implizit erfolgt. Hilfsfelder zu diesem Zweck nicht angelegt werden. In letzterem Fall wird der Eingabewert um ein festes Zeichen ergänzt, wobei der Ursprungswert über eine Referenz des Feldes auf sich selbst in Form einer Feldvariable angesprochen wird.
Die beschriebenen Initialisierungsmakros sind eine spezielle Variante, um Felder direkt beim Aufbau des Feldkatalogs mit Werten vorzubelegen. Alternativ können den Feldern in dem allgemeinen Makroabschnitt (ProcessMacro) neue Werte zugewiesen werden. In diesem Fall sind die Feldmakros keinem konkreten Feld zugeordnet. Ein solcher Ausdruck muss daher als Zuweisung formuliert werden, d.h. das Zielfeld, an das der Ergebniswert der Makroausführung übergeben werden soll, muss explizit definiert werden. Das Beispiel beschränkt sich auf solche Zuweisungen für 2 weitere Felder. Dies ist eine Rechenoperation für das numerische Feld und für das Datumsfeld. Als weitere Makrotypen können an dieser Stelle aber auch Dokumentmakros und Dateimakros eingesetzt werden.
Output
Die Ausgabe erfolgt in 2 Schritten. Der erste Schritt ist die Erstellung eines Ausgabeformats (OutputFormat) in Form einer neuen XML-Dateianlage. Der zweite Schritt ist die Übergabe dieser Datei an ein Ausgabesystem (OutputSystem). In der Beispielkonfiguration ist die Übergabe an ein Ausgabesystem das Schreiben ins Dateisystem. Mehrere Ausgabeformate und Ausgabesysteme können beliebig miteinander verbunden werden. Die Verarbeitungsreihenfolge ist über die Eigenschaft .Order vorgegeben. Eine einzelne XML-Ausgabedatei example_outputData_1.xml wird in dem Beispiel mit ausgeliefert. Mithilfe dieser Ausgabedatei können die nachfolgenden Erläuterungen zum Aufbau einer solchen Datei nachvollzogen werden, ohne das Szenario ausführen zu müssen. Die XML-Eingabedatei umfasst mehrere Dokumente, die als einzelne Dokumente ausgegeben werden. Der numerische Wert im Ausgabedateinamen (.FileName) ist ein Zähler mit der Dokumentnummer.
Die Konfiguration des Ausgabeformats "Xml" ist vergleichbar mit der Konfiguration des Indexdatenlesers "Xml". In der Auflistung .Field erfolgt die Zuordnung von den Quellfeldern aus dem Feldkatalog zu den Zielfeldern (.OutputName), die in der XML-Datei ausgegeben werden. Die Ausgabedatei hat einen anderen Aufbau als die XML-Eingabedatei. Die Feldnamen und Feldwerte werden nicht in einem XML-Knoten, sondern in 2 parallelen XML-Knoten ausgegeben. Der Ausgabename setzt sich daher aus mehreren Teilparametern zusammen. Diese Teilparameter sind XPath-Ausdrücke für den Namens- und den Wertknoten und die Feldnamen, die im Namensknoten ausgegeben werden.
Analog zum Indexdatenleser ist in der Eigenschaft .ItemNode festgelegt, unter welchem XML-Knoten die Daten einer Positionszeile zusammengefasst werden. Dieser Knoten wiederholt sich namentlich. Für die Kopffelder und die Felder unterhalb einer Positionszeile muss auch ein XML-Knoten festgelegt werden (.FieldNode und .ItemFieldNode). Die Knoten dieser Felder wiederholen sich ebenfalls namentlich und können nur anhand der Feldnamen unterschieden werden, die in den Unterknoten aufgeführt sind.
In der XML-Eingabedatei sind die Dateianlagen direkt eingebettet. Bei der Ausgabe werden hingegen Referenzen auf separat mitzuführende Anlagendateien verwendet (.AttachFileMode). Die physische Ausgabe der Anlagendateien erfolgt erst durch das nachfolgende Ausgabesystem. Die Dateiverweise müssen aber schon bei der Erstellung des Ausgabeformats in die XML-Datei eingefügt werden. Eingabeseitig sind die Dateianlagen im Beispiel Textdateien, die unverändert durchgereicht werden. Zur ausgabeseitigen Auswahl dieser Anlagen ist daher ein Filter auf Textdateien gesetzt (.AttachFileFilter). In .AttachFileNode ist angegeben, unter welchen Knoten die Referenzen und ergänzend die zugehörigen Dateinamen erzeugt werden sollen. In .AttachFileRefMacro ist über einen Makroausdruck angegeben, wie die Referenzen inhaltlich aufgebaut sind. Zur Generierung eindeutiger Dateinamen setzen sich die Referenzen hier aus der internen UUID einer Dateianlage und deren Namen zusammen.
Beim Ausgabesystem ist ein passender Dateinamensfilter (.FileFilter) gesetzt. Durch diesen Filter werden die als Ausgabeformat neu erzeugten XML-Ausgabedateien und die zugehörigen Textdateianlagen ausgewählt. Wichtig ist die Fallunterscheidung bei der Bestimmung des Ausgabedateinamens per Makroausdruck (.OutputFileMacro). Die XML-Ausgabedateien werden unverändert unter dem Namen ausgegeben, unter dem diese erzeugt wurden. Die zugehörigen Textdateianlagen müssen hingegen genau den angepassten Dateinamen erhalten, unter dem diese im Ausgabeformat als Referenz eingefügt wurden (zusammengesetzter Wert aus interner UUID und dem Originalnamen). Im Ausgabeverzeichnis (.OutputFolder) werden dynamisch Unterordner erstellt, die den Namen des Eingabestapels erhalten, ergänzt um dessen internen Datenbankschlüssel.