Gambio Modul Vertrieb Lizenzschlüssel / v1.0.x

Modul-Installation

Hochladen der Modul-Dateien

Entpacken Sie das downgeloadete Modul-Zip-Paket. In diesem zip-Paket finden Sie einen Datei-Ordner, welcher zwei Unterverzeichnisse hat: admin und GXModules.

Ordner 'admin'

Laden Sie per FTP-Programm die Dateien aus Ihrem lokalen Ordner /admin/ in den Ordner [root]/admin/ am Server auf dem Ihr Shop installiert ist.

Ordner 'GXModules'

Laden Sie per FTP-Programm die Dateien aus Ihrem lokalen Ordner /GXModules/ in den Ordner [root]/GXModules/ am Server auf dem Ihr Shop installiert ist.

Befindet sich im Ordner [root]/GXModules/ bereits ein Ordner /LW/ (weil Sie weitere Module von uns im Einsatz haben) laden Sie per FTP-Programm die Dateien aus Ihrem lokalen Ordner /GXModules/LW/ in den Ordner [root]/GXModules/LW/ am Server auf dem Ihr Shop installiert ist.

Caches leeren

Rufen Sie im Shop den Gambio-Admin-Bereich auf. Leeren Sie unter Toolbox -> Cache den Cache in der nachfolgenden Reihenfolge:

1. Cache für Modulinformationen
2. Cache für Text
3. Cache für E-Mail-Vorlagen
4. Cache für Seitenausgabe

Ordnerberechtigungen prüfen

Im Ordner [root]/GXModules/LW/Licenses wird während der nachfolgend beschriebenen Modul-Installation die Datei securityConfig.json angelegt. Die Datei enthält den Sicherheitsschlüssel, mit welchem die Lizenzschlüssel in der Datenbank verschlüsselt abgespeichert werden. Auf Ihrem Webspace müssen auf diesen Ordner ausreichende Schreibrechte zugewiesen sein - sonst kann die Datei nicht angelegt werden! Bitte prüfen Sie vor Modul-Installation ob dem Ordner die entsprechenden Schreibrechte zugewiesen sind!

Modul installieren

Wechseln Sie nach Module -> Modul-Center. In der Liste der verfügbaren Module finden Sie einen Eintrag mit der Bezeichnung Lizenzschlüssel Vertriebsmodul. Markieren Sie diese Zeile. Durch einen Klick auf den Button Installieren installiert sich das Modul in den Shop.

Prüfung ob die Datei 'securityConfig.json' angelegt wurde

Nach Modul-Installation sollte geprüft werden, ob unter [root]/GXModules/LW/Licenses die Datei securityConfig.json angelegt wurde. Ist die Datei nicht vorhanden, muss das Modul wieder deinstalliert, dem Ordner [root]/GXModules/LW/Licenses ausreichende Schreibrechte zugewiesen und das Modul erneut installiert werden.

Caches leeren

Nach der Installation müssen ein weiteres mal folgende Caches geleert werden:

1. Cache für Modulinformationen
2. Cache für Text
3. Cache für E-Mail-Vorlagen
4. Cache für Seitenausgabe

Modul-Konfiguration

In der Modul-Konfiguration nehmen Sie allgemeine Einstellungen für das Modul vor. Die Modul-Konfiguration können Sie auf folgendem Weg aufrufen:

• Öffnen Sie im Gambio-Admin-Bereich das Modul-Center. Suchen Sie in der Liste der verfügbaren Module nach dem Modul Lizenzschlüssel Vertriebsmodul. Markieren Sie die Zeile. Durch einen Klick auf den Button Bearbeiten öffnet sich die Modul-Konfiguration.

Allgemein

Der Bereich Allgemein hat aktuell nur eine Einstellmöglichkeit - den Schalter Status. Mit dem Schalter wird die komplette Modul-Funktionalität ein- respektive ausgeschaltet. Steht der Status-Schalter auf aus, werden alle Modul-Erweiterungen im Shop-Admin-Bereich sowie im Shop-Frontend nicht mehr angezeigt. Zudem ist die automatische Zuweisung von Lizenzschlüsseln durch den Cronjob deaktiviert. Das heißt, bei Bestellung eines lizenzschlüsselfähigen Artikels erfolgt keine automatische Zuordnung eines freien Lizenzschlüssels.

Konfiguration Steuerung E-Mail-Versand Lizenzschlüssel

Mit den nachfolgenden Einstellungen wird der Versand der Lizenzschlüssel per E-Mail zum Kunden gesteuert. Der Versand der E-Mail ist abhängig von den nachfolgend zu konfigurierenden Werten. Zusätzlich zu diesen Werten müssen noch folgende Bedingungen erfüllt sein:

• Es wurde bisher noch keine Lizenzschlüssel-E-Mail versendet
• Oder zum Zeitpunkt als die erste Lizenzschlüssel-E-Mail versendet wurde, gab es für die Bestellmenge keine ausreichende Anzahl an verfügbaren Lizenzschlüsseln - inzwischen stehen wieder Lizenzschlüssel zur Verfügung.

Zeitraum für zu verarbeitende Bestellstatusänderungen in Minuten

Das Versenden der Lizenzschlüssel per E-Mail an den Kunden wird automatisiert durch den Gambio CronJob ausgelöst. Dieser CronJob läuft üblicherweise jede Minuten. Beim Ausführen des CronJobs prüft der Prozess, ob es Bestellungen gibt, deren aktueller Status einem der konfigurierten Status (welche den E-Mail-Versand auslösen sollen - siehe nächster Konfigurationspunkt) entspricht. Mit der Zeitraum-Konfiguration wird die Zeitspanne festgelegt, welche der CronJob zurückblicken soll. Alle Bestellungen, welche in dem konfigurierten Zeitraum eine Bestellstatusänderung erfahren haben, werden vom CronJob verarbeitet.

Bestellstatus E-Mail-Versand Lizenzschlüssel

In dieser Konfiguration werden die Bestellstatus festgelegt, welche den Versand der Lizenzschlüssel per E-Mail an den Kunden auslösen. Die Konfiguration erlaubt es mehrere Bestellstatus auszuwählen.

Gambio CronJob einrichten

Für die automatisierte Zuweisung von Lizenzschlüssel zu den Bestell-Artikeln und den Versand der Lizenzschlüssel-E-Mail an den Kunden ist der Gambio CronJob zuständig. Um zu prüfen ob der CronJob bereits eingerichtet ist, wechseln Sie im Admin-Bereich in die Toolbox. Unter Zeitgesteuerte Aufgaben finden Sie die Informationen zum CronJob. Im Bereich Allgemein zeigt der Status an ob der CronJob bereits läuft (grünes aktiv) oder nicht (rotes inaktiv). Falls noch kein CronJob eingerichtet ist (Status inaktiv unter Allgemein), finden Sie im Gambio-Handbuch unter dem Punkt Zeitgesteuerte Aufgaben eine Anleitung.

CronJob für Lizenzschlüssel E-Mail-Versand aktivieren

Um den CronJob für den Lizenzschlüssel E-Mail-Versand zu aktivieren im Bereich Aufgaben in der Zeile Lizenzschlüssel E-Mail-Versand auf das Stift-Symbol klicken. Im Konfigurationsfenster den CronJob aktivieren und das Abrufintervall einstellen. Wir empfehlen ein minütliches Abrufintervall.

Sicherheit/Backup

Angelegte Lizenzschlüssel werden in der Shop-Datenbank verschlüsselt gespeichert. Für die Ver-/Entschlüsselung ist ein Verschlüsselungskey nötig, welcher während des Installationsprozesses automatisch erzeugt wird. Nur mit Hilfe dieses Verschlüsselungskeys können die Lizenzschlüssel in die Shop-Datenbank geschrieben respektive von dort ausgelesen werden. Der Verschlüsselungskey wird auf dem Server in der Datei [root]/GXModules/LW/Licenses/securityConfig.json gespeichert.

Optional: Vorlage für die Lizenzschlüssel-Mail anpassen

Das Modul wird mit einer Vorlage für die Kunden-Lizenzschlüsselmail ausgeliefert. Diese Vorlage kann individuell angepasst werden. Rufen Sie hierfür den Shop-Admin-Bereich auf und wechseln Sie zu Kunden -> E-Mails. Im Reiter E-Mail-Vorlagen findet sich die Vorlage Lizenzschlüssel. Ein Klick auf den Text öffnet das Bearbeitungsfenster.

Optional: Modul-Texte anpassen

Das Modul verwendet den Begriff Lizenzschlüssel. In der Praxis kommen dafür auch viele andere Synonyme zum Einsatz - z. B. „Softwareschlüssel“, „Product Key“ „Freischaltkey“, „Freischaltnummer“ „Aktivierungscode“, "Passwörter".

Die vom Modul verwendeten Texte lassen sich im Shop anpassen. Wechseln Sie hierfür im Admin-Bereich zu Inhalte -> Texte anpassen. Geben Sie unter Suchtext die Textpassage ein die Sie ändern möchten. Führen Sie anschließend die Suche aus. Jeder Suchtreffer lässt sich nach einen Klick auf Bearbeiten individuell anpassen.

Lizenzschlüsselfähige Artikel

Jeder Artikel kann lizenzschlüsselfähig werden. Der entscheidende Faktor ist, ob zu einem Artikel Lizenzschlüssel angelegt wurden (siehe nächstes Kapitel). Zudem spielt der Zeitpunkt, wann der erste Lizenzschlüssel zu einem Artikel angelegt wurde, eine entscheidende Rolle. Dieser Zeitpunkt (nachfolgend mit Grenz-Zeitpunkt bezeichnet) ist die Abgrenzung zwischen alten Bestellungen, welche vom Lizenzschlüssel-Prozess nicht verarbeitet, und neuen Bestellungen, zu welchen Lizenzschlüssel vergeben werden sollen. Eine Bestellung (respektive die Bestell-Artikel darin) wird dann vom Lizenzschlüssel-Prozess verarbeitet, wenn das Bestelldatum jünger ist als der Grenz-Zeitpunkt. Dabei wird für jeden Artikel der artikelspezifische Grenz-Zeitpunkt ermittelt und mit dem Bestelldatum verglichen.

Lizenzschlüssel unter einem Artikel anlegen

Für die Anlage von Linzenzschlüsseln unter einem Artikel rufen Sie im Admin-Bereich über den Menüpunkt Artikel sowie den Unterpunkt Artikel/Kategorien den gewünschten Artikel auf. In der Artikel-Konfigurationsoberfläche, welche Sie über den Button Bearbeiten erreichen, finden Sie den Abschnitt Lizenzschlüssel. Der Abschnitt besteht aus 3 Sektionen:

• Verfügbare Lizenzschlüssel
• Neue Lizenzschlüssel anlegen
• Verbrauchte Lizenzschlüssel

Verfügbare Lizenzschlüssel

In der Sektion Verfügbare Lizenzschlüssel finden sie alle noch verfügbaren Lizenzschlüssel welche noch nicht verkauft sind. Über den Button löschen kann ein verfügbarer Lizenzschlüssel gelöscht werden. Die Löschung eines Lizenzschlüssel wird erst durch Speichern respektive Aktualisieren des Artikels endgültig ausgeführt.

Neue Lizenzschlüssel anlegen

In der Sektion Neue Lizenzschlüssel anlegen können neue Lizenzschlüssel hinzugefügt werden. Neue Lizenzschlüssel müssen zeilenweise eingegeben werden. Erst durch Speichern respektive Aktualisieren des Artikels werden die neuen Lizenzschlüssel in die Datenbank gespeichert.

Verbrauchte Lizenzschlüssel

In der Sektion Verbrauchte Lizenzschlüssel werden alle verkaufen Lizenzschlüssel aufgelistet. Durch Klick auf die Bestellnummer kann die entspechende Bestellung aufgerufen werden.

Bestellprozess

Der Bestellprozess wird durch das Modul nicht beeinflusst. Für den Kunden ist kein Unterschied zum Gambio-Standard-Bestellprozess zu sehen.

Versand der Lizenzschlüssel per E-Mail an den Kunden

Die Zuweisung von verfügbaren Lizenzschlüsseln zu einem Bestellartikel erfolgt durch den Gambio-CronJob (siehe Kapitel Gambio CronJob einrichten), welcher üblicherweise minütlich ausgeführt wird.

Zuweisung von verfügbaren Lizenzschlüsseln zu Bestellartikeln

Der CronJob verarbeitet alle Bestellungen, welche im konfigurierten Zeitraum (siehe Kapitel Zeitraum für verarbeitende Bestellstatusänderungen in Minuten) eine Bestellstatusänderung erfahren haben. Dabei werden nur Bestellstatusänderung berücksichtigt, die einem der konfigurierten Bestellstatus (siehe Kapitel Bestellstatus E-Mail-Versand Lizenzschlüssel) entsprechen.

Bei den relevanten Bestellungen werden nur Artikel verarbeitet, welche den Lizenzschlüsselprozess unterstützen (Artikel bei denen mindestens schon einmal ein Lizenzschlüssel hinterlegt wurde). Unterstützt ein Bestell-Artikel den Lizenzschlüsselprozess und wurden diesem noch keine Lizenzschlüssel zugewiesen, erledigt dies der CronJob-Prozess.

Versand der E-Mail mit den Lizenzschlüsseln

Nachdem die Lizenzschlüssel dem Bestell-Artikel zugewiesen wurden generiert der CronJob die Lizenzschlüssel-E-Mail und versendet diese an den Kunden.

Mindermenge: Die Anzahl der verfügbaren Linzenzschlüssel ist kleiner als die Bestellmenge

Im Fall, das die Anzahl der verfügbaren Lizenzschlüssel kleiner ist als die Bestellmenge, bekommt der Shop-Admin pro Bestellung eine Mail mit den Daten der Mindermenge.

In diesem Fall müssen neue Lizenzschlüssel angelegt werden. Nach Anlage der fehlenden Lizenzschlüssel muss dafür gesorgt werden, das die betroffenen Bestellungen erneut vom CronJob verarbeitet werden. Durch das manuelle Setzen eines der konfigurierten Bestellstatus (siehe Kapitel Bestellstatus E-Mail-Versand Lizenzschlüssel) landet eine Bestellung wieder im Verarbeitungspool des CronJob.

Anzeige der zugewiesenen Lizenzschlüssel im Kundenkonto

Neben der E-Mail mit den Lizenzschlüsseln findet ein Kunde seine Lizenzschlüssel auch in seinem Kundenkonto. Ruft ein Kunde unter Ihr Konto sein Konto auf, finden sich unter Meine Bestellungen die letzten platzierten Bestellungen. Enthält eine Bestellung ein Produkt, welches den Lizenzschlüsselprozess unterstützt, werden die Lizenzschlüssel in einer eigenen Spalte angezeigt.

Wechselt der Kunde in die Bestell-Detailansicht, sind auch hier etwaige Lizenzschlüssel innerhalb der Artikel-Auflistung zu finden.

Anzeige der zugewiesenen Lizenzschlüssel im Admin-Bereich

Im Admin-Bereich finden sich zugewiesene Lizenzschlüssel (analog zum Kundenkonto) in der Bestell-Detailansicht. Die Admin-Bestell-Detailansicht listet im Abschnitt Artikel die bestellten Produkte auf. Die Lizenzschlüssel finden sich in einem separaten Bereich unterhalb des Artikel-Abschnitts.

Löschen eines lizenzschlüsselfähigen Artikels im Shop

Wird im Shop ein lizenzschlüsselfähiger Artikel gelöscht, werden auch sämliche, zu dem gelöschten Artikel noch verfügbaren Lizenzschlüssel aus der Datenbank entfernt. Datensätze mit verkauften Lizenzschlüsseln zu dem gelöschten Artikel bleiben hingegen erhalten.

Modul-Deinstallation

Wechseln Sie im Shop-Admin-Bereich nach Module -> Modul-Center. In der Liste der verfügbaren Module markieren Sie den Eintrag mit der Bezeichnung Lizenzschlüssel Vertriebsmodul. Nach Klick auf den Button Deinstallieren und bestätigen der nachfolgenden Sicherheitsabfrage wird das Modul deinstalliert.

Bei Modul-Installation wurden in der Shopdatenbank folgende Tabelle angelegt:

• lw_licenses_keys
• lw_licenses_keyless_order_products

Nach Deinstallation müssen im Shop-Admin-Bereich unter Toolbox -> Cache die Caches geleert werden:

1. Cache für Modulinformationen
2. Cache für Text
3. Cache für E-Mail-Vorlagen
4. Cache für Seitenausgabe

Entfernen der Moduldateien

Möchten Sie die Moduldaten aus dem Shop entfernen, verbinden Sie sich mittels eines FTP-Programms mit Ihrem Server. Wechseln Sie in das Verzeichnis in das Ihr Shop installiert ist. Rufen Sie dort den Ordner /GXModules/LW/ auf. Die Moduldaten können gelöscht werden, in dem der Unterordner /Licenses/ und sein kompletter Inhalt entfernt wird. Befinden sich in dem /LW/ Ordner keine weiteren Daten, kann auch dieser gelöscht werden.

Löschen Sie die Datei order_status_multiselect.html aus folgendem Ordner: [root]/admin/html/content/module_center/gx_modules/snippets.

Nach Löschen der Ordner müssen im Shop-Admin-Bereich unter Toolbox -> Cache die Caches geleert werden:

1. Cache für Modulinformationen
2. Cache für Text
3. Cache für E-Mail-Vorlagen
4. Cache für Seitenausgabe

Öffnen Sie die Admin-Oberfläche Ihrer Shop-Datenbank. Ihr Hoster stellt Ihnen diese üblicherweise über ein Tool zur Verfügungen (oftmals phpMyAdmin). Löschen Sie folgende Tabellen:

• lw_licenses_keys
• lw_licenses_keyless_order_products

Limitierungen

• Das Modul verwaltet Lizenzschlüssel auf Artikel-Ebene. Eine Verwaltung von unterschiedlichen Lizenzschlüsseln auf Ebene von Artikel-Eigenschaften, -Optionen, -Varianten ist nicht möglich!
• Zwischen der Anzahl an verfügbaren Lizenzschlüssel und der Lagermenge eines Artikels gibt es keinen Abgleich. Der Shop-Administrator ist dafür verantwortlich das beide Mengen in ausreichender Anzahl verfügbar sind. Nur wenn eine Bestellung auf Grund einer zu geringen Anzahl an verfügbaren Lizenzschlüsseln nicht vollständig bedient werden kann wird der Shop-Administrator benachrichtigt (siehe Kapitel Mindermenge: Die Anzahl der verfügbaren Linzenzschlüssel ist kleiner als die Bestellmenge).
• Innerhalb eines Lizenzschlüssel-Strings sind keine HTML-Tags erlaubt. HTML-Tags innerhalb eines Lizenzschlüssels werden als String ausgegeben.

Häufige Fehler

Fehler
Nach Modul-Installation fehlt unter [root]/GXModules/LW/Licenses die Datei securityConfig.json.
Ursache
Dem Ordner [root]/GXModules/LW/Licenses sind auf dem Webspace keine ausreichenden Schreibrechte zugewiesen.
Lösung
Das Modul wieder deinstallieren, dem Ordner [root]/GXModules/LW/Licenses die nötigen Schreibrechte zuweisen und das Modul wieder installieren.

Fehler
Nach Modul-Installation erscheint bei Aufruf des ModuleCenters die Fehlermeldung Call to undefined function GXModules\LW\Licenses\sodiumcrypto....
Ursache
Auf dem Shop-Webspace fehlt die PHP-Bibliothek Sodium.
Lösung
Für die Ver-/Entschlüsselung der Lizenzschlüssel kommt die PHP-Bibliothek Sodium zum Einsatz. Die Bibliothek wird seit PHP 7.2 im Core ausgeliefert. Es kann sein, das diese auf Ihrem Webspace deaktiviert wurde. Prüfen können Sie das, in dem Sie im Shop-Admin-Bereich Server Info aufrufen. In der Sektion PHP Version finden Sie eine Liste mit allen installierten/aktiven PHP-Bibliotheken. In der alphabetisch nach Bibliothek-Namen sortierte Liste sollten Sie einen Eintrag für Sodium finden. Ist kein Eintrag vorhanden, ist die Bibliothek nicht installiert. Ist ein Eintrag vorhanden aber die Info zeigt disabled an, ist die Bibliothek deaktiviert. In beiden Fällen nehmen Sie bitte Kontakt mit Ihrem Webhoster auf um die Bibliothek installieren/aktivieren zu lassen.

Fehler
Nach Modul-Installation werden einem Artikel keine Lizenzschlüssel zugewiesen. In der Bestell-Detailansicht ist nichts zu finden und es wird keine Lizenzschlüssel-Mail an den Kunden versendet.
Mutmaßliche Ursache
Ob ein Artikel den Lizenzschlüsselprozess unterstützt oder nicht wird ermittelt, in dem abgefragt wird, ob bei dem Artikel jemals ein Lizenzschlüssel hinterlegt wurde. Der Prozess verarbeitet den Artikel nicht, weil vermutlich vergessen wurde unter dem Artikel Lizenzschlüssel anzulegen.
Lösung
Lizenzschlüssel unter dem Artikel anlegen.

Fehler
Der CronJob läuft auf Fehler.
Mutmaßliche Ursache
Es wurde vergessen die Modul-Konfiguration vorzunehmen.
Lösung
In der Modul-Konfiguration müssen Werte für Zeitraum für verarbeitende Bestellstatusänderungen in Minuten und/oder Bestellstatus E-Mail-Versand Lizenzschlüssel vergeben werden.

Fehler
In der Bestell-Detailansicht steht bei einem Artikel der Text Fehlende Lizenzschlüssel werden nachgereicht.
Ursache
Der betroffene Bestell-Artikel hat keine für die Bestellung ausreichend verfügbare Menge an Lizenzschlüssel.
Lösung
Dem Artikel müssen neue Lizenzschlüssel hinzugefügt werden. Anschließend muss der betroffenen Bestellung ein Status zugewiesen werden, welcher die E-Mail an den Kunden auslöst.

Fehler
In der Bestell-Detailansicht steht bei einem Artikel der Text Lizenzschlüssel wurden noch nicht zugewiesen!.
Ursache 1
Die Bestellung wurde vom CronJob noch nicht verarbeitet.
Lösung 1
Beim nächsten Lauf des CronJob werden die Lizenzschlüssel zugewiesen und der Text ist verschwunden.
Ursache 2
Der Bestellung konnten kein einziger Lizenzschlüssel zugeordnet werden, da alle Bestell-Artikel keine verfügbaren Lizenzschlüssel haben.
Lösung 2
Bei den Bestell-Artikeln muss eine ausreichende Anzahl an Lizenzschlüsseln hinzugefügt werden. Anschließend muss der betroffenen Bestellung ein Status zugewiesen werden, welcher die E-Mail an den Kunden auslöst.