Dies ist eine alte Version des Dokuments!
Inhaltsverzeichnis
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:
Name | Version | Download |
---|---|---|
jameica | 1.10 oder höher | http://www.willuhn.de/projects/jameica/download.php |
jameica.webadmin | 1.2 oder höher | http://www.willuhn.de/projects/jameica/download_ext.php |
jameica.xmprpc | 1.1 oder höher | http://www.willuhn.de/projects/jameica/download_ext.php |
hibiscus | 1.12 oder höher | http://www.willuhn.de/projects/hibiscus/download.php |
hibiscus.xmlrpc | 1.0 oder höher | http://www.willuhn.de/projects/hibiscus/download_ext.php |
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.
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. Folgen Sie hierbei der Installations-Anleitung (Schritt „Erste Schritte / Konfiguration“).
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 | konto | Durch Aktivierung dieses Services können wir Konten und Salden abfragen |
hibiscus.xmlrpc | umsatz | Erlaubt das Abfragen der Kontoauszüge |
hibiscus.xmlrpc | ueberweisung | Ermöglicht das Abrufen und Erstellen neuer Überweisungen |
hibiscus.xmlrpc | lastschrift | Ermöglicht das Abrufen und Erstellen neuer Lastschriften |
hibiscus.xmlrpc | sammelueberweisung | Ermöglicht das Abrufen und Erstellen von Sammel-Überweisungen |
hibiscus.xmlrpc | sammellastschrift | Ermöglicht das Abrufen und Erstellen von Sammel-Lastschriften |
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.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
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.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
(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 Tabellen erläutern die nun verfügbaren XML-RPC-Funktionen im Detail:
hibiscus.xmlrpc.konto
Name der Funktion | list |
Verwendung | Abrufen der eingerichteten Konten |
Aufruf-Parameter | <keine> |
Rückgabe-Wert | String[] (String-Array) Jede Zeile des Arrays enthält die Daten zu einem Konto. Die Werte in jeder Zeile sind durch Doppelpunkte getrennt. Aufbau der Zeilen <ID des Kontos>:<Kontonummer>:<BLZ>:<Bezeichnung>:<Kundennummer>: <Kontoinhaber>:<Saldo im Format "0,00">:<Saldo-Datum im Format "dd.mm.yyyy"> |
Name der Funktion | checkAccountCRC |
Verwendung | Prüfung einer Kontonummer-/BLZ-Kombination auf Plausibilität; Prüfsummen-Check der Kontonummer |
Aufruf-Parameter | 1 String BLZ 2 String Kontonummer |
Rückgabe-Wert | boolean. TRUE, wenn die Konto-/BLZ-Kombination korrekt ist, sonst FALSE |
Name der Funktion | getBankname |
Verwendung | Ermitteln des Namens des Kreditinstituts zu einer BLZ |
Aufruf-Parameter | 1 String BLZ |
Rückgabe-Wert | String Name des Kreditinstituts oder ein Leer-String, wenn zu dieser BLZ kein Kreditinstitut gefunden wurde |
hibiscus.xmlrpc.umsatz
Name der Funktion | list |
Verwendung | Abrufen von Umsätzen (Kontoauszügen) aus der Hibiscus-Datenbank |
Aufruf-Parameter | 1 String Suchbegriff 2 String Start-Datum im Format „dd.mm.yyyy“ 3 String End-Datum im Format „dd.mm.yyyy“ Alle drei Parameter sind optional. Falls bei der Suche keine Einschränkungen vorgenommen werden sollen, können auch Leer-Strings oder NULL-Werte übergeben werden. In jedem Fall jedoch müssen 3 Parameter (wenn auch leere) angegeben sein. |
Rückgabe-Wert | String[] (String-Array) Jede Zeile des Arrays enthält die Daten zu einem Umsatz. Die Werte in jeder Zeile sind durch Doppelpunkte getrennt. Aufbau der Zeilen <ID des Kontos>:<Kontonummer Gegenkonto>:<BLZ Gegenkonto>:<Inhaber Gegenkonto>:<Betrag im Format "0,00">: <Valuta-Datum im Format "dd.mm.yyyy">:<Buchungsdatum-Datum im Format "dd.mm.yyyy">:<Verwendungszweck 1>: <Verwendungszweck 2>:<Saldo zu diesem Zeitpunkt im Format "0,00">:<Primanota>:<Kundenreferenz>: <Umsatz-Kategorie>:<Kommentar> |
Name der Funktion | list |
Verwendung | Abrufen von Umsätzen (Kontoauszügen) aus der Hibiscus-Datenbank |
Aufruf-Parameter | 1 Map (struct) Suchparameter Die Map kann folgende Schlüssel enthalten: konto_id (ID des Kontos) art empfaenger_name empfaenger_konto empfaenger_blz id id:min id:max saldo saldo:min saldo:max valuta (im Format „YYYY-MM-DD“) valuta:min (im Format „YYYY-MM-DD“) valuta:max (im Format „YYYY-MM-DD“) datum (im Format „YYYY-MM-DD“) datum:min (im Format „YYYY-MM-DD“) datum:max (im Format „YYYY-MM-DD“) betrag betrag:min betrag:max primanota customer_ref umsatz_typ Endet der Schlüssel auf „:min“ oder „:max“ werden nur Datensätze geliefert, bei denen das zugehörige Attribut (also „id“, „saldo“, „valuta“, „datum“, „betrag“) größer oder gleich bzw kleiner oder gleich als das übergebene Value in der Map ist. Alle Parameter sind optional. Sind keine angegeben, werden ALLE Umsätze aus Hibiscus geliefert. |
Rückgabe-Wert | List<Map> (Liste mit Elementen vom Typ Map bzw. struct) Jedes Element der zurückgelieferten Liste ist eine Map (struct) mit folgenden Schlüsseln: id konto_id empfaenger_name empfaenger_konto empfaenger_blz saldo valuta datum betrag primanota customer_ref umsatz_typ zweck kommentar |
hibiscus.xmlrpc.ueberweisung
Name der Funktion | list |
Verwendung | Abrufen der bisher angelegten Überweisungen aus der Hibiscus-Datenbank |
Aufruf-Parameter | <keine> |
Rückgabe-Wert | String[] (String-Array) Jede Zeile des Arrays enthält die Daten zu einer Überweisung. Die Werte in jeder Zeile sind durch Doppelpunkte getrennt. Aufbau der Zeilen <ID des Kontos>:<Kontonummer Gegenkonto>:<BLZ Gegenkonto>:<Inhaber Gegenkonto>: <Verwendungszweck 1>:<Verwendungszweck 2>:<Betrag im Format "0,00">: |
Name der Funktion | create |
Verwendung | Anlegen einer neuen Überweisung |
Aufruf-Parameter | 1 String ID des Kontos (siehe „hibiscus.xmlrpc.konto.list“) 2 String Kontonummer des Gegenkontos 3 String BLZ des Gegenkontos 4 String Inhaber des Gegenkontos 5 String Verwendungszweck 1 6 String Verwendungszweck 2 7 double Betrag 8 String Termin im Format „dd.mm.yyyy“ Die Parameter 6 und 8 können leer gelassen werden. |
Rückgabe-Wert | NULL wenn die Erstellung der Überweisung erfolgreich verlief. Andernfalls ein String mit der Fehlermeldung |
hibiscus.xmlrpc.lastschrift
Name der Funktion | list |
Verwendung | Abrufen der bisher angelegten Lastschriften aus der Hibiscus-Datenbank |
Aufruf-Parameter | <keine> |
Rückgabe-Wert | String[] (String-Array) Jede Zeile des Arrays enthält die Daten zu einer Lastschrift. Die Werte in jeder Zeile sind durch Doppelpunkte getrennt. Aufbau der Zeilen <ID des Kontos>:<Kontonummer Gegenkonto>:<BLZ Gegenkonto>:<Inhaber Gegenkonto>: <Verwendungszweck 1>:<Verwendungszweck 2>:<Betrag im Format "0,00">: |
Name der Funktion | create |
Verwendung | Anlegen einer neuen Lastschrift |
Aufruf-Parameter | 1 String ID des Kontos (siehe „hibiscus.xmlrpc.konto.list“) 2 String Kontonummer des Gegenkontos 3 String BLZ des Gegenkontos 4 String Inhaber des Gegenkontos 5 String Verwendungszweck 1 6 String Verwendungszweck 2 7 double Betrag 8 String Termin im Format „dd.mm.yyyy“ (9 String Textschlüssel) „04“=Abbuchung, „05“=Einzugsermächtigung Die Parameter 6 und 8 können leer gelassen werden. Parameter 9 kann weggelassen werden. In dem Fall wird der Textschlüssel „05“ verwendet. |
Rückgabe-Wert | NULL wenn die Erstellung der Lastschrift erfolgreich verlief. Andernfalls ein String mit der Fehlermeldung |
Beispiel-Code Java
Das folgende Beispiel ermittelt die Liste der Konten aus Hibiscus. Sie benötigen hierzu das Modul Apache XML-RPC. Ersetzen Sie die Werte in spitzen Klammern (z.Bsp. “<Master-Passwort>”) gegen die von Ihnen genutzten Werte.
import java.net.URL; import java.security.SecureRandom; import java.security.cert.X509Certificate; import javax.net.ssl.HostnameVerifier; import javax.net.ssl.HttpsURLConnection; import javax.net.ssl.SSLContext; import javax.net.ssl.SSLSession; import javax.net.ssl.TrustManager; import javax.net.ssl.X509TrustManager; import org.apache.xmlrpc.client.XmlRpcClient; import org.apache.xmlrpc.client.XmlRpcClientConfigImpl; public class Test { public static void main(String[] args) throws Exception { String url = "https://<Servername>:8080/xmlrpc/"; // Client-Config erzeugen XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl(); config.setBasicPassword(<Master-Passwort>); config.setBasicUserName("admin"); config.setServerURL(new URL(url)); if (url.startsWith("https")) disableCertCheck(); XmlRpcClient client = new XmlRpcClient(); client.setConfig(config); Object[] lines = (Object[]) client.execute("hibiscus.xmlrpc.konto.list",null); if (lines == null) return; // Kein Ergebnis erhalten for (int i=0;i<lines.length;++i) { System.out.println(lines[i]); } } /** * Falls HTTPS aktiviert ist, muessen Sie entweder Java das Jameica-Zertifikat * (Datei->Einstellungen->Zertifikate) bekannt machen. Sie können es mit dem * bei SUN Java mitgelieferten Programm [[http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/keytool.html|keytool]] * importieren oder (NUR ZU TESTZWECKEN!) die Zertifikats-Prüfung abschalten. * Die folgende Funktion tut dies. * @throws Exception */ private static void disableCertCheck() throws Exception { TrustManager dummy = new X509TrustManager() { public java.security.cert.X509Certificate[] getAcceptedIssuers(){return null;} public void checkClientTrusted (X509Certificate[] certs, String authType) {} public void checkServerTrusted(X509Certificate[] certs, String authType) {} }; SSLContext sc = SSLContext.getInstance("SSL"); sc.init(null, new TrustManager[]{dummy}, new SecureRandom()); HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory()); HostnameVerifier dummy2 = new HostnameVerifier() { public boolean verify(String host, SSLSession session) {return true;} }; HttpsURLConnection.setDefaultHostnameVerifier(dummy2); } }
Beispiel-Code Perl
Das folgende Beispiel ermittelt die Liste der Konten aus Hibiscus. Sie benötigen hierzu das CPAN-Modul RPC::XML. Ersetzen Sie die Werte in spitzen Klammern (z.Bsp. „<Master-Passwort>“) gegen die von Ihnen genutzten Werte.
#!/usr/bin/perl use strict; use RPC::XML; use RPC::XML::Client; my $cli = RPC::XML::Client->new('https://<servername>:8080/xmlrpc/'); $cli->credentials("XML-RPC","admin","<Master-Passwort>"); my $resp = $cli->send_request('hibiscus.xmlrpc.konto.list'); die("Keine Antwort vom Server erhalten") unless ($resp); die("Fehler: ".$resp) unless (ref($resp)); # kein korrektes Response-Objekt my $konten = $resp->value; for(@{$konten}) { print $_."\n"; }
Achtung: $resp→value
liefert nicht das Array selbst sondern eine Referenz darauf.
Dieses Beispiel erstellt eine neue Lastschrift:
#!/usr/bin/perl use strict; use RPC::XML; use RPC::XML::Client; my $cli = RPC::XML::Client->new('https://<servername>:8080/xmlrpc/'); $cli->credentials("XML-RPC","admin","<Master-Passwort>"); my @params = ( RPC::XML::string->new("1"), # ID des Kontos RPC::XML::string->new("1234567890"), # Kontonummer Gegenkonto RPC::XML::string->new("12345678"), # BLZ des Gegenkontos RPC::XML::string->new("Max Mustermann"), # Inhaber Gegenkonto RPC::XML::string->new("Test"), # Verwendungszweck 1 RPC::XML::string->new(""), # Verwendungszweck 2 (optional) RPC::XML::double->new(100.99), # Betrag (Achtung - Punkt statt Komma!) RPC::XML::string->new(""), # Termin im Format dd.mm.yyyy (optional) RPC::XML::string->new("05") # Einzugsermaechtigung ); my $resp = $cli->send_request('hibiscus.xmlrpc.lastschrift.create',@params); die("Keine Antwort vom Server erhalten") unless ($resp); if ($resp =~ /ex:nil/i) { # Auftrag erfolgreich angelegt, wenn NULL (= "ex:nil" in XML-RPC) # zurueckgeliefert wurde. print "Auftrag erfolgreich angelegt\n"; } else { print ref($resp)."\n"; die($resp->value); }
Beispiel-Code PHP
Das folgende Beispiel ermittelt die Liste der Konten aus Hibiscus. Sie benötigen hierzu das PHP-Modul XML-RPC. Ersetzen Sie die Werte in spitzen Klammern (z.Bsp. “<Master-Passwort>”) gegen die von Ihnen genutzten Werte.
include("lib/xmlrpc.inc"); $client = new xmlrpc_client("https://admin:<Master-Passwort>@<Servername>:8080/xmlrpc/"); $client->setDebug(0); // alternativ auch "1" oder "2" // Wenn im folgenden Parameter "1" steht, müssen Sie vorher das SSL-Zertifikat aus // Jameica exportieren (Datei->Einstellungen->Zertifikate), es anschliessend mit // "openssl x509 -inform DES -in <datei>.crt -out outcert.pem -text" konvertieren und dann // an "/usr/share/curl/curl-ca-bundle.crt" anhängen (Curl wird von PHP intern für // HTTP-Kommunikation verwendet) // Verwenden Sie "0", wenn der Hostname des Server-Zertifikats (Common-Name, CN) nicht geprüft werden soll. $client->setSSLVerifyHost(1); // Aktiviert/deaktiviert die Prüfung des Server-Zertifikates. $client->setSSLVerifyPeer(1); $msg = new xmlrpcmsg("hibiscus.xmlrpc.konto.list"); $response = $client->send($msg); if (!response) { print("Keine Antwort vom Server erhalten\n"); exit(1); } if ($response->faultCode()) { print("Fehler. Code: ".$response->faultCode()." ".$response->faultString()."\n"); exit(1); } $value = $response->value(); $konten = $value->scalarval(); while ($konto = current($konten)) { print($konto->scalarval()."\n"); next($konten); }
Impressum | Datenschutz