OXID ERP Interface – Einfache Anbindung von Drittsystemen an den Onlineshop
OXID ERP Interface – Einfache Anbindung von Drittsystemen an den Onlineshop
Moderne E-Commerce Systeme bestehen in der Regel aus verschiedenen, einzelnen Systemen, die miteinander verknüpft sind. Der reibungslose Datenaustausch zwischen diesen Systemen ist maßgeblich für die Qualität sowie Aktualität der Daten und damit für den wirtschaftlichen Erfolg des Onlineshops.
Die OXID Plattform verfügt über eine Schnittstelle zur Anbindung von Drittsystemen wie ERP, PIM, etc. an den OXID eShop. Es handelt sich hierbei um ein standardisiertes Modul, welches im OXID eShop installiert wird. Im folgenden Beitrag werden die Themen Kompatibilität und die grundlegende Funktionalität der Schnittstelle anhand von Praxisbeispielen beschrieben.
Kompatibilität
Für die ERP SOAP/CSV-Schnittstelle gibt es zwei Versionsnummern: eine für die Version des Moduls und eine für die Version des Datenbanklayers. Die Modul-Versionsnummer ändert sich, wenn etwas an den Dateien des Moduls geändert wird (beispielsweise bei neuen Features oder Bugfixes). Die Datenbanklayer-Version definiert, welche Datenbankstruktur verwendet wird.
Bei Aktualisierungen der Shopsoftware und Änderungen an der Datenbankstruktur des Shops werden beide Versionsnummern angepasst. So ist es bei jeder Aktualisierung der Software erforderlich, zu prüfen, ob es Änderungen in der Datenbank gab, die bei der Kommunikation zwischen den einzelnen Systemen von Bedeutung sind. Wird eine aktuelle Version der ERP-Schnittstelle in einer älteren Shop-Version eingesetzt, sollte beim Erstellen der Session auf die Versionsnummer der Datenbanklayer geachtet werden (siehe Array: oxERPBase::$_aDbLayer2ShopDbVersions [modules/erp/oxerpbase.php]). Damit das ERP-Modul ohne Einschränkungen mit den Daten des Shops arbeiten kann, ist es wichtig, die korrekte Datenbanklayer-Versionsnummer anzugeben.
Ein Beispiel: Es gibt keine WSDL-Datei (Web Services Description Language) mit der Versionsnummer 2.12.0, da sich die Anzahl der verfügbaren OXERP* Methoden nicht geändert hat. Lediglich das Feld oxpicgenerated wurde aus der Tabelle oxarticles entfernt.
Die WSDL-Dateien bieten ausschließlich eine Liste aller verfügbaren Methoden (sowie die Parameter der Methode), um die Shop-Funktionalität zur Speicherung von Daten korrekt ansprechen zu können. Welche Felder in einer Tabelle verfügbar sind, wird in den oxerptype_* Klassen im Verzeichnis modules/erp/objects/ definiert. So wurde bei der Datenbanklayer Version 2.12.0 die Kompatibilität durch das Entfernen des Tabellenfeldes in dem Array oxERPType_Article::$_aFieldListVersions(modules/erp/objects/oxerptype_article.php) gesichert.
Ein Auszug des Arrays (Abbildung 1) oxERPType_Article::$_aFieldListVersions zeigt, dass das Feld oxpicgenerated ab der Datenbanklayer Version 11 entfernt wurde. Hat der Shopbetreiber eine Shop-Version installiert, die das Feld oxpicgenerated nicht mehr verwendet, muss mindestens die Datenbanklayer-Version 2.11.0 verwendet werden, damit das ERP-Modul die passende Datenbankstruktur anwenden kann. Nachfolgend zwei Beispiele, wann eine neue WSDL-Datei erstellt wird und wann sich der Datenbanklayer ändert.
Beispiel 1: Die Shop-Datenbank wird um eine Tabelle erweitert.
Folgen:
• Eine neue WSDL-Datei mit Methoden zur Manipulation der Daten der neuen Tabelle wird erstellt.
• Das entsprechende OXERPType-Objekt für die neue Tabelle wird erstellt.
• Die WSDL-Versionsnummer wird erhöht.
Beispiel 2: Ein Tabellenfeld wird umbenannt.
Folgen:
• Das entsprechende OXERPType-Objekt für die betroffene Tabelle wird erweitert.
• Die WSDL-Versionsnummer wird erhöht.
Aufgrund der oben genannten Funktionalität der Datenbanklayer-Versionsnummer ist das Modul prinzipiell abwärtskompatibel. Eine aktuelle Modulversion kann daher auch in einer älteren Shop-Version eingesetzt werden. Dies gilt allerdings nicht, wenn sich etwas am Shop-Framework geändert hat. Ein Beispiel ist die Implementierung der Datei bootstrap.php. Diese sorgt dafür, dass grundlegende Funktionen des Frameworks zur Verfügung stehen. Hierfür wurde die ERP-Schnittstelle so angepasst, dass die Datei eingebunden und das Shop Framework genutzt werden kann.
Wird also nichts Grundlegendes am Framework des Shops geändert, ist es auch nicht erforderlich, die Moduldateien der Schnittstelle zu aktualisieren. Bei neuen Features oder nach Bugfixes ist ein Update der Moduldateien erforderlich, was eine Erhöhung der Modulversion zur Folge hat.
Anders verhält es sich mit der WSDL-Version. Diese war lange Zeit identisch mit der Modul-Versionsnummer. Ist jedoch ein Shop der Version 5.0.0 und das ERP-Modul 2.14.0 installiert, muss beim Aufrufen des ERP-Moduls darauf geachtet werden, dass die der Shop Datenbank entsprechende WSDL-Version verwendet wird. In diesem Fall ist es die Version 2.13.0. So erkennt die ERP-Schnittstelle die Datenbankstruktur des Shops und kann die Eingaben den entsprechenden Feldern zuordnen.
Funktionsweise
Die Schnittstelle arbeitet eng mit dem Shop-Framework zusammen. Das hat die Vorteile, dass nicht bei jedem Shop-Update eine Aktualisierung der Schnittstelle nötig ist und individuelle Anpassungen nicht aufwändig getestet werden müssen.
Als Beispiel folgendes Szenario:
Eine Enterprise Edition mit aktivierter Hochlastoption ist im Einsatz. Für eine noch bessere Performance wird ein Varnish Cache vor den Frontend Server geschaltet. So werden die Widgets des Shops im Cache vorgehalten, damit ein schneller Abruf der benötigen Seiten möglich ist.
Wird ein Artikel bestellt, verringert sich der Lagerbestand. Da diese Prozesse innerhalb des Shop-Frameworks abgearbeitet werden können, sendet der Shop eine Information an den Proxy Cache, dass das Widget mit dem Lagerbestand des Artikels ungültig ist. Entsprechend invalidiert Varnish die Cache-Datei und fordert beim nächsten Aufruf des Artikels das Widget mit dem aktualisierten Lagerbestand neu an.
Darüber hinaus kann der Lagerbestand auch durch einen externen Dienst, sei es durch eine telefonische Bestellung oder durch einen Einkauf in einem Laden verändert werden. Wird der Lagerbestand direkt in der Datenbank des Shops manipuliert, kann der Shop jedoch nicht registrieren, dass möglicherweise ein Event ausgelöst werden muss. In diesem Beispiel wird der betroffene Part im Cache nicht invalidiert und auch nicht aktualisiert. So kann die Verfügbarkeit des betroffenen Artikels nicht vom Shop neu berechnet werden und es erfolgt auch keine automatische Benachrichtigung an den Shop-Administrator über kritische Lagerbestände.
Import (OXERPSet* Methoden)
Wird der Lagerbestand über die Schnittstelle gepflegt, hat dies zur Folge, dass die Informationen nicht direkt in die Datenbank geschrieben, sondern über das Shop-Objekt oxArticle aktualisiert werden. Der Vorteil dabei ist, dass das Shop-Framework in Relation stehende Events auslöst.
So wird beim Speichern bzw. Ändern eines Artikels automatisch die Methode oxArticle::onChange() aufgerufen. Wird diese Methode von weiteren implementierten Modulen überladen, werden auch diese ausgeführt.
Die Schnittstelle selbst besitzt keine eigene Logik, um Objekte zu schreiben. Manipulationen erfolgen über das Shop-Framework, mit dem Vorteil, dass alle registrierten Events beim Speichern eines Objekts abgearbeitet werden. Das Format der Daten wird über die Verwendung des Objekts OXERPType definiert.
Der Aufbau, um den Titel des Artikels mit der ID (Beispiel) 09602cddb5af0aba745293d08ae6bcf6 auf „Foobar“ zu ändern wird in Abbildung 3 dargestellt.
Hinweis: Benutzer mit Shop-Administrationsrechten können nicht über die ERP-Schnittstelle ausgelesen werden. Definiert wird dies in der Methode oxERPType_User::getSQL(). Dort wird im SQL-Befehl explizit auf nicht administrative Benutzer gefiltert, in dem der Wert der Spalte oxrights auf „user“ beschränkt wird.
Dies gilt jedoch nicht für Benutzer, die lediglich der Gruppe Shop-Admin (Id: oxidadmin) hinzugefügt wurden.
Export (OXERPGet* Methoden)
Im Gegenzug zum Import liest die ERP-Schnittstelle die angeforderten Datensätze aus der Datenbank ohne das eigentliche Model des Shops zu verwenden. Diese Art des Auslesens der Informationen von Objekten, kann auf diese Weise durchgeführt werden, da beim Lesen kein Event gestartet wird. Events werden ausschließlich beim Speichern (ob ein neuer Datensatz erstellt oder ein bereits bestehender aktualisiert wird, ist hierbei irrelevant) oder beim Löschen ausgelöst. Als Beispiel wird das Model Order herangezogen.
Ruft man die ERP SOAP-Schnittstellenmethode OXERPGetOrders auf, wird Modul-intern die Methode oxERPSoap::_ExportOrder() ausgeführt. Diese wiederum verwendet das oxERPType Objekt oxERPType_Order, das alle Datenbankfelder der Tabelle oxorder kennt und entsprechend ausliest. Wenn gegebenenfalls weitere Abhängigkeiten beachtet werden müssen, um das aktuelle Objekt zu vervollständigen, geschieht dies in den jeweiligen oxERPSoap::_Export*() Methoden.
Alle oxERPType_* Objekte besitzen das Klassenattribut $_aFieldListVersions. In diesem Array befindet sich ein Abbild der zugehörigen Datenbanktabelle des Models. Da sich die Felder in Ihrer Anzahl und Benennung ändern können, befindet sich im Array eine komplette Auflistung aller bisherigen Tabellenversionen. Das passende Datenbankschema wird über den HTTP GET Parameter „version“ definiert.
Anhand der nun bekannten Tabellenfelder kann ein SQL-Query erstellt werden, welcher die benötigten Informationen ausliest.
Speziell im Fall der Tabelle oxorder werden weitere Verknüpfungen zu anderen Tabellen durch das Shop-Framework berücksichtigt. Daher gilt: Die grundsätzliche Information des jeweiligen Getters wird durch das direkte Auslesen des kompletten Datensatzes (ermöglicht durch die oxErpType Objekte) bereitgestellt, ohne das Model des Shops zu verwenden. Jedoch können bei Verknüpfungen zu anderen Tabellen entsprechende Models hinzugezogen werden.
Handling von Sprachen
Die OXID ERP Schnittstelle ist darauf ausgelegt, mit Multimandanten und allen angelegten Sprachen zu arbeiten. Beim Erstellen einer Session über die ERP-Schnittstelle muss eine gültige Sprach- und Shop-ID angegeben werden. Auswirkungen hat dies jedoch nur beim Lesen von Objekten. Je nach angegebener Sprache wird die Übersetzung aus der Datenbank gelesen. Möchte man Informationen mehrsprachig für ein Objekt hinterlegen, kann dies über einen einzigen Request erfolgen. Hierfür müssen lediglich die Datenbankfelder definiert (oxtitle_0, oxtitle_1, …) und die jeweilige Übersetzung als Wert angegeben werden.