Its.connect/Dokumentation

Aus ITscope GmbH - Wissensbasis

Wechseln zu: Navigation, Suche

its.connect ist das Synonym für den generischen Konnektor zu externen (Shop-)Systemen. Die Dokumentation für die Version 1.4.0 ist für den Enbenutzer gedacht.

Inhaltsverzeichnis

1 Installation

Die Installation wird in der Regel immer durch ITscope oder einen authorisierten Partner durchgeführt. Dazu gehört die korrekte Einrichtung aller Skripte in dem Verzeichnis its.connect, welches unterhalb des Dokumentenverzeichnisses des Webservers (z.B. httpdocs/) angelegt wird.

Zum Einrichtungsprozess werden normalerweise auch alle weiteren Anpassungen unternommen, die zum korrekten Ausführen nötig sind. Zur Vollständigkeit werden diese Anpassungen hier nachfolgend noch einmal aufgelistet.

1.1 Verzeichnisse

Der ITscope Konnektor besteht aus der Kernsoftware (Core) und Modulen (Modules) für die jeweilen Zielsysteme. Grundlegend gibt es folgende Verzeichnisse:

  • /alterable, enthält alle veränderlichen Dateien welche Schreibrechte benötigen
  • /core, beinhaltet den Programmkern welcher geschützt* ist
  • /modules, hat ein oder mehrere Module für den Produktkern und ist geschützt*
  • /thirdparty, enthält alle Drittsoftware welche benötigt wird

(*) Die Quelltexte der PHP-Dateien werden mit IonCube bytecodiert und benötigen eine Lizenz.

1.1.1 Zugriffsrechte

Alle Verzeichnisse sollten das Zugriffsrecht 750 bekommen. Alle Dateien das Zugriffsrecht 640. Ausnahmen werden in der Beschreibung zu den Verzeichnissen erläutert.

1.1.2 Verzeichnis: /alterable

Dieser Ordner beinhaltet alle veränderlichen Dateien. Alle Ordner und Unterordner sollten das Recht 777 besitzen, um den Schreibzugriff zu ermöglichen.

  • /cache mit dem Unterverzeichnis /phpthumb und smarty
    Verzeichnis zum Zwischenspeichern von Dateien. Aktuell werden diese jedoch nicht verwendet.
  • /imports/full
    In diesen Ordner wird per FTP aus dem MarketViewer der Vollimport abgegelegt. Ohne das Vorhandensein dieser Importdatei, kann keine vollständige Synchronisierung stattfinden. Der Dateiname kann in der lokalen Konfiguration hinterlegt werden. Im Fall von Subshops wie bei der Shopware, müsse die Subshopdateien hier her ausgeliefert werden.
  • /imports/update
    In diesen Ordner wird per FTP aus dem MarketViewer das Update abgegelegt. Ohne das Vorhandensein dieser Datei, kann keine abgleichende Synchronisierung stattfinden. Der Dateiname kann in der lokalen Konfiguration hinterlegt werden.
  • /tmp
    Dieser Ordner muss auf dem Server Schreibrechte besitzen, vorzugsweise 777. In ihm werden die ausgelieferten CSV-Dateien entpackt und weiter verarbeitet. Weiterhin können hier auch Unterverzeichnisse während der Ausführung des Konnektors erstellt werden.
  • /logs
    Alle Log-Dateien, welche die Skripte erzeugen, werden hier abgelegt. its.connect packt diese Dateien mit Abruf der Synchronisation um Platz zu sparen. Die Archive werden unterhalb des Ordners in /logs/backup/days und /logs/backup/months abgelegt. Dieser Ordner muss für PHP Schreibrechte besitzen, vorzugsweise 777.

1.1.3 Verzeichnis: /core

  • /classes
    Enthält alle benötigten Klassen des Programmkerns. Dateirechte sollten hier für alle Dateien auf Lesen stehen, vorzugsweise 640.
  • /includes
    Dieser Ordner enthält die Konfigurationsdateien. Die Datei coreconfig.php wird als Bytecode ausgeliefert und enthält alle Stamminformationen für its.connect. Für den Kundenserver ist die zweite Datei localconfig-sample.php anzupassen, welche als Quelltext ausgeliefert wird. Die Datei ist anschließend in localconfig.php umzubennen.
  • /license
    Ordner in dem eine gültige Lizenz erwartet wird.
  • /media
    Der Ordner beinhaltet alle verwendeten Bilder. Das "no_image"-Bild, was angezeigt wird, wenn kein Produktbild vorhanden ist, liegt ebenfalls hier - und nicht in den entsprechenden Shopverzeichnissen. Der Ordner wird im Moment nur von dem Modul xt-commerce genutzt.
  • /templates
    Der Ordner wird aktuell noch nicht verwendet. Für neue Versionen von its.connect soll eine Ausgabe über eine Templateengine wie Smarty erfolgen.

1.1.4 Verzeichnis: /modules

  • /modules
    Enthält die Unterverzeichnisse für die einzusetzenden Module. Module werden in der Konfiguration festgelegt. Die Verzeichnisse der Module müssen exakt den gleichen Namen haben wie im Modul festgelegt. Weitere Informationen dazu sind den Modulen selbst zu entnehmen. Je nach Paket wird nur das benötigte Modul ausgeliefert - zum Beispiel wird das Modul für einen Konnektor zum xt:Commerce Shop im Ordner xt-commerce angelegt. Die Module haben die gleiche Ordnerstruktur wie das Kernprogramm. Jedes Modul bringt seinen eigenen Classloader mit.

1.1.5 Verzeichnis: /thirdparty

  • /thirdparty
    Alle jene Fremdprodukte, welche von its.connect benutzt werden, befinden sich in diesem Ordner. Die aktuelle Standardinstallation benötigt zum Beispiel die Pakete: AdoDBLite 1.42, dUnzip2, Snoopy 1.2.4. Die Verwendung wird in der Kernkonfiguration getroffen und ist für den Kunden unabänderlich.

1.2 Dateianpassungen

Nachdem alle Dateien hochgeladen wurden und die Verzeichnisrechte richtig gestetzt sind kann mit der Anpassung von individuellen Dateien begonnen werden.

Als erstes muss die /includes/localconfig.php angepasst werden. Hier sind Datenbankzugänge sowie kundenspezifische Einstellungen zu treffen. Dazu gehört auch der Dateiname für die aus dem MarketViewer generierten Dateien.

Weiterhin muss die Datei .htaccess und die Datei .htpasswd angepasst werden. Der Kunde sollte einen eigenen Zugang bekommen. Der ITscope Nutzer sollte immer gleich bleiben. Die Passwortzeile kann wahlweise mit einem Generator im Netz erzeugt werden oder über den Shellzugang mit dem Befehl htpasswd zur Datei .htpasswd hinzugefügt werden. Eine Anleitung ist der MAN-Page zu entnehmen.

1.3 Erstellen einer Lizenz

Die Lizenz wird mit IonCube angefertigt und benötigt die Adapter-Informationen vom Zielsystem, welche aus Domain(s), IP-Adresse(n) und MAC-Adresse(n) besteht. Zur automatisierten Erzeugung kann das Skript request_license.php genutzt werden. Wenn kein Parameter angegeben wird, erzeugt das Skript eine Textdatei zum Herunterladen. Alternativ dazu kann auch eine Emailadresse angegeben werden, zu der die Datei versandt werden soll. 

http://www.shop.de/its.connect/request_license.php
http://www.shop.de/its.connect/request_license.php?target=email@seite.de

Mit der erhaltenen Datei adapater-info.txt kann eine gültige Lizenzdatei license.txt generiert werden, welche in das Verzeichnis core/license kopiert werden muss. Wenn das IonCube-Modul korrekt installiert ist sollte nach Aufruf der URL zum its.connect-Verzeichnis eine Ausgabe in Form einer kleinen Seite erfolgen erfolgen. 

http://www.shop.de/its.connect/

2 Deinstallation

Alle eingeführten Änderungen können wieder rückgängig gemacht werden. Dies geschieht über das Skript uninstall.php. Ein Aufruf per URL kann dabei wie folgt aussehen: 

http://www.shop.de/its.connect/uninstall.php
Achtung: Alle Produkte und Kategorien bleiben dabei erhalten - auch ITscope Produkte! Es wird lediglich die Struktur der Tabellen zurückgesetzt. Eine Zuordnung von ITscope und Nicht-ITscope-Produkten ist danach nicht mehr möglich! Bei einigen Modulen kann es bei einer Neuinstallation erforderlich sein, den kompletten Produktstamm sowie zugehörige Kategorieeinträge zu löschen und erneut einzuspielen. Eine genauere Beschreibung ist der Dokumentation des eingesetzten Moduls zu entnehmen.

3 Synchronisierung

Damit die im MarketViewer über das Produktportfolio definierten Artikel und zugehörige Informationen im Shop bereit stehen, müssen diese zunächst im MarketViewer generiert werden. Die hier definierte Auslieferung legt die generierten Dateien im its.connect Verzeichnis ab auf dem angegebenem FTP-Server ab. Für den Vollimport ist das Verzeichnis import_full und für das Update das Verzeichnis import_update vorgesehen. Aktuell werden die generierten Dateien zwingend erwartet.

Its.connect marketviewer generierung.png

Für die korrekte Funktionsweise des ITscope Konnektors, müssen in der Datei /includes/localconfig.php die richtigen Dateinamen hinterlegt werden, wie sie aus dem MarketViewer erzeugt wurden.

Achtung: Im MarketViewer 2 wird der Dateiname vom Portfolioname abgeleitet. Wird der Name vom Portfolio verändert, so muss auch der Dateiname in der localconfig.php angepasst werden. Alternativ ist es dazu auch möglich den Namen der Exportdatei im MarketViewer zu definieren - auch hier muss die Einstellung von its.connect angepasst werden.

Der Abgleich der ITscope Produkte mit dem Shopsystem erfolgt über die PHP-Datei synchronize.php. Wird das Skript ohne Parameter aufgerufen erfolgt ein Vollimport. 

synchronize.php?[mode=full|update][&clean=its|all|none][&logger=<Logger Klasse>]

Wahlweise kann über die Parameter das Verhalten gesteuert werden.

Der Parameter mode bestimmt die Art des Imports. Es gibt einen Vollimport (full) und ein Update (update).

Weiterhin besteht die Möglichkeit Produkte und Kategorien vor dem Import zu bereinigen bzw. leeren. Über den Parameter clean können entweder nur ITscope Produkte und Kategorien gelöscht werden (its) oder alle Produkte und Kategorien (all). Der Standard ist keine Leerung bzw Löschung der Produkte (none) und muss nicht angegeben werden. Der Parameter zum Löschen der Produkte bewirkt, dass zunächst die gewählten Produkte entfernt werden und anschließend sofort mit den neuen Daten ersetzt werden. Da es sich um den Synchronisierungsvorgang handelt ist ein ausschließliches Löschen der Produkte nicht erreichbar!

Die Ausgabe des Loggers kann über den Parameter logger gesteuert werden. Dieser erwartet den Bezeichner einer Logger Klasse. Standard ist hier der LoggerHTML, welche für die Webausgabe gedacht ist. 

http://www.shop.de/its.connect/synchronize.php
http://www.shop.de/its.connect/synchronize.php?mode=update
http://www.shop.de/its.connect/synchronize.php?mode=full&clean=its

4 Lokale Einstellungen

In der Datei localsettings.php im Ordner includes müssen individuelle Einstellungen für die its.connect-Installation getroffen werden. Es wird dabei unterschieden in Pflichteinträge und optionale Einträge - beide sind in den folgenden Tabellen entsprechend markiert.

Achtung: Die Datei wird nicht direkt ausgeliefert, sondern als localconfig.sample.php und muss vor dem Einsatz umbenannt werden. Dies wurde in Hinsicht auf ein Update der Software festgelegt, damit die lokalen Einstellungen nicht automatisch überschrieben werden.

4.1 Module

Die Verwendung von Modulen muss in der localconfig.php definiert werden. Beschreibung für Module haben den Haupteintrag module.

Gruppe: module
Name Beschreibung Programmcode
connector Aktuell werden alle Funtkionalitäten über diese Modulbeschreibung abgefragt. Als Wert wird der Modulname erwartet. Dieser wird vom Entwickler des entsprechenden Moduls fetstgelegt und kann der zugehörigen Dokumentation entnommen werden. $registry->set('module', 'connect', 'shopware');

4.2 FTP

Alle Registry Einträge beginnen mit ftp. Aktuell werden diese Parameter noch nicht produktiv verwendet, müssen aber vorhanden sein. Diese Einstellungen werden in Zukunft für das Update genutzt.

Achtung: Die Einträge für den FTP werden derzeit noch nicht verwendet und sollen hier nur zur Vollständigkeit für zukünftige Version bereits aufgeführt werden.
Gruppe: ftp
Name Beschreibung Programmcode
hostname Der Hostname des Webservers auf dem its.connect installiert wurde für den FTP-Zugriff. $registry->set('ftp', 'hostname', 'localhost');
port Der Port unter dem der FTP zu erreichen ist. Standard ist Port 21. $registry->set('ftp', 'port', 21);
timeout Definiert, ab wann die Verbindung im Fehlerfall abgebrochen werden soll. $registry->set('ftp', 'timeout', 15);
password Das Passwort zum FTP-Nutzer. $registry->set('ftp', 'password', 'FTP-Passwort');
pathtoits Der Pfad zur its.connect-Installation, in der Regel direkt unterhalb des Zielsystems mit dem Namen /its.connect. $registry->set('ftp', 'pathtoits', '/its.connect');

4.3 Datenbank

Name Beschreibung Programmcode
hostname Der Hostname der Datenbank auf der der Shop installiert wurde. $registry->set('db', 'hostname', 'localhost');
database Der Datenbankname. $registry->set('db', 'database', 'db_shop');
username Der Datenbank-User der Zugriff auf die Shopdatenbank hat. $registry->set('db', 'username', 'root');
password Das Passwort zum Datenbank-Nutzer. $registry->set('db', 'password', );
driver $registry->set('db', 'driver' , 'mysqli');


modules $registry->set('db', 'modules' , );
options $registry->set('db', 'options' , );

4.4 Pfadangaben

Name Beschreibung Programmcode
catalog Verzeichnis in dem das Shopsystem liegt. $registry->set('path', 'catalog', $_SERVER['DOCUMENT_ROOT'].'/');
ws_application Pfad zur its.connect Installtion in der URL, mit abschließendem Schrägstrich. $registry->set('path', 'ws_application', 'its.connect/');

4.5 Integration in den Shop

Name Beschreibung Programmcode
charset Seitencharset, zum Beispiel: iso-8859-15, utf-8. Dieses hat zum Beispiel Einfluss auf die Darstellung des Datenblatts - auch im IFrame! $registry->set('integration','charset','iso-8859-15');
useIFrame Depricated: Datenblattanzeige im IFrame. Dieses Feld wird ab der Version core-1.3.2 nicht mehr ausgelesen! Siehe dazu: [datasheet]=>[wrapper]. $registry->set('datasheet','wrapper', 'iframe');
wrapper Datenblattanzeige im IFrame. Dieses Feld hat sich ab Version core-1.3.2 geändert. Es muss jetzt als Wert iframe oder embedded angegeben werden. $registry->set('datasheet','wrapper', 'iframe');
width Breite des Datenblatts im IFrame $registry->set('datasheet','width' , 520);

4.6 Synchronisation

Die Synchronisation benötigt ein paar serverspezifische Einstellungen. Dazu gehört zum Beispiel wie viele Einträge auf einmal in die Datenbank gespielt werden dürfen. Die Registryeinträge fangen sind unter sync eingeordnet.

Name Beschreibung Programmcode
file_full Dateiname für die Vollimportdatei $registry->set('sync', 'file_full' , 'full.zip');
file_update Dateiname für die Updatedatei $registry->set('sync', 'file_update', 'update.zip');
block_size Bestimmt wie viele Zeilen am Stück in die Datenbank gespielt werden. Standard ist 250. Wenn die Datenbankverbindung beim Einspielen abbricht, kann man versuchen den Wert niedriger zu setzen. Zu kleine oder zu große Werte erhöhen die Laufzeit merklich. $registry->set('sync', 'block_size', 250);
max_offset Definiert wie lang eine Zeile der CSV maximal sein darf, also die Anzahl der Zeichen. Sind die tatsächlichen Einträge länger wird ein Fehler angezeigt. Dieser Parameter ist besonder wichtig, wenn im Export sehr lange Zeilen auftreten. 4096 Zeichen heisst also 4 Kilobyte an Daten pro Zeile. Ist dieser Wert zu gering wird eine Exception geworfen, die auch darauf hinweißt. In der Regel sollten 32kb, also 32768 Bytes ausreichen. $registry->set('sync', 'max_offset', 32768);

4.7 Logdateien und Debuggen

Logger-Einstellungen für die Synchronisierung
Name Beschreibung Programmcode
debug Aktivieren / Deaktivieren des Debuggings; true = aktiviert, false = deaktiviert $registry->set('log_sync','debug',true);
level Der Logger besitzt gestufte Ausgaben gestaffelt nach Schweregrad. Debugausgaben = 0, Informationen = 1, Warnungen = 2, Fehler = 3, Kritische Fehler = 4. $registry->set('log_sync', 'level', '0');
time Zeitmessung aktivieren.true = Zeitmessung fuer Queries aktiviert, false = deaktiviert $registry->set('log_sync', 'time', true);
warntime Zeit in ms ab der eine Warnung ausgegeben wird; 0 = deaktiviert $registry->set('log_sync', 'warntime', 500);
abbreviate Anzahl Zeichen nach denen eine Nachricht abgetrennt wird. $registry->set('log_sync', 'abbreviate', 100);


Logger-Einstellungen für den Seitenaufruf
Name Beschreibung Programmcode
debug Aktivieren / Deaktivieren des Debuggings

true = aktiviert, false = deaktiviert

$registry->set('log_page','debug',true);
level das Level für den Logger; 0 = Debug, 1 = Info, 2 = Warning, 3 = Error, 4 = Critical $registry->set('log_page', 'level', '0');
time Zeitmessung aktivieren. true = Zeitmessung fuer Queries aktiviert, false = deaktiviert $registry->set('log_page', 'time', true);
warntime Zeit in ms ab der eine Warnung ausgegeben wird; 0 = deaktiviert $registry->set('log_page', 'warntime', 0);
abbreviate Anzahl Zeichen nach denen eine Nachricht abgetrennt wird. $registry->set('log_page', 'abbreviate', 100);

5 Funtkionen

5.1 Bilderabruf

Da Bilder in der Regel nicht lokal verwendet werden dürfen, müssen diese über das Internet vom Server des jeweiligen Anbieter benutzt werden. Der Export über den MarketViewer liefert dazu die zum Produkt zur Verfügung stehende Bild-URL. Damit Bilder in den meisten Shopsystemen in der richten Größe vorliegen, werden diese skaliert werden. Dies geschieht über das Skript thumb.php im Ordner its.connect. Das Skript ist bewusst schlank gehalten und ruf nur das Bild ab, um es kurzfristig zu skalieren. Es ist kein Mechanismus zur Zwischenspeicherung der Bilder vorgesehen - es wird immer direkt mit dem zur Verfügung stehendem Bild gearbeitet.

Die Bild-URL wird dem Skript über den Parameter src in codierter Form mitgeteilt. Der Bildlink wird bereits automatisch von its.connect generiert und funktioniert zusammen mit einem Eintrag in der lokalen .htaccess oder direkt in der Apache-Konfiguration wenn dort Zugriff besteht.

Der Aufruf als URL sieht dann wie folgt aus. Die letzte Zahl zwischen den beiden Schrägstrichen vor bild.jpg gibt dabei die gewünschte Größe an und wird in der Regel im Template festgelegt. 

http://www.shop.de/image/aHR0cDov2K235K235K23=YXRlbmJsYXR0LmRlL2Nkcy9kZS8/cGlkPTVkODIxZDFkR19EQ0kyOTM2NDk=/120/bild.jpg

Für die Größe kann ein beliebiger Wert in Pixel angegeben werden, wobei ein Hochskalieren zwar möglich ist - es wurde jedoch mit Absicht ein sehr einfacher Skalierungsfilter benutzt, wodurch hochskalierte Bilder je nach Größe verpixelt wirken werden. Wenn das Bild in Originalgröße angezeigt werden soll, so kann als Wert -1 übergeben werden.

6 Module

Das Kernprogramm its.connect ist speziell für die Verwendung von Modulen geschrieben. Für Gewöhnlich stellt ein Modul alle Funktionalitäten für das Zielsystem zur Verfügung. Der Kern gibt dabei die Aktionen wie Synchronisierung, Integration, Installation oder dergleichen vor, welche vom Modul spezifisch ausgeführt werden. Nicht jedes Modul muss jede Aktion unterstützen.

Module werden stets im Verzeichnis /modules erwartet. Der Verzeichnisname des Moduls muss exakt der Vorgabe entsprechen und darf nicht abweichen. Ein Modul für eine Shopware ist demnach immer im Verzeichnis /modules/shopware zu hinterlegen. Die Bezeichnung wird vom Entwickler des Moduls festgelegt und kann nicht geändert werden.

Module haben eine ähnliche Verzeichnisstruktur wie die Core selbst. In der Regel wird es Verzeichnisse wie classes und includes immer geben. Es können noch eine beliebige Anzahl weiterer Verzeichnisse vorhanden sein. Diese werden in der Beschreibung zum jeweiligen Modul genauer erklärt.

7 Siehe auch

8 Weblinks

Von „http://www.itscope.de/wiki/Its.connect/Dokumentation“