Zuordnung
Der Zuordnung-Reiter des Routeneditors legt fest, wie die Felder einer internen Nachricht auf die Zielstruktur abgebildet werden. Eine Route kann aus mehreren Schritten bestehen, jeder Schritt erzeugt ein eigenes Zieldokument mit eigenen Zuordnungen. Änderungen werden im Entwurf gesammelt und mit dessen Aktivierung wirksam.
Bei einer Exportroute bildet die Zuordnung Felder der internen Nachricht auf ein Zieldokument für das externe System ab; bei einer Importroute auf ein SAP-Business-One-Objekt. Der Editor selbst ist in beiden Fällen identisch aufgebaut – es unterscheiden sich nur die Datenquelle für die Zielfeld-Auswahl (SAP-Business-One-Feldstruktur bei Import, Referenzdaten bei Export) und einzelne Beschriftungen.
Berechtigungen
Die Seite ist sichtbar, sobald Ihnen die Berechtigung Konfiguration – Routen (Lesen oder Voll) zugewiesen ist. Ohne die Stufe Voll ist der Routeneditor nur lesbar: Sie sehen die Konfiguration, können sie aber nicht ändern.
Schritte
Die Leiste Schritte über dem Arbeitsbereich zeigt alle Schritte der Route als Kacheln, zwischen aufeinanderfolgenden Schritten steht ein Pfeil-Symbol. Ein Klick auf eine Kachel wählt den Schritt aus und zeigt seine Zuordnungen darunter; per Ziehen einer Kachel ändern Sie die Reihenfolge. Die Leiste lässt sich zuklappen – der frei werdende Platz geht an den Arbeitsbereich darunter. Sind noch keine Schritte konfiguriert, zeigt sie den Hinweis „Keine Schritte konfiguriert“.
In der Kopfzeile der Leiste stehen der Name des ausgewählten Schritts, das Kennzeichen Schreiben für dessen Modus und die Aktionen:
| Aktion | Wirkung |
|---|---|
| Schritteinstellungen | Öffnet die Schritteinstellungen des ausgewählten Schritts. |
| Testbereich | Blendet den Testbereich neben den Zuordnungen ein oder aus. Die Schaltfläche zeigt ihn nur an – gestartet wird der Test dort. |
| Schritt hinzufügen | Legt einen weiteren Schritt an. |
| Schritt löschen | Löscht den ausgewählten Schritt nach einer Rückfrage, die seinen Namen nennt. Die Aktion steht im Überlaufmenü (⋯), damit sie nicht versehentlich getroffen wird. Eine Route braucht mindestens einen Schritt; beim letzten meldet eine Kurznachricht „Der letzte Schritt kann nicht gelöscht werden“. |
Schritteinstellungen
Über die Schaltfläche Schritteinstellungen öffnen Sie die Einstellungen des ausgewählten Schritts – ein Dialog mit den Reitern Allgemein, Bedingung, Zielstruktur und Antwortstruktur. Der Reiter Zielstruktur steht nur bei einem Schritt im Modus Schreiben zur Verfügung.
Allgemein
| Feld | Hinweis |
|---|---|
| Name | Anzeigename des Schritts. Bei nur einem Schritt in der Route bleibt das Feld leer und die Route selbst liefert die Anzeige. |
| Kennung | Technischer Bezeichner des Schritts, schreibgeschützt. |
| Hauptschritt | Markiert den Schritt, der das Hauptobjekt der Route schreibt. Nur bei Routen mit mehreren Schritten sichtbar; bei genau einem Schritt entfällt die Auswahl. |
| Zielpfad | Der Zielpfad, an den das Zieldokument dieses Schritts übergeben wird – z. B. ein API-Pfad beim Export oder ein Service-Layer-Pfad beim Import. Bietet Vorschläge an. Enthält der Pfad den Platzhalter {{key}} – etwa artikel/{{key}} –, setzt Xchange dort den Schlüssel aus der markierten Zuordnungszeile ein. Das setzt die Schlüsselquelle Markierte Zuordnungszeile voraus: Ein Schlüssel aus der Antwort des Zielsystems liegt beim Zusammenstellen des Aufrufs noch nicht vor. Bei einer Exportroute steht rechts neben dem Feld die Schaltfläche Schlüsselplatzhalter einfügen (Schlüsselsymbol); sie setzt {{key}} an der Cursorposition ein. |
| Schlüssel | Nur bei einer Importroute, am schreibenden Hauptschritt: der Schlüssel des SAP-Business-One-Datensatzes, den der Schritt anlegt. Xchange leitet ihn aus der Feldstruktur der Entität ab, die der Zielpfad benennt, und hält den angelegten Datensatz darüber fest. Mehrteilige Schlüssel stehen kommagetrennt in einem Feld. Das Feld ist schreibgeschützt – es gibt nichts zu wählen; bleibt es leer, ließ sich zum Zielpfad noch keine Entität auflösen. |
Bei einer Exportroute stehen darunter die Felder zur Schlüsselermittlung. Sie legen fest, woher der Schlüssel des Datensatzes stammt, den der Schritt im Zielsystem anlegt. Xchange hält diesen Schlüssel fest, damit spätere Läufe denselben Datensatz treffen. Die Felder erscheinen nur am Hauptschritt und nur, wenn dieser schreibt.
| Feld | Hinweis |
|---|---|
| Schlüsselquelle | Markierte Zuordnungszeile – Xchange vergibt den Schlüssel selbst; Sie markieren die Zuordnungszeile, die ihn liefert (siehe Symbole). Antwort des Zielsystems – das Zielsystem vergibt ihn und meldet ihn zurück. Kein externer Schlüssel – das Zielsystem führt keinen Schlüssel, den Xchange festhalten kann. Eine Angabe ist erforderlich. |
| Entnehmen aus | Nur bei Antwort des Zielsystems: ob der Schlüssel aus den Antwortdaten oder aus einer Kopfzeile der Antwort gelesen wird. Kopfzeile steht nur zur Auswahl, wenn die Anbindung des Zielsystems Kopfzeilen zurückliefert. |
| Pfad in den Antwortdaten | Nur bei Antwortdaten: der Pfad zum Schlüsselfeld in der Antwort, z. B. $.id. |
| Name der Kopfzeile | Nur bei Kopfzeile: der Name der Kopfzeile, z. B. Location. Eine Angabe ist erforderlich. |
| Wert übernehmen | Nur bei Kopfzeile: Vollständig übernimmt den Wert der Kopfzeile unverändert, Letzter Pfadabschnitt nur den Teil hinter dem letzten Schrägstrich – aus https://shop.example.com/artikel/4711 also 4711. |
Bei einer Importroute entfallen diese Felder – dort ist nichts zu wählen, und an ihrer Stelle steht das schreibgeschützte Feld Schlüssel unter dem Zielpfad.
Bedingung
Legt fest, ob der Schritt ausgeführt wird. Ohne Bedingung läuft der Schritt immer. Ist eine Bedingung gesetzt, prüft Xchange sie vor der Ausführung des Schritts gegen die interne Nachricht; trifft sie nicht zu, wird der Schritt übersprungen – ohne Fehler, die Verarbeitung fährt mit dem nächsten Schritt fort. Bedingungen prüfen ausschließlich Werte der internen Nachricht; nachzuladende Werte stellen Sie zuvor über Zusatzdaten bereit.
Über Bedingung hinzufügen legen Sie eine Zeile mit Feld, Operator und Wert an. Bei mehreren Zeilen bestimmt die Verknüpfung, ob alle Bedingungen zutreffen müssen (UND) oder eine genügt (ODER).
Zielstruktur
Nur bei einem Schritt im Modus Schreiben. Zeigt die Referenzdaten, aus denen sich Zuordnungen automatisch ableiten lassen (siehe Referenzdaten unten) – bei Importrouten ein Strukturskelett aus der SAP-Business-One-Feldstruktur, bei Exportrouten eine eingefügte Beispielnachricht des Zielsystems. Über Zuordnungen generieren (nur auf diesem Reiter sichtbar) übernimmt Xchange die enthaltenen Felder als neue Zuordnungszeilen.
Antwortstruktur
Eine Beispielantwort dieses Schritts als JSON. Daraus leitet Xchange ab, welche Felder ein Folgeschritt unter Ergebnisse vorheriger Schritte auswählen kann – ohne hinterlegte Antwortstruktur steht dort nichts zur Auswahl. Anders als bei der Zielstruktur gibt es kein Strukturskelett zum Vorbefüllen: Sie fügen die Antwort ein oder übernehmen sie über Aus letztem Lauf übernehmen aus dem letzten erfolgreichen Lauf dieses Schritts. Liegt noch keiner vor, meldet das eine Kurznachricht. Am letzten Schritt der Route weist ein Hinweis darauf hin, dass seine Antwortdaten keinen Folgeschritt mehr speisen.
Zuordnungen
Die Tabelle Zuordnungen zeigt alle Zuordnungen des ausgewählten Schritts – einfache Zeilen ebenso wie Listen – in ihrer Verarbeitungsreihenfolge. Über Zeile hinzufügen legen Sie eine neue einfache Zuordnung an, über Liste hinzufügen eine neue Listenzuordnung (siehe Listen unten); per Ziehen einer Zeile ändern Sie die Reihenfolge. Alle Zuordnungen löschen im Überlaufmenü (⋯) der Tabelle leert den Schritt vollständig – einschließlich aller Listen samt ihren Einträgen, nach einer Rückfrage.
Beim Übernehmen eines Zielfelds ordnet Xchange die Zeile selbst ein: Zuordnungen mit gemeinsamem Pfadanfang – etwa lines.itemCode und lines.quantity – stehen zusammen, die Gruppen in der Reihenfolge ihres ersten Auftretens. Eine neu angelegte Zeile wandert damit vom Ende an ihren Platz, sobald ihr Zielfeld feststeht. Haben Sie es über die Auswahlliste gewählt, folgt der Fokus der Zeile an die neue Position; bei einer getippten Eingabe bleibt der Fokus stehen, und die Zeile wird nur sichtbar gescrollt.
| Spalte | Hinweis |
|---|---|
| (Nummer) | Die laufende Nummer der Zeile in der Verarbeitungsreihenfolge. Die Spalte trägt keine Überschrift. |
| Zielfeld | Der Zielfeldpfad, z. B. data.sku. Bei einer Liste der Zielpfad der Liste, bei einer Zusatzzeile ihr Bezeichner. |
| Quelle | Der Quellpfad bzw. die Konstante. Die Schaltfläche links im Feld schaltet zwischen Feldverweis und konstantem Wert um; ihr Symbol zeigt, was gerade gilt. Bei einer der Transformationen Verketten, Aktueller UTC-Zeitstempel, Neue GUID, Objekttyp, Umgebungskennung oder Bedingte Wertermittlung steht hier stattdessen eine Kurzfassung – bei Verketten die Bestandteile, bei Objekttyp der nachgeschlagene Entitätstyp, bei Bedingte Wertermittlung die Anzahl der Fälle, sonst der Transformationsname; bei einer Liste ihr Quellpfad. |
Über das Zahnrad-Symbol einer einfachen Zuordnung öffnen Sie ihre Feldeigenschaften, über das Entfernen-Symbol löschen Sie die Zeile. Eine Listenzuordnung oder Zusatzzeile öffnet stattdessen per Klick auf die Zeile ihre eigene Detailansicht.
Neben den Feldern der Quelldaten bietet die Auswahlliste bei Exportrouten das Feld Ereignisart an. Es nennt den Anlass des Laufs – Anlage, Änderung oder Löschung – und lässt sich wie jedes andere Quellfeld zuordnen oder in einer Bedingung prüfen. Damit meldet eine Route einen herausgefallenen Datensatz auch an ein Zielsystem, das keine Löschung kennt: die Zuordnung setzt bei Löschung ein Kennzeichen, statt den Datensatz zu entfernen. Bei Importrouten steht das Feld nicht zur Verfügung – dort ist die Ereignisart immer Änderung.
Listenwerte
Zeigt ein Quellpfad auf ein Element einer Liste – erkennbar an der eckigen Klammer im Pfad, etwa OriginalPayload.DocumentLines[0].LineTotal –, erscheint neben der Quelle die Auswahl Listenwerte:
- Einzelwert – der Pfad zeigt auf genau ein Element, und dessen Wert wird übernommen.
- Summe – alle passenden Elemente werden addiert. Xchange stellt den Pfad dabei selbst auf alle Elemente um: aus
[0]wird[*]. - Anzahl – die passenden Elemente werden gezählt. Ergebnis ist eine Ganzzahl; der Pfad wird ebenso auf alle Elemente umgestellt.
Die Summe eignet sich für Beträge, die SAP Business One über mehrere Belegzeilen führt – etwa die Summe aller Zeilenbeträge eines Belegs. Trifft der Pfad auf kein Element, ist das Ergebnis 0; ein nicht numerisches Element bricht den Vorgang mit einem Fehler ab.
Die Anzahl zählt Elemente, nicht Werte: ein leeres Element zählt mit, ein nicht numerisches ebenso. Trifft der Pfad auf kein Element, ist die Anzahl 0. Soll nur ein Teil der Elemente gezählt werden, schränken Sie den Pfad selbst ein – etwa OriginalPayload.DocumentLines[?@.ItemCode!=''] für alle Zeilen mit Artikelnummer. Zusammen mit der Transformation Addieren ergibt die Anzahl die Nummer einer Zeile, die Xchange selbst einfügt.
Die Auswahl steht überall dort zur Verfügung, wo Sie ein Quellfeld wählen: an der Zuordnung selbst, am Ersatzwert des Leerverhaltens, an den Bestandteilen von Verketten, an den Werten der Bedingten Wertermittlung und am Argument einer arithmetischen Transformation. In einer Bedingung und in einem Filter wird sie nicht angeboten.
Symbole
Rechts in der Zeile zeigen Symbole aktive Eigenschaften der Zuordnung; das Schlüssel-Symbol ist zugleich eine Schaltfläche:
| Symbol | Bedeutung |
|---|---|
| Zahnrad (Stufe) | Eine Transformation ist aktiv – die Kurzinfo nennt ihren Namen. |
| „Tt“ (Textformatierung) | Bei leerem Quellwert ist Ersatzwert verwenden oder Null schreiben konfiguriert. |
| Fahne | Technisches Pflichtfeld. |
| Mehrfachauswahl | Fachliches Pflichtfeld. |
| Trichter | An einer Liste: ein Filter ist aktiv. An einer einfachen Zuordnung: eine Bedingung ist aktiv. Die Kurzinfo nennt beides. |
| Kette (nur Listen) | Diese Liste wird mit mindestens einer weiteren Liste in dieselbe Zielliste zusammengeführt (siehe Mehrere Listen zusammenführen). |
| Schlüssel | Diese Zeile liefert den Schlüssel des Datensatzes im Zielsystem. Ein Klick setzt die Markierung, ein weiterer nimmt sie zurück; je Schritt trägt höchstens eine Zeile die Markierung. Das Symbol erscheint nur, wenn in den Schritteinstellungen bereits die Schlüsselquelle Markierte Zuordnungszeile gewählt ist – die Quelle wird also dort gewählt, nicht hier, und das Markieren ändert sie nicht. Weitere Voraussetzung: der Hauptschritt einer Exportroute, und dieser schreibt. Ohne Bearbeitungsrechte ist nur die markierte Zeile am Symbol zu erkennen. |
Feldeigenschaften
Das Zahnrad-Symbol einer einfachen Zuordnung öffnet ihre Details in einem Dialog mit drei Reitern:
- Transformation – die Transformation selbst und das Leerverhalten.
- Bedingung – trifft sie nicht zu, wird die ganze Zuordnung übersprungen (siehe unten).
- Optionen – Pflichtfeld und Änderungserkennung.
Ein farbiger Punkt am Reiter markiert, welcher Reiter einen Fehler enthält. Mit Zurück / Weiter im Fuß des Dialogs blättern Sie ohne Schließen zur vorigen bzw. nächsten Zeile.
Transformation
Wandelt den Quellwert vor der Übernahme um. Eine Zuordnung kann mehrere Transformationen nacheinander anwenden: Die Kette steht als Leiste über dem Formular, das Ergebnis einer Transformation ist die Eingabe der nächsten.
- Hinzufügen – das Plus-Symbol am Ende der Leiste hängt eine Transformation an und öffnet gleich die Auswahlliste.
- Bearbeiten – ein Klick auf eine Transformation in der Leiste zeigt ihre Einstellungen im Formular darunter.
- Umsortieren – ziehen Sie eine Transformation an eine andere Stelle der Leiste.
- Entfernen – das Entfernen-Symbol löscht die ausgewählte Transformation nach einer Rückfrage.
Ein farbiger Punkt an einer Transformation markiert einen Fehler in deren Einstellungen. Ist die Kette leer, weist die Leiste mit „Keine Transformation – der Quellwert wird unverändert übernommen“ darauf hin.
| Transformation | Kategorie | Zusätzliche Felder |
|---|---|---|
| Aktueller UTC-Zeitstempel | Wert erzeugen | – |
| Neue GUID | Wert erzeugen | – |
| In Wahrheitswert umwandeln | Typkonvertierung | – |
| In Ganzzahl umwandeln | Typkonvertierung | – |
| In Dezimalzahl umwandeln | Typkonvertierung | Dezimaltrennzeichen |
| Herausschneiden | Zeichenkette | Ab Zeichen (inkl.), Anzahl Zeichen |
| Aufteilen | Zeichenkette | Trennzeichen, Teil |
| Verketten | Zeichenkette | Bestandteile – siehe unten |
| Ersetzen | Zeichenkette | Suchtext, Ersatztext – siehe unten |
| Umschließende Leerzeichen entfernen | Zeichenkette | – |
| In Großbuchstaben umwandeln | Zeichenkette | – |
| In Kleinbuchstaben umwandeln | Zeichenkette | – |
| Wertetabellen | Nachschlagen | Wertetabelle |
| Bedingte Wertermittlung | Nachschlagen | Fälle – siehe unten |
| Objekttyp | Wert erzeugen | Objekt |
| Umgebungskennung | Wert erzeugen | – |
| Addieren | Arithmetik | Summand – siehe unten |
| Dividieren | Arithmetik | Divisor – siehe unten |
| Multiplizieren | Arithmetik | Faktor – siehe unten |
| Subtrahieren | Arithmetik | Subtrahend – siehe unten |
| Datum formatieren | Datum | Format – siehe unten |
| In Datum umwandeln | Datum | Quellformat |
| In Datum/Uhrzeit umwandeln | Datum | Quellformat |
Sechs Transformationen erzeugen ihren Wert selbst, statt einen Quellwert umzuwandeln – Aktueller UTC-Zeitstempel, Neue GUID, Verketten, Objekttyp, Umgebungskennung und Bedingte Wertermittlung. Sie sind nur an erster Stelle der Kette zulässig und werden an den weiteren Stellen nicht angeboten.
Verketten reiht beliebig viele Bestandteile zu einer Zeichenkette; jeder Bestandteil ist entweder ein Feld (Quellfeld-Auswahl) oder fester Text. Über Bestandteil hinzufügen fügen Sie weitere Bestandteile an; ob ein Bestandteil ein Feld oder fester Text ist, stellen Sie am Bestandteil selbst um. Über das Entfernen-Symbol eines Bestandteils löschen Sie ihn.
Ersetzen tauscht jedes Vorkommen des Suchtexts gegen den Ersatztext. Gesucht wird wortwörtlich und unter Beachtung der Groß-/Kleinschreibung; der Suchtext ist keine Suchmaske, ein Punkt bleibt also ein Punkt. Bleibt der Ersatztext leer, wird der Suchtext ersatzlos entfernt – so lassen sich Trennzeichen aus einer Nummer waschen, etwa 12-345/678 über zwei aufeinanderfolgende Ersetzen-Schritte zu 12345678.
Addieren addiert einen Summanden zum Quellwert – entweder eine feste Konstante oder der Wert eines anderen Feldes, wahlweise über eine Wertetabelle nachgeschlagen. Zusammen mit der Listenwert-Auswahl Anzahl (siehe Listenwerte) ergibt das die Nummer einer Zeile, die Xchange selbst einfügt: Anzahl der vorhandenen Zeilen plus 1.
Dividieren teilt den Quellwert durch einen Divisor, der entweder eine feste Konstante oder der Wert eines anderen Feldes ist – im letzteren Fall wahlweise über eine Wertetabelle nachgeschlagen.
Multiplizieren multipliziert den Quellwert mit einem Faktor – wie beim Divisor entweder eine feste Konstante oder der Wert eines anderen Feldes, wahlweise über eine Wertetabelle nachgeschlagen. Ein Faktor von -1 kehrt das Vorzeichen um, etwa für eine Rabattzeile, deren Preis negativ übergeben werden muss.
Subtrahieren zieht einen Subtrahenden vom Quellwert ab – wie beim Faktor entweder eine feste Konstante oder der Wert eines anderen Feldes, wahlweise über eine Wertetabelle nachgeschlagen. Die Reihenfolge ist dabei fest: gerechnet wird Quellwert − Subtrahend.
Eine feste Konstante geben Sie mit den Trennzeichen Ihrer Firma ein – Xchange übernimmt Dezimal- und Tausendertrennzeichen aus den allgemeinen Einstellungen von SAP Business One. Beim Verlassen des Feldes wird der Wert in diese Form gebracht; ein mitgetipptes Tausendertrennzeichen entfällt in der Anzeige. Bei Komma als Dezimaltrennzeichen wird aus 0.32 also 0,32 und aus 1.500,3 wird 1500,3. Nicht zu verwechseln mit dem Dezimaltrennzeichen von In Dezimalzahl umwandeln – das beschreibt die Quelldaten des angebundenen Systems, nicht Ihre Eingabe.
Datum formatieren bietet eine Auswahl gängiger Formate (ISO-Datum, Datum deutsch, Jahr, Monat, Tag, Kalenderwoche, Jahr + KW) sowie Benutzerdefiniert… mit einem freien Muster (z. B. dd.MM.yyyy).
Bedingte Wertermittlung ermittelt den Zielwert über eine Liste von Fällen: Jeder Fall besteht aus einer Bedingung (Wenn) und einem Wert (Dann verwende); der erste zutreffende Fall liefert den Wert. Trifft kein Fall zu, greift Sonst.
Wertetabellen und Objekttyp schlagen den Quellwert in einer separaten Tabelle nach – siehe Wertetabellen (Referenz) für die Pflege der Einträge.
Umgebungskennung liefert die Umgebung Ihrer Lizenz als Wert – Test, Live oder, im Entwicklungsmodus, Development. Sie brauchen dafür kein Quellfeld und keine weiteren Einstellungen. So pflegen Sie die Kennung nicht als Konstante in mehreren Routen: nach einem Lizenzwechsel von Test auf Produktiv ändert sich der Wert von selbst. Lässt sich der Lizenzzustand nicht zuverlässig bestimmen, schlägt die Zuordnung fehl – die Umgebung wird nicht geraten.
Leerverhalten
Legt fest, was geschieht, wenn der Quellwert leer ist:
| Option | Wirkung |
|---|---|
| Nicht übertragen | Das Zielfeld wird bei leerem Quellwert ausgelassen. |
| Ersatzwert verwenden | Ein fester Ersatzwert wird stattdessen übernommen; zusätzlich wählbar ist sein Werttyp (Text, Zahl, Wahrheitswert). |
| Null schreiben | Das Zielfeld wird explizit auf null gesetzt. |
Bedingung
Eine optionale Bedingung wirkt als Schalter für die ganze Zeile: Trifft sie nicht zu, wird die Zuordnung übersprungen und das Zielfeld erscheint gar nicht in der Ziel-Nachricht – es wird weder ein Wert noch null geschrieben. Über Bedingung hinzufügen legen Sie eine Zeile mit Feld, Operator und Wert an; bei mehreren Zeilen bestimmt die Verknüpfung (UND / ODER), ob alle zutreffen müssen oder eine genügt. Ohne Bedingung wird die Zuordnung immer angewendet. Geprüft wird ausschließlich gegen die interne Nachricht.
Welche Operatoren angeboten werden, richtet sich nach dem Typ des gewählten Feldes:
| Feldtyp | Operatoren |
|---|---|
| Text | ist gleich, ist ungleich, enthält, enthält nicht, beginnt mit, beginnt nicht mit, ist leer, ist nicht leer |
| Zahl, Datum | ist gleich, ist ungleich, ist größer als, ist größer oder gleich, ist kleiner als, ist kleiner oder gleich, ist leer, ist nicht leer |
| Wahrheitswert, Auswahlwert | ist gleich, ist ungleich, ist leer, ist nicht leer |
| Pfad, der eine Liste auswählt | enthält Wert, ist leer, ist nicht leer |
enthält nicht und beginnt nicht mit schließen leere Werte ein: Fehlt der Wert im Quellfeld, ist die Bedingung erfüllt – ein fehlender Wert beginnt nicht mit dem gesuchten Text. Die Zuordnung wird dann also angewendet.
Felder ohne hinterlegten Typ – Zusatzdaten, Ergebnisse vorheriger Schritte und eine eingefügte Testnachricht – behalten die volle Auswahl. Wechseln Sie das Feld und der bisherige Operator gehört nicht mehr dazu, stellt Xchange auf den ersten angebotenen um.
Der Wert ist entweder ein fester Wert oder ein Verweis auf ein anderes Feld: Die Schaltfläche links im Wertfeld schaltet zwischen beidem um, wie in der Spalte Quelle der Zuordnungen. So vergleichen Sie zwei Felder miteinander, statt gegen eine Konstante zu prüfen. Bei ist leer und ist nicht leer entfällt das Wertfeld ganz.
Auf einem Datumsfeld lässt sich als Vergleichswert statt eines festen Datums der aktuelle Tag wählen: Das Kalender-Symbol im Wertfeld setzt „Heute“, ein erneuter Klick nimmt es zurück. Verglichen wird tagesgenau, die Uhrzeit bleibt außer Betracht. Angeboten wird „Heute“ bei den Vergleichsoperatoren, nicht bei enthält, enthält nicht, beginnt mit, beginnt nicht mit, enthält Wert, ist leer und ist nicht leer.
Beides gilt für jede Bedingung im Reiter Zuordnung – Zeilenbedingung, Schrittbedingung, Zusatzzeilen-Bedingung und das Wenn eines Falls der Bedingten Wertermittlung; der Listenfilter folgt derselben Typregel, bietet aber kein enthält Wert. „Heute“ steht ebenso in den Datenfiltern der Quelldaten und im Ereignisauslöser zur Verfügung; dort wird der Tag je Lauf beziehungsweise je Ereignis neu bestimmt.
Pflichtfeld
Zwei unabhängige Kennzeichen, die eine Zuordnung als Pflichtfeld markieren: Technisch und Fachlich. Bei Importrouten ist Technisch aus der SAP-Business-One-Feldstruktur abgeleitet und dort nicht änderbar.
Änderungserkennung
Das Kontrollkästchen Von der Änderungserkennung ausschließen nimmt die Zuordnung aus der Berechnung der Änderungserkennung heraus – Änderungen an diesem Feld allein lösen dann keine erneute Übertragung aus.
Sind alle Zuordnungen eines Schritts ausgeschlossen, weist ein Warnhinweis über der Zuordnungsliste darauf hin, dass Änderungen dann nie erkannt werden.
Listen
Eine Listenzuordnung füllt eine Zielliste – üblicherweise aus einer Quell-Liste, also einem Array in der internen Nachricht (die weiteren Möglichkeiten stehen unter Befüllung). Ein Klick auf die Zeile öffnet ihr Detail: die Zuordnungen-Tabelle der Listenelemente – technisch dieselbe Zeilenvorlage wie die Zuordnungen-Tabelle des Schritts, per Ziehen ebenfalls umsortierbar und mit demselben Einordnen beim Übernehmen eines Zielfelds. Ein Elementfeld wird aus den Elementfeldern der Quell-Liste, aus der übergeordneten Zeile oder aus dem Hauptdatensatz gewählt – siehe Quellfelder eines Elements.
Über der Tabelle steht ein Pfad aus dem Namen des Schritts und dem Zielpfad der Liste. Die vorangehenden Abschnitte sind anklickbar und führen dorthin zurück – aus dem Listendetail also zurück zu den Zuordnungen des Schritts. Rechts daneben liegen die Aktionen der Liste:
| Aktion | Wirkung |
|---|---|
| Listeneinstellungen | Öffnet den Dialog mit den Reitern Allgemein und Filter – die einmalige Listeneinrichtung und der Elementfilter liegen nicht in der Tabelle. Der Dialog lässt sich auch ohne Bearbeitungsrechte öffnen und lesen. |
| Liste löschen | Löscht die Liste mit allen ihren Zuordnungen, nach einer Rückfrage, die den Zielpfad nennt. Die Aktion steht im Überlaufmenü (⋯). |
Listeneinstellungen
Im Dialog Listeneinstellungen enthält der Reiter Allgemein die Grundeinstellungen der Liste:
| Feld | Hinweis |
|---|---|
| Zielliste | Der Zielpfad der Liste, z. B. data.item.salesPrices. |
| Befüllung | Woraus die Elemente entstehen – Aus Quell-Liste, Feste Zeilen oder Aus Textwert, siehe unten. |
| Quell-Liste | Bei Aus Quell-Liste: der Array-Pfad in der internen Nachricht, z. B. Enrichments.PriceList[*]. Der Pfad darf in eine Liste innerhalb einer Liste führen, z. B. OriginalPayload.DocumentLines[*].BatchNumbers[*]. |
| Quellfeld | Bei Aus Textwert: das Textfeld, dessen Inhalt aufgeteilt wird, z. B. OriginalPayload.packageIdentifier. |
| Trennzeichen | Bei Aus Textwert: das Zeichen, an dem der Text getrennt wird, z. B. |. |
| Pflichtfeld | Technisch / Fachlich – wie bei einfachen Zuordnungen. |
| Leerverhalten | Nicht übertragen, Null schreiben oder Leere Liste schreiben. |
Befüllung
Die Befüllung entscheidet, woraus die Elemente der Zielliste entstehen – und damit, welche der Felder oben überhaupt sichtbar sind:
- Aus Quell-Liste – die Elemente stammen aus einem Array der internen Nachricht, gewählt in Quell-Liste. Woraus ein Elementfeld zugeordnet wird, steht unter Quellfelder eines Elements.
- Feste Zeilen – die Liste hat keine Quelle; sie enthält ausschließlich fest eingefügte Zeilen. Der Reiter Filter entfällt. Da es ohne Quell-Liste auch keine Elementfelder gibt, steht im Listendetail nur eine Schaltfläche Zeile hinzufügen, und sie legt eine feste Zeile an – nicht die Zuordnung eines Elementfelds.
- Aus Textwert – ein einzelnes Textfeld (Quellfeld) wird am Trennzeichen zerlegt, und jeder Bestandteil wird ein Element: aus
4711|4712|4713entstehen drei Elemente. Das Trennzeichen gilt wörtlich, es ist nichts zu maskieren. Leere Bestandteile werden übersprungen, umgebende Leerzeichen entfernt. Ein Bestandteil hat keine Elementfelder – in der Zuordnung eines Elementfelds steht er als Wert des Elements zur Verfügung, und der Elementfilter prüft ebenfalls gegen diesen Wert.
Beim Wechsel der Befüllung fragt Xchange vorher nach und nennt, was dabei entfernt wird: Einstellungen, welche die neue Befüllung nicht kennt – etwa die Quell-Liste beim Wechsel zu Aus Textwert – werden geleert. Die Zuordnungen selbst bleiben erhalten. Eine Quelle, welche die neue Befüllung nicht ausdrücken kann, wird dabei ebenfalls geleert und in der Prüfung anschließend als fehlende Quelle gemeldet.
Quellfelder eines Elements
Die Feldauswahl im Listendetail führt die Quellfelder eines Elements in Gruppen – von innen nach außen, in der Reihenfolge, in der sie ineinanderliegen:
| Gruppe | Inhalt |
|---|---|
| Elementfelder | Die Felder des Elements selbst. Bei Befüllung Aus Textwert steht hier stattdessen der Wert des Elements. |
| Übergeordnete Zeile | Die Felder der Zeile, in der die Quell-Liste liegt. Erscheint nur bei Befüllung Aus Quell-Liste und nur, wenn diese Liste in einer anderen Liste liegt. |
| Hauptdatensatz | Die Felder des einlaufenden Datensatzes. |
Die Gruppe Übergeordnete Zeile zeigt die Zeile unmittelbar darüber, nicht die gesamte Kette. Bei einer Liste innerhalb einer Liste erreicht ein Element damit drei Ebenen: sich selbst, die Zeile darüber und den Hauptdatensatz.
Ein Feld, das eine Zusatzdaten-Abfrage auf Zeilenebene geladen hat, steht in der Gruppe der Zeile, an der es hängt – bei einer Abfrage auf die Quell-Liste also unter Elementfelder, bei einer Abfrage auf die Liste darüber unter Übergeordnete Zeile.
Filter
Der Reiter Filter desselben Dialogs filtert die Elemente der Quell-Liste, bevor sie zugeordnet werden – nur Elemente, auf die der Filter zutrifft, erscheinen in der Zielliste. Über die Schaltfläche UND / ODER legen Sie die Verknüpfung der Filterbedingungen fest, über Bedingung hinzufügen fügen Sie eine weitere hinzu (maximal 10). Ohne jede Bedingung zeigt die Tabelle den Hinweis „Keine Bedingung – alle Einträge werden übernommen“.
| Feld | Hinweis |
|---|---|
| Feld | Das Elementfeld, auf das die Bedingung geprüft wird. |
| Operator | Richtet sich nach dem Typ des Elementfelds – siehe Bedingung. enthält Wert steht hier nicht zur Verfügung. |
| Wert | Der Vergleichswert. Ausgeblendet bei den Operatoren ist leer / ist nicht leer. |
Mehrere Listen zusammenführen
Zeigen zwei oder mehr Listenzuordnungen dieselbe Zielliste, führt Xchange ihre Elemente automatisch in dieser gemeinsamen Zielliste zusammen – ohne weitere Konfiguration. Das Ketten-Symbol in der Zuordnungen-Tabelle markiert alle beteiligten Listen.
Zusatzzeilen
Innerhalb einer Liste lässt sich über Zusatzzeile hinzufügen ein fester Eintrag einfügen, der zusätzlich zu den aus der Quell-Liste abgeleiteten Elementen in der Zielliste erscheint – etwa ein Basispreis-Fallback neben den regulären Preisstufen. Ein Klick auf die Zusatzzeile öffnet ihre eigene Zuordnungen-Tabelle (Zeilen ebenfalls per Ziehen umsortierbar und beim Übernehmen eines Zielfelds selbst eingeordnet, über Zeile hinzufügen erweiterbar).
Bei der Befüllung Feste Zeilen heißen dieselben Einträge schlicht Zeilen: Die Schaltflächen lauten dort Zeile hinzufügen und Zeile löschen, eine neue Zeile heißt „Neue Zeile“. Es ist derselbe Eintragstyp – nur ohne Quell-Elemente, neben denen er stünde.
Wie bei einer Liste steht auch hier ein Pfad über der Tabelle, der zurück zur Liste und zum Schritt führt. Die Einstellungen der Zusatzzeile liegen hinter der Schaltfläche Zusatzzeilen-Einstellungen – ein Dialog mit den Reitern Allgemein (der Bezeichner der Zusatzzeile) und Bedingung; Zusatzzeile löschen bzw. Zeile löschen steht im Überlaufmenü (⋯) daneben. Über den Reiter Bedingung (eine der Bedingungs-Tabelle bei Listenfiltern sehr ähnliche Tabelle, mit Bedingung hinzufügen) lässt sich festlegen, dass die Zusatzzeile nur unter einer bestimmten Bedingung eingefügt wird – ohne Bedingung erscheint sie immer. Anders als beim Listenfilter steht hier zusätzlich enthält Wert zur Verfügung – angeboten, sobald der gewählte Pfad eine Liste auswählt, und dann anstelle der Vergleichsoperatoren (siehe Bedingung).
Referenzdaten
Statt jede Zuordnung einzeln anzulegen, lassen sich Referenzdaten einfügen, aus denen Xchange die enthaltenen Felder als Zuordnungsvorschläge ableitet (Reiter Zielstruktur der Schritteinstellungen, siehe oben). Über Zuordnungen generieren übernimmt Xchange neue Felder, Listen und Listenfelder als Zuordnungszeilen; bereits vorhandene Zuordnungen bleiben unverändert. Eine Rückmeldung nennt, wie viele Felder, Listen und Listenfelder neu erzeugt bzw. bereits vorhanden waren. Entstehen dabei viele Zeilen auf einmal, fragt Xchange vor dem Anlegen nach und nennt die Anzahl – ein Beleg aus SAP Business One bringt mehrere hundert Felder mit.
Testbereich
Über die Schaltfläche Testbereich in der Kopfzeile der Leiste Schritte blenden Sie einen Bereich zum Testen der Zuordnungen ein. Test ausführen wertet die aktuell konfigurierten Zuordnungen aus, ohne eine echte Nachricht zu verarbeiten und ohne etwas ins Zielsystem zu schreiben.
Testnachricht – das JSON, gegen das getestet wird. Sie fügen es ein oder laden es aus den Quelldaten; solange nichts hinterlegt ist, steht dort der Hinweis „Keine Testnachricht – hier einfügen oder laden über Quelldaten“, dessen Link direkt zu den Quelldaten führt. Auf Referenz zurücksetzen stellt die Beispielnachricht der Quelldaten wieder her – die Schaltfläche erscheint nur, wenn dort eine hinterlegt ist; Testnachricht leeren verwirft den Inhalt.
Über Ereignisart legen Sie fest, als welcher Anlass der Testlauf gelten soll; die Auswahl füllt das gleichnamige Quellfeld der Testnachricht. Ohne Auswahl bleibt das Feld leer, sodass eine Zuordnung darauf nichts liefert.
Antwort aus „…“ – für jeden vorangehenden Schritt, dessen Ergebnis dieser Schritt verwenden kann, steht darunter eine eigene Karte. Was Sie dort eintragen, tritt im Test an die Stelle der echten Antwort dieses Vorschritts – sonst fänden Zuordnungen auf Ergebnisse vorheriger Schritte nichts vor. Auf Antwortstruktur zurücksetzen übernimmt die im Vorschritt hinterlegte Antwortstruktur; ist dort noch keine gepflegt, weist die Karte darauf hin, und Sie geben die Antwort testweise direkt hier ein.
Das Ergebnis erscheint als JSON. Zwei Kennzeichen in seiner Kopfzeile ordnen es ein:
- Teilergebnis – siehe Feldfehler – mindestens eine Zuordnung ist fehlgeschlagen. Das Ergebnis enthält nur die übrigen Felder; an den betroffenen Zeilen ist markiert, welche Zuordnungen es getroffen hat.
- Veraltet – neu testen – die Zuordnungen wurden nach dem Test geändert, das angezeigte Ergebnis passt nicht mehr zur aktuellen Konfiguration. Dieses Kennzeichen verdrängt Teilergebnis.