Zum Hauptinhalt springen

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​

  1. 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.
  2. 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.
  3. 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.

  1. Im Feld Zielliste DocumentLines eintragen – die Liste im Zielsystem, die gefüllt werden soll.
  2. 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.
  3. Darunter erscheint das Feld Quell-Liste. Dort OriginalPayload.lines[*] auswählen.
  4. 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.
  5. Fertig wählen. Der Dialog schließt sich.

Die Quell-Liste der Bestellung wird der Belegpositionsliste zugeordnet.

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.

  1. Zeile hinzufügen wählen und in der Spalte Zielfeld ItemCode eintragen.
  2. In der Spalte Quelle das Feld auswählen. Die Auswahl ist nach Gruppen sortiert; unter Elementfelder steht sku.
  3. Dasselbe für die zweite Zeile: Zielfeld Quantity, Quelle qty aus der Gruppe Elementfelder.
  4. An der Zeile ItemCode das 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.

  1. Auf dem Reiter Zuordnung die Schaltfläche Testbereich wählen.
  2. Eine Beispielnachricht einfügen – am besten eine mit mehreren Einträgen in lines, weil sich erst daran zeigt, ob die Liste stimmt.
  3. 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 }]
  1. In der geöffneten Liste Listeneinstellungen wählen.
  2. Im Feld Verknüpfen über line_id auswählen.
  3. 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:

GruppeWas sie anbietet
Elementfelderdie Felder des einzelnen Eintrags – sku, qty
Übergeordnete Zeiledie Felder der Liste darüber, wo eine Liste in einer Liste steckt
Hauptdatensatzdie 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.

Eine Positionszeile greift auf die Felder des Eintrags und auf die des Kopfes zu.

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:

EinstellungWirkung
Nicht übertragenDie Liste fehlt in der Nachricht ganz. Vorgabe.
Null schreibenDie Liste geht mit einem ausdrücklichen Leerwert hinaus.
Leere Liste schreibenDie 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:

EinstellungWirkung
EinzelwertDer Pfad muss genau einen Wert treffen. Vorgabe.
SummeAlle getroffenen Werte werden addiert.
AnzahlEs 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​

Siehe auch​