Modul-Dokumentation "Artikel / Produkte CSV Export"

Allgemeine Infos zum Modul und zu uns 😊

Was dieses Modul kann

Eine Liste aller Produkte ist für viele Einsatzmöglichkeiten nützlich. Sei es, um die Produkte an Partner zu übermitteln, um Lagerbestände abzugleichen, um die Daten an Google oder andere Partner zu übertragen usw.

Mit diesem Modul lassen sich deine Produkte aus dem OXID Shop schnell und automatisiert per CSV exportieren. CSV ist das am meisten genutze Format für den Austausch von Datenlisten.

Du kannst im Modul beliebig viele Exporte erstellen, in denen du sowohl den Aufbau als auch die Produkte, die exportiert werden sollen, ganz flexibel einstellen kannst.

Alle Exporte lassen sich - einmal konfiguriert - voll automatisieren und sogar automatisch per eMail oder ftp versenden.

Update von Versionen < 6.0

Bitte deaktiviere das Modul im Shop. Lösche das Verzeichnis dwa_csvexport in modules/dwa. ACHTUNG: Sichere dir ggf. vorher eigene Export-Templates!

Jetzt kannst du mit Schritt 1 der Installation fortfahren.

composer require --no-update --update-no-dev dwa/dwa_csvexport
composer update --no-dev

Modul-Id: dwa_csvexport

Anpassen des Export-Users

Mit der Installation wird ein neuer Benutzer namens CSV Export User sowie eine Benutzergruppe namens DWA CSV Export Benutzer angelegt.

Der CSV Export verwendet die Einstellungen für den Benutzer, um verschiedene Daten aus dem Shop zu ermitteln, z. B. Artikelpreis, Rabatte, zulässige Versand- und Zahlungsarten usw.

Auch das Lieferland wird aus der Adresse dieses Benutzers gezogen (zur Kalkulation der Versandkosten).

Damit der Export korrekt funktioniert, muss dieser Benutzer die entsprechenden Rechte erhalten.

Weise dem Benutzer die Benutzergruppen zu, anhand derer die gültigen Versand- und Zahlungsarten ermittelt werden sollen.

Falls nötig, weise dem Benutzer einen anderen Bonitätsindex zu.

Wenn du z. B. die Zahlungsart „Kreditkarte“ erst ab einem Bonitätsindex von 100 zulässt, der CSV Export User aber einen Index von 50 hat, wird die Zahlungsart Kreditkarte nicht exportiert.

Wenn du in deinem Shop einen allgemeinen Rabatt von 0% eingestellt hast, und der CSV Export User einer Benutzergruppe zugeordnet ist, für die der Rabatt gilt, werden auch in der Export-Datei alle Preise einen 20% Rabatt haben.

Über den Benutzer oder/und die Benutzergruppe kannst du die zulässigen Versand- und Zahlungsarten, Rabatte usw. für den Export steuern. So hast du die volle Kontrolle darüber, welche Daten und Preise exportiert werden.

Du kannst zur Benutzergruppe DWA CSV Export Benutzer weitere Benutzer anlegen und diese dann Ihren Export-Schemata zuweisen, um Exportdateien für verschiedene Länder zu erstellen. Mehr dazu unter "Zugehörigen Benutzer festlegen".

Update-Installation

Alle bereits erstellten Schemata bleiben bei einem Update vollständig erhalten und können nach Ausführen des Updates bei Bedarf erweitert werden. Führe unter Berücksichtigung der Hinweise unten die Update-Installation durch. Dazu befolgst du bitte die Schritte oben, gehe also genauso vor wie bei der Installation.

Wichtige Versions-Hinweise

Deine aktuelle Versionsnummer ermittelst du bitte VOR dem Update, du findest sie auf dem Tab mit den Moduldaten.

bisherige Version < 4.10

Deaktiviere das Modul und lösche es dann komplett.

bisherige Version < 4.17

• Wenn dein Shop mehrsprachig ist, müssen alle Export-Schemata, die du in anderen Sprachen ausführst, nach dem Update angepasst werden. Die Sprache der Exportdatei wird jetzt am Export-Schema eingestellt. Du benötigst für denselben Export in mehreren Sprachen jetzt mehrere Schemata. Mehr dazu unter "Export in verschiedenen Sprachen".
• Nach dem Update muss zwingend eine Datenmigration durchgeführt werden. Bitte gehe dazu auf CSV Export → Artikeldaten und führe dort über den Button „Migration durchführen“ die Migration aus. Nach erfolgreichem Abschluss der Migration kannst du die Backup-Tabelle entfernen. Kopiere dafür den folgenden Code im OXID Adminbereich in Service → Tools in das Textfeld „Sql ausführen“ und klick dann auf „Update ausführen“.

DROP TABLE oxarticles_migr218_bak;

bisherige Version < 4.32

• das Attribut oxtags (Stichworte) ist in OXID -Version 6 entfernt worden und kann nun auch nicht mehr exportiert werden. Bitte speichere nach dem Update auf Version 4.32 alle Schemata einmal, damit die Spalte auch aus dem Schemata entfernt wird.

Export-Schemata (Vorlagen) erstellen

Der Export kann unter CSV Export → Artikeldaten eingerichtet und auch ausgeführt werden. Mit dem Modul kommen bereits verschiedene fertige Export-Vorlagen, die du für dich anpassen oder auch vervielfältigen (kopieren) und dann anpassen kannst.

Installation der Schemata

Die CSV-Schemata liegen als einzelne SQL-Dateien unter /Vorlagen vor. Du kannst dir einzelne CSV-Schemata importieren, oder auch alle. Um ein Schema zu importieren, öffne die SQL-Datei und kopiere den enthaltenen Code im OXID Adminbereich in Service → Tools in das Textfeld „Sql ausführen“ und klick dann auf „Update ausführen“.

Achtung – der direkte Import der Datei über „Durchsuchen“ funktioniert an dieser Stelle nicht, weil das Statement für OXID zu lang ist.

Für Google Merchant sind Anpassungen nötig

Mit dem Modul kommt auch eine Vorlage für Google Merchant, die jedoch aus technischen Gründen noch nicht ganz vollständig ist. Wenn du sie nutzten möchtest, sind ein paar kleine Handgriffe vonnöten.

Gehe dazu im OXID Adminbereich in Erweiterungen → Module und dort auf das Modul „Artikel /Produkt Export CSV“.

Auf dem Tab Einstellungen legst du bitte folgende variable Artikel-Spalten an (du findest eine Anleitung zu variablen Spalten in Kapitel 5.8):

• „Verfügbarkeit“ mit einem der folgenden Default-Werte: „auf Lager“, „nicht auf Lager “, „vorbestellbar “
• „Zustand“ mit einem der folgenden Default-Werte: „neu“, „gebraucht“, „generalüberholt “

Die Defaultwerte sind die Werte, die immer dann eingetragen werden, wenn am Artikel selbst nichts Abweichendes festgelegt wurde. Um artikelbezogene Werte für die Artikel-Spalten festzulegen, geh im Artikel auf den Tab „Erweitert“. Dort findest du für jede variable Spalte, die du hier mit einem Namen versehen hast, ein entsprechendes zusätzliches Eingabefeld.

Analog gehst du für die Kategorien vor.

Bei den „variablen Kategoriespalten“ kannst du die Spalte „Google Produktkategorie“ anlegen, ggf. kannst du hier auch einen Defaultwert vergeben (falls ein Großteil oder alle deiner Artikel in dieselbe Google Produktkategorie einzuordnen sind).
Diese Spalte ist optional, wenn du sie nicht verwendets, wählt Google automatisch eine Produktkategorie für dich aus.

Bei den Kategorien kannst du jeweils auf den Tab „Stamm“ einen vom Defaultwert abweichenden Wert angeben.

Versandkosten

Für die Versandkostenübertragung haben wir für die DACH-Länder Beispieltemplates im Modul mitgeliefert. Diese erleichtern dir die Einbindung deiner Versandkosten in dem von Google geforderten Schema. Das Template für Deutschland (versand.tpl) kannst du in der Regel so nutzen, da die Berechnung der Versandkosten hier über den im Exportschema gesetzten Benutzer nach Shoplogik läuft. Für weitere Länder musst du jedoch die Preislogik im Template selbst gestalten, da man die Shoplogik an dieser Stelle nicht nutzen kann. Gern helfen wir dir hier, wenn du Unterstützung benötigst. (kostenpflichtig)

Aktiviere die gewünschten Templates wie unter Punkt "Eigene Smarty-Templates für Export-Spalten hinterlegen" beschrieben und füge sie dem Google Schema hinzu. Für die Versandkosten setze in den Einstellungen als Spaltenüberschriften "Versand".

Anschließend müssen die variablen Spalten noch dem Google-Schema zugewiesen werden, siehe unten.

Informationen zu den Anforderungen von Google Merchant an die Exportdatei findest du hier.

Eigene Export Schemata anlegen

Gehe auf CSV Export → Artikeldaten.

Du stehst in der leeren Schema Maske. Gib dem Schema einen eindeutigen Namen.

Vergib einen Dateinamen. Er kann eine beliebige Endung haben. Wenn du keine Endung angibst, ergänzt das Modul automatisch .csv.

Die Datei wird unter diesem Namen im Verzeichnis /export in deinem Shop gespeichert.

Du kannst statt eines einfachen Dateinamens auch einen Verzeichnisnamen voranstellen, z. B. google/google.csv → die Datei wird im Verzeichnis export/google angelegt. Achtung – das Verzeichnis muss vorhanden sein! Bitte leg es vorher an und geben ihm die nötigen Schreibrechte.

Stell die verschiedenen Export-Parameter ein (siehe auch folgende Kapitel).

Speicher deine Einstellungen. Das Schema kann jederzeit erweitert oder geändert werden.

Zugehörigen Benutzer festlegen

Über den Benutzer zieht sich das Modul beim Export die eingestellten (für den Export geltenden) Rabatte, Rechte und Versandkosten. Dafür werden z. B. Bonität, das für den Benutzer eingestellte Land sowie die zugeordneten Benutzergruppen berücksichtigt.

Das Modul installiert automatisch den Benutzer CSV Export User, der jedem Schema standardmäßig zugeordnet ist. Lösch diesen Benutzer nicht!

Du kannst weitere CSV Benutzer anlegen (z. B. für eine Exportdatei für ein anderes Land). Wenn du einem beliebigen Benutzer in OXID die Benutzergruppe DWA CSV Export Benutzer zuweist, wird dieser in der Auswahlliste im Schema erscheinen und kann dem Schema zugeordnet werden.

Spalten-Überschriften

Rechts auf dem Tab „Allgemein“ kannst du Spalten-Überschriften ändern. Diese Änderung muss für jedes Export-Schema separat eingestellt werden. Wenn du die Überschrift nicht änderst, wird sie wie hier dargestellt in die CSV-Datei übernommen.

Dies ist auch nur nötig, wenn du in der CSV Datei die Headerzeile aktiviert hast.

Dateiaufbau und Spalten-Reihenfolge

Geh nun zum Tab „Export-Spalten“.

Links kannst du hier den allgemeinen Aufbau Ihrer Export-Datei festlegen.

Falls du in der Export-Datei für Varianten einen abweichenden Spalten-Aufbau benötigst, kannst du diesen rechts festlegen. Achte dabei bitte darauf, dass die Spalten-Anzahl mit der links eingestellten übereinstimmt. Verwendest du gegebenenfalls Leerspalten.

Übrigens: Falls dir die hier angezeigten Felder mit den Spaltennamen zu hoch sind, und das Scrollen mühsam wird (abhängig von der Bildschirmauflösung), kannst du für die Felder auch Scrollbalken aktivieren. Geh dazu in die Moduleinstellungen (Erweiterungen → Module → CSV Export → Einstellungen) und setz unter „Allgemeine Einstellungen“ das entsprechende Häkchen.

Nur Artikel mit Lagerbestand

Setze das Häkchen in „nur aktive Artikel exportieren“, so werden nur aktive Artikel exportiert, wobei OXID nach den Standardeinstellungen auch den Lagerbestand prüft. D. h. bei dieser Einstellungwerden die aktiven Artikel wie im OXID Standard geladen.

Wenn du Artikel ohne Lagerbestand immer nicht mit exportieren willst (auch wenn du sie standardmäßig weiterhin im Shop anzeigst), aktivier die zusätzliche Option „nur Artikel mit Lagerbestand > 0 exportieren“. Artikel, bei denen „wenn ausverkauft offline“ als Lagerbestandsflag gesetzt ist, werden nicht mit exportiert.

Tracking-URL mit Parametern

Verwende unbedingt Trackingparameter, so kannst du z.B. die Herkunft deiner Kunden genau auswerten. Wenn du die Daten automatisch in deinem Trackingtool z.B. mit Google Analytics auswerten möchtest, nutze am besten UTM-Parameter, diese sind in allen Trackingtools bekannt. Hier findest du weitere Infos für den Aufbau deiner Trackingparameter:
https://support.google.com/analytics/answer/1033863?hl=de

Über Trackingparameter kannst du später auch besondere Aktionen (Rabatte, Hinweise, Preise, Versandkostennachlässe etc.) im Shop steuern.

Für eine solche Umsetzung sprich uns gern an.

CSV-Datei erstellen

Auf dem Tab „Cronjob“ siehst du nach dem Speichern unten den Link für den Cronjob (ggf. in mehreren Sprachen).

Die Export-Datei wird unter dem von dir festgelegten Namen im Verzeichnis "export" deines Shops gespeichert.

Soll der Export regelmäßig durchgeführt werden, legst du dafür einen Cronjob an (z. B. www.cronjob.de).

CSV-Datei per E-Mail oder ftp senden

Die CSV-Datei kann direkt nachdem sie generiert wurde, automatisch per E-Mail oder per ftp versendet werden.

Stellst du dazu die entsprechenden Parameter auf dem Tab „Cronjob & Versand“ ein. Du kannst hier auch die eingegebenen ftp-Daten auf Gültigkeit prüfen – nutz das, denn ein Fehler schleicht sich rasch ein und führt dazu, dass keine Daten auf dem ftp-Server ankommen!

Es ist auch möglich, beides anzugeben. Die Datei wird dann sowohl per E-Mail als auch per ftp versendet.

Export in verschiedenen Sprachen

Ab Version 4.17 muss die Sprache des Exports im Schema festgelegt werden.

Willst du denselben Export in mehreren Sprachen ausführen, kopier einfach das Schema und speicher es mit der abweichenden Spracheinstellung unter einem neuen Namen.

Eigene Datenfelder für Artikel oder Kategorien hinzufügen

Du kannst für den Export individuelle Artikel- und Kategorie-Spalten hinzufügen, die du mit beliebigen Daten füllen kannst. Diese Funktion ist z. B. hilfreich für Google Merchant, wo weitere, standardmäßig in OXID eShop nicht verfügbare Daten mitgeliefert werden müssen.

Es stehen derzeit sechs Artikelspalten sowie drei Kategoriespalten zur Verfügung.

Die Spalten können beliebig benannt und mit beliebigen Default- oder spezifischen Werten gefüllt werden.

Spalten-Bezeichner / Funktion aktivieren

Um individuelle Spalten zu aktivieren, müssen zunächst Spaltenbezeichner angegeben werden. Geh dazu in die Moduleinstellungen des CSV Export-Moduls (Erweiterungen→Module, Tab „Einstellungen“). Unter „Variable Artikelspalten – Bezeichnungen“ bzw. „Variable Kategoriespalten - Bezeichnungen“ leg für alle Spalten, die du nutzen möchtest, eine Spaltenbezeichnung fest. Unter dieser Bezeichnung kannst du das Feld später in den Artikeln oder Kategorien füllen, und im CSV Export den Exportdaten hinzufügen.

Für die Bezeichnung kann auch eine Language-Konstante verwendet werden. So ist es möglich, die Spaltenbezeichner mehrsprachig zu verwenden. Bitte beachte, dass hier nur auf Admin-Languagedateien zugegriffen werden kann.

Werte festlegen

Du kannst nun für die Felder Standardwerte festlegen, die für alle Artikel bzw. für alle Kategorien gelten, für die du keine abweichenden Werte festgelegt hast. Bitte beachte, dass dieser Wert dann IMMER exportiert wird, wenn der Artikel selbst über keinen Wert verfügt.

In den Artikeln können die Werte auf dem Tab „Erweitert“ festgelegt werden. Varianten erben diesen Wert, wenn du selbst keinen eigenen Wert hast, d. h. wenn eine Variante einen anderen Wert als ihren Vater bekommen soll, trag ihn einfach bei der Variante ein.

In den Kategorien können die Werte auf dem Tab „Stamm“ festgelegt werden.

Alle Werte werden multilingual gespeichert, d. h. wenn du mit mehreren Sprachen arbeitest (und auch deinen Export mehrsprachig verwendest), leg Werte für alle verwendeten Sprachen fest. Beim Default-Wert kannst du dabei mit Language-Konstanten arbeiten. Bitte beachte, dass hier nur auf Admin-Languagedateien zugegriffen werden kann. Verwende bei Bedarf die Datei application/views/admin/[sprache]/cust_lang.php. Pass nicht die Modul-Sprachdateien an, da diese Änderungen sonst beim nächsten Modulupdate wieder überschrieben werden!

Eigene Smarty-Templates für Export-Spalten hinterlegen

Ab Version 4.20 gibt es die Möglichkeit, Smarty-Templates zum Exportieren von Daten (spaltenweise) zu hinterlegen, um diese in bestimmten Zusammenstellungen oder mit bestimmtem Layout zu exportieren.

Damit wird der Export extrem mächtig und flexibel. Wenn du Unterstützung bei der Erstellung der Templates benötigst, stehen wir gerne zur Verfügung.

Dazu legst du neue dynamische Spalten an, denen du jeweils ein Template zuordnest und die du anschließend in den Export einfügen kannst.

Beim Export wird dieses Template gerendert und das Ergebnis in die jeweilige Spalte im Export eingefügt.

Schritt 1: Spalten-Bezeichner / Funktion aktivieren

Geh dazu in die Moduleinstellungen des CSV Export-Moduls (Erweiterungen→Module, Tab „Einstellungen“). Unter „Variable Templatespalten – Bezeichnungen“leg für alle Spalten, die du nutzen möchtest, eine Spaltenbezeichnung fest. Unter dieser Bezeichnung kannst du das Feld später in den Artikeln oder Kategorien füllen, und im CSV Export den Exportdaten hinzufügen.

Z. B. willst du die Langbeschreibung der Artikel um die Attribute ergänzen. Trag in Spalte 1 den Namen „Langbeschreibung mit Attributen“ an.

Schritt 2: Templatepfade festlegen

Unter „Variable Templatepfade“ kannst du nun den Namen Ihres Templates inklusive Dateiendung .tpl angeben. Bitte beachte, dass sich alle für den CSV Export genutzten Templates in folgendem Verzeichnis befinden müssen:

Bis Modulversion <6

modules/dwa/dwa_csvexport/out/export/tpl/

Ab Modulversion 6

modules/dwa/dwa_csvexport/Application/views/export/

Du findest in diesem Verzeichnis bereits ein vorgefertigtes Beispieltemplate, passend zu dem hier vorgestellten Beispiel.

Um bei unserem Beispiel oben zu bleiben, das Template dazu soll langbeschreibung-attribute.tpl heißen. Genau das trägst du also unter Variable Templatepfade 1 ein.

Schritt 3: Template erstellen

Erstell nun das Template unter diesem Namen mit den gewünschten Inhalten. Ein Beispieltemplate wird mit dem Modul mitgeliefert. Bitte benenn es um, wenn du es verwenden möchtest, damit es beim Update nicht überschrieben wird!

In den Templates steht dir das Artikel-Objekt $oArticle zur Verfügung.

Schritt 4: Spalte in den Export einfügen

Öffne nun das Exportschema und wechsle zum Tab „Export-Spalten“. Dort findest du eine zusätzliche Spalte mit der in Schritt 1 von dir gewählten Bezeichnung sowie dem Zusatz (ind.). Du siehst diese Spalte, die wir oben als Beispiel ergänzt haben, im folgenden Screenshot mit Pfeil markiert:

Export großer Artikelbestände

Das CSV Export Modul wurde auch speziell für den Export großer Datenbestände entwickelt.

Hintergrund ist, dass alle Skripte, auch das Export-Skript, nur eine bestimmte, begrenzte Laufzeit auf dem Server erhalten. Nach Ablauf dieser Zeit wird das Skript automatisch durch den Server beendet, um eine Überlastung zu vermeiden, die durch falsch programmierte Skripte entstehen können. In der Regel beträgt diese Zeit unter einer Minute. Große Artikelbestände lassen sich in dieser Zeit jedoch nicht vollständig exportieren. Daher ruft das Skript sich immer wieder selbst auf, denn jeder neue Aufruf gilt wie ein neuer Skriptstart und hat wiederum ca. 30 – 45 Sekunden Zeit (je nach Servereinstellung).

Über den Parameter „Anzahl Datensätze pro Export-Durchlauf“ kannst du festlegen, nach wie vielen Artikeln sich das Skript neu aufrufen soll. Je nach Anzahl der zu exportierenden Artikel sowie Art und Anzahl der Spalten des Exports können hier unterschiedliche Werte optimal sein. Voreingestellt ist 1000.

Export über mehrere Cronjobs

Zudem kannst du optional einen Export auf mehrere Cronjobs aufteilen. So führt der zweite (dritte usw.) Cronjob die Arbeit des 1. fort. Um diese Funktion zu nutzen, aktivier die Option „Export über mehrere Cronjobs aktivieren“ in den Schema-Einstellungen. Leg nun einen „normalen“ Cronjob (generierter Link) an, sowie einen oder beliebig viele weitere Folge-Cronjobs, für die du dem Link folgendes hinzufügst:

&repeat=1

Diese Cronjobs führen den Export nur dann fort, wenn der Haupt-Cronjob (ohne repeat in der URL) nicht komplett ausgeführt wurde. Anderenfalls werden sie ignoriert.

 Konkrete Probleme und Lösungen für große Artikelbestände

Server-Timeout

Ein Timeout bedeutet, dass das Skript in einem Durchlauf zu lange lief. Setze die „Anzahl Datensätze pro Export-Durchlauf“ niedriger.

Fehler 500 oder Endlosschleife

Dieser Fehler bedeutet in der Regel, dass das Skript die maximal zulässige Anzahl an Selbstaufrufen erreicht hat und sich nicht noch einmal selbst neu aufrufen konnte. Du kannst die „Anzahl Datensätze pro Durchlauf“ erhöhen, um mehr Artikel in einem Aufruf zu exportieren. Oder teile den Export auf zwei Aufrufe auf (siehe unten), um den Export an der Stelle, wo abgebrochen wurde, fortzuführen.

Export auf zwei Cronjobs aufteilen

Bei sehr großen Datenbeständen kann es vorkommen, dass die Daten nicht in einem Skriptaufruf exportiert werden können. Dies trifft insbesondere dann zu, wenn du eine große Anzahl an Spalten (ggf. mit kompliziertem Rechen-Algorithmus, z. B. Versandkosten) exportieren willst.

Du kannst in diesem Fall den Export auf zwei Cronjobs aufteilen. Dazu startest du den Export per Cronjob und starten einen zweiten Cronjob im Abstand von ca. 20 – 30 Minuten, dem du Folgendes im URL anfügst: „&repeat=1“. Bitte beachte, dass die entsprechende Option aktiviert sein muss (siehe oben).

Im Administrationsbereich siehst du, ob ein Export vollständig ausgeführt wurde. Falls dies nicht der Fall ist, erscheint eine entsprechende Meldung, wenn du das Schema öffnest.

Gern unterstützen wir dich auch bei der optimalen Einrichtung deiner Cronjobs. Bitte fordere einfach ein Angebot an.