Anbindungen
Eine Anbindung beschreibt, wie Xchange mit einem angebundenen System kommuniziert – über welche Adresse und mit welchen Zugangsdaten. Das kann ein externes System mit HTTP-Schnittstelle sein oder eine weitere SAP-Business-One-Mandantendatenbank. Jede Route basiert auf einer Anbindung. Änderungen an Anbindungen werden im Entwurf gesammelt und mit dessen Aktivierung wirksam.
Berechtigungen
Die Seite ist sichtbar, sobald Ihnen die Berechtigung Konfiguration – Anbindungen (Lesen oder Voll) zugewiesen ist. Neue Anbindung, das Bearbeiten der Felder, Verbindung testen und Löschen stehen nur mit derselben Berechtigung in der Stufe Voll zur Verfügung – ohne sie ist die Detailansicht nur lesbar.
Listenansicht
Die Listenansicht zeigt alle konfigurierten Anbindungen mit Typ und Basisadresse des externen Systems. Die Sortierung erfolgt alphabetisch nach Name.
Über die Suche grenzen Sie die Liste auf Name und Beschreibung ein. Wird eine Anbindung über ihre Beschreibung gefunden, zeigt die Zeile diese zusätzlich unter dem Namen – sonst bleibt die Beschreibung ausgeblendet. Der Suchbegriff steht in der Adresse der Seite: Sie können den Link als Lesezeichen ablegen oder weitergeben, ein Neuladen stellt die gefilterte Liste wieder her, und das Schließen der Detailansicht führt auf sie zurück.
Spalten
| Spalte | Inhalt |
|---|---|
| Name | Anzeigename der Anbindung. Klick auf eine Zeile öffnet die Detailansicht rechts. |
| Typ | Verbindungstyp: REST für externe Systeme mit HTTP-Schnittstelle oder SAP Business One für eine weitere Mandantendatenbank über deren Service Layer. |
| Basisadresse | Basisadresse des externen Systems. Alle Endpunktpfade der Routen werden relativ dazu aufgelöst. |
| Verwendung | Anzahl der Routen, die diese Anbindung verwenden. |
| Zuletzt geändert | Zeitpunkt der letzten Änderung der Anbindung. |
Ist eine Anbindung nicht aktiv, zeigt die Liste ein Statusabzeichen: Pausiert, wenn die Anbindung pausiert ist, oder Gesperrt, wenn Xchange sich nicht mehr anmelden kann (z. B. ungültige Zugangsdaten). Routen über eine pausierte oder gesperrte Anbindung werden nicht ausgeführt, bis der Zustand behoben ist.
Aktionen
Mit Neue Anbindung (oben rechts) öffnen Sie einen Dialog mit zwei Angaben: Name (Pflichtfeld, maximal 150 Zeichen) und Typ – zur Auswahl stehen REST und SAP Business One, und der Typ lässt sich nach der Anlage nicht mehr ändern. Anlegen erzeugt die Anbindung und öffnet direkt die Detailansicht zur weiteren Konfiguration.
Bearbeitet eine andere Person gerade eine Anbindung, erscheint in der Name-Spalte ein Stift-Symbol; eine Kurzinfo zeigt, wer aktuell arbeitet.
Detailansicht
Die Detailansicht gliedert sich in zwei Spalten: links die Formularabschnitte Allgemeine Angaben, Technische Konfiguration und Authentifizierung, die mit dem Verbindungstest abschließt; rechts Feldstruktur, Aufbau des Abrufergebnisses und Verwendung in Routen. Welche Felder und Bereiche erscheinen, hängt vom Verbindungstyp ab: bei Anbindungen vom Typ SAP Business One entfällt Aufbau des Abrufergebnisses, weil der Service Layer den Antwortumschlag festlegt.
Änderungen werden automatisch in den aktuellen Entwurf übernommen – der Zeitpunkt der letzten automatischen Speicherung steht in der Fußzeile. Liegen zu dieser Anbindung Meldungen aus der Entwurfsprüfung vor, steht dort zusätzlich eine Schaltfläche mit deren Anzahl: Ein Klick öffnet die Liste der Meldungen, ein Klick auf einen Eintrag springt zum betroffenen Feld.
Wird die Anbindung gerade von einer anderen Person bearbeitet, erscheint oben in der Detailansicht der Warnhinweis „Wird gerade von … bearbeitet – Ihre Änderungen könnten zu einem Konflikt führen“, mit dem Namen dieser Person anstelle der Auslassungspunkte.
Ist die Anbindung gesperrt, steht dort ebenfalls ein Warnhinweis mit dem Grund – abgelehnte Zugangsdaten oder Zugangsdaten, die sich nicht mehr entschlüsseln lassen. Solange die Sperre besteht, laufen keine Routen über diese Anbindung; hinterlegen Sie neue Zugangsdaten und heben Sie die Sperre mit einem erfolgreichen Verbindung testen auf.
Allgemeine Angaben
| Feld | Hinweis |
|---|---|
| Name | Anzeigename der Anbindung. Pflichtfeld, jederzeit änderbar, maximal 150 Zeichen. |
| Beschreibung | Freitext zur Einordnung der Anbindung, maximal 254 Zeichen. Optional. Die Suche in der Listenansicht berücksichtigt dieses Feld. |
| Typ | Verbindungstyp. Bei der Anlage festgelegt, danach nicht mehr änderbar. |
Technische Konfiguration
| Feld | Hinweis |
|---|---|
| Basisadresse | Basisadresse des externen Systems, ohne Pfad oder Parameter, z. B. https://api.beispiel.de/v2. Alle Endpunktpfade der Routen werden relativ dazu aufgelöst. Bei Anbindungen vom Typ SAP Business One tragen Sie hier die Adresse des Service Layer ein. Verwendet bereits eine andere Anbindung dieselbe Basisadresse, erscheint ein Warnhinweis mit deren Namen – die Anbindung lässt sich trotzdem speichern. |
Authentifizierung
Xchange unterstützt drei Methoden. Welche davon zur Auswahl stehen, bestimmt der Verbindungstyp: REST bietet die ersten beiden an, SAP Business One ausschließlich die dritte.
- Keine Authentifizierung – offene Verbindung ohne Zugangsdaten.
- OAuth 2.0 – Token-basierte Authentifizierung. Xchange holt sich selbstständig einen Zugriffstoken vom Token-Endpunkt des externen Systems und erneuert ihn vor Ablauf automatisch. Verwendet wird der Client-Credentials-Flow: Es gibt keine Benutzeranmeldung, der Token wird direkt zwischen Xchange und dem Autorisierungsserver ausgetauscht.
- Service-Layer-Anmeldung – Anmeldung am Service Layer einer SAP-Business-One-Mandantendatenbank mit Benutzername und Passwort. Xchange hält die Sitzung selbst offen und meldet sich bei Ablauf neu an.
| Feld | Hinweis |
|---|---|
| Authentifizierungstyp | Keine Authentifizierung, OAuth 2.0 oder Service-Layer-Anmeldung, je nach Verbindungstyp. |
| Token-Endpunkt | URL, unter der Xchange den Zugriffstoken anfordert, z. B. https://idp.example.com/oauth/token. Pflicht bei OAuth 2.0. |
| Client-ID | Client-Kennung, die der Anbieter für diese Integration ausgestellt hat. Pflicht bei OAuth 2.0. |
| Mandantendatenbank | Name der SAP-Business-One-Mandantendatenbank, an der sich Xchange anmeldet, z. B. SBODEMODE. Pflicht bei der Service-Layer-Anmeldung. Groß- und Kleinschreibung werden unterschieden. |
| Benutzername | Benutzer, mit dem sich Xchange an dieser Mandantendatenbank anmeldet. Pflicht bei der Service-Layer-Anmeldung. |
| Client-Secret / Passwort | Zugehöriges Secret – bei OAuth 2.0 das Client-Secret, bei der Service-Layer-Anmeldung das Passwort des Benutzers. Wird verschlüsselt gespeichert und nach dem ersten Speichern nicht mehr im Klartext angezeigt. Status Konfiguriert (grün) oder Nicht konfiguriert. |
Über Ersetzen neben dem Secret-Status lässt sich ein neues Secret hinterlegen: Xchange zeigt ein Eingabefeld, das Secret wird erst mit Speichern übernommen (aktiv, sobald etwas eingegeben ist) – Abbrechen verwirft die Eingabe und behält das bisherige Secret.
Zwei Angaben prüft die Entwurfsprüfung zusätzlich am Feld Mandantendatenbank, beide blockieren die Aktivierung:
- Die Mandantendatenbank, mit welcher der Xchange-Dienst selbst arbeitet, lässt sich nicht als Anbindung eintragen – sie ist ohnehin schon angebunden.
- Dieselbe Mandantendatenbank auf derselben Basisadresse darf nur einmal vorkommen. Gemeldet werden beide beteiligten Anbindungen, weil sich der Konflikt von jeder Seite auflösen lässt.
Verbindung testen
Verbindung testen schließt den Abschnitt Authentifizierung ab, weil der Test Basisadresse und Zugangsdaten zusammen prüft. Damit lässt sich jederzeit feststellen, ob Xchange das externe System erreicht und sich erfolgreich anmeldet – unabhängig davon, ob gerade ein Entwurf aktiv ist. Das Ergebnis und der Zeitpunkt des letzten Tests werden direkt darunter angezeigt.
Bei der Service-Layer-Anmeldung meldet sich Xchange für den Test tatsächlich an der angegebenen Mandantendatenbank an. Gelingt das, nennt das Ergebnis den Namen der Firma, die dort hinterlegt ist: Erfolgreich – Musterfirma GmbH. So sehen Sie unmittelbar, ob Sie die richtige Mandantendatenbank erwischt haben. Der Name bleibt am Ergebnis stehen, auch wenn Sie zwischenzeitlich woanders hin navigieren.
Vor dem Test speichert Xchange offene Änderungen. Fehlt eine Angabe, die der Test braucht – Basisadresse, Authentifizierungstyp und je nach Methode Token-Endpunkt, Client-ID, Mandantendatenbank, Benutzername oder Secret –, erscheint stattdessen ein kurzer Hinweis mit den betroffenen Feldern, und der Test läuft nicht.
Ein fehlgeschlagener Test blockiert weder das Speichern noch die Aktivierung; die Entwurfsprüfung meldet eine nie getestete oder zuletzt fehlgeschlagene Anbindung aber als Hinweis. Ein erfolgreicher Test räumt diesen Hinweis ab und hebt eine bestehende Sperre der Anbindung auf.
Feldstruktur
Den Bereich gibt es bei jeder Anbindung – eine Feldstruktur hat jeder Anbindungstyp. Unterschiedlich ist nur, woher sie kommt: Bei REST hinterlegen Sie, wo das externe System sein Datenmodell veröffentlicht; bei SAP Business One kennt Xchange das Datenmodell bereits und liest es beim Abruf direkt aus dem angebundenen System, Sie konfigurieren nichts. Xchange stellt die Felder des angebundenen Systems im Routen-Editor zur Auswahl, statt dass Sie sie aus einer Beispielnachricht übernehmen müssen.
Die beiden folgenden Felder erscheinen deshalb nur, wenn Sie das Datenmodell selbst hinterlegen:
| Feld | Hinweis |
|---|---|
| Quelle | Pfad zur Feldstruktur, relativ zur Basisadresse, z. B. _info/entity-schema.json. Maximal 254 Zeichen. |
| Format | Format, in dem das externe System sein Datenmodell veröffentlicht: Keine Feldstruktur oder Shopware-Feldstruktur (Version 6 und neuer). |
Beide Felder gehören zusammen: Entweder Sie füllen beide aus oder keines von beiden.
Mit Feldstruktur abrufen holt Xchange die Feldstruktur und meldet, wie viele Objekte sie enthält. Wie beim Verbindungstest werden offene Änderungen zuvor gespeichert; fehlt eine der Angaben oder ist die Basisadresse unvollständig, erscheint ein Hinweis statt des Abrufs. Ist die Feldstruktur nur vorübergehend nicht erreichbar, unterscheidet die Meldung das von einem dauerhaften Fehler in Quelle oder Format der Feldstruktur.
Der Abruf holt die Feldstruktur dabei immer frisch aus dem externen System, nie aus einem Zwischenspeicher. Er prüft dabei zugleich die Verbindung – und er ist der Weg, eine geänderte Feldstruktur zu übernehmen: Hat das externe System neue Felder bekommen, drücken Sie hier Feldstruktur abrufen, und die Feldauswahlen der Routen zeigen den neuen Stand. Für Felder aus SAP Business One ist dagegen Feldstruktur abrufen im Systemzustand zuständig.
Aufbau des Abrufergebnisses
Der Bereich beschreibt den Umschlag, in den das angebundene System seine Datensätze packt: wo in der Antwort die Datensätze stehen, wo das Lesezeichen für den nächsten Abruf steht, woran erkennbar ist, dass noch weitere Daten folgen – und unter welchem Namen dieses Lesezeichen beim nächsten Abruf zurückgeht. Die Feldstruktur beschreibt, was in einem Datensatz steht – dieser Bereich, was um die Datensätze herum steht. Er gilt für jede Route dieser Anbindung, weil er das Protokoll des angebundenen Systems beschreibt und nicht die Auswahl einer einzelnen Route. Bei Anbindungen vom Typ SAP Business One entfällt der Bereich: dort legt der Service Layer den Umschlag fest.
Die ersten drei Felder adressieren die Antwort, die hereinkommt; das letzte nennt einen Wert, der mit der nächsten Anfrage hinausgeht. In dieser Reihenfolge stehen sie auch im Formular.
| Feld | Hinweis |
|---|---|
| Datensätze | Wo in der Antwort die Liste der Datensätze steht, z. B. $.items. Leer bedeutet den Standard, der als Platzhalter im Feld steht. |
| Lesezeichen | Wo das System den Stand mitteilt, ab dem der nächste Abruf weiterliest, z. B. $.deltaToken. Leer bedeutet den Standard. |
| Hinweis auf weitere Daten | Wo das System meldet, dass noch weitere Datensätze folgen, z. B. $.hasMore. Hier gibt es keinen Standard: Bleibt das Feld leer, schickt das System keinen solchen Hinweis. Der Platzhalter ist deshalb als Beispiel gekennzeichnet. |
| Parameter beim Abruf | Unter welchem Namen Xchange diesen Stand beim nächsten Abruf mitschickt, z. B. token. Leer bedeutet den Standard. Maximal 50 Zeichen. |
Alle vier Felder sind optional. Eine Route dieser Anbindung ruft auch ohne sie inkrementell ab – dann gelten die Standardwerte.
Mit Beispielantwort einfügen (im Kopf des Bereichs) öffnen Sie einen Dialog, in den Sie eine echte Antwort des angebundenen Systems einfügen. Fertig liest sie ein und füllt damit die Vorschlagslisten der drei Pfad-Felder; ist der eingefügte Text kein gültiges JSON oder nur ein einzelner Wert, bleibt der Dialog mit einem Hinweis offen. Die Beispielantwort wird nicht gespeichert – sie ist ein Werkzeug zum Ausfüllen der Felder, keine Konfiguration.
Daraus entstehen zwei Vorschlagslisten und nicht eine gemeinsame. Datensätze zeigt die Listen der Antwort selbst – auswählbar, aber nicht aufklappbar, denn gesucht ist items und nicht items[0].email. Lesezeichen und Hinweis auf weitere Daten zeigen die Werte außerhalb dieser Listen: ein Lesezeichen steht nie in einem einzelnen Datensatz.
Eine Feldstruktur kann diese Pfade nicht liefern, weil sie den einzelnen Datensatz beschreibt und nicht den Umschlag. Solange keine Beispielantwort eingefügt ist, lassen sich die Vorschlagslisten trotzdem öffnen und nennen die beiden Wege: eine Beispielantwort einfügen oder den Pfad direkt eintragen.
Verwendung in Routen
Der Bereich listet alle Routen, die diese Anbindung verwenden – mit Richtungssymbol, Routennamen und der Objektart am rechten Rand. Ein Klick auf einen Eintrag öffnet die Route. Verwendet noch keine Route die Anbindung, steht dort Keine Verwendung.
Anbindung löschen
Eine Anbindung lässt sich nur löschen, wenn keine Route sie mehr verwendet. Ist sie noch in Gebrauch, öffnet Löschen statt der Bestätigung einen Warnhinweis mit der Anzahl referenzierender Routen – welche das sind, zeigt der Bereich Verwendung in Routen. Die Anbindung bleibt erhalten, bis die Referenzen entfernt sind.