GREYHOUND Docs Hilfstools & Addons GREYHOUND Connect Addons

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)

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).

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).

Beispiel-Addon herunterladen

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:

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.
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.
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:

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
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.
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:

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->getFormatted('d.m.Y') . ' um ' . $orderDate->getFormatted('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.

Download “exampleConnect.zip”

Zugriff von GREYHOUND Addons auf Schnittstellen von Drittsystemen

In den meisten Fällen erfolgt der Zugriff vom GREYHOUND Addon entweder über die ID eines Auftrags oder über die E-Mail-Adresse des Kunden (da der Großteil der Kommunikation in der Regel E-Mail-basiert abläuft).

Wird die Suchfunktion im Addon genutzt, so wird (je nachdem, welche Möglichkeiten die Schnittstelle des Drittsystems bereitstellt) anhand der E-Mail-Adresse, des (Nach-)Namens oder der Anschrift des Kunden (Straße, Postleitzahl, Stadt), der Bestellnummer, Kundennummer oder Rechnungsnummer nach Kunden gesucht. Diese gefundenen Kunden werden vom Addon in einer Auswahlliste angeboten. Zusätzlich werden alle Aufträge der gefundenen Kunden in einer zweiten Auswahlliste angeboten (wieder nur die Basisdaten). Wird ein Kunde aus der Kundenliste ausgewählt, so werden nur noch die Bestellungen dieses Kunden abgerufen (über die ID des Kunden) und in der Bestellauswahl angeboten. Wird eine Bestellung aus der Bestellliste ausgewählt, so werden die Details dieses Auftrags über dessen ID abgerufen und angezeigt.

Technisch ergeben sich also im Prinzip zwei Funktionen, die das Addon beim Drittsystem aufruft (die Namen sind nur Vorschläge/Beispiele):

GetOrders (Filter)

Als Filter sollten folgende Kriterien möglich sein:

E-Mail-Adresse des Kunden
Auftrags-ID
Kunden-ID
Bestellnummer
Kundennummer
Rechnungsnummer
Nachname des Kunden
Straße (aus der Anschrift des Kunden)
Postleitzahl (aus der Anschrift des Kunden)
Stadt (aus der Anschrift des Kunden)

Bei Angabe mehrerer Kriterien sollten diese per “oder” verknüpft betrachtet werden, d.h. es soll reichen, wenn eines der Kriterien zutrifft. Der Grund hierfür ist, dass das Addon z. B. bei einer Suche nach einem Suchbegriff, der nur aus Ziffern besteht, nach Aufträgen sucht, in denen dieser Begriff in einem der Felder Bestellnummer, Kundennummer, Rechnungsnummer und Postleitzahl steht. Gut wären als zusätzliche Parameter noch die maximale Anzahl zu liefernder Ergebnisse und ein Offset, um Ergebnisse “seitenweise” abzurufen. Notwendig ist das allerdings nicht, es kann auch ein festes Limit (z .B. max. 100 Ergebnisse) festgelegt werden. Um die Bandbreite (und auch die Laufzeit im Drittsystem) überschaubar zu halten, ist eine Begrenzung der Ergebnismenge sinnvoll:

Limit (max. Anzahl Aufträge, die geliefert werden sollen)
Offset (Start-Index, ab dem die über Limit angegebenen Aufträge gezählt werden)

Als Rückgabe sollte eine Liste mit Aufträgen aller Kunden geliefert werden, auf die die Filterkriterien zutreffen (nicht nur die Aufträge, auf die die Kriterien direkt zutreffen). Bei Angabe einer Auftrags-ID soll also z .B. der Kunde des Auftrags identifiziert werden und dann alle Aufträge des Kunden geliefert werden. Die Aufträge sollten absteigend nach Datum sortiert sein (die neuesten also zuerst). Falls eine Sortierung nicht möglich ist, so ist das nicht dramatisch, die Sortierung kann das Addon auch im Zweifelsfall selbst nachholen. Als Daten wären folgende Felder in den Aufträgen wünschenswert:

Auftrags-ID
Kunden-ID
Bestelldatum
Name und Anschrift des Kunden, z. B. Rechnungsadresse
E-Mail-Adresse des Kunden
Gesamtbetrag des Auftrags (Bestellsumme)
Währung des Auftrags (z. B. EUR, USD)
Bestellnummer
Kundennummer
Rechnungsnummer

Falls es für das Drittsystem nicht gut möglich ist, eine Liste der Aufträge aller über die Filterkriterien gefundenen Kunden zu liefern, so kann das System auch alternativ nur die direkt über die Kriterien gefundenen Aufträge liefern. Das Addon wird dann aus diesen Aufträgen die Kunden-IDs ermitteln und in einem zweiten Aufruf die Aufträge dieser Kunden anhand der Kunden-IDs ermitteln. Technisch ist das unproblematisch, der einzige Nachteil ist hier lediglich, dass ein weiterer Aufruf und erneut Ergebnisdaten über das Netz übertragen werden müssen und so ggf. die Antwortzeit im Addon verlängert.

GetOrderDetails (OrderID)

Als Parameter genügt hier die Auftrags-ID. Das Ergebnis soll der Auftrag mit der passenden Auftrags-ID sein. Es können beliebig viele Details geliefert werden, wünschenswert wären folgende Daten:

Auftrags-ID
Kunden-ID
Bestelldatum
Auftragsstatus (z .B. offen, bezahlt, versendet o.ä.)
Rechnungsadresse des Kunden
Lieferadresse des Kunden (falls keine abweichende Lieferanschrift vorliegt, kann diese natürlich weggelassen werden)
Gesamtbetrag des Auftrags (Bestellsumme) und (falls möglich) Währung
Währung des Auftrags
Verkaufsplattform und Benutzerkennung (falls externe Plattformen unterstützt werden, z. B. “eBay” und der eBay-Name des Kunden)
Zahlungsart
Kosten für die Zahlungsart (manche Anbieter erheben einen Aufschlag auf bestimmte Zahlungsarten)
Datum des Zahlungseingangs
Transaktions-ID der Zahlung (z. B. PayPal-Transaktionsnummer)
Zahlungsziel
Versanddienstleister bzw. Versandmethode
Versandkosten
Versanddatum
Sendungsverfolgungsnummer (ggf. mehrere, falls der Auftrag auf mehrere Sendungen verteilt wird), idealerweise mit Tracking-URLs (andernfalls versucht das Addon, diese anhand der Sendungsnummern selbst festzustellen)
Anmerkungen (zum Auftrag, zu den Zahlungen, zum Kunden usw.)
Bestellte Artikel (siehe unten)

Anmerkung zu den Ergebnisdaten

Adressdaten sollten folgende Felder enthalten:

Firma
Name (Vor- und Nachname, falls sie separat vorliegen gerne getrennt)
Straße und Hausnummer
Adresszusatz (z. B. “2. Etage”)
Postleitzahl
Stadt
Provinz/Bundesstaat (falls vorliegend)
Land (am besten als ISO 3166 ALPHA-2 Code, z.B. “DE” für Deutschland, “US” für USA)

Folgende ergänzende Kundendaten können gerne in den Adressdaten mitgeliefert werden, z. B. wenn sie für Rechnungs- und Lieferadresse separat vorliegen):

E-Mail-Adresse
Telefonnummer
Faxnummer
Mobiltelefonnummer
Geschlecht des Kunden (männlich/weiblich – das ist in der Kommunikation für die Anrede nützlich)
Titel des Kunden (falls vorhanden, z. B. “Prof. Dr.” o.ä.)
Geburtsdatum (das Addon zeigt dieses derzeit nicht an, bietet es aber in Textbausteinen an wenn es vorliegt)

Die bestellten Artikel enthalten idealerweise folgende Daten:

Artikel-ID
Artikelnummer (falls abweichend von der Artikel-ID)
Artikelbezeichnung
Artikelpreis
Anzahl (Bestellmenge)
Gesamtpreis (falls diese nicht vorhanden ist, errechnet das Addon den Preis, indem es die Anzahl mit dem Artikelpreis multipliziert)
Verfügbarkeit / Bestand (falls möglich)
Bearbeitungsstatus (falls möglich, bzw. falls dieser für einzelne Artikel von dem Status des gesamten Auftrags abweichen kann)

Hyperlinks zu Aufträgen, Artikeln, Kundennummern

Im Addon wird – sofern das möglich ist – die Bestellnummer, die Kundennummer und die Artikelnummern mit einem Hyperlink hinterlegt, der beim Anklicken direkt in die Oberfläche des Drittsystems springt und dort den entsprechenden Datensatz aufruft. So kann ein Kundenservice-Mitarbeiter beispielsweise mit einem Klick direkt in einem Auftrag springen, um Daten einzusehen, die das Addon nicht anbietet oder um Änderungen am Auftrag vorzunehmen.

Technisch hängt die Gestaltung dieser Links vom Drittsystem ab. Falls es sich um eine Webanwendung handelt, in der über URL-Parameter Bestellungen, Kunden und Artikel angesprungen werden können, so wäre hier der Aufbau dieser Links interessant. Alternativ können diese URLs natürlich gerne in den Ergebnisdaten von GetOrderDetails mitgeliefert werden. Handelt es sich bei der Oberfläche um eine Desktop-Applikation, so kann das Addon (über den GREYHOUND Client) auch die WM_COPYDATA Schnittstelle von Windows nutzen, um der Anwendung mitzuteilen, dass sie einen bestimmten Auftrag, Kunden oder Artikel anzeigen soll. Hier wäre dann die Information nötig, wie die Fensterklasse der Anwendung heißt, ob im Titel des Fensters bestimmte Begriffe vorkommen, anhand derer die Anwendung möglichst eindeutig identifiziert werden kann, und wie die an die Anwendung zu sendenden Daten aussehen sollen.