XMLReader
Mit dem XMLReader Step kann man eine oder mehrere XML-Dateien einlesen und als Spreadsheet ausgeben. Oft wird dieser Prozess auch als parsen oder parsing bezeichnet.
Die Funktionsweise verdeutlicht sich am besten an einem Beispiel.
- Die Inputs und Outputs sind hier beschrieben.
XML-Einlesen ohne Skripting
Für einfach strukturierte XML-Dateien kann man auch den Step XMLReaderVisual verwenden. Dieser macht die Verarbeitung durch eine graphische Oberfläche noch einfacher.
Tutorial: REST-API Anbindung
Lernen Sie in unserem Tutorial REST API Anbindung mit Synesty, wie man jede beliebige HTTP-API mit JSON oder XML anbinden kann - auch ohne Add-Ons von Synesty und ohne Programmierung in PHP, Java oder Javascript.
Beispiel XML-Datei
Nehmen wir folgende XML-Datei an (Beispieldatei herunterladen). Diese Datei enthält Daten für 2 Artikel, mit allerlei Artikelnummern und weiteren typischen Feldern.
<?xml version="1.0" encoding="ISO-8859-1"?>
<ARTIKELLISTE>
<ARTIKEL>
<LFSN>ZEG</LFSN>
<LFKURZBEZ>ZEG</LFKURZBEZ>
<INTARTNR>8592</INTARTNR>
<ARTNR>010-12983</ARTNR>
<REFARTNR>010-12983</REFARTNR>
<HERSTNR>870310 / 10870310</HERSTNR>
<MARKE>Schwalbe</MARKE>
<MARKENLOGO></MARKENLOGO>
<MODELL>High Pressure</MODELL>
<MODELLJAHR>0</MODELLJAHR>
<FARBE>blau</FARBE>
</ARTIKEL>
<ARTIKEL>
<LFSN>ZEG</LFSN>
<LFKURZBEZ>ZEG</LFKURZBEZ>
<INTARTNR>8593</INTARTNR>
<ARTNR>010-12984</ARTNR>
<REFARTNR>010-12984</REFARTNR>
<HERSTNR>870311 / 10870311</HERSTNR>
<MARKE>Simson</MARKE>
<MARKENLOGO></MARKENLOGO>
<MODELL>High Pressure</MODELL>
<MODELLJAHR>0</MODELLJAHR>
<FARBE>rot</FARBE>
</ARTIKEL>
</ARTIKELLISTE>
Ziel Spreadsheet
Ziel ist es, diese Datei einzulesen und einige der Felder als tabellarisches Spreadsheet auszugeben, um damit weiter zu arbeiten.
Beispiel-Flow
Folgender Beispiel-Flow liest die XML-Datei ein.
Die eigentliche Einlese-Logik steckt im Input transformationTemplate.
XML Parsing Variante 1
Die Einlese-Logik nutzt hierbei die XML-Parsing-Möglichkeiten der Skriptsprache Freemarker sowie eine Synesty-Hilfsfunktion addColumns().
<#assign row = target.addRow()>
<#list xml["ARTIKELLISTE"]["ARTIKEL"] as art>
<#assign row = target.addRow()>
${addColumns(row, art)}
</#list>
Sehen wir uns nun diese Logik im Detail an:
<#assign row = target.addRow()>
Die Variable target repräsentiert unser Ziel-Spreadsheet. (Hinweis: Diese Variable ist fest vergeben und muss zwingend so heißen.) Über target.addRow(), wird dem Spreadsheet eine Zeile hinzugefügt. In diesem Fall eine leere Kopfzeile.
<#list xml["ARTIKELLISTE"]["ARTIKEL"] as art>
...
</#list>
Die im Hintergrund geparste XML-Datei steht als Variable xml im transformationTemplate zur Verfügung und beinhaltet die komplette XML-Struktur als DOM-Tree (oder sog. Node-Modell). Man kann nun auf einzelnen Felder der XML-Datei zugreifen.
(Hinweis: Diese Variable ist fest vergeben und muss zwingend so heißen.)
Mit der list-Anweisung wird über alle ARTIKEL der ARTIKELLISTE iteriert. Auf die Daten eines Artikels wird dann über den Alias art zugegriffen. (Hinweis: Anstatt art, kann auch ein beliebiges anderes Wort genutzt werden. )
<#assign row = target.addRow()>
${addColumns(row, art)}
Über target.addRow(), wird dem Spreadsheet pro Iteration eine weitere Zeile hinzugefügt. Diese Zeile wird einer neuen Variable row zugewiesen, damit wir anschließend dieser Zeile Spalten hinzufügen können.
Wir erinnern uns dass die Felder des Artikels, über den wir gerade iterieren, in der Variable art zur Verfügung stehen.
Um nun die Zeile (row) mit Spalten (Columns) zu füllen, rufen wir folgendes auf:
${addColumns(row, art)}
Damit wird die Funktion addColumns für die row aufgerufen und mit Spalten gefüllt. Die Spaltennamen und Inhalte stammen aus dem dem aktuellen XML-Knoten der sich hinter der Variable art verbirgt.
Parameter von addColumns()
Syntax:
${addColumns(row, node, [prefix], [options])}
Parameter | Beschreibung | |||||||
---|---|---|---|---|---|---|---|---|
row | Die Zeile (das Row-Objekt des Spreadsheets), der die Spalten hinzugefügt werden sollen. | |||||||
node | Der Ober-Knoten (Node) im XML-Baum, dessen Unterknoten als Spalten hinzugefügt werden sollen. | |||||||
prefix | optional: Dieser optionale Prefix wird allen hinzugefügten Spaltennamen vorangestellt. Beispiel:
1
1 Hier werden Spalten eines XML-Unterknotens shipping_address und billing_address hinzugefügt. Da beide Adressen Spalten wie Vorname, Nachname enthalten können, ist es sinnvoll diese durch ein Prefix (hier shipping_address_ und billto_address_) von einander abzugrenzen und unterscheidbar zu machen. | |||||||
options(optional) | Ein Hash/Map (Schlüssel/Wert-Paare) mit optionalen Konfigurationsparametern. Die Notation der options ist technisch gesehen ein JSON-Objekt. Beispiel:Hier werden die beiden Parameter columns und mode dargestellt, die etwas weiter unten noch genauer erklärt werden. 2 Parameter: columns und mode
1 2 3 4 5 6 7 8 9 10 D.h. ein kompletter addColumns-Befehl inkl. options sieht wie folgt aus:
1 Wichtig Wird options ohne den prefix Parameter verwendet, dann ist für prefix ein Platzhalter in Form von "" einzufügen. | |||||||
columns (optional)&mode (optional) | columns: Ein String-Array von Feldnamen, die im Spreadsheet hinzugefügt (include) oder ausgeschlossen (exclude) werden sollen. mode: Über mode kann man steuern, ob die im Parameter columns definierten Spalten ausgegeben oder ignoriert werden.
Beispiel: Nur bestimmte Feld ausgeben (include)
1 Diese Zeile sorgt dafür, dass nur die Felder zip und city des Knotens shipping_address im Spreadsheet landen. Alle anderen Address-Felder wie z.B. street oder country werden nicht ausgegeben.
1 Beispiel: Bestimmte Felder ausschließen (exclude)
1 Diese Zeile sorgt dafür, dass alle Felder außer zip und city des Knotens shipping_address im Spreadsheet landen. Wichtig Die eckigen Klammern bei ["zip", "city"] sind wichtig, da dies die Freemarker-Notation für ein Array ist. Bitte nicht vergessen! | |||||||
skipEmptyValues (optional) | Über skipEmptyValues (true/false, default: false) kann man steuern, ob man eine Spalte nur hinzufügen möchte, wenn der Wert der XML-Node nicht leer ist. Das ist praktisch bei riesigen XML-Dateien, die haufenweise leere Tags enthalten, die man nicht im Output-Spreadsheet sehen möchte. Damit kann man das resultierende Spreadsheet auf die nötigsten nicht-leeren Spalten beschränken.
1 Diese Zeile sorgt dafür, dass die Felder zip und city dem Spreadsheet hinzugefügt werden, allerdings nur wenn das Feld jeweils gefüllt ist. Wenn z.B. die Spalte zip immer leer wäre, dann würde im Output-Spreadsheet keine Spalte für zip auftauchen. | |||||||
autoExpand (optional) | Der Parameter autoExpand steuert, ob und wie Unter-Nodes automatisch "aufgeklappt" werden, wenn deren Wert ebenfalls wieder Unter-Nodes enthält.
Beispiel asColumns: XML Quelle
1 2 3 4 5 6 7 8 9 10 Das entscheidende hier ist der Category-Knoten, welcher wieder Unter-Knoten enthält. Damit diese Unterknoten (Name und Visible) auch durch addColumns() mit ausgegeben werden, muss die Option "autoExpand": "asColumns" gesetzt werden.
1 2 3 4 5 6 7 Ausgabe:
|
XML Parsing Variante 2
Diese Einlese-Logik verzichtet auf die addColumns() Hilfsfunktion und ist somit länger. Sie zeigt quasi den manuellen Weg, wenn man volle Flexibilität braucht. Das ist in etwas das, was *addColumns() *im Hintergrund automatisch macht.
<#assign row = target.addRow()>
<#list xml["ARTIKELLISTE"]["ARTIKEL"] as art>
<#assign row = target.addRow()>
${row.addCol("Artikelnummer",art["ARTNR"])}
${row.addCol("Marke",art["MARKE"])}
${row.addCol("Modell",art["MODELL"])}
</#list>
XML-Dateien mit XML-Namespace Deklaration (xmlns)
In einigen Fällen werden in XML-Dateien auch sogenannte Namespaces deklariert. Namespaces dienen der eindeutigen Identifizierung vom XML Elementen. Deklarierte Namespaces erkennt man am xmlns Attribut, z.B.
xmlns="http://meistensirgendeinelangeurl.de/" für einen Default Namespace oder xmlns:prefix="http://meistensirgendeinelangeurl.de/erweitert"
XML Beispiel mit xmlns Namespace Deklaration
<?xml version="1.0" encoding="ISO-8859-1"?>
<ARTIKELLISTE xmlns="http://meistensirgendeinelangeurl.de/" xmlns:prefix="http://meistensirgendeinelangeurl.de/erweitert">
<ARTIKEL>
<ARTNR>010-12983</ARTNR>
<MARKE>Schwalbe</MARKE>
<MODELL>High Pressure</MODELL>
<prefix:DETAILS>
<IMG>image1.jpg</IMG>
</prefix:DETAILS>
</ARTIKEL>
<ARTIKEL>
...
</ARTIKEL>
</ARTIKELLISTE>
Wenn das der Fall ist, dann würde das obige Freemarker-Skript zum Einlesen nicht funktionieren.
Man muss Freemarker erst mitteilen, dass dieser Namespace verwendet werden soll. Der Default-Namespace wird immer mit "D" angegeben, alle anderen über den Namespace-Präfix, z.B. "prefix"
Dazu fügt man im transformationTemplatefolgende Zeile an den Anfang ein:
<#ftl ns_prefixes={"D":"http://meistensirgendeinelangeurl.de/", "prefix":"http://meistensirgendeinelangeurl.de/erweitert"}>
Danach funktioniert das Skript wieder so wie oben.
Das komplette Skript sieht dann so aus.
<#ftl ns_prefixes={"D":"http://meistensirgendeinelangeurl.de/", "prefix":"http://meistensirgendeinelangeurl.de/erweitert"}>
<#assign row = target.addRow()>
<#list xml["ARTIKELLISTE"]["ARTIKEL"] as art>
<#assign row = target.addRow()>
${row.addCol("Artikelnummer",art["ARTNR"])}
${row.addCol("Marke",art["MARKE"])}
${row.addCol("Modell",art["MODELL"])}
${row.addCol("Bild1", art["prefix:DETAILS"][0]["IMG"])}
</#list>
Details zu Freemarker und XML Namespaces:
Komplexere XML-Strukturen
Das obige Beispiel repräsentiert eine sehr einfache XML-Datei.
XML-Dateien können aber wesentlich komplexere und verschachtelte Strukturen beinhalten.
Da dies immer von der konkreten XML-Struktur abhängt empfehlen wir sich ausgiebig mit folgenden Seiten aus der Freemarker Dokumentation auseinander zu setzen:
XML-Dateien mit Attributen
In manchen Fällen besitzen XML-Elemente sog. Attribute. Ein Attribut gibt weitere Informationen über das XML-Element an. In dem folgenden Beispiel (Beispieldatei herunterladen) besitzt das Element <PREIS> die Attribute "typ" und "wert".
<?xml version="1.0" encoding="ISO-8859-1"?>
<ARTIKELLISTE>
<ARTIKEL>
<LFSN>ZEG</LFSN>
<LFKURZBEZ>ZEG</LFKURZBEZ>
<INTARTNR>8592</INTARTNR>
<ARTNR>010-12983</ARTNR>
<REFARTNR>010-12983</REFARTNR>
<HERSTNR>870310 / 10870310</HERSTNR>
<MARKE>Schwalbe</MARKE>
<MARKENLOGO></MARKENLOGO>
<MODELL>High Pressure</MODELL>
<MODELLJAHR>0</MODELLJAHR>
<FARBE>blau</FARBE>
<PREISE>
<PREIS typ="EKN" wert="1000"/>
<PREIS typ="EKB" wert="1190"/>
<PREIS typ="VKN" wert="1400"/>
<PREIS typ="VKB" wert="1666"/>
</PREISE>
</ARTIKEL>
</ARTIKELLISTE>
In der Beispiel XML-Datei sind mehrere Preise aufgelistet. Diese Preise sollen in einen Spreadsheet ausgegeben werden. Für eine bessere Unterscheidung wird der Typ mit angegeben. Am besten lässt sich dies bewerkstelligen wenn jeder Typ in eine separate Spalte im Spreadsheet geschrieben wird. Das hat außerdem noch den Vorteil das man später die Preise besser filtern und bearbeiten kann.
Ziel Spreadsheet
Auch hier wird wieder eine list-Anweisung verwendet um über jedes PREIS-Element zu iteriern. Auf die Daten eines Attributs wird dann mit der freemarker Anweisung attr("Attributename", Element) zugegriffen.
<#assign row = target.addRow()>
<#list xml["ARTIKELLISTE"]["ARTIKEL"] as item>
<#assign row = target.addRow()>
<#list item["PREISE"]["PREIS"] as preis>
${row.addCol(attr("typ", preis), attr("wert", preis)!)}
</#list>
</#list>
Zugriff auf XML-Attribute per attr()
Die Funktion attr() ist eine Synesty-eigene Funktion, weil der Zugriff auf XML-Attribute direkt per Freemarker starke Performance-Probleme hat.
Details zu Freemarker und XML Attributes:
- http://freemarker.incubator.apache.org/docs/xgui_imperative_learn.html#autoid_133
XML in Spreadsheet-Spalten einlesen
Der XMLReader Step kann außer FILE und FILELIST Inputs auch mit dem Typ SPREADSHEET umgehen - d.h. ein Spreadsheet, in dem in einer Spalte ein XML-String steht.
Wann braucht man das?
Meistens wird das gebraucht wenn man vorher mit dem Step SpreadsheetURLDownload arbeitet und z.B. eine Webservice- oder REST-API anbindet. Die Ausgabe des SpreadsheetURLDownload ist ein Spreadsheet, in dem in einer Spalte die XML-Antwort des API-Calls steht (so ist das zumindest bei einigen-APIs der Fall).
Anwendung
Sobald Sie dem XMLReader Step das Input-Spreadsheet übergeben, erscheint eine weitere Option spreadsheetXMLColumn, mit der man bestimmt, in welcher Spalte dieses Spreadsheets der XML-String steht, der geparst werden soll.
Mit anderen Worten: statt einer Liste von XML-Dateien (FILELIST) wird eine eine Liste von Spalten verarbeitet, in denen XML drin steht.
Zugriff auf die Spreadsheet-Spalten
Man kann im transformationTemplate auch auf die anderen Spalten des Input-Spreadsheets zuzugreifen. Meistens wird das genutzt in Verbindung mit dem SpreadsheetURLDownload und der dortigen Möglichkeit Spalten über die Option outputSourceColumns durchzuschleifen (z.B. Artikelnummer / SKU).
Dafür existiert eine Variable inputRow.
Damit haben Sie immer die aktuelle Zeile des Input-Spreadsheets verfügbar und können auf die Spaltenwerte zugreifen.
Beispiel:
${inputRow.get("meinSKUSpalte")!}
Angenommen im Input-Spreadsheet gibt es eine Spalte *meineSKUSpalte, *die eine Artikelnummer enthält, und die auch wieder in der Ausgabe des XMLReader Steps auftauchen soll.
Sie können im XMLReader dann grob sowas machen, um eine Spalte mit dieser Artikelnummer hinzuzufügen:
${row.addCol("SKU", inputRow.get("meinSKUSpalte") )}
Fehler im Parsing Code
Das Einlesen von XML Dateien ist nicht ganz einfach und es passieren auch schnell einmal Tippfehler, man verschreibt sich bei einem XML-Tag, welche es dann nicht gibt.
In diesem Fall gibt der Step Fehlermeldungen wie folgt aus:
Error in XML parsing code: No compatible overloaded variation was found; can't convert (unwrap) the 2nd argument to the desired Java type.The FTL type of the argument values were: string (wrapper: f.t.SimpleScalar), sequence+hash (wrapper: f.e.dom.NodeListModel).
title: XMLReader (API-Connector-Tools)
description: "Einlesen einer XML Datei in ein Spreadsheet."
head:
- - meta
- name: category
content: step
- - meta
- name: parent
content: API-Connector-Tools
---
-----FTL stack trace ("~" means nesting-related): - Failed at: ${row.addCol("Modell", art["MODELLa"])} [in template "xmlToSpreadsheet" at line 6, column 9]---- (responsible code: - Failed at: ${row.addCol("Modell", art["MODELLa"])} [in template "xmlToSpreadsheet" at line 6, column 9])
Dieser Fehler wird genauer in diesem Knowledge Base Artikel erklärt.
Beispiel Flow zum Download
Das komplette Beispiel von oben gibt es als installierbare Vorlage oder
(Rechtsklick und Speichern unter) und im Studio als Flow importieren.
Weitere Beispiele
Weitere auch etwas komplexere Beispiele finden Sie auf der Seite XML und JSON Parsing am Beispiel.
Inputs
Das sind die Optionen, mit denen man den Step konfigurieren kann.
Name | Datentyp | Beschreibung | Pflichtfeld | Werte |
---|---|---|---|---|
xmlfile | OBJECT | Die XML FILE, FILELIST or SPREADSHEET, die eingelesen werden soll. Wenn eine FILELIST genutzt wird, müssen alle XML Dateien nach dem gleichen Schema aufgebaut sein. Wenn ein SPREADSHEET genutzt wird, muss die Spalte mit dem XML Inhalt als spreadsheetXMLColumn ausgewählt werden. | Ja | |
mode | STRING | Definiert, wie der XML-Inhalt geparst werden soll. | Nein |
|
spreadsheetXMLColumn | STRING | Spreadsheet Spalte zum Einlesen auswählen | Nein | |
transformationTemplate | STRING | Vorlage in Freemarker Syntax um die XML Datei in ein Spreadsheet umzuwandeln. | Ja | |
sourcefileCharset | STRING | Der Zeichensatz der XML Quell Datei. Default: [AUTO-DETECT] | Nein |
|
parsingOptions | STRINGLIST | Definiert Optionen, wie der XML-Inhalt im automatischen Modus geparst werden soll. | Nein |
|
headerSeparator | STRING | Definiert welches Trennszeichen in den Spaltentitel verwendet werden soll. | Nein |
|
Outputs
Das sind die Ergebnisse des Steps, die von nachfolgenden Steps, nach der Ausführung verwendet werden können.
Name | Datentyp | Beschreibung | Pflichtfeld | Werte |
---|---|---|---|---|
output | SPREADSHEET | Das entstandene Speadsheet zur weiteren Bearbeitung. | Ja |