Zum Hauptinhalt springen

XML-Dateiimport

Wenn Ihr System Aufträge oder Adressen als XML exportiert, können Sie diese mit der Datei-Import-Funktion importieren — genauso wie CSV-Dateien, jedoch mit einem XML-Importprofil.

Der Unterschied zu CSV liegt darin, wie das Profil Ihre Feldnamen erfährt:

CSVXML
Spalte FeldnameEine Dropdown-Liste, gefüllt aus der Kopfzeile einer BeispieldateiEin freies Texteingabefeld — Sie geben den Elementnamen oder Pfad ein
Beispieldatei im ProfilJa (Datei hochladen → Datei verarbeiten)Nicht erforderlich — das Profil hat keinen Upload-Schritt
StrukturFlache SpaltenVerschachtelte Elemente und Attribute werden unterstützt

Profil erstellen​

Vor dem Import müssen Sie ein Importprofil erstellen.

XML-Import-Menü

  1. Gehen Sie zu Profile → Adressen oder Sendungen → drücken Sie +
  2. Wählen Sie Importtyp → Adressen oder Sendungen
  3. Geben Sie einen Profilnamen ein (z. B. Aufträge XML)
  4. Wählen Sie Importdateityp → XML
  5. Füllen Sie XML Zeilenelement (Tag oder XPath) aus — das Element, das sich pro Sendung oder Adresse einmal wiederholt (siehe Zeilenelement auswählen)

XML-Profil erstellen — Formular

Dezimaltrennzeichen und Mehrwerttrennzeichen können standardmässig bleiben (. und ,).

warnung

XML Zeilenelement ist ein Pflichtfeld — ohne Angabe können Sie nicht fortfahren.

XML Zeilenelement ist erforderlich

  1. Drücken Sie Weiter
  2. Tragen Sie in der Spalte Feldname den Elementnamen oder Pfad jedes Feldes ein, das Sie importieren möchten

XML-Feld-Mapping

hinweis

Bei XML-Profilen ist Feldname ein freies Texteingabefeld, keine Dropdown-Liste, und es gibt keine Schaltfläche Datei hochladen / Datei verarbeiten. Geben Sie den Namen genau so ein, wie er in Ihrer Datei steht — siehe Wie Elementnamen zu Feldnamen werden.

Die Spalte Funktion kann unverändert bleiben.

Falls erforderlich, fügen Sie eine Transformation hinzu — diese wird erstellt und verwendet, wenn Daten aus der XML-Datei für den Import angepasst werden müssen. Zum Beispiel wenn der Ländername in Ihrer Datei "Schweiz" lautet, unser System es aber im Format ISO 3166-1 alpha-2 ("CH") benötigt.

Transformation

Sobald alle Pflicht- (und optionalen) Feldnamen eingegeben sind, drücken Sie Speichern.

Sendungsfelder, die Sie zuordnen können​

Die Liste der Felder, die Sie füllen können, ist genau dieselbe wie bei CSV — Absender- und Empfängeradresse, Service-, Paket- und Zollangaben, mit denselben Maximallängen und denselben Pflichtfeldern. Siehe Sendungsfelder, die Sie zuordnen können auf der CSV-Seite.

tipp

Das Gewicht ist für jedes Paket erforderlich — stellen Sie sicher, dass Ihre XML-Datei vor dem Import ein Gewichtselement oder -attribut (in kg) enthält.

XML-Datei hochladen​

Datei-Importe-Menü

  1. Gehen Sie zu Datei-Importe
  2. Drücken Sie Datei importieren oben rechts

Datei importieren — Schaltfläche

  1. Wählen Sie das Profil (das XML-Profil, das Sie in Schritt 1 erstellt haben)
  2. Laden Sie die .xml-Datei hoch und drücken Sie Importieren

XML-Import-Dialog

  1. Drücken Sie Aktualisieren

Nach dem Import — Aktualisieren

Die importierten Informationen erscheinen in Ihrem Adressbuch oder Ihren Sendungen. Zeilen, die nicht importiert werden konnten, werden mit ihrer Fehlermeldung aufgelistet; der Rest der Datei wird dennoch importiert.

Technische Anforderungen für XML-Dateien​

Die Datei muss ein wohlgeformtes XML-Dokument mit der Endung .xml sein und darf nicht grösser als 25 MB sein.

Zeilenelement auswählen​

Das XML-Zeilenelement legt fest, wo eine Sendung (oder eine Adresse) beginnt und endet. Jedes übereinstimmende Element wird zu einer Zeile.

Sie können es auf zwei Arten angeben:

Was Sie eingebenBedeutungWann verwenden
Ein einfacher Tag-Name, z. B. shipmentJedes Element mit diesem NamenIhre Zeilen liegen direkt in einem einfachen Dokument
Ein XPath-Ausdruck, z. B. //order oder /root/data/orders/orderJedes Element, das der Ausdruck auswähltIhre Zeilen sind tiefer verschachtelt, oder derselbe Tag-Name kommt an mehreren Stellen vor

Für diese Datei ist das Zeilenelement shipment:

<?xml version="1.0" encoding="UTF-8"?>
<shipments>
    <shipment>
        <receiver_name>Andreas Brauchle</receiver_name>
        <receiver_countryCode>CH</receiver_countryCode>
        <receiver_zipCode>8055</receiver_zipCode>
        <receiver_city>ZÜRICH</receiver_city>
        <receiver_street>Schaufelbergerstrasse 30</receiver_street>
        <service_code>B2B</service_code>
        <weight>2.3</weight>
    </shipment>
    <shipment>
        ...
    </shipment>
</shipments>
gefahr

Verwenden Sie das sich wiederholende Element, nicht die umschliessende Hülle. Oben ist shipment richtig und shipments falsch.

Eine Hülle wird nur einmal gefunden, dadurch fällt die gesamte Datei zu einer einzigen Zeile zusammen, die nur die Werte des letzten Eintrags behält. Der Verlust wird nirgends gemeldet: Ist diese eine Zeile gültig, wird der Import als Erfolgreich gekennzeichnet, und eine Datensatzanzahl wird nur bei teilweise importierten Dateien angezeigt — eine zusammengefallene Datei sieht daher völlig normal aus. Wenn eine Datei mit 5 Einträgen als 1 importiert wird, ist das der Grund.

Bei einer Adressdatei mit der Hülle <Recipients><Recipient>… ist das Zeilenelement folglich Recipient — oder //Recipient, was das Element in beliebiger Tiefe findet:

XML Zeilenelement auf //Recipient gesetzt

Für diese Datei ist das Zeilenelement //order (oder /root/data/orders/order):

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <data>
        <orders>
            <order id="ORD-001">
                <recipient>
                    <address>
                        <name>John Doe</name>
                        <street>Main Street 1</street>
                        <zip>8000</zip>
                        <city>Zurich</city>
                        <country>CH</country>
                    </address>
                    <contact>
                        <email>john@example.com</email>
                    </contact>
                </recipient>
                <parcel weight="2.5" service="B2B">
                    <reference>REF-001</reference>
                </parcel>
            </order>
        </orders>
    </data>
</root>
warnung

Findet das Zeilenelement keine Treffer, schlägt der Import mit "No XML elements matched the configured row element" fehl. Prüfen Sie Schreibweise und Gross-/Kleinschreibung — XML-Elementnamen sind case-sensitiv.

Wie Elementnamen zu Feldnamen werden​

Feldnamen werden relativ zum Zeilenelement angegeben, mit / zwischen den Ebenen und @ für Attribute. Am verschachtelten order-Beispiel oben:

In der DateiWas Sie als Quellfeld eingebenWert
Attribut id am Zeilenelement@idORD-001
<city> direkt unter dem Zeilenelementcity—
<recipient><address><city>recipient/address/cityZurich
<recipient><contact><email>recipient/contact/emailjohn@example.com
Attribut weight an <parcel>parcel/@weight2.5
<parcel><reference>parcel/referenceREF-001

Regeln, die für jeden Wert gelten:

  • Werte werden getrimmt, und unsichtbare Zeichen (geschützte Leerzeichen, Zero-Width-Spaces, Steuerzeichen) werden entfernt
  • Leere Elemente (<recipient_name2></recipient_name2> oder <customs_date />) gelten als nicht geliefert
  • Über mehrere Zeilen verteilter Text wird zu einem Wert zusammengefügt
  • Elemente, die Sie nicht zuordnen, werden ignoriert
warnung

Bleiben Sie innerhalb eines Profils konsistent: Ist Ihre XML-Datei verschachtelt, geben Sie für jedes Feld den vollständigen Pfad an. Ein einfacher Blattname (city) gemischt mit einem Pfad (recipient/address/city) im gleichen Profil kann den einfachen Namen leer lassen, da der Wert bei verschachtelten Dateien nur unter seinem vollständigen Pfad verfügbar ist.

Fortgeschritten: eines von mehreren wiederholten Elementen auswählen​

Wenn sich dasselbe Element innerhalb einer Zeile wiederholt und Sie ein bestimmtes Vorkommen benötigen, fügen Sie dem Quellfeld ein XPath-Prädikat hinzu. Bei folgender Datei:

<shipment id="ORD-001">
    <addresses>
        <address kind="billing">
            <city>Zurich</city>
        </address>
        <address kind="shipping">
            <city>Bern</city>
        </address>
    </addresses>
    <parcels>
        <parcel type="standard" weight="1.0">
            <reference>REF-STD-001</reference>
        </parcel>
        <parcel type="express" weight="2.5">
            <reference>REF-EXP-001</reference>
        </parcel>
    </parcels>
    <items>
        <item>First item</item>
        <item>Second item</item>
    </items>
</shipment>
QuellfeldAuswahlWert
addresses/address[@kind='shipping']/cityDie Lieferadresse, nicht die RechnungsadresseBern
parcels/parcel[@type='express']/@weightDas Gewicht des Express-Pakets2.5
parcels/parcel[@type='express']/referenceDie Referenz des Express-PaketsREF-EXP-001
items/item[1]Das erste Element nach PositionFirst item
warnung

Feldpfade müssen innerhalb der Zeile bleiben. Ein Pfad, der mit / oder // beginnt, wird beim Speichern des Profils mit "Mapping XPaths must be relative to the root row element" abgelehnt — so kann eine Zeile nicht versehentlich Daten einer anderen Zeile übernehmen. Absolute Pfade und // sind nur in der Einstellung des Zeilenelements selbst erlaubt.

XML mit Namensräumen​

Tragen Ihre Elemente ein Namensraum-Präfix (<ns:order>), wählen Sie das Zeilenelement über den lokalen Namen statt über das Präfix aus:

//*[local-name()='order']

Feldpfade können genauso geschrieben werden, z. B. *[local-name()='recipient']/*[local-name()='city'].

Zeichenkodierung​

XML-Dateien geben ihre Kodierung in der Deklaration in der ersten Zeile an:

<?xml version="1.0" encoding="UTF-8"?>
Profileinstellung KodierungWas passiert
Automatisch erkennen (für XML empfohlen)Die Kodierung aus der XML-Deklaration wird verwendet
Eine bestimmte Kodierung (UTF-8, ISO-8859-1, Windows-1250/1251/1252)Diese Kodierung wird verwendet
tipp

Setzen Sie die Kodierung des Profils auf Automatisch erkennen und halten Sie die Deklaration in Ihrer Datei korrekt. Wenn Sie eine bestimmte Kodierung wählen, muss sie zur Datei passen — sonst werden Sonderzeichen zerstört (Müller wird zu Müller).

Sie können die Kodierung auch für eine einzelne Datei über Importkodierung im Dialog Datei importieren überschreiben, ohne das Profil zu ändern — mit Profileinstellung verwenden bleibt der Wert des Profils aktiv.

XML-Konfigurationsparameter​

ParameterTypBeschreibungBeispielwerte
xmlTagZeichenketteDas Zeilenelement — einfacher Tag-Name oder XPathshipment, //order
decimalSeparatorZeichenketteDezimaltrennzeichen für Zahlen wie das Gewicht. (Standard) oder ,
multiValueDelimiterZeichenketteTrennzeichen innerhalb eines Elements mit mehreren Werten, z. B. Optionscodes, (Standard), ;, |

Gewicht mit Punkt (decimalSeparator = .):

<weight>2.5</weight>

Gewicht mit Komma (decimalSeparator = ,):

<weight>2,5</weight>

Mehrere Optionscodes in einem Element (multiValueDelimiter = ,):

<option_codes>136,140</option_codes>

Sicherheitseinschränkungen​

Aus Sicherheitsgründen weist der Import Dateien mit einer Dokumenttypdefinition (<!DOCTYPE ...>) oder eigenen Entities ab und lädt niemals Inhalte, die von ausserhalb der Datei referenziert werden. Exportieren Sie Ihre Daten ohne DTD.

Häufige Probleme & Lösungen​

"No XML elements matched the configured row element"

Das Zeilenelement aus dem Profil existiert in der Datei nicht. Öffnen Sie die Datei in einem Texteditor und prüfen Sie die genaue Schreibweise und Gross-/Kleinschreibung des sich wiederholenden Elements. Liegen Ihre Zeilen tiefer verschachtelt, verwenden Sie einen XPath wie //order statt eines einfachen Tag-Namens.

Ein zugeordnetes Feld bleibt leer

Der Text des Quellfeldes stimmt nicht genau mit der Datei überein. Prüfen Sie, ob Sie den vollständigen Pfad relativ zum Zeilenelement angegeben haben (recipient/address/city, nicht city), ob Attribute mit @ beginnen (parcel/@weight), und ob die Gross-/Kleinschreibung passt.

"Invalid content type for XML"

Die hochgeladene Datei wurde nicht als XML erkannt. Stellen Sie sicher, dass sie die Endung .xml hat und mit einer korrekten XML-Deklaration oder einem Wurzelelement beginnt — eine in .xml umbenannte CSV- oder Textdatei wird abgewiesen.

"Failed to parse XML file"

Die Datei ist nicht wohlgeformt (nicht geschlossenes Tag, einzelnes &, abgeschnittener Export) oder enthält eine <!DOCTYPE ...>-Deklaration. Öffnen Sie sie in einem Browser oder XML-Editor — dieser zeigt die erste fehlerhafte Zeile. Schreiben Sie & als &amp; und < als &lt;.

"Mapping XPaths must be relative to the root row element"

Ein Feldpfad beginnt mit / oder //. Entfernen Sie die führenden Schrägstriche, damit der Pfad relativ zum Zeilenelement ist: recipient/address/city statt //city.

Sonderzeichen werden falsch angezeigt — z. B. Müller erscheint als Müller

Die Profilkodierung passt nicht zur Datei. Setzen Sie Kodierung auf Automatisch erkennen, damit die XML-Deklaration entscheidet, oder wählen Sie die Kodierung, in der Ihre Datei tatsächlich gespeichert ist.

Das Gewicht wird nicht als Zahl erkannt

Ihr Dezimalzeichen passt nicht zum Profil. Setzen Sie Dezimaltrennzeichen passend zur Datei: ein Komma (,), wenn die Datei 2,5 schreibt, einen Punkt (.), wenn sie 2.5 schreibt.

Es wurden weniger Datensätze importiert, als die Datei enthält

Das Zeilenelement zeigt auf die umschliessende Hülle statt auf das sich wiederholende Element, daher wurde die ganze Datei als eine Zeile gelesen. Vergleichen Sie die beiden Elementnamen in Ihrer Datei — bei <shipments><shipment>… ist das Zeilenelement shipment. Siehe die Warnung unter Zeilenelement auswählen.

Nur einige Zeilen sind fehlgeschlagen

Das ist das erwartete Verhalten: Jede Zeile wird einzeln importiert, und eine Zeile, die die Validierung nicht besteht (fehlendes Gewicht, unbekanntes Land, ungültige Postleitzahl), wird mit ihrer Fehlermeldung als fehlgeschlagen aufgeführt, während die übrigen Zeilen importiert werden. Korrigieren Sie diese Zeilen und importieren Sie die Datei erneut.

Die Datei wird dann als Teilweise importiert gekennzeichnet, mit Fehlerhafte Werte und der Anzahl der betroffenen Zeilen. Öffnen Sie sie, um pro fehlgeschlagener Zeile einen Eintrag mit dem Grund und einer Rohdaten-Ansicht der gelesenen Werte zu sehen:

Teilweise importierte Datei mit Fehlern

Im Beispiel oben verwendete die Datei numerische Ländercodes (528, 276), wo das System einen zweistelligen ISO-Code erwartet — genau der Unterschied, den eine Transformation auf dem Länderfeld behebt.

Checkliste vor dem Import​

Vor dem Import überprüfen:

  • Die Datei ist wohlgeformtes XML und hat die Endung .xml
  • Keine <!DOCTYPE ...>-Deklaration in der Datei
  • Die XML-Deklaration nennt die richtige Kodierung, und die Kodierung des Profils steht auf Automatisch erkennen
  • Das Zeilenelement im Profil stimmt mit dem sich wiederholenden Element in der Datei überein, nicht mit dessen Hülle (exakte Gross-/Kleinschreibung)
  • Nach dem Import entspricht die Anzahl der Datensätze der Anzahl der Einträge in der Datei
  • Jedes zugeordnete Quellfeld ist relativ zum Zeilenelement angegeben, mit / für Ebenen und @ für Attribute
  • Alle Pflichtfelder sind zugeordnet — Empfängername, Strasse, Postleitzahl, Stadt, Land und Gewicht
  • Das Gewicht ist in kg, und das Dezimaltrennzeichen passt zum Profil
  • Sonderzeichen (ä, ö, ü, é) werden im Texteditor korrekt angezeigt
  • Dateigrösse unter 25 MB