OXID Connect

Das Addon “OXID Connect” kann jederzeit mit wenigen Vorbereitungen einem bestehenden GREYHOUND-Vertrag hinzugebucht werden. Der GREYHOUND Server und die Clients installieren das Addon dann vollautomatisch.

Vorbereitung im OXID eShop

Das Addon “OXID Connect” benötigt ein zugehöriges Modul, um eine API bereit zu stellen, über die alle vom Addon benötigten Daten möglichst effizient aus dem OXID eShop abgerufen werden können. Für OXID eShop 6 wird das Modul über Composer installiert, für die Versionen 4 und 5 kann dieses Modul, wie auch das GREYHOUND Basismodul, im OXID eXchange heruntergeladen werden.

OXID eShop 6

Das GREYHOUND OXID Connect Modul für OXID eShop 6 wird über das Composer Kommando auf der Kommandozeile hinzugefügt:
composer require greyhound-software/greyhound-oxid6-connect:^2.0.0

Danach wird das hinzugefügte Modul installiert:
composer install --no-dev

Das Modul ist nun im Administrationsbereich des Shops unter “Erweiterungen” > “Module” in der Liste als “GREYHOUND OXID Connect Modul” zu finden. Das Modul muss nun aktiviert werden (im Tab “Stamm”). Im Tab “Einstell.” kann das Modul dann bei Bedarf konfiguriert werden. Hier finden sich auch der API Key und die API URL, die im weiteren Verlauf für die Einrichtung des GREYHOUND OXID Connect Addons in GREYHOUND benötigt werden.
Der API Key wird automatisch zufällig erzeugt, wenn das Modul aktiviert wird. Er kann nach Belieben geändert werden – der aktuelle API Key muss dann in den Addon Einstellungen in GREYHOUND hinterlegt werden. Die API URL wird automatisch ermittelt und gibt immer die URL an, unter der die Schnittstelle des Moduls erreichbar ist. Sie wird ebenfalls für die Einstellungen des GREYHOUND Addons benötigt.

Die Option “Unsichere Verbindung zulassen” wird nur benötigt, wenn das Shop-Frontend nicht über eine SSL-Verbindung erreichbar ist. Das Modul verweigert unsichere Verbindungen, da über die Schnittstelle Kunden- und Auftragsdaten übertragen werden.
Die Option “Daten der Subshops über die API des Hauptshops zur Verfügung stellen” kann aktiviert werden um in einem Shop mit mehreren Subshops die Daten der Subshops ebenfalls über die Schnittstelle des Haupt-Shops abrufbar zu machen. Auf diese Weise muss dann in GREYHOUND in den Addon Einstellungen nur eine Verbindung zum Hauptshop eingerichtet werden und nicht eine Verbindung pro Subshop.

OXID eShop 4 und 5

Für OXID eShop Version 4 und 5 wird das GREYHOUND OXID Connect Modul über OXID eXchange bezogen und im Shop installiert. Dieses Modul erfordert zusätzlich das GREYHOUND OXID Basismodul.

Das Basismodul wird im eXchange einmal für die Community Edition (CE) und einmal für die Professional und Enterprise Edition (PE/EE) angeboten. Beide Versionen sind identisch, OXID ermöglicht lediglich keine Einstellung für alle drei Systeme zugleich.

Das OXID Connect Modul muss nun im Administrationsbereich des Shops konfiguriert werden. Hier muss ein API Key erzeugt (oder festgelegt) werden. Die API URL und der API Key werden später in GREYHOUND für die Konfiguration des Addons benötigt und können aus den entsprechenden Textfeldern auf der Konfigurationsseite kopiert werden.

Das GREYHOUND Basismodul muss nicht zwingend konfiguriert werden, es stellt nur einige Funktionen im Shop bereit, auf die das OXID Connect Modul zurückgreift.

OXID Connect dem GREYHOUND Vertrag hinzubuchen

Das OXID Connect Addon kann über den GREYHOUND Kundenservice oder das Control Center zum Vertrag hinzugebucht werden und wird dann automatisch installiert, sobald der GREYHOUND Server neu startet oder ein Administrator die Funktion “Addons aktualisieren” verwendet. Die GREYHOUND Clients beziehen das Addon vom Server wenn sie sich das nächste Mal mit ihm verbinden.

  • Nach dem Login unter Verträge den Vertrag auswählen und bearbeiten:

  • Unter den Vertragsinhalten auf Produkte ändern klicken:

  • Das gewünschte Addon hinzubuchen:

  • Änderungen mit Weiter bestätigen:

  • Änderungen überprüfen und übernehmen:

Wichtig: Kunden im Eigenbetrieb müssen die Verwendung des gebuchten Addons zusätzlich im GREYHOUND Admin aktivieren (-> Anleitung siehe hier).

OXID Connect in GREYHOUND einrichten

Nach der Installation des Addons sollte der Administrator im Client unter Einstellungen > Erweiterungen die Benutzergruppen festlegen, die auf die “OXID Connect”-Erweiterung zugreifen dürfen.

Verbindungseinstellungen

Im Client kann unter “Erweiterungen > OXID Connect – Einstellungen“ das Addon konfiguriert werden. Durch einen Klick auf das grüne Icon unten links legt man wie folgt eine neue Verbindung an:

  • Neben einer optionalen Bezeichnung müssen hier die API URL und der API Key des OXID eShops eingetragen werden. Diese können in der Konfigurationsseite des OXID Connect Moduls im OXID eShop eingesehen und kopiert werden.
  • Standardmäßig wird das SSL-Zertifikat, das bei OXID hinterlegt ist, durch das GREYHOUND Connect Addon validiert, also auf Gültigkeit geprüft. Bei Bedarf kann die Validierung des SSL Zertifikats abgeschaltet werden.
  • Falls die Verbindung zum OXID Shop über einen Proxy-Server hergestellt wird, ist in dem entsprechenden Feld der Hostname / die IP und der Port einzutragen, also z. B. so: 127.0.0.1:8888.
  • In dem Feld Empfänger können die E-Mailadressen eingetragen werden, bei denen das Addon in pixi nach Auftragsdaten suchen soll. Sollen alle Mails durchsucht werden, ist der Platzhalter “*” einzugeben. Das Feld darf nicht leer bleiben!

Es ist sinnvoll, bei den Empfängern nur die E-Mail-Adressen einzutragen, an die pixi-Kunden auch Nachrichten schreiben. Beispielsweise “kundenservice@meinefirma.de”. So vermeidet man, dass das Addon auch bei eingehenden Lieferanten-E-Mails an einkauf@meinefirma.de unnötig nach Kundendaten sucht.

Mehrere Mandanten / Shops anbinden

Selbstverständlich lassen sich auch mehrere Mandaten / Shops mit dem Addon anbinden. Dazu legt man einfach im Reiter „Verbindung“ über das grüne Plus-Icon unten links eine neue, weitere Verbindung an und trägt die Daten des zusätzlichen Shops entsprechend ein:

Tipp
Vor allem bei der Anbindung mehrere Mandaten bzw. Shops ist es sinnvoll, dem Addon zu sagen, bei welchen Empfänger-Mail-Adressen er überhaupt nach Auftragsdaten suchen soll. Denn wenn der Kunde bei Mustershop A gekauft hat, braucht das Addon nicht unnötig bei Mustershop B nach Auftragsdaten zu suchen.
Bei welchen Mail-Adressen das Addon im Drittsystem suchen soll, das steuert man über das Feld „Empfänger“: Hier sollte man die die E-Mail-Adresse(n) einzutragen, an die Shop- und Verkaufsplattform-Kunden auch Nachrichten schreiben. Beispielsweise „kundenservice@mustershop-A.de“. So sucht das Addon nur bei eingehenden Nachrichten, die an diese Adresse gingen nach Daten, nicht aber bei eingehenden Nachrichten an den zweiten Mandanten (Mustershop B) oder bei Lieferanten-E-Mails, die an „einkauf@ mustershop-A.de“ gesendet wurden. Das wirkt sich positiv auf die Performance aus.

Globale Einstellungen

  • Präfix für Vorgangsnummern: Um eingehende Nachrichten zum gleichen pixi-Auftrag automatisch zu einem Vorgang zusammen zu fassen, kann diese Funktion hier aktiviert und das gewünschte Präfix ausgewählt werden.
  • Vorgangsnummern automatisch zuordnen: Wenn diese Option aktiviert ist, werden die Vorgangsnummern von Nachrichten, zu denen ein OXID-Auftrag gefunden wird, automatisch dem Auftrag zugeordnet. Ist die Option deaktiviert, so kann diese Zuordnung nur manuell erfolgen.
  • Feld für Kunden-ID: Sofern bereits ein benutzerdefiniertes Feld in GREYHOUND angelegt wurde, kann dieses Feld hier ausgewählt werden. Alternativ kann dieses hier angelegt werden. Sofern keine automatische Kontaktsynchronisierung in GREYHOUND eingerichtet wurde, sind hier keine Angaben notwendig.
  • Schnellzugriff für Textbausteine: Hier kann der Basistextbaustein ausgewählt werden, welcher direkt über das Addon erreichbar sein soll. Damit entfällt das Wechseln des Karteireiters zwischen Addon und Textbausteinen.
  • CC an Auftrags-E-Mail: Hakt man diese Option an, wird beim Antworten über das Addon eine Kopie (CC) der Nachricht an die E-Mail-Adresse des Kunden gesendet, welche im Auftrag steht.

Erweiterte Einstellungen

  • Administration
    Normalerweise ist der Einstellungsdialog des Addons nur für Administratoren sichtbar und bearbeitbar. Dies hängt von der Berechtigung “Erweiterungen bearbeiten” im Profil ab. Wenn die Option “Einstellung für alle Benutzer bearbeitbar machen” im OXID-Addon aktiviert wird, dann können alle Benutzer, also auch solche, die dieses Profilrecht nicht besitzen, die Einstellungen des Addons sehen und bearbeiten. Die Option sollte unter normalen Umständen nicht aktiviert werden, weil sie die normale Berechtigungsstruktur aushebelt.
  • Timeout: Bei besonders großen OXID-Systemen kann es notwendig sein, den Timeout-Wert anzuheben, damit Verbindungsdaten angezeigt werden.
  • Debug-Modus: Zu besseren Fehleranalyse kann der Debugmodus aktiviert werden. Damit werden dann detailliertere Informationen bei Problemen angezeigt. Zusätzlich wird damit eine Option aktiv, mit der Informationen direkt an den GREYHOUND Kundenservice gesendet werden können.

Variablen für Textbausteine

Beim Beantworten oder Verfassen einer Nachricht über die Buttons in der Seitenleiste stellt das OXID-Addon einige Variablen bereit, die im Text der Nachricht oder in eingefügten Textbausteinen ersetzt werden. Der Inhalt der Variablen hängt von den Auftrags- und Kundendaten ab, die das Addon ermittelt hat. Welche Addon-Variablen für Textbausteine zur Verfügung stehen, variiert je nach Addon. Eine Liste aller aus OXID zur Verfügung stehenden Werte ist im GREYHOUND Client zu finden:

  1. Über Erweiterungen den Eintrag des Addons mit der Ergänzung – Hilfe auswählen.
  2. Der damit geöffnete Dialog zeigt – neben kurzen Hinweisen und Links – im Wesentlichen eine umfassende Liste aller vom Addon bereitgestellten Werte an. Links findet sich jeweils die genaue Bezeichnung der Variable, wie sie auch in Textbausteinen verwendet werden kann. Recht steht zu jeder Variable eine kurze Beschreibung.

Tipp
Wenn man einen Variablennamen einfach anklickt, wird automatisch der gesamte Name ausgewählt. Man kann ihn nun mit STRG + C in die Zwischenablage kopieren und mit STRG + V von dort in einer Nachricht oder einem Textbaustein direkt wieder einfügen.

NEU: Artikel-IDs & Artikeldetails als Addon-Variable bereitstellen

OXID arbeitet mit Artikelnummern bzw. Artikel-IDs. Um mit diesen auch in GREYHOUND “weiterarbeiten” zu können, stehen diese ab Version 2.0.45 build 248 des OXID Connect Addons ebenfalls als Variablen bereit. Neu hinzugekommen sind damit folgende Addon-Variablen:

[$Order.ItemIDs] – Artikel-ID(s) der Bestellung
[$Order.ItemIDsSearch] – Artikel-ID-Suchindex. Dies ist eine dediziert für die Suche in GREYHOUND angelegte Variable. Sie ermöglicht es, in GREYHOUND nach Artikel-IDs suchen und alle Elemente finden zu können, in denen es um den entsprechenden Artikel geht. Eine Eingabe von “,A4711,” in das Suchfeld bei GREYHOUND zeigt beispielsweise alle Elemente an, in denen es um den Artikel mit der ID A4711 geht. Die Kommas direkt vor und hinter einer Artikel-ID (ohne Leerzeichen!), dienen dazu, dass man bei der Suche nach “,A1001,” nur Elemente findet, wo es um den Artikel A1001 geht – nicht aber um Artikel A100123. Möchte man nach mehreren Artikel-IDs gleichzeitig suchen, ist die Syntax wie folgt: “,A123,A234,A456,”
[$Order.ItemNumbers] – Artikelnummer(n) der Bestellung
[$Order.ItemNumbersSearch] – Artikelnummern-Suchindex. Dies ist eine dediziert für die Suche in GREYHOUND angelegte Variable. Sie ermöglicht es, in GREYHOUND nach Artikelnummern suchen und alle Elemente finden zu können, in denen es um den entsprechenden Artikel geht. Eine Eingabe von “,A4711,” in das Suchfeld bei GREYHOUND zeigt beispielsweise alle Elemente an, in denen es um den Artikel mit der Artikelnummer A4711 geht. Die Kommas direkt vor und hinter einer Artikelnummer (ohne Leerzeichen!), dienen dazu, dass man bei der Suche nach “,A1001,” nur Elemente findet, wo es um den Artikel A1001 geht – nicht aber um Artikel A100123. Möchte man nach mehreren Artikelnummern gleichzeitig suchen, ist die Syntax wie folgt: “,A123,A234,A456,”

Diese Werte können in GREYHOUND in Textbausteinen verwendet werden oder in benutzerdefinierte Felder übernommen werden.

Zusätzlich werden die wesentlichen Daten aus den einzelnen Auftragspositionen, also z. B. Artikelnummer und -name, bereitgestellt. Diese Möglichkeit ist limitiert auf die ersten 10 Artikel des Auftrags. Für diese stehen zudem folgende Variablen zur Verwendung in Textbausteinen oder an anderer Stelle zur Verfügung:

[$Order.Item1.ID] – Artikel-ID von Artikel 1 des Auftrags
[$Order.Item1.Number] – Artikelnummer von Artikel 1 des Auftrags
[$Order.Item1.Name] – Artikelname von Artikel 1 des Auftrags
[$Order.Item1.Quantity]– Artikelanzahl von Artikel 1 des Auftrags
[$Order.Item1.Price] – Einzelpreis von Artikel 1 des Auftrags
[$Order.Item1.PriceInfo.Value] – Preisinformation – Wert von Artikel 1 des Auftrags
[$Order.Item1.PriceInfo.Currency] – Preisinformation – Währung von Artikel 1 des Auftrags
[$Order.Item1.TotalPrice] – Gesamtpreis von Artikel 1 des Auftrags
[$Order.Item1.TotalPriceInfo.Value] – Preisinformation – Gesamtwert von Artikel 1 des Auftrags
[$Order.Item1.TotalPriceInfo.Currency] – Preisinformation- Währung des Gesamtpreises von Artikel 1 des Auftrags

All die oben stehenden Variablen beziehen sich auf Order.Item1 der Bestellung, also das technisch gesehen erste Produkt des Auftrags. Tauscht man die 1 durch eine 2 aus, werden die Werte für Produkt 2 ausgegeben usw. – das geht bis Artikel 10 des Auftrags, also: [$Order.Item10.ID].