Benutzer-Werkzeuge

Webseiten-Werkzeuge


develop:xmlrpc

Dies ist eine alte Version des Dokuments!


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

Wir benötigen SUN Java in Version 6 (oft auch „1.6“ bezeichnet) oder höher. Die Verwendung von Java-Versionen anderer Hersteller (z.Bsp. IBM Java, GNU GCJ/Classpath, OpenJDK, usw.) wird nicht empfohlen, da auf diesen Plattformen keine Tests durchgeführt wurden.

Jameica und Plugins

Wir benötigen folgende Komponenten:

Das Plugin „jameica.webadmin“ erweitert Jameica um Webfunktionalität mithilfe eines embedded Webservers (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 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 der Webfrontent unter https://<server>:8080/hibiscus.

Installation

Jameica und Hibiscus können wie gehabt installiert werden. Die zusätzlichen Plugins „jameica.webadmin“, „jameica.xmlrpc“ und „hibiscus.xmlrpc“ entpacken wir nun 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.

Richten Sie nun wie gewohnt ein Sicherheitsmedium (Chipkarte, PIN/TAN oder Schlüsseldiskette) ein und legen Sie Ihre Konten an.

XML-RPC-Services aktivieren

Wir klicken oben im Menu auf „Datei>Einstellungen“. Hier werden nun zwei zusätzliche Reiter („Tabs“) angezeigt.

Auf dem Reiter „HTTP“ können wir den TCP-Port einstellen, über den wir anschließend auf den XML-RPC-Service zugreifen. 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!

Wir öffnen nun 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 ueberweisung Abrufen, Erstellen und Löschen von Überweisungen
hibiscus.xmlrpc lastschrift Abrufen, Erstellen und Löschen von Lastschriften
hibiscus.xmlrpc sammelueberweisung Abrufen, Erstellen und Löschen von Sammel-Überweisungen
hibiscus.xmlrpc sammellastschrift Abrufen, Erstellen und Löschen von Sammel-Lastschriften
hibiscus.xmlrpc sepaueberweisung Abrufen, Erstellen und Löschen von SEPA-Überweisungen

Alternativ können die XML-RPC-Services auch manuell in der Konfigurations-Datei cfg/de.willuhn.jameica.xmlrpc.Plugin.properties (im 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.ueberweisung.shared=true
hibiscus.xmlrpc.lastschrift.shared=true
hibiscus.xmlrpc.sammellastschrift.shared=true
hibiscus.xmlrpc.sammelueberweisung.shared=true
hibiscus.xmlrpc.sepaueberweisung.shared=true

Konfiguration prüfen

Wir beenden Hibiscus und starten die Anwendung nun neu. In der Log-Datei „jameica.log“ im 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://<hostname>:8080/xmlrpc/hibiscus.xmlrpc.address
[...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage]    * https://<hostname>:8080/xmlrpc/hibiscus.xmlrpc.konto
[...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage]    * https://<hostname>:8080/xmlrpc/hibiscus.xmlrpc.umsatz
[...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage]    * https://<hostname>:8080/xmlrpc/hibiscus.xmlrpc.ueberweisung
[...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage]    * https://<hostname>:8080/xmlrpc/hibiscus.xmlrpc.lastschrift
[...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage]    * https://<hostname>:8080/xmlrpc/hibiscus.xmlrpc.sammellastschrift
[...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage]    * https://<hostname>:8080/xmlrpc/hibiscus.xmlrpc.sammelueberweisung
[...Datum/Zeit...][INFO][de.....ServiceNotify.handleMessage]    * https://<hostname>:8080/xmlrpc/hibiscus.xmlrpc.sepaueberweisung

(optional) Hibiscus ohne GUI starten

Wenn Sie Hibiscus auf einem Server verwenden wollen und keine grafische Benutzeroberfläche benötigen, können Sie das Jameica-Startscript mit den Parametern „-d“ (um die GUI nicht zu starten) und „-p <Master-Passwort“ (um das Master-Passwort bereits beim Start zu übergeben) ausführen. Alle Log-Ausgaben erscheinen zusätzlich auf der Konsole. Öffnen Sie hierzu eine Shell (Linux), ein Terminal (MacOS) oder eine DOS-Eingabeaufforderung (Windows), wechseln Sie in das Programmverzeichnis von Jameica und geben starten Sie Hibiscus wie folgt:

Betriebssystem Kommando
Windows jameica-win32.exe -d -p <Master-Passwort>
Linux ./jameica.sh -d -p <Master-Passwort>
MacOS ./jameica-macos.sh -d

Hinweise:

  • Das Übergeben des Master-Passwortes wird für MacOS nicht unterstützt.
  • Für Linux können Sie auch das Init-Script „rcjameica“ zum Starten und Beenden verwenden. Es ist für OpenSuSE Linux vorbereitet, kann von Ihnen jedoch auch leicht an Ihre Distribution angepasst werden.

Alternativ können Sie Hibiscus natürlich auch wie gewohnt mit Benutzeroberfläche starten. Der Zugriff auf die XML-RPC-Services funktioniert auch in diesem Betriebsmodus.

XML-RPC-Aufrufe im Detail

Die folgenden Seiten erläutern die verfügbaren XML-RPC-Funktionen im Detail inclusive Code-Beispielen:

Verhalten der Services anpassen

Quoting aktivieren/deaktivieren

  • Konfigurationsdatei: .jameica/cfg/de.willuhn.jameica.hbci.xmlrpc.Plugin.properties
  • Name des Parameters: quoting.char=<Wert>
  • Default-Wert: <keiner>

Einige XML-RPC-Funktionen liefern Listen als Rückgabe-Werte, deren Zeilen durch Doppelpunkt getrennte Spalten enthalten (z.Bsp: Liste der Umsätze (veraltet), Liste der Konten (veraltet) oder 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: .jameica/cfg/de.willuhn.jameica.hbci.xmlrpc.Plugin.properties
  • Name des Parameters: xmlrpc.result.limit=<Wert>
  • Default-Wert: 10000

Einige XML-RPC-Funktionen liefern Rückgabe-Werte in Listenform (z.Bsp. Liste der Umsätze, Liste der Konten oder 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: .jameica/cfg/de.willuhn.jameica.hbci.xmlrpc.Plugin.properties
  • Name des Parameters: xmlrpc.supports.null=<true|false>
  • Default-Wert: true

Der XML-RPC-Standard unterstützt eigentlich keinen NULL-Datentyp. Es existiert jedoch eine Protokoll-Erweiterung, die NULL-Werte in Form des Elementes “<nil/>„ bzw. “<ex:nil/>„ zulässt. Die 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 werden 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


Impressum | Datenschutz
develop/xmlrpc.1320869721.txt.gz · Zuletzt geändert: d.m.Y H:i von willuhn