Kopf und Positionen zuordnen, wenn das Ziel anders schneidet
Eine Bestellung aus dem Webshop ist eine Nachricht. Der Beleg in SAP Business One, der daraus entsteht, sind zwei Dinge: ein Kopf mit Kunde, Datum und Zahlungsart – und darunter beliebig viele Positionen mit Artikel und Menge.
{
"order_id": "WS-2026-104877",
"customer_no": "K-10042",
"lines": [{ "sku": "ARM-4711", "qty": 2 }]
}
customer_no ist ein Wert und wird ein Feld. lines ist eine Liste und wird viele Zeilen. Für
den zweiten Fall braucht die Zuordnung eine Liste.
Diese Anleitung baut die Positionen der Route „Bestellungen Webshop“. Am Ende steht im
Testergebnis unter DocumentLines je ein Eintrag mit ItemCode und Quantity, und zwar so viele,
wie die Bestellung Positionen hat.
Was Sie brauchen
- Die Berechtigung Routen in der Stufe Voll. Siehe Berechtigungen.
- Eine Route mit einer Zuordnung, in der die Kopffelder bereits zugeordnet sind. Diese Anleitung ergänzt die Positionen.
- Einstieg: Konfiguration → Routen, die Route auswählen, Reiter Zuordnung.
Xchange sichert jede Eingabe automatisch. Im Betrieb wirkt sie erst mit dem aktivierten Konfigurationsstand – das ist Schritt 4.
1. Die Liste anlegen und öffnen
- In der Kopfzeile der Tabelle Zuordnungen die Schaltfläche Liste hinzufügen wählen. Sie steht dort neben Zeile hinzufügen. In der Tabelle erscheint eine neue Zeile.
- Diese Zeile anklicken. Die Liste öffnet sich und füllt den Arbeitsbereich: Sie sehen jetzt die Zuordnungen, die innerhalb der Liste gelten. Über der Tabelle steht der Weg dorthin, vom Schritt bis zur Liste – ein Klick auf einen früheren Eintrag bringt Sie zurück.
- Neben diesem Weg steht die Schaltfläche Listeneinstellungen. Sie erscheint erst hier, denn sie gehört zur geöffneten Liste. Diese wählen.
Nur Listenzeilen lassen sich so öffnen. Eine gewöhnliche Zuordnungszeile bleibt beim Klick, wie sie ist – daran erkennen Sie im Zweifel, welche Art von Zeile vor Ihnen steht.
2. Sagen, welche Liste welche füllt
Der Dialog Listeneinstellungen öffnet sich auf dem Reiter Allgemein.
- Im Feld Zielliste
DocumentLineseintragen – die Liste im Zielsystem, die gefüllt werden soll. - Im Feld Befüllung steht Aus Quell-Liste. Das ist die Vorgabe und der Fall dieser Anleitung: Die Quelle bringt die Liste mit, und jeder ihrer Einträge wird ein Eintrag im Ziel.
- Darunter erscheint das Feld Quell-Liste. Dort
OriginalPayload.lines[*]auswählen. - Im Feld Suchen über Markierte Felder wählen. Weil die Bestellung einen vorhandenen Beleg auch aktualisieren kann, muss Xchange dessen Positionen wiederfinden – über das Feld, das Sie im nächsten Schritt als Schlüssel markieren.
- Fertig wählen. Der Dialog schließt sich.

Die Liste ist ein Behälter. Sie sagt nur, welche Liste der Quelle welcher Liste des Ziels entspricht. Was ein einzelner Eintrag enthält, ordnen Sie im nächsten Schritt zu.
3. Die Positionsfelder zuordnen
Sie stehen weiterhin in der geöffneten Liste.
- Zeile hinzufügen wählen und in der Spalte Zielfeld
ItemCodeeintragen. - In der Spalte Quelle das Feld auswählen. Die Auswahl ist nach Gruppen sortiert; unter
Elementfelder steht
sku. - Dasselbe für die zweite Zeile: Zielfeld
Quantity, Quelleqtyaus der Gruppe Elementfelder. - An der Zeile
ItemCodedas Schlüsselsymbol wählen. Eine Position mit demselben Artikel wird dann aktualisiert statt ein zweites Mal angehängt.
Eine Zuordnung in der Liste läuft für jeden Eintrag einmal. Sie schreiben zwei Zeilen hin, und eine Bestellung mit sieben Positionen erzeugt daraus vierzehn Werte in sieben Einträgen.
Ein Filter auf dem gleichnamigen Reiter der Listeneinstellungen schränkt ein, welche Einträge überhaupt übernommen werden – etwa nur Positionen mit einer Menge größer als null. Welche Vergleiche zur Verfügung stehen, führt Routen – Zuordnung.
4. Prüfen im Testbereich
Bevor Sie aktivieren, sehen Sie nach, was herauskommt.
- Auf dem Reiter Zuordnung die Schaltfläche Testbereich wählen.
- Eine Beispielnachricht einfügen – am besten eine mit mehreren Einträgen in
lines, weil sich erst daran zeigt, ob die Liste stimmt. - Test ausführen wählen.
Im Ergebnis steht DocumentLines mit einem Eintrag je Position. Ein Test läuft nur im
Testbereich, das Zielsystem bleibt unberührt; Sie können ihn also auch an einer laufenden Route
benutzen.
5. Aktivieren
Ihre Änderung liegt im Entwurf. Prüfen Sie ihn und aktivieren Sie ihn; erst dann schreibt die Route die Positionen. Der Weg dorthin steht in Prüfen und aktivieren.
Wenn sich der Artikel einer Position ändert
Der Schlüssel aus Schritt 3 findet eine Position, solange ihr Artikel gleich bleibt. Tauscht der
Kunde im Shop ARM-4711 gegen ARM-4712, findet Xchange keine Position mit dem neuen Artikel und
hängt eine zweite an.
Schickt die Quelle je Position eine eigene Kennung mit, die beim Tausch erhalten bleibt, findet
Xchange die Position über diese Kennung wieder. Angenommen, der Shop liefert sie als line_id:
"lines": [{ "line_id": "ln-3a81f2", "sku": "ARM-4711", "qty": 2 }]
- In der geöffneten Liste Listeneinstellungen wählen.
- Im Feld Verknüpfen über
line_idauswählen. - Fertig wählen.
Den Schlüssel ItemCode lassen Sie stehen. Xchange merkt sich beim Schreiben, welche Position zu
welcher line_id gehört, und findet sie ab dem nächsten Lauf darüber wieder – auch mit neuem
Artikel. Fehlt das Feld Verknüpfen über, lassen sich die Zeilen dieser Liste nicht verknüpfen. In
welcher Reihenfolge Verknüpfung und Schlüssel greifen, wann das Feld fehlt und was bei einer leeren
Kennung gilt, steht unter
Zuordnung – Zeilen über ihre Verknüpfung wiederfinden.
Ein Wert aus dem Kopf in jeder Position
Manche Zielsysteme verlangen einen Wert an jeder Position, den die Quelle nur einmal schickt – eine Lagernummer, eine Kostenstelle, das Bestelldatum.
Die Auswahl in der Spalte Quelle reicht deshalb über den Eintrag hinaus. Sie ist nach Gruppen sortiert, von innen nach außen:
| Gruppe | Was sie anbietet |
|---|---|
| Elementfelder | die Felder des einzelnen Eintrags – sku, qty |
| Übergeordnete Zeile | die Felder der Liste darüber, wo eine Liste in einer Liste steckt |
| Hauptdatensatz | die Felder der ganzen Nachricht – customer_no, order_id |
So bekommt jede Position denselben Wert aus dem Kopf, auch wenn die Quelle ihn nur einmal schickt.

Die Gruppe Übergeordnete Zeile erscheint nur, wenn es eine gibt. Steht Ihre Liste unmittelbar unter dem Hauptdatensatz, entfällt sie – dort reichen Elementfelder und Hauptdatensatz.
Wenn die Quell-Liste leer ist
Eine Bestellung ohne Positionen ist selten. Häufiger leert erst der Filter die Liste: Übernehmen Sie nur Positionen mit Menge größer als null, bleibt bei einer reinen Stornobestellung die Liste leer.
Das Feld Leerverhalten in den Listeneinstellungen entscheidet, was dann ins Ziel geht:
| Einstellung | Wirkung |
|---|---|
| Nicht übertragen | Die Liste fehlt in der Nachricht ganz. Vorgabe. |
| Null schreiben | Die Liste geht mit einem ausdrücklichen Leerwert hinaus. |
| Leere Liste schreiben | Die Liste geht als Liste ohne Einträge hinaus. |
Ein Feld hat ein Leerverhalten mit demselben Namen und anderen Werten. Dort heißt die Vorgabe Unverändert übertragen – der leere Wert geht also hinaus, wie er ist. Diese Einstellung gibt es nur beim Feld; die Liste steht stattdessen auf Nicht übertragen. Stellen Sie beide nebeneinander ein, rechnen Sie leicht mit dem falschen Vorgabewert. Leere Liste schreiben gibt es nur hier.
Darüber steht das Feld Pflichtfeld mit Technisch und Fachlich. Ist es gesetzt und fehlt die Liste in der Quelle ganz, bricht die Zuordnung ab und der Vorgang landet in der Manuellen Klärung. Bringt die Quelle die Liste mit und der Filter leert sie, greift das Leerverhalten – der Unterschied entscheidet, ob Sie den Fall zu sehen bekommen.
Aus einem Textwert mehrere Zeilen machen
Manche Quellen schicken eine Liste als Text: Sie packen mehrere Werte in ein Textfeld,
getrennt durch ein Zeichen. Der Shop liefert so die Zahlungsarten eines Kunden, als
"payment_methods": "paypal|invoice".
Dafür steht im Feld Befüllung die Einstellung Aus Textwert. Statt Quell-Liste erscheinen dann zwei andere Felder:
- Quellfeld – das Textfeld, das zerlegt werden soll.
- Trennzeichen – das Zeichen, an dem getrennt wird.
Jeder Teil wird ein Eintrag. In den Zuordnungen darunter bietet die Gruppe Elementfelder genau einen Eintrag an: Wert des Elements – der Teil selbst, denn er ist ein bloßer Wert.
In „Kunden Webshop“ füllt das die Liste BPPaymentMethods des Geschäftspartners: Quellfeld
OriginalPayload.payment_methods, Trennzeichen |. Ihre eine Zuordnung schreibt
PaymentMethodCode aus Wert des Elements, über die Wertetabelle „Zahlungsarten Webshop“. Aus
paypal|invoice werden so zwei Einträge, PP und RG.
Die dritte Einstellung, Feste Zeilen, kommt ohne Quelle aus: Jeder Eintrag ist eine Zusatzzeile, die Sie von Hand anlegen.
Eine Zusatzzeile kann auch neben einer Quell-Liste stehen. In „Bestellungen Webshop“ entsteht so die
Frachtposition. Der Shop schickt die Versandkosten als einen Betrag im Kopf, shipping_total; die
Liste DocumentLines trägt dafür neben ihren Elementfeldern die Zusatzzeile „Fracht“ mit ItemCode
FRACHT-PAUSCHAL, Quantity 1 und UnitPrice aus OriginalPayload.shipping_total. Eine
Bedingung auf der Zeile – OriginalPayload.shipping_total ist größer als 0 – lässt die Position
bei versandkostenfreien Bestellungen weg.
Ein Wechsel der Befüllung verwirft, was zur bisherigen gehörte. Xchange fragt vorher nach und sagt in der Rückfrage, was dabei verlorengeht – lesen Sie sie, bevor Sie bestätigen.
Aus mehreren Zeilen ein Wert
Der Weg zurück ist der engere. Ein Kopffeld, das etwas über alle Positionen aussagen soll, wird in einer gewöhnlichen Zuordnungszeile gebaut. Neben der Quelle steht dafür eine zweite Auswahl, Listenwerte:
| Einstellung | Wirkung |
|---|---|
| Einzelwert | Der Pfad muss genau einen Wert treffen. Vorgabe. |
| Summe | Alle getroffenen Werte werden addiert. |
| Anzahl | Es wird gezählt, wie viele Werte getroffen werden. |
Der Pfad entscheidet mit, und Xchange schreibt ihn beim Umschalten selbst um:
OriginalPayload.lines[0].qty trifft die erste Position, OriginalPayload.lines[*].qty trifft
alle. Wählen Sie Summe oder Anzahl, wird aus [0] ein [*]; stellen Sie zurück auf
Einzelwert, wird wieder [0] daraus.
Daraus folgt der häufigste Fehler an dieser Stelle: Ein Pfad mit [*] und Einzelwert bricht
ab, sobald die Liste mehr als einen Eintrag hat – mehrere Treffer, aber nur Platz für einen. Die
erste Position bekommen Sie über den Pfad mit [0].
Summe und Anzahl liefern immer einen Wert, auch bei einer leeren Liste. Eine fehlende oder leere Liste ergibt die 0. Ein Ersatzwert auf dieser Zeile bleibt deshalb ungenutzt – für ihn ist das Feld gefüllt. Wenn Sie zwischen „null Stück“ und „keine Angabe“ unterscheiden müssen, tun Sie es über eine eigene Zeile mit Anzahl.
Zur Verfügung stehen genau Summe und Anzahl. Werte aus mehreren Zeilen aneinanderzuhängen – etwa zu einem Zielfeld, das eine Aufzählung aller Artikelnummern trägt – ist mit der Zuordnung nicht möglich.
Wie es weitergeht
- Soll ein einzelnes Zielfeld aus mehreren Werten entstehen, statt eine Liste aus einer Liste: Ein Zielfeld aus mehreren Quellwerten bilden.
- Soll ein Wert der Positionen übersetzt werden, etwa eine Einheit: Werte umwandeln und umschlüsseln.
- Steht ein Feld der Positionen nicht in der Auswahl: Ein Feld fehlt in der Zuordnung.
Siehe auch
- Routen – Zuordnung (Referenz) – alle Felder der Listeneinstellungen, der Filter und die Zusatzzeilen
- Manuelle Klärung (Referenz) – wo ein abgebrochener Vorgang landet
- Zuordnung (Grundkonzept) – warum eine Route Schritte hat und in welcher Reihenfolge sie schreibt