====== Tutorial: Auf Hibiscus via XML-RPC zugreifen ====== ===== Einleitung ===== Dieses Tutorial beschreibt, wie aus anderen Anwendungen und Programmiersprachen heraus auf die Daten von Hibiscus zugegriffen werden kann. Hierbei können beispielsweise Konten und Umsätze abgefragt aber auch neue Überweisungen oder Lastschriften angelegt werden. Auf diese Weise kann zum Beispiel eine Shop-Software prüfen, ob und wann Rechnungen beglichen wurden. Eine Buchhaltungssoftware könnte automatisch eine Überweisung anlegen. ===== System-Voraussetzungen ===== ==== Java ==== Du benötigst Java 8 oder höher. Lade die aktuelle Version von https://adoptopenjdk.net/ herunter und installiere sie. ==== Jameica und Plugins ==== Folgende Komponenten werden benötigt: ^ Name ^ Download ^ | jameica | [[http://www.willuhn.de/products/jameica/download.php]] | | jameica.webadmin | [[http://www.willuhn.de/products/jameica/download_ext.php]] | | jameica.xmlrpc | [[http://www.willuhn.de/products/jameica/download_ext.php]] | | hibiscus | [[http://www.willuhn.de/products/hibiscus/download.php]] | | hibiscus.xmlrpc | [[http://www.willuhn.de/products/hibiscus/download_ext.php]] | Das Plugin "jameica.webadmin" erweitert Jameica um Webfunktionalität mithilfe eines embedded Webservers ([[http://jetty.mortbay.org/jetty/index.html|Jetty]]). "jameica.xmlrpc" setzt auf diesen Webserver auf und erweitert ihn um XML-RPC-Fähigkeiten. Neben Hibiscus selbst wird nun noch "hibiscus.xmlrpc" benötigt, welches die Hibiscus-Daten via XML-RPC bereitstellt. **Hinweis** Der [[http://willuhn.de/products/hibiscus-server|Hibiscus Payment-Server]] enthält bereits alle benötigten Komponenten. Beachte hier jedoch, dass das eine reine Server-Anwendung ist, die nicht über die grafische Benutzer-Oberfläche bedient werden kann sondern nur über das Webfrontend unter [[https://:8080/hibiscus]]. Alle folgenden Hinweise, die sich auf die grafische Benutzer-Oberfläche von Hibiscus/Jameica beziehen, gelten für den Payment-Server nicht. Hier werden alle Aktionen stattdessen über das genannte Web-Frontend ausgeführt. ===== Installation ===== Jameica und Hibiscus können wie gehabt [[handbuch:sonstiges:install|installiert]] werden. Entpacke die zusätzlichen Plugins "jameica.webadmin", "jameica.xmlrpc" und "hibiscus.xmlrpc" anschließend ebenfalls (wie Hibiscus auch) im Verzeichnis "plugins". Fertig. ===== Erster Start ===== Jameica wird wie gewohnt gestartet (mit jameica.sh, jameica-win32.exe, etc.) . Sollten hierbei bereits Fehler auftreten, ist die häufigste Ursache ein Versionskonflikt zwischen den verwendeten Plugins. Bitte beachte die oben angegebenen Versionsnummern. Richte nun wie gewohnt ein Sicherheitsmedium (Chipkarte, PIN/TAN oder Schlüsseldiskette) ein und lege die Konten an. ===== XML-RPC-Services aktivieren ===== Klicke oben im Menu auf "Datei>Einstellungen". Hier werden nun zwei zusätzliche Reiter ("Tabs") angezeigt. Auf dem Reiter "HTTP" kann ein abweichender TCP-Port eingestellt werden, über den anschließend auf den XML-RPC-Service zugegriffen werden kann. Weiterhin kann der Zugriff mittels SSL (also HTTPS) verschlüsselt und durch Authentifizierung mittels Master-Passwort geschützt werden. Sicherheitshinweis: HTTPS und Authentifizierung mittels Master-Passwort sollte nur zum Testen deaktiviert werden! Öffnen den Reiter "XML-RPC". Lediglich die folgenden Services müssen aktiviert werden, um Zugriff via XML-RPC zu erhalten. ^ Plugin ^ Service ^ Beschreibung ^ | hibiscus.xmlrpc | address | Abfragen, Anlegen und Löschen von Adressen im Adressbuch | | hibiscus.xmlrpc | konto | Zugriff auf die Liste der Konten und Salden | | hibiscus.xmlrpc | umsatz | Abfragen der Kontoauszüge | | hibiscus.xmlrpc | sepaueberweisung | Abrufen, Erstellen und Löschen von SEPA-Überweisungen | | hibiscus.xmlrpc | sepalastschrift | Abrufen, Erstellen und Löschen von SEPA-Lastschriften | | hibiscus.xmlrpc | sepasammelueberweisung | Abrufen, Erstellen und Löschen von SEPA-Sammel-Überweisungen | | hibiscus.xmlrpc | sepasammellastschrift | Abrufen, Erstellen und Löschen von SEPA-Sammel-Lastschriften | Alternativ können die XML-RPC-Services auch manuell in der Konfigurations-Datei cfg/de.willuhn.jameica.xmlrpc.Plugin.properties (im [[support:backup#benutzerverzeichnis|Benutzerverzeichnis]]) durch Hinzufügen folgender Zeilen aktiviert werden: hibiscus.xmlrpc.address.shared=true hibiscus.xmlrpc.konto.shared=true hibiscus.xmlrpc.umsatz.shared=true hibiscus.xmlrpc.sepaueberweisung.shared=true hibiscus.xmlrpc.sepalastschrift.shared=true hibiscus.xmlrpc.sepasammelueberweisung.shared=true hibiscus.xmlrpc.sepasammellastschrift.shared=true ===== Konfiguration prüfen ===== Beende Hibiscus und starte die Anwendung nun neu. In der Log-Datei "jameica.log" im [[support:backup#benutzerverzeichnis|Benutzerverzeichnis]] werden nun die URLs der aktivierten Services angezeigt. Beispiel: [...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage] XML-RPC-Services [...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage] * https://:8080/xmlrpc/hibiscus.xmlrpc.address [...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage] * https://:8080/xmlrpc/hibiscus.xmlrpc.konto [...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage] * https://:8080/xmlrpc/hibiscus.xmlrpc.umsatz [...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage] * https://:8080/xmlrpc/hibiscus.xmlrpc.sepaueberweisung [...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage] * https://:8080/xmlrpc/hibiscus.xmlrpc.sepalastschrift [...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage] * https://:8080/xmlrpc/hibiscus.xmlrpc.sepasammelueberweisung [...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage] * https://:8080/xmlrpc/hibiscus.xmlrpc.sepasammellastschrift ===== (optional) Hibiscus ohne GUI starten ===== Wenn du Hibiscus auf einem Server verwenden willst und keine grafische Benutzeroberfläche benötigst, kannst Du das Jameica-Startscript mit den Parametern "-d" (um die GUI nicht zu starten) und "-p (beim Payment-Server stattdessen "jameicaserver.exe") | | Linux | ./jameica.sh -d -p (beim Payment-Server stattdessen "jameicaserver.sh") | | MacOS | ./jameica-macos.sh -d | Hinweise: * Das Übergeben des Master-Passwortes wird für MacOS nicht unterstützt. * Für Linux kann auch das Init-Script "rcjameica" zum Starten und Beenden verwendet werden. Es ist zwar für OpenSuSE Linux vorbereitet, kann jedoch auch an andere Distributionen angepasst werden. ===== XML-RPC-Aufrufe im Detail ===== Die folgenden Seiten erläutern die verfügbaren XML-RPC-Funktionen im Detail inclusive Code-Beispielen: * [[develop:xmlrpc:init|XML-RPC-Verbindungsaufbau]] * [[develop:xmlrpc:address|Adressbuch]] * [[develop:xmlrpc:konto|Konten]] * [[develop:xmlrpc:umsatz|Umsätze]] * [[develop:xmlrpc:einzelauftrag|Überweisungen und Lastschriften]] * [[develop:xmlrpc:sammelauftrag|Sammel-Überweisungen und -Lastschriften]] **Tipp**: Für PHP gibt es unter https://github.com/willuhn/hibiscus.php bereits "gebrauchsfertigen" Code.\\ **Tipp**: Verschiedene Java-Beispiele finden sich unter https://github.com/mathisdt/optigem-spoonfeeder und http://www.zephyrsoft.org/hibiscus-watcher. ===== Verhalten der Services anpassen ===== ==== Quoting aktivieren/deaktivieren ==== * Konfigurationsdatei: [[support:backup#benutzerverzeichnis|.jameica]]/cfg/de.willuhn.jameica.hbci.xmlrpc.Plugin.properties * Name des Parameters: quoting.char= * Default-Wert: Einige XML-RPC-Funktionen liefern Listen als Rückgabe-Werte, deren Zeilen durch Doppelpunkt getrennte Spalten enthalten (z.Bsp: [[develop:xmlrpc:umsatz#liste_der_umsaetze_ermitteln_veraltet|Liste der Umsätze (veraltet)]], [[develop:xmlrpc:konto#liste_der_konten_ermitteln_veraltet|Liste der Konten (veraltet)]] oder [[develop:xmlrpc:einzelauftrag#liste_der_auftraege_ermitteln_veraltet|Liste der Aufträge (veraltet)]]). Die einzelnen Werte der Spalten können optional mit einem beliebigen Quoting-Zeichen - z.Bsp <"> umschlossen werden - für den Fall, dass Werte existieren, die Doppelpunkte enthalten (welcher ja bereits als Spaltentrenner verwendet wird. Beispiel: quoting.char=" ==== Ergebnisliste einschränken ==== * Konfigurationsdatei: [[support:backup#benutzerverzeichnis|.jameica]]/cfg/de.willuhn.jameica.hbci.xmlrpc.Plugin.properties * Name des Parameters: xmlrpc.result.limit= * Default-Wert: 10000 Einige XML-RPC-Funktionen liefern Rückgabe-Werte in Listenform (z.Bsp. [[develop:xmlrpc:umsatz#liste_der_umsaetze_ermitteln|Liste der Umsätze]], [[develop:xmlrpc:konto#liste_der_konten_ermitteln|Liste der Konten]] oder [[develop:xmlrpc:einzelauftrag#liste_der_auftraege_ermitteln|Liste der Aufträge]]). Abhängig von der Anzahl der Zeilen können diese Listen bei der Erstellung sehr viel Speicher verbrauchen. Mit dem Parameter kann die maximale Anzahl von zurückzuliefernden Zeilen beschränkt werden. ==== NULL-Support aktivieren/deaktivieren ==== * Konfigurationsdatei: [[support:backup#benutzerverzeichnis|.jameica]]/cfg/de.willuhn.jameica.hbci.xmlrpc.Plugin.properties * Name des Parameters: xmlrpc.supports.null= * Default-Wert: true Der XML-RPC-Standard unterstützt eigentlich keinen [[http://de.wikipedia.org/wiki/XML-RPC#Null-Datentyp|NULL-Datentyp]]. Es existiert jedoch eine [[http://ontosys.com/xml-rpc/extensions.php|Protokoll-Erweiterung]], die NULL-Werte in Form des Elementes "" bzw. "" zulässt. Die [[http://ws.apache.org/xmlrpc/types.html|Apache-Implementierung]] unterstützt dies beispielsweise. Da NULL-/NUL- bzw. NIL-Werte in verschiedenen Programmiersprachen jedoch Probleme verursachen können, kann das Verhalten des Plugins "hibiscus.xmlrpc" mit diesem Parameter beeinflusst werden. Einige Funktionen des Plugins (insb. Funktionen zum Erstellen neuer Adressen oder Aufträge) liefern per Default im Erfolgsfall NULL zurück und im Fehlerfall einen String mit dem Fehlertext. Falls jedoch die ID des erstellten Datensatzes benötigt wird oder die verwendete Programmiersprache auf Client-Seite keine NULL-Werte unterstützt, kann in die o.g. Datei eine Zeile "xmlrpc.supports.null=false" eingetragen werden. Die betreffenden Funktionen ändern dabei ihr Verhalten. Im Erfolgsfall liefern Sie die ID des erstellten/geänderten/gelöschten Datensatzes zurück. Im Fehlerfall werfen sie eine Exception (Fault). ^ Parameter-Wert ^ Verhalten im Erfolgsfall ^ Verhalten im Fehlerfall ^ | xmlrpc.supports.null=true | return NULL | return Fehlertext | | xmlrpc.supports.null=false | return ID | throws Exception |