Beiträge

OXID eShop ERP Integration

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.

MK_Pic2

Abb.2: Bsp. Paramter für die Versionskompatibilität

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.

XML3

Abb.3: XML Aufbau um den Titel eines bestehenden Artikels zu ändern.

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.

Autor:

Bild_MK_Blog_swMichael Keiluweit ist Fachinformatiker und arbeitet seit 2011 bei der OXID eSales AG im Bereich Support und Services. Er verfügt über umfangreiches Fachwissen und langjährige Erfahrung im Umgang mit der OXID Plattform sowie fundierte Kenntnisse in PHP, MySQL, Java, CSS, Git und OOP.

New article on PHPbuilder.com – PHP Module Programming with OXID eShop CE

Recently, a new technical tutorial was published on PHPbuilder.com: introducing module coding by using the OXID eShop framework.

Andreas Ziethen, an OXID Premium Solution Partner for many years and author of this article, starts by describing the installation process of OXID eShop on a server. The article continues with a basic description of the OXID eShop software architecture, namely its:

  • MVC implementation
  • template system
  • module interface

He furthermore provides helpful hands-on instructions on how to access the module APIs to tweak the built-in content management system of OXID eShop.

Concluding the article, Andreas states:

This simple example should illustrate that OXID offers a sophisticated framework for customizing every aspect of a merchant site.

Thank you Andreas for the good job!

Collaboration Platform for Developing OXID Extensions

We are happy to announce a web-based project management and collaboration platform for developers of open source extensions and more for OXID eShop.

The collaboration platform is located at http://dev.oxidforge.org and provides a lot of useful tools available to each extension development project:

  • Mailing Lists
  • Surveys
  • Forums
  • Task Management
  • SVN/CVS-Support
  • FTP-Support
  • Documentation Management

For developing OXID eShop, we already have such systems in place and won’t switch to the new collaboration platform. Instead, all the built-in features on the platform are intended to work solely for your specific project. You – as a project owner – can decide yourself which features to use or not.

I used the word „project“ here, because it could mean very different things. Of course, the tool was originally made for complete software projects (including their modules and extensions) but it works just as well for language and localization packs, themes, off-line tools, interfaces,  and other extensions and optional modules. Also, it would be a great place to find patches or hacks before the official release.

When creating a new project, after approval, you will receive two e-mails. The first contains some instructions, the second is your project’s mailing list subscription notification. Be aware that creation of a URL for your project page (such as http://myproject.dev.oxidforge.org) may take up to 24 hours to propagate through DNS (the Domain Name Service).

OXIDforge has now become a real collaboration platform. The clear advantage of this new functionality is it facilitates working in teams – work shared is work halved. Even if the developer of a module, for time or other reasons, cannot support his own module any longer, he could hand it over to another person from the community.

If you want  more visibility and awareness for your stable extension, you are welcome to upload it to the OXID eXchange application.

Please note that the collaboration platform is currently in beta. Should you encounter any problems, please file and issue.

As „collaboration platform“ obviously is much too long, we still search for a proper name for it like „dev-zone“. Do you have any suggestions? Please feel free to leave a comment, contact us via the dev-general mailing list or write to the forums.

OK, enough said. Feel free to register your project to start developing for OXID eShop on OXIDforge. The only criteria is that it must be under an Open Source license.

Let’s collaborate!

New extensions for OXID eShop available: OXID-to-Sugar Connector, Celebros and Template Sets

Over the last few days, some very interesting extensions have been introduced in OXID eXchange – the Marketplace for exchanging OXID eShop extensions. We would like to present a few of them to you:

The MyCRM OXID-to-Sugar Connector is a tool to integrate data gathered in your online store with SugarCRM (Customer Relationship Management software). The connector creates leads, contacts, accounts and opportunities in SugarCRM when a new client registers with your online store and places orders. As this interface is still in a beta stage, MyCRM requests your help as beta testers. Please feel free to download the OXID-to-Sugar Connector and share your experience.

Also, we are glad to announce new template sets on eXchange. If you prefer two columns to three, you might want to take a look at the pink, red or blue themes. These template sets are tableless, support mult-language use of the store and provide a simple banner rotation system on the index page.

Another very interesting extension is the Celebros interface. Celebros increases your conversion rate by providing sophisticated onsite search solutions for online stores. The interface is free and open source.

Opening OXID eXchange with introduction phase

Dear OXID shop owners, community developers and partners,

for some weeks, during the preview phase, many of you already had a look behind the curtains of OXID eXchange to test and get familiar with the platform. Many thanks at this point for your valueable feedback and your ideas, which we will use for some optimization and fine tuning! Please keep that great feedback coming!

For those, who didn’t yet participate during the preview phase, here are some words on our newest idea: OXID eXchange is a new platform where you can download or purchase modules, themes and language packs to extend core OXID eShop functionality. You can browse commercial and community extensions or add one yourself. Test it out at http://www.oxid-esales.com/en/exchange

No commission until June 30th 2009:
During the introduction phase will no provision be charged for revenues of your commercial extensions. Thereafter, the price list applies.

Looking forward to find your extensions on our OXID eXchange!

Kind regards
Andrea

 

Some hints how to add your own extensions

Enlargement of profile as extension provider
A provider profile has to be created one-time to add extensions. The profile is shown with all extensions offered by you.

Extension description
You have the possibility to describe your extension significantly and add image files e.g. screenshots. In addition every extension gets a product image that is shown on the list and in the detail view.

Multilingualism of OXID eXchange
Each extension is only available in one language version. This means that you have to edit and update only one dataset.
To do justice to the international community it is recommended to offer always an English description and further text blocks in other languages underneath if required.
The user interface of OXID eXchange is offered in English and German like the OXID website.

Extension variants
You have the possibility to add different variants of your extensions for the particular OXID eShop products (EE, PE, CE).
You may decide on the terms of use and terms of licence for your extensions in your own discretion but with regards to the OXID eSales GPL v3 FAQ (http://www.oxidesales.com/en/products/community-edition/gpl-v3-faq). The choice and contents of your terms of use and terms of licence lie solely and exclusively within you.
Furthermore extensions can be marked as stable, beta or alpha.

Purchase or download of extensions
The purchase or download of extensions is processed via OXID eXchange.
A ZIP file has to be provided for download of each version.
That ZIP file contains all necessary source code files as well as further help documents and your general terms and conditions or terms of licence for the extension.

Accounting and provisioning
The billing and the downstream debitor management and dunning will be processed comfortably via the platform by OXID eSales.
During the introduction phase will no provision be charged for revenues of your commercial extensions. Thereafter, the price list applies.
The credit is transferred to your bonus account, which has to be edited in your profile.

Customer reviews
The OXID users have the possibility to review all extensions one-time (5 star ranking) and write comments.