GREYHOUND Erweiterungen

GREYHOUND Erweiterungen ermöglichen das Verknüpfen von GREYHOUND mit anderen Systemen sowie das Entwickeln individueller Lösungen im Rahmen von GREYHOUND.

Diese Dokumentation beschreibt die Einbindung von Drittsystemen in den GREYHOUND Client und wurde für Integrationspartner, Administratoren und Entwickler geschrieben. Entsprechende Vorkenntnisse werden also vorausgesetzt.

Eigene Erweiterungen für GREYHOUND entwickeln

Neben der Interaktionsmöglichkeit über die XML-RPC und JSON-RPC Schnittstelle bietet GREYHOUND die Möglichkeit, andere Systeme direkt in die Programmoberfläche des GREYHOUND Client zu integrieren.

Konzept

Das Konzept sieht vor, dass Drittsysteme Daten via HTTP(S) als Mini-Webseite bzw. Widget zur Verfügung stellen. Diese Mini-Webseiten bzw. Widgets nennen wir “Erweiterungen”. Jede Erweiterung ist also eine kleine Webseite, welche Daten aus dem Drittsystem abruft und mit HTML, CSS und JS für den Benutzer aufbereitet und darstellt. Diese Erweiterungen werden im GREYHOUND Client an verschiedenen Stellen dargestellt:

Als eigenes Formular (Eigenes Fenster, ohne Abbildung).
Als eigenes Modul im Hauptfenster (Modul Tab).
Als eigenes Modul in der Sidebar (Sidebar Tab).
Als eigenes Modul in der Vorschau von Elementen (Vorschau Tab).
Als Zeile oberhalb der Feldansicht (Vorschau Zeile).

Modul Tab

Als eigenes Modul im Hauptfenster (Modul Tab).

Sidebar Tab

Als eigenes Modul in der Sidebar (Sidebar Tab).

Vorschau Tab links

Als eigenes Modul in der Vorschau von Elementen links abgeordnet (Vorschau Tab links).

Vorschauzeile

Als Zeile oberhalb der Feldansicht (Vorschauzeile)

Vorschau Tab rechts

Als eigenes Modul in der Vorschau von Elementen rechts abgeordnet (Vorschau Tab rechts).

Außerdem sind Hintergrundaufrufe von URLs möglich (Stichwort: Tracking). Eine Erweiterung kann auch den Aufruf einer Webseite im Standard-Webbrowser, den Start oder die Fernsteuerung einer Drittapplikation (via WM_COPYDATA) abbilden.

Die Daten einer Erweiterung können immer dann aktualisiert werden, wenn der Benutzer ein anderes Element im GREYHOUND Client öffnet. Dies ist unabhängig davon, wo die Erweiterung eingebunden ist und gilt auch für den Aufruf von Drittapplikationen. Die meisten Erweiterungen lassen sich auch per Knopfdruck im Erweiterungs-Menü des Hauptfensters oder über das erweiterte Kontextmenü (Strg+Rechtsklick) aktivieren oder aktualisieren.

GREYHOUND kann bei jedem Aufruf bzw. jeder Aktualisierung einer Erweiterung verschiedenste Variablen zur Verfügung stellen, welche es ermöglichen, innerhalb der Erweiterung die gewünschten oder passenden Daten zu beschaffen. Die Variablen werden der HTTP-Anfrage wahlweise per GET oder POST zur Verfügung gestellt. Als Variablen können beispielsweise auch Login-Daten für das Drittsystem zur Verfügung gestellt werden. Dieses Vorgehen empfiehlt sich aber nur bei der Verwendung von SSL.

Konfiguration einer Erweiterung

Eine in GREYHOUND konfigurierte Erweiterung könnte beispielsweise so aussehen:

Diese Erweiterung wird bei jedem Wechsel eines Elements automatisch aktualisiert. Dabei wird die URL http://localhost/ghextension/ mit einigen GET-Parametern aufgerufen. Die Domain localhost ist in diesem Beispiel die Testumgebung. Die übergebenen GET-Parameter zeigen einige Möglichkeiten für Variablen. Neben der ID und dem Namen/Betreff des Elements, welches die Aktualisierung ausgelöst hat, wird die Farbe (als Hexadezimal-Wert) eines Panels und der Typ der Erweiterung an die Webseite übergeben. Die Liste aller verfügbaren Variablen befindet sich im Kontextmenü des Eingabefeldes. Die Bedeutung der Variablen erklärt sich in der Regel selbst.

Die Eindeutige ID der Erweiterung wird später bei der Interaktion von mehreren Erweiterungen wichtig. Beispielsweise wenn durch eine Erweiterung, welche in der Vorschauzeile eingebunden ist, eine andere Erweiterung geöffnet werden soll. Die eindeutige ID sollte so gewählt werden, dass diese nicht mit Erweiterungen anderer Anbieter kollidiert. Es ist also ratsam, über den Namen des Autors bzw. des Unternehmens einen eigenen Namensraum zu definieren. In obigem Beispiel wäre das Company_.

Die zur Verfügung stehenden Variablen können über den gleichnamigen Reiter erweitert werden. So können beispielsweise neue Variablen gewonnen werden, indem zum Beispiel der Name/Betreff nach einer Kundennummer über einen regulären Ausdruck durchsucht wird. Die Variable Hallo steht im o.g. Beispiel im Kontextmenü bereits zur Verfügung (siehe vorheriger Screenshot).

Eine Variable mit dem selben Namen kann mehrfach angelegt werden. Dadurch ergibt sich folgende Möglichkeit: Die Kundennummer soll zunächst im selektierten Text gesucht werden. Das gibt dem Benutzer die Möglichkeit, die Kundennummer beispielsweise im Nachrichtentext auszuwählen. Wenn kein Text selektiert ist oder wenn die Selektion keine gültige Kundennummer enthält, kann im Betreff weitergesucht werden. Findet sich auch hier keine Kundennummer, kann ein statischer Text vergeben werden. Natürlich sind auch andere Szenarien denkbar. Die Reihenfolge der Variablen kann über die Knöpfe ganz rechts in der Toolbar verändert werden.

Die hier konfigurierten Variablen werden an die aufgerufene Webseite alle per POST übermittelt. Dabei wird immer der Content-Type application/x-www-form-urlencoded mit der Zeichenkodierung ISO-8859-15 verwendet. Die UTF-8 Unterstützung ist in dieser GREYHOUND Client-Version leider nicht vorgesehen. Ob eine Variable via POST an den Server gesendet wird, kann bei der Konfiguration der Variable jeweils festgelegt werden:

Wenn die Checkbox Die Variable als POST-Variable zur Verfügung stellen angehakt ist, wird die Variable in der Auflistung mit einer kleinen Sprechblase dargestellt.

Als Variablentyp stehen folgende Möglichkeiten zur Verfügung:

Gesamter Text: Dies kann der Text des Elements sein, wenn ein Element ausgewählt wurde. Falls die Erweiterung beispielsweise für Gruppen ausgeführt wurde, können hier die Namen sämtlicher Gruppen stehen. Die beste Möglichkeit für die Ermittlung der zur Verfügung stehenden Daten ist eine Ausgabe der Variable innerhalb der Erweiterung.
Selektierter Text: Der aktuell ausgewählte Text. Dies kann ein Teil eines Elements sein oder der Name der aktuell ausgewählten Gruppe. Die Daten stammen immer aus dem aufrufenden Modul, wenn die Erweiterung über das erweiterte Kontextmenü (Strg+Rechtsklick) aufgerufen wird.
Systemvariable: Stellt verschiedene Variablen zur Verfügung. Je nach Kontext, stehen beispielsweise die Variablen mit dem Prefix Item. zur Verfügung. Wenn die Erweiterung über das Gruppen-Modul ausgeführt wird, stehen beispielsweise keine passenden Variablen für den Prefix Item. zur Verfügung.
Fester Wert: Diese Variable kann als Konstante verwendet werden. Sinnvoll ist dies beispielsweise, wenn Zugangsdaten zum Drittsystem hinterlegt werden sollen.

In diesem Beispiel sind auch die Möglichkeiten für den regulären Ausdruck zu erkennen. Im Feld Index des Wertes kann $0 für das Ergebnis des gesamten Ausdrucks verwendet werden und $1 für die erste Klammerung, $2 für die zweite, usw. Weitere Informationen zu regulären Ausdruck finden sich in der Dokumentation der Skriptsprache.

Bereitstellung der Webseite

Die Webseite kann entweder über einen bestehenden Webserver (ggf. mit PHP) bereitgestellt werden (in dem Fall wird in der Erweiterung die URL eingetragen, unter der die Webseite bzw. das entsprechende PHP Skript erreichbar ist), sie kann aber auch vom GREYHOUND Client bereitgestellt werden.

Der GREYHOUND Client bringt eine eigene PHP Umgebung mit, die eigentlich für die Ausführung der Addons gedacht ist. Normalerweise bezieht der GREYHOUND Client die Addons automatisch vom GREYHOUND Server (der sie wiederum vom GREYHOUND Control Center abruft) und legt sie im Windows-Profil des Benutzers ab. Es lassen sich aber, gerade um die Entwicklung solcher Addons oder ähnlicher Erweiterungen zu vereinfachen, auch eigene PHP Skripte dort ablegen. Der Ordner, in dem der GREYHOUND Client seine PHP Skripte erwartet, liegt unterhalb des Benutzerordners in AppData\Roaming\GREYHOUND. Der Ordner AppData ist standardmäßig unsichtbar, evtl. müssen also im Explorer die versteckten Dateien und Ordner erst angezeigt werden. Dort gibt es ein Unterverzeichnis, das nach dem Ordner benannt ist, in dem der GREYHOUND Client installiert ist, z.B. C-Program Files (x86)-GREYHOUND. In diesem Ordner gibt es einen Unterordner Addons und darin einen Unterordner pro GREYHOUND Server, da unterschiedliche GREYHOUND Server mit unterschiedlichen Addons ausgestattet sein können. Dieser Ordner ist dann gewissermaßen der Document-Root für die PHP Skripte des GREYHOUND Clients. Für eigene Skripte sollte hier ein entsprechender Unterordner angelegt werden, die GREYHOUND Addons werden hier ebenfalls in Unterordnern abgelegt. Der GREYHOUND Client wird die Ordner der Addons, die er vom GREYHOUND Server erhalten hat, bei Updates überschreiben. Alle anderen Ordner, die dort angelegt werden, bleiben jedoch unberührt und können somit für eigene Erweiterungen und Skripte genutzt werden.

Wird dieser Addon-Ordner im GREYHOUND Client für eigene Erweiterungen genutzt, so kann im URL der Erweiterung die Variable [$Extension.Client.Url] verwendet werden. Sie wird dann so aufgelöst, dass sie auf den Ordner mit den Addons verweist (und bereits einen abschließenden Verzeichnis-Trenner enthält).

Beispiel: Um im GREYHOUND Client (im Standard-Installationspfad) PHP Dateien für eine eigene Erweiterung anzulegen, erzeugt man einen Unterordner (z.B. myExtension) im Benutzerprofil und legt dort die Datei (z.B. sidebar.php) an: C:\Users\<benutzername>\AppData\Roaming\GREYHOUND\C-Program Files (x86)-GREYHOUND\Addons\<hostname-oder-ip-des-greyhound-servers>\myExtension\sidebar.php

In der Erweiterung sieht die URL dann z.B. so aus: [$Extension.Client.Url]myExtension/sidebar.php?itemId=[$Item.ID]

Der Vorteil dieser Lösung liegt darin, dass kein eigener Webserver betrieben werden muss, allerdings muss dann der Ordner mit den PHP Skripten (im Beispiel myExtension) in allen Benutzerprofilen angelegt werden, die auf die Erweiterung zugreifen sollen. Dies ist natürlich nur für die Entwicklung von Erweiterungen sinnvoll, wo beispielsweise nur ein einzelner Entwickler Zugriff auf die Erweiterung hat. Soll die Erweiterung unternehmensweit eingesetzt werden, so empfiehlt es sich, die PHP Skripte auf einem eigenen Webserver bereit zu stellen. Soll die Erweiterung Funktionen bereitstellen, die auch für andere GREYHOUND Kunden von Interesse sind, z. B. eine Anbindung an ein verbreitetes Drittsystem, so kann gerne Kontakt mit uns aufgenommen werden, um zu besprechen, ob eine Bereitstellung als GREYHOUND Addon über unsere zentrale Vertragsverwaltung in Frage kommt.

Bereitstellung der Benutzeroberfläche

Die Bereitstellung der Benutzeroberfläche für die Darstellung der Daten und die Benutzerinteraktion kann auf verschiedenen Wegen erfolgen:

Die Benutzeroberfläche wird über die GREYHOUND eigene PHP-Bibliothek erstellt. Die Bibliothek befindet sich im Ordner GREYHOUND\Libraries\php\ghgui\. In dieser Bibliothek werden verschiedene Controls zur Verfügung gestellt, welche ein GREYHOUND ähnliches “Look and Feel” erzeugen. Die Controls basieren auf dem Dojo-Toolkit. Die Dokumentation der PHP-Klassen und Funktionen für die Kapselung des Dojo-Toolkits befinden sich in der Dokumentation der PHP API.
Die Benutzeroberfläche wird mit einer anderen Bibliothek erzeugt. In diesem Fall können die Variablen der Erweiterung für die Farbe von Panels und Linien helfen, ein GREYHOUND “Look and Feel” zu erzeugen.
Die Benutzeroberoberfläche wird im “Look and Feel” der Drittapplikation mithilfe einer eigenen Bibliothek erzeugt.
Die Benutzeroberfläche zeigt nur Daten an, bietet aber wenig/keine Interaktion. In diesem Fall bietet sich ein einfaches Design via CSS mithilfe der Variablen der Erweiterung für die Farbe von Panels und Linien an.

Wir machen hier keine genauen Vorgaben. Wichtig ist uns allerdings, dass die Erweiterung gute Bedienbarkeit und eine ansprechende und passende Optik vereint. So sollte sich die Erweiterung gut in die GREYHOUND Benutzer-Oberfläche integrieren, und zum richtigen Zeitpunkt genau die Informationen bereitstellen die zur effizienten Bearbeitung einer Nachricht benötigt werden.

Der aktuelle native GREYHOUND Windows-Client verwendet zur Anzeige der Erweiterung die im jeweiligen System hinterlegte Internet Explorer-Rendering Engine. Die Version des Browsers richtet sich also nach dem Betriebssystem und der aktuell installierten Internet Explorer-Version. Wir empfehlen deshalb dringend, Erweiterungen mindestens auf Kompatibilität zum IE 8 und IE 9 hin zu prüfen! Die Erweiterungen können und sollen zukünftig aber auch im in Entwicklung befindlichen GREYHOUND Web-Client verwendet werden. Was bedeutet, dass sämtliche verfügbaren Webbrowser Versionen verschiedener Hersteller zum Einsatz kommen können. Wir bitten deshalb darum, dies bereits jetzt in der Planung zu berücksichtigen.

Steuerung des GREYHOUND-Clients über Erweiterungen

Jede Erweiterung hat die Möglichkeit bestimmte Funktionen im nativen GREYHOUND Windows-Client zu steuern. Ermöglicht wird dies über den Protokollhandler greyhound:. Die Möglichkeiten entsprechen denen, welche im Artikel ->GREYHOUND Client fernsteuern beschrieben sind.

Der Aufbau des URI sieht folgendermaßen aus:

greyhound:<Action>?<Parameter1>=<Value1>&<Parameter2>=<Value2>

Die URI könnte nun folgendermaßen lauten, um eine andere Erweiterung mit der eindeutigen ID “Sipdome_Form” aufzurufen:

greyhound:ExecExtension?Identifier=Sipdome_Form

Die URI kann beispielsweise in einem Link im Attribut “href” angegeben werden. In dieser Form wird die Erweiterung allerdings ohne weitere Variablen aufgerufen. Ausgehend davon, dass dieser Aufruf aus der oben beschriebenen Beispielerweiterung heraus erfolgen soll, könnte nun beispielsweise eine bereits ermittelte Kundennummer an die Erweiterung weitergegeben werden. So kann das Drittsystem weitere Daten zum Kundendatensatz anzeigen:

greyhound:ExecExtension?Identifier=Sipdome_Form&CustomerNo=K-123456789-5

Die Variable CustomerNo steht nun zusätzlich zu den bereits in der Erweiterung “Sipdome_Form” definierten Variablen zur Verfügung. Diese Variable wird vor allen anderen Variablen mit dem Namen “CustomerNo” verwendet, sofern sie einen Wert enthält. Die Variable muss in der Zielerweiterung als GET-Parameter übergeben werden, damit sie der Webseite zur Verfügung steht. Einer Übergabe von Daten via POST ist auf diesem Weg nicht möglich. Damit die Systemvariablen für Variablen mit dem Prefix Item. zur Verfügung stehen, muss die ItemID als Parameter des Aufrufs ebenfalls angegeben werden.

Analog zu diesem Beispiel können alle anderen Funktionen des Artikels -> GREYHOUND Client fernsteuern verwendet werden, um eine Interaktion der Erweiterung mit dem GREYHOUND Client zu bewirken.

Übermittlung von Daten via POST

Neben der Übermittlung von Daten über URL-Parameter ist auch die Übermittlung via POST (zum Beispiel von Formularen) möglich. Dies kann sinnvoll sein, etwa wenn sehr viele Daten übergeben werden müssen. URLs werden nach einer (vom Internet Explorer festgelegten Länge) automatisch abgeschnitten. Das Ziel des Formulars (also die action) enthält dann zum Beispiel folgenden Wert: greyhound:NewItem. Weitere Parameter können entweder in der action oder im Formular durch Eingabefelder oder auch versteckte Felder hinzugefügt werden.

<html>
<body>
 <form method="post" action="greyhound:NewItem?Kind=EMail">
  <input type="text" name="Subject" value="Hallo Welt" />
  <input type="submit" value="Neue E-Mail mit Betreff" />
 </form>
</body>
</html>

Wird diese kleine Seite als Erweiterung in GREYHOUND eingebunden, kann eine neue E-Mail mit dem gewünschten Betreff erzeugt werden. Auch hier stehen sämtliche Parameter aus dem Artikel GREYHOUND Client fernsteuern zur Verfügung.