Connect Addon erstellen

Diese Dokumentation gibt einen Überblick darüber, wie eigene Connect Addons für GREYHOUND erstellt werden können. Zunächst werden einige konzeptuelle Details zu den Connect Addons behandelt. Anschließend wird anhand eines Beispiel-Addons beschrieben, wie man ein Addon für die Entwicklung in GREYHOUND aufsetzt. Danach folgt eine Beschreibung der Dateien, die im Beispiel-Addon angepasst werden müssen, um daraus ein eigenes Connect Addon zu erstellen.

Konzepte

Die Connect Addons erweitern den GREYHOUND Client und ermöglichen es, Auftragsdaten aus einem Quellsystem anzuzeigen, z. B. aus einem Online-Shop oder einem ERP-System. Das Ziel ist dabei, den Benutzern die Arbeit zu vereinfachen, indem sie Informationen, die sie für die Beantwortung von Kundenanfragen benötigen, direkt innerhalb von GREYHOUND einsehen können, ohne erst in eine andere Anwendung wechseln zu müssen.

Addon vs. Erweiterungen

Der Begriff “Addon” bezeichnet ein Paket aus mehreren Dateien. Das sind zum einen die Erweiterungen des GREYHOUND Clients und zum anderen Quellcode Dateien (PHP, JavaScript). die für die Darstellung der Inhalte in den Erweiterungen verwendet werden. Ein Addon enthält üblicherweise die folgenden Erweiterungen:

  • Vorschauzeile: Zusammenfassung von Auftragsdaten zwischen der Nachrichtenliste und dem Nachrichteninhalt
  • Seitenleiste: Anzeige von Auftragsdetails auf der linken Seite (als Karteireiter bei den Filtern)
  • Einstellungsdialog: Konfiguration des Addons (im Erweiterungsmenü)
  • Hilfedialog (im Erweiterungsmenü)
  • Erweitertes Kontextmenü: im Addon nach einem markierten Begriff suchen (z.B. Auftragsnummer in einer E-Mail)
  • WebLink: versteckte Erweiterung, die URLs im Standardbrowser des Systems öffnet (z.B. Sendungsverfolgungs-Links)

Die Inhalte der Erweiterungen werden von PHP-Dateien geliefert, die der GREYHOUND Client über einen integrierten HTTP-Port ausführt. Dieser HTTP-Port ist nur innerhalb des Computers erreichbar, auf dem der GREYHOUND Client läuft, d. h. er kann nicht missbräuchlich über das Netz angesprochen werden.

Shortcuts

Eine wesentliche Komfortfunktion der Addons sind Shortcuts zu Aufträgen, Kunden, Rechnungen und Artikeln. Dabei werden die Auftragsnummer, Kundennummer, Rechnungsnummer und Artikelnummer mit einem Hyperlink hinterlegt. Wird dieser angeklickt, so wird der entsprechende Datensatz direkt im Backend des Quellsystems angezeigt. Das ist ein außerordentlich beliebtes Feature, da man nicht manuell den Suchbegriff kopieren, in die zweite Anwendung wechseln, die entsprechende Eingabemaske aufrufen und die Suche durchführen muss.

Accounts

Um in den Addons die Anbindung mehrerer Quellsysteme (z. B. mehrerer Online-Shops oder ERP-Konten) zu ermöglichen, können im Einstellungsdialog des Addons mehrere Verbindungen (Accounts) angelegt werden. Damit das Addon entscheiden kann, welcher Account für das Abrufen von Daten genutzt werden soll, kann in jedem Account ein Empfänger-Filter festgelegt werden. Wenn ein Element – z. B. eine E-Mail – im GREYHOUND Client angeklickt wird, dann werden die Accounts des Addons der Reihe nach durchlaufen und geprüft, ob der Empfänger dieser E-Mail auf den Empfängerfilter des jeweiligen Accounts passt. Auf diese Weise lassen sich anhand der Empfänger-Adresse z. B. unterschiedliche Online-Shops ansprechen. Der letzte (oder einzige) Account sollte im Empfängerfilter die Standardeinstellung “*” (Wildcard) beibehalten. Dadurch greift er bei allen Empfängeradressen, die nicht bereits von anderen Accounts abgedeckt sind.

Setup

Um ein Connect Addon zu entwickeln, kann entweder ein Beispiel-Addon heruntergeladen und angepasst werden oder ein bereits individualisiertes Addon bei uns angefragt werden.

Beispiel-Addon

Ein Beispiel-Addon kann am Ende diesers Artikels heruntergeladen werden (Datei exampleConnect.zip).

Individualisiertes Addon

Unsere Entwicklungsabteilung kann ein Addon-Paket bereitstellen, das dem Beispiel-Addon entspricht, bei dem aber bereits einige Anpassungen durchgeführt wurden (Datei-/Klassennamen, String-Inhalte, Product-ID, GREYHOUND Erweiterungen). Um ein individualisiertes Addon-Paket anzufragen, schicke bitte eine E-Mail an unsere Entwicklungsabteilung. In der E-Mail benötigen wir folgende Angaben:

  1. Name des Drittsystems (z.B. “Xyz ERP”). Das sollte die offizielle Schreibweise sein. Dieser Name wird z. B. für die Namen der Erweiterungen, Tooltips usw. verwendet, ist also für den Nutzer sichtbar.
  2. Ggf. der technische Name des Drittsystems, sofern sich dieser vom offiziellen Namen unterscheidet. Dieser Name wird unter anderem für den Ordnernamen des Addons verwendet sowie für die Datei- und Klassennamen.
  3. Das Icon für die Erweiterung als PNG-Grafik mit 16×16 Pixeln Auflösung. Dieses Icon wird für die GREYHOUND Erweiterungen, sowie für Anzeige in der Vorschauzeilen-Erweiterung verwendet.

Einrichten des Addons in GREYHOUND

Um die Entwicklung eines Connect Addons zu beginnen, sollten folgende Schritte ausgeführt werden, um das Addon zunächst so einzurichten, dass es im GREYHOUND Client angezeigt wird und die Quelltextdateien bearbeitet und ausprobiert werden können:

  1. Zunächst muss das Addon in dem Ordner abgelegt werden, den der GREYHOUND Client für seinen lokalen HTTP-Port verwendet, um PHP auszuführen. Dieser Ordner befindet sich im Benutzerordner unter AppData\Roaming\GREYHOUND\Pfad-zum-GREYHOUND-Ordner\Addons\Hostname-oder-IP\. Der GREYHOUND Client muss vorher einmal gestartet worden sein, damit der entsprechende Unterordner angelegt wird. Der letzte Ordner im Pfad enthält den Hostnamen oder die IP, die im Verbindungsdialog des GREYHOUND Clients eingetragen wurde. In diesen Ordner wird der Addon-Ordner kopiert, sodass dort der Ordner mit den Dateien previewline.php, sidebar.php usw. existiert. Der Pfad zur previewline.php sollte also so aussehen: Beispiel-Pfad:
    c:\Users\xyz\AppData\Roaming\GREYHOUND\Pfad-zum-GREYHOUND-Ordner\Addons\Hostname-oder-IP\exampleConnect\previewline.php
  2. Anschließend wird der GREYHOUND Client gestartet und unter “Einstellungen > Erweiterungen” die Dateien aus dem Unterordner extensions des Addons importiert. Erweiterungen können über den Toolbar-Button “Erweiterung importieren” oder das Tastenkürzel Strg+Shift+i importiert werden.
  3. Die importierten Erweiterungen werden in der Regel nicht sichtbar sein, weil sie noch keiner Benutzergruppe zugeordnet sind, in der der aktive Benutzer Mitglied ist. Am besten wird nun eine Benutzergruppe für das neue Addon erstellt und der aktive Benutzer in diese Benutzergruppe aufgenommen (unter “Einstellungen > Benutzergruppen“). Über diese Benutzergruppe lässt sich dann steuern, welche Benutzer das Addon angezeigt bekommen.
    Die nicht sichtbaren, neu importierten Erweiterungen können angezeigt werden, indem in der Toolbar der Schalter “Alle Erweiterungen anzeigen” aktiviert wird:

  4. Nun müssen die neuen Erweiterungen jeweils bearbeitet und der für das Addon angelegten Benutzergruppe zugewiesen werden.

Anpassungen

Die GREYHOUND Addons werden üblicherweise unter einer Lizenz erstellt, die der MIT Lizenz entspricht – also Anpassungen erlaubt und den Einsatz sowohl in Closed- als auch OpenSource Software erlaubt. Falls eine andere Lizenz erwünscht ist, so sollte die Datei doc/license.txt sowie der Kommentarblock am Anfang der PHP-Dateien im Hauptordner des Addons und im core-Ordner angepasst werden.

An einigen Stellen (z. B. der Seitenleiste, der Vorschauzeile und den Hauptmenu-Einträgen) wird das Logo des Addons als Icon dargestellt. Falls dieses Icon ausgetauscht werden soll, so muss die Datei lib/images/icon.png ersetzt werden. Das Icon muss eine PNG Grafik der Größe 16×16 Pixel sein. Außerdem müssen alle Erweiterungen des Addons bearbeitet, und dort das neue Icon gesetzt werden. Die so geänderten Erweiterungen müssen dann anschließend einmal exportiert werden und die entsprechenden Dateien im Ordner extensions überschrieben werden.

In der Regel müssen nur wenige Dateien des Addons angepasst werden. Diese werden in den folgenden Abschnitten aufgeführt. Der Übersichtlichkeit halber wird an dieser Stelle die Datei-/Ordnerstruktur des Addons kurz vorgestellt:

exampleConnect/
+ core/
 ghexampleaccount.php  - Account-Klasse (anzupassen)
 ghexampleaddon.php   - Addon-Klasse (anzupassen)
 ghexampledata.php   - Daten-Klasse (anzupassen)
 ghexampleexception.php - Exception-Typ für das Addon
+ doc/
 addon.ini      - Metadaten für den automatischen Rollout über die GREYHOUND Vertragsverwaltung
 license.txt     - Lizenz (ggf. anzupassen)
+ extensions/     - Erweiterungen (ggf. anzupassen)
+ lib/
 + ghAddonFramework/ - Addon-Framework
 + images/
  icon.png     - Icon/Logo des Addons
ajax.php     - Hilfs-Script für AJAX-Calls der anderen Erweiterungen
help.php     - Inhalt des Hilfedialogs
previewline.php - Inhalt der Vorschauzeile
settings.php   - Inhalt des Einstellungsdialogs
sidebar.php    - Inhalt der Seitenleiste

Addon-Dateien

Im Folgenden werden die PHP-Klassen aufgeführt, in denen in der Regel Bearbeitungen nötig sind. Die Stellen in den Dateien, die üblicherweise angepasst werden müssen, sind mit //TODO-Kommentaren gekennzeichnet:

//TODO Auftragsnummer:

$order->OrderNumber = GhAddonData::safeGet($orderData, 'orderNumber');

Addon-Klasse

Die Klasse GhExampleAddon in der Datei core/ghexampleaddon.php repräsentiert das eigentliche Addon. Diese Klasse liefert einige Basisdaten, wie den Namen und die Version des Addons sowie die möglichen Konfigurations-Optionen, die im Einstellungsdialog angezeigt werden. Die Eigenschaft _addonProductId legt die Product-ID fest, unter der im GREYHOUND Server die Einstellungen des Addons gespeichert werden. Diese ID muss eindeutig sein (z. B. ein MD5-Hash über den Namen des Addons), damit nicht zwei unterschiedliche Addons gegenseitig ihre Einstellungen überschreiben. Bei den individualisierten Addons, die von uns bereit gestellt werden, ist bereits sichergestellt, dass die Product-ID nicht von einem anderen Addon verwendet wird. Falls die Product-ID geändert wird, oder eine eigene eingetragen wird, sollte mit unserer Entwicklungsabteilung Rücksprache gehalten werden, um zu vermeiden, dass diese Product-ID bereits bei einem anderen Addon verwendet wird.

Die Addon-Klasse enthält Funktionen, die von den anderen Klassen des Addons aufgerufen werden, um zentrale Informationen über das Addon oder globale Einstellungen abzurufen. Die Dokumentation im Quellcode zeigt, wofür die Funktion dient bzw. was sie zurück liefern sollte. So liefert beispielsweise die Methode getAccountOptions die Konfigurations-Optionen eines Accounts für den Einstellungsdialog zurück.

Account-Klasse

Die Klasse GhExampleAccount in der Datei core/ghexampleaccount.php repräsentiert einen Account mit seinen Verbindungsdaten.

Die Account-Klasse enthält die Funktionen zum Abrufen von Daten aus dem Quellsystem. In ihr finden sich einige search-Methoden, z. B. für die Suche nach E-Mail Adressen, Auftrags- und Kunden-IDs sowie sonstigen Suchbegriffen. Diese Funktionen müssen entsprechend ausgefüllt werden, um Daten vom Quellsystem abzurufen. Idealerweise fügt man eine Funktion hinzu, die die eigentlichen Requests an das Quellsystem durchführt und ruft diese dann in den search-Methoden entsprechend auf. Beim Abruf von Daten sollten immer alle Aufträge aller durch die Suche gefundenen Kunden ermittelt werden, da das Addon in einem solchen Fall eine Auswahl der gefundenen Kunden, sowie eine Auswahl der gefundenen Aufträge anbietet. Die Kundenauswahl dient dann dazu, die Auswahl der Aufträge weiter einzuschränken, aber der Nutzer kann auch direkt einen Auftrag auswählen (und damit implizit auch den zugehörigen Kunden).

Die Daten, die aus einer Suchanfrage zurück kommen, werden in ein Objekt der Klasse GhExampleData (s. u.) übergeben, die sich um das Extrahieren der Kunden- und Auftragsdaten für die Anzeige im Addon kümmert.

In der Account-Klasse sind außerdem Funktionen enthalten, die für die Hyperlinks für die oben angesprochenen Shortcuts auf Kunden-, Auftragsnummern usw. zuständig sind. Wenn diese Daten im Quellsystem direkt per Deep-Link angesprungen werden können, so reicht es, wenn die Account-Klasse in den entsprechenden Funktionen die jeweilige URL zurück liefert.

Ist das Quellsystem keine Webanwendung, sondern z. B. eine Desktop-Anwendung, so gibt es auch dort unter Umständen die Möglichkeit, die Anwendung so anzusteuern, dass sie die entsprechenden Datensätze anzeigt. Da dies meist komplizierter als über einfache Deep-Links abläuft, nehmen Sie hierzu am besten Kontakt zu unserer Entwicklungsabteilung auf.

Auftragsdaten-Klasse

Die Klasse GhExampleData in der Datei core/ghexampledata.php repräsentiert eine Liste von Aufträgen und Kunden, die bei einer Abfrage aus dem Quellsystem zurück geliefert wurden.

Die Klasse erhält im Konstruktor die Daten, und befüllt damit Objekte der Klassen GhAddonOrder und GhAddonCustomer. Diese beiden Klassen sind Teil des Addon-Frameworks im Unterordner lib/ghAddonFramework und müssen in der Regel nicht angepasst werden. In GhAddonOrder gibt es zusätzlich zu den einzelnen Eigenschaften wie Auftragsnummer, Zahlungsart usw. auch die Eigenschaft OrderInfo. Dies ist ein Array, in dem die einzelnen Zeilen der tabellarisch ausgegebenen Auftragsdaten in der Seitenleiste des Addons aufgeführt werden. Jeder Eintrag ist ein generisches Objekt mit den Eigenschaften “Icon”, “Caption” und “Value”. Während die anderen Eigenschaften des GhAddonOrder Objekts für die Vorschauzeile, die Datenübernahme und die Textbaustein-Variablen verwendet werden, kann über die OrderInfo exakt festgelegt werden, welche Daten in welcher Reihenfolge in der Seitenleiste des Addons angezeigt werden.

Hilfsfunktionen

Um den Umgang mit Daten aus der Antwort eines API-Aufrufs des Quellsystems zu vereinfachen, enthält die Basisklasse GhAddonData einige statische Hilfsfunktionen. Die Funktionen und ihre Parameter können in der Datei lib/ghAddonFramework/ghaddondata.php nachgeschlagen werden. In der Beispiel-Datenklasse GhExampleData ist bereits Code enthalten, der die Verwendung dieser Hilfsfunktionen zeigt. Auf die Wichtigsten soll im Folgenden dennoch kurz eingegangen werden:

Die Funktion GhAddonData::safeGet($var, $path, [$type, $allowNull, $defaultValue]) liefert Daten aus einem Objekt oder Array $var anhand eines Pfads und konvertiert das Ergebnis in einen gewünschten Typ (üblicherweise einen String). Sind beispielsweise die Währung und der Betrag eines Auftrags in einem Objekt $orderData in einem Unterobjekt in der Eigenschaft totalAmount als Eigenschaften currency und value enthalten, so lassen sie sich wie folgt auslesen – unabhängig davon, ob die Daten als Objekte oder key-value Arrays vorliegen:

$currency = GhAddonData::safeGet($orderData, 'totalAmount/currency');
$totalAmount = GhAddonData::safeGet($orderData, 'totalAmount/value', 'float');

Falls das Objekt $orderData gar keine Eigenschaft totalAmount besitzt, so liefer GhAddonData::safeGet einen leeren String bzw. den Float-Wert 0.0.

Weitere statische Hilfsfunktionen in GhAddonData stehen für das Abrufen von Daten als Array (egal, ob der Wert existiert oder nicht) oder das Formatieren von Zahlen als Währung zur Verfügung (GhAddonData::getArray(), GhAddonData::formatCurrency()).

Um Datums-/Zeitangaben einheitlich zu verarbeiten, verwenden die Addons die Klasse GhRpcDateTime. Diese ist Teil der GREYHOUND PHP API und wird mit dem GREYHOUND Client ausgeliefert. Sie befindet sich im GREYHOUND Installationsordner unter Libraries/php/ghrpc/core/ghrpcdatetime.php. Diese Klasse kapselt eigentlich Datumsangaben in der RPC Schnittstelle von GREYHOUND, aber sie wird der Einfachheit halber auch von den Addons genutzt. Für die Verwendung sind üblicherweise nur der Konstruktor und die format Methode relevant:

$dateValue = GhAddonData::safeGet($orderData, 'date');
$orderDate = new GhRpcDateTime($dateValue);
$orderDateStr = $orderDate->format('d.m.Y') . ' um ' . $orderDate->format('H:i') . ' Uhr';

Dem Konstruktor kann eine Zahl mit einem Unix-Zeitstempel übergeben werden oder ein String mit einem der üblichen Datumsformate (z. B. ISO 8601). Die Format-Funktion akzeptiert dieselben Format-Strings, die auch die PHP-Funktion date verwendet.