Berichte im Web-Portal, als PDF und per E-Mail (BIRT)

2009/04/14

Nachdem wir lokal Berichte mit BIRT erzeugen können, sollten sie auch über ein Webportal abrufbar sein und wir wollen sie automatisch erzeugen und verschicken.

Zu BIRT gehört eine Web-Applikation, die die Report-Dateien aus dem Designer im Webbrowser darstellen und als PDF, Excel und so weiter exportieren kann. Diese Engine läuft in einem Applikationsserver wie Apache Tomcat oder JBoss. Im BIRT-Projekt wird dies beschrieben unter [1]

Um diese Applikation zu nutzen sind folgende Schritte erforderlich:

  1. Tomcat installieren
  2. BIRT Engine in Tomcat installieren und testen
  3. BIRT Engine mit einem Report aus einer Webseite aufrufen
  4. Reports als aus einem Skript heraus erzeugen
  5. PDF-Dateien per Mail verschicken

Tomcat installieren

Die aktuelle Version BIRT 2.3.2 läuft mit Tomcat 5.5, obwohl es schon die Tomcat 6 gibt. Meine Versuche mit Tomcat 6 waren nicht sehr erfolgreich, also bleibe ich erst mal bei 5.5.

Tomcat wiederum läuft auf JRE 6. Zuerst stellen wir also sicher, dass JRE6 SE betriebsbereit ist. Falls nicht vorhanden, kann man JRE 6 SE von [2] laden.

Das Windows Binary von Tomcat 5.5 liegt auf [3] Am einfachsten ist das Binary mit Installer. Nach der Installation muss der Tomcat manuell gestartet werden; entweder mit der Frage am Ende der Installation oder über das Startmenü.

Tomcat nistet sich im Tray mit einem Symbol ein. Das Systemmenü von Tomcat kann man dort mit der rechten Maustaste erreichen.

tomcat_05

Achtung: Tomcat läuft, einmal gestartet, als Dienst, das heisst auch ohne das Tray-Symbol.

Mit dem Webbrowser kann man unter http://127.0.0.1:8080 nachsehen, ob alles funktioniert.

tomcat_01

BIRT-Viewer in Tomcat installieren

Viele Details dazu stehen auf [4] Hier kommt die Kurzfassung.

Zuerst brauchen wir das BIRT-Binary. Das steht auf [5] Wir brauchen die Datei „Runtime“ unter Deployment. Das Zip-File packen wir erst mal in ein temporäres Verzeichnis aus.

Als nächstes suchen wir das Tomcat-Installationsverzeichnis. Unter Windows dürfte das „c:\Programme\Apache Software Foundation\Tomcat 5.5“ sein. Darin findet sich das Verzeichnis webapps, in dem alle Tomcat-Applikationen installiert werden, jede Applikation in einem eigenen Unterverzeichnis. In dieses Unterverzeichnis webapps kopieren wir aus dem temporären Auspackverzeichnis der BIRT-Runtime das Unterverzeichnis WebViewerExample. Schliesslich benennen wir das kopierte Verzeichnis um in birt-viewer.

Um die Applikation zu aktivieren müssen wir den Tomcat einmal stoppen und wieder starten; am einfachsten mit der rechten Maustaste auf das Tomcat-Tray-Icon. Im Browser rufen wir wieder die Startseite von Tomcat auf – http://127.0.0.1:8080/ – und klicken auf „Tomcat Manager“. In der Liste der Anwendungen muss birt-viewer auftauchen.

tomcat_02

Für einen ersten Funktionstest der Web-Applikation klicken wir auf „birt-viewer“ in der Tomcat-Liste. Das Eclipse-Symbol und die Bemerkung „BIRT viewer has been installed“ sollte angezeigt werden.

tomcat_03

Mit einem Klick auf „View Example“ sollte der Report Viewer angezeigt werden und uns zur korrekten Installation beglückwünschen.

tomcat_04

MySQL-Treiber installieren und eigenen Report testen

Auch in der Web-Applikation muss der MySQL-Treiber installiert werden, bevor wir den Test-Report abrufen können. Der Treiber ist wieder die Jar-Datei aus dem vorherigen Beitrag. Diesmal muss sie in das Verzeichnis „WEB-INF\platform\plugins\org.eclipse.birt.report.data.oda.jdbc_2.3.2.r232_v20090212\drivers\“ im birt-viewer-Verzeichnis kopiert werden.

Dann muss der Test-Report in Reichweite der Engine gebracht werden. Es ist die Datei kpi-report1.rptdesign aus dem Workspace des Report-Designer, die nach birt-viewer\Report kopieren.

Im Browser können wir jetzt den Report im BIRT-Viewer direkt aufrufen: http://localhost:8080/birt-viewer/frameset?__report=Report\kpi-report1.rptdesign. Gezeigt wird der komfortable Webviewer mit Frames und Export-Möglichkeiten. Die Engine bietet auch eine web-only, report-only Ansicht, wenn man sie mit run statt frameset aufruft: http://localhost:8080/birt-viewer/run?__report=Report\kpi-report1.rptdesign

Insgesamt kennt die Engine folgende Parameter:

  • __format: Output format. „html“ oder „pdf“.
  • __isnull: Definiert einen reportParameter als Null
  • __locale: Setzt die Java Sprachvorwahl (locale), wie en, de, en-us oder ch-zh. Default: Java-Default
  • __report: Pfad zur Report-Datei
  • __document: Pfad zum erzeugten Dokument, wenn run und frameset getrennt benutzt werden.
  • reportParameter: Ein Parameter, wie im Report design definiert.

Zulässig sind…

  • … in frameset: __locale, __report, __document, reportParam
  • … in run: __format, __isnull, __locale, __report, reportParam

Beispiel: http://localhost:8080/birt-viewer/run?__format=pdf&__report=Report\kpi-report1.rptdesign&mypara=17

Wichtig bei Parametern und Pfaden: Alles muss URL-kompatibel sein. Bei Leerzeichen oder Umlauten muss gegebenenfalls urlencode() verwendet werden.

Eine vollständige Beschreibung aller Argumente für die Engine steht unter [6].

Der Pfad zur Report-Datei kann absolut oder relativ angegeben werden. Für relative Pfade sucht die Engine mit Hilfe der beiden Settings BIRT_VIEWER_DOCUMENT_FOLDER und BIRT_VIEWER_WORKING_FOLDER in der Datei web.xml im birt-viewer. Wenn die Datei darüber nicht gefunden werden kann, wird das Verzeichnis birt-viewer als Basis genommen.

In der web.xml können auch verschiedene andere Einstellungen gesetzt werden.

Reports aus PHP heraus erzeugen und an den Browser ausliefern

Natürlich können wir die Reports einfach als Link auf die Engine anbieten. Damit liefern wir den Anwendern aber zum einen viele Informationen über unsere Installation und die Reports. Zum anderen ist offen, ob er überhaupt auf den Report-Server und die Portnummer des Tomcat zugreifen kann.

Wir können aber den Aufruf der BIRT-Engine in einem PHP-Skript verbergen und so tun, als ob dieses Skript den Report ausliefert:

<?php
$r = fopen('http://127.0.0.1:8080/birt-viewer/run?__report=Report\kpi-report1.rptdesign&__format=pdf', 'r');
if(!$r) { print "Kann Report nicht öffnen!"; exit; }
header('Content-Type: application/pdf');
fpassthru($r); // gesamte Datei an den Browser liefern
?>

Dieses Skript benutzt die Wrapper-Funktionen, durch man eine URL wie eine Datei öffnen kann. Hier geht natürlich nur die run-Methode der Engine und sämtliche Parameter für den Report müssen bereits beim Aufruf in der URL übergeben werden.

Je nach Laufzeit muss hier unter Umständen ein set_time_limit() eingefügt werden, wenn die Engine länger braucht.

Etwas ähnliches steht unter [7] beschrieben, aber die dortige bewirkt eine Umleitung des Browsers, womit die Original-URL der Engine wieder dem Empfänger bekannt gegeben würde; siehe oben.

Report als PDF erzeugen und abspeichern

Zum Schluss sollen Reports automatisch erzeugt und per Mail verschickt werden. Mit PHP sieht das so aus:

<?php
$rname = 'kpi-report1';
$wname = $rname . '_' . date('Ymd_Hi') . '.pdf';
$pdf = file_get_contents("http://127.0.0.1:8080/birt-viewer/run?__report=Report\\" . $rname . ".rptdesign&__format=pdf");
file_put_contents($wname, $pdf);
?>

Wieder wird der Wrapper benutzt. Der Report wird als PDF komplett geladen und dann in die Zieldatei gespeichert. Als Komfort-Add-on hängen wir einen Zeitstempel und die Dateiendung an den Namen an.

Dieses Skript kann aus einem Batchfile heraus aufgerufen werden, das wiederum zyklisch durch den Windows Scheduler („Geplante Tasks…“) oder unter Linux per cron gestartet werden kann.

Die andere Methode für den Aufruf der Engine führt über Java. Das ist beschrieben in [8] und [9]. Da dies aber für unsere bisherigen Zwecke keine Vorteile bietet, belasse ich es bei den Links.

Oh, Mailversand! PDFs sollten wir als ordentlichen Anhang verschicken. Das geht mit mail() in PHP nicht so einfach. Ich habe gute Erfahrungen mit der SMTP-Klasse von [10] gemacht, aber auf phpclasses.org finden sich verschiedene andere Lösungen, zum Beispiel [11]. Damit sieht der Versand der PDF-Datei oben so aus:

<?php
$mail = new attach_mailer
( $name = "Mein Name",
$from = "me@mymail.com",
$to = "you@gmail.com",
$cc = "kopie@provider.org",
$bcc = "blind@copy.org",
$subject = "Report", $body = "Was zum Report zu sagen ist"
);
$mail->create_attachment_part($wname);
$mail->process_mail();
?>

Links

[1] http://www.eclipse.org/birt/phoenix/deploy/viewerSetup.php
[2] http://java.sun.com/javase/downloads/
[3] http://tomcat.apache.org/
[4] http://www.eclipse.org/birt/phoenix/deploy/viewerSetup.php
[5] http://download.eclipse.org/birt/downloads/
[6] http://www.eclipse.org/birt/phoenix/deploy/viewerUsage.php
[7] http://www.eclipse.org/birt/phoenix/deploy/usingPHP.php
[8] http://www.theserverside.com/tt/articles/article.tss?l=IntegratingBIRTwithPHP
[9] http://www.birt-exchange.com/devshare/deploying-birt-reports/743-calling-birt-from-php/
[10] http://www.phpclasses.org/browse/package/1044.html
[11] http://www.phpclasses.org/browse/package/2822.html

Advertisements

Berichte für lau

2009/04/09

Freie Report-Tools gibt es einige, aber die meisten können nur einfache tabellarische Darstellungen. Excel-Anwender sind aber verwöhnt und möchten schicke Tabellen und dazu passende Grafiken schön seitenweise angeordnet haben. Warum auch nicht. Ob die Zahlen dau aus einer handgepflegten Tabelle kommen oder einer Datenbank sollte ja keinen Unterschied machen.

Unser Tool sollte ausserdem eine einigermassen zuverlässige Entwicklerbasis haben. Bei Open Source Software achte ich normalerweise darauf, ob noch regelmässig am Projekt gearbeitet wird und wie groß die Gruppe ist. Wenn es dann noch Teil eines größeren, aktiven Projekts ist, stehen die Chancen gut, dass es weiter gepflegt wird.

Für mich ist derzeit Eclipse BIRT das Reporting-Tool der Wahl. Eclipse ist ein sehr großes Open Source Projekt für eine Software-Entwicklungsumgebung. Es besteht aus einer Basis-Oberfläche, die mit Plug-Ins und Add-Ons erweitert werden kann. Man kann nicht nur in Java, C/C++ oder PHP programmieren, sondern eben auch mit dem BIRT-Plug-In Reports erstellen oder mit dem BPEL-Plug-In Business-Prozesse modellieren.

Eclipse läuft auf allen gängigen Plattformen, die eine Java Runtime-Umgebung bieten. Es besteht zum einen aus dem Report-Designer, mit dem man Reports erstellen, testen und drucken kann, inklusive Export nach PDF, Excel und so weiter. Das reicht schon mal für Einzelanwender, die lokal für sich Berichte erstellen wollen.

Die zweite Komponente ist die Report-Engine, die in einem Java-Applikationsserver installiert wird. Damit kann man lokal erstellte Reports in einem Web-Portal bereitstellen. Beim Aufruf können sogar Parameter abgefragt werden. Den Abruf kann man natürlich auch automatisieren. Das werden wir uns zunutze machen, um zeitgesteuert Berichte zu erzeugen und zu versenden.

Eclipse/BIRT installieren

Für Windows-Anwender ist die einfachste Art der direkte Download von der Projektseite http://download.eclipse.org/birt/downloads/ und dort den Button „All-In-One“. Die Zip-Datei packt man in ein neues Verzeichnis irgendwo auf der Platte aus. Das ist alles. Die Datei eclipse.exe kann direkt gestartet werden.

Wer nicht auf Windows arbeitet findet unter „More Downloads“ auch eine Version für Linux und den BIRT Report-Designer als Plug-In für eine vorhandene Eclipse-Umgebung. Wie man das Plug-In installiert steht unter http://www.eclipse.org/birt/phoenix/build/#updating

Kontakt zur Datenbank

Für die Verbindung zu unserer MySQL-Datenbank benötigen wir noch einen JDBC-Treiber. Den gibt es bei MySQL.com unter dem Namen „MySQL Connector/J“ auf der MySQL-Downloadseite. Windows-User laden am besten die Zip-Version. Aus diesem Archiv kopieren wir die Datei mysql-connector-java-5.1.6-bin.jar (oder die gerade aktuelle Version) erst mal in das Eclipse-Verzeichnis. Sie wird später bei unserem ersten Report integriert.

Erststart, Datenquelle und erster Report

Ziel des ersten Berichts ist eine Wochenübersicht ausgewählter Messwerte als Kreuztabelle und Grafik. Die Kreuztabelle soll die Namen der Messstellen zeilenweise auflisten und das Tagesdatum als Spalten. Zeilen- und Spaltensummen sind selbstverständlich. Die Grafik soll für jeden Tag der Woche die Tageswerte der Messstellen übereinander gestapelt anzeigen. Los geht’s:

  • Eclipse.exe starten
  • Workspace auswählen, optional: Neuen Ordner anlegen (empfohlen)
  • Für Erstanwender ist es auch empfehelnswert, den „Overview“ anzugucken
  • Danach „To Workbench“ – Zur Arbeitsumgebung
  • Zuerst ein neues Projekt anlegen: File / New / Project… / Business Intelligence and Reporting Tools / Report Project. Name „KPI“.
  • Eclipse fragt, ob es die Oberfläche entsprechend anpassen soll: „Open Perspective?“; ja, das ist eine gute Idee.
  • Im neuen Projekt einen neuen Report anlegen: File / New / Report;Parent Folder: KPI;File name: „kpi-report1.rptdesign“;Type of Report: „Blank Report“

Datenquellen

Um echte Daten in den Report einzufügen brauchen wir mindestens eine Datenquelle (Data Source). Das ist bei uns unsere MES-Datenbank. Das Hinzufügen geht so: Data / New Data Source / Create from a data source in the following list / JDBC Data Source. Data source name: „KPI“. Der Name ist willkürlich.

Jetzt wird einmalig der MySQL-Datenbank-Treiber mit BIRT verbunden: „Manage Drivers…“ / Tab „JAR Files“ / „Add…“. Wenn der mysql-driver im Eclipse-Verzeichnis liegt, steht er in der Liste. Einfach auswählen und Okay klicken.

Weiter mit der Definition der Datenquelle:

  • Zurück in „Create a new data source. Driver class: „com.mysql.jdbc.Driver (v5.1)“ wählen, das ist der eben hinzugefügte Treiber
  • Die Driver URL enthält Verbindungstyp, Datenbanktyp und die Verbindungsparameter nach dem Schema: „jdbc:mysql://[host][,failoverhost…][:port]/[database]“. Bei lokaler Datenbank kann man das meiste weglassen: „jdbc:mysql:///mes“, wobei „mes“ der Datenbankname in MySQL ist. Näheres steht in der Dokumentation zum Treiber unter http://dev.mysql.com/doc/refman/5.1/en/connector-j-reference-configuration-properties.html
  • Zum Schluss: Username und Passwort eingeben und Finish klicken

Data Set

Zur Datenquelle können wir jetzt Data Sets anlegen. Data Sets sind entweder einzelne Abfragen aus genau einer Datenquelle oder ein „Joint Data Set“ aus zwei verschiedenen Datenquellen.

  • Data / New Data Set / New Data Set.
  • Data Source Selection: „KPI“.
  • Data Set Type: „SQL Select Query“.
  • Data Set Name: „Wasser“.
  • Als Query nehmen wir die „Daten der letzten Woche“:

    select * from tagvalues v
    join tagequipment e on v.tagname = e.tagname
    where e.eqpath = 'Wasser/STW/Verbraucher/Sekundär'
    and v.time like '____-__-__'
    and v.time between from_days(to_days(now()) - (7 + weekday(now()))) and from_days(to_days(now()) - (1 + weekday(now())))

  • Weil Zeitangaben und Messwerte als Strings aus der Datenbank kommen, legen wir Computed Columns an, die in den passenden Datentyp wandeln:
    Column Name: Datum; Data Type: Date; Expression: row[„time“]
    Column Name: Wert; Data Type: Float; Expression: Math.round(new Number(row[„value“]))
    crosstab-reports_10
  • Preview Results

Statt der Computed Columns hätten wir auch in der SQL-Abfrage selbst die passenden Typen durch MySQL-Funktionen herstellen können. Das ist weitgehend Geschmackssache. Geschwindigkeitsunterschiede habe ich noch nicht getestet.

Daten für Kreuztabelle anlegen

Für die Kreuztabelle benötigen wir einen Data Cube. Cube deshalb, weil er im Gegensatz zu einer einfachen Tabelle, wie sie aus der SQL-Abfrage kommt, die Werte („measures“) über mehrere sogenannte Dimensions in Beziehung setzt. Dimensions spannen sozusagen Koordinatensysteme auf, in deren Kreuzungspunkten die jeweiligen Werte stehen. Bei zwei Dimensions – Name der Messstelle und Tagesdatum – ist der Cube eine Kreuztabelle. Näheres zu Data Cubes steht zum Beispiel in der Wikipedia unter Cube_(OLAP).

  • Im Outline oder Data Explorer bei Data Cubes rechts klicken und „New Data Cube“ wählen.
    Der Name soll „WasserCube“ sein.
    Mit Rechtsklick auf „WasserCube“ und „Edit“ die Einstellungen öffnen
  • Als Dataset „Wasser“ wählen.
  • Bei Groups and Summaries werden die Dimensionen und Measures festgelegt
  • Feld „Datum“ in die Groups ziehen („Drop a field here to create a group“), um eine Group bzw. Dimension zu erzeugen
  • Feld „eqproperty“ ebenso erzeugt eine zweite Gruppe mit den Namen der Messstellen
  • Feld „Wert“ in die Summaries ziehen

Der Data Explorer (linke Spalte) sollte so aussehen:

Crosstab (Pivot-Tabelle) anlegen

Jetzt kann die eigentliche Kreuztabelle angelegt werden.

  • Im Hauptfenster den Tab Layout anwählen. Hier wird der Bericht entworfen
  • Aus der Palette eine Crosstab auf die Fläche ziehen
  • Im Data Explorer den WasserCube ausklappen und die Group mit eqproperty in die linke Zelle ziehen („… to define rows here“).
  • Desgleichen die Group mit time in die obere Zelle ziehen („… to define columns here“).
  • Summary Field1 aus WasserCube in das Summenfeld ziehen („… to be summarized here“).

Das Ergebnis können wir sofort testen durch einen Klick auf den Tab Preview oder über das Menü mit Run / View Report / as PDF
Im Detail können noch sehr viele Einstellungen optimiert werden.

Chart anlegen

Charts zu erzeugen funktioniert ebenso wie bei der Kreuztabelle. Das Tagesdatum – Spalte „Datum“ – wird auf die X-Achse gestellt, die Messwerte auf die Y-Achse. Die Stapelung der Werte pro Tag wird durch Gruppierung nach den Namen der Messstellen erreicht.

  • Layout anklicken und aus der Palette ein Chart auf die Fläche ziehen.
  • Rechtsklick auf das Chart im Layout für die Einstellung der Parameter.
  • Chart-Typ: Gestapelt

crosstab-reports_111

  • Select Data:
  • Use Data from: „Data Source Wasser“
  • Value Series: Spalte „Wert“ ins Feld ziehen
  • Category Series: Spalte „Datum“ ins Feld ziehen
  • Y Series Grouping: Spalte „eqproperty“ ins Feld ziehen

crosstab-reports_12

  • Format Chart: Achsenbeschriftungen einstellen, X-Axis, Format Datum

crosstab-reports_09

Fertig. Den ganzen Report mit Tabelle und Grafik sehen wir durch einen Klick auf Preview oder Run / View Report / as PDF. Meinen habe ich hier etwas unkenntlich gemacht, weil ja Originaldaten drin sind.

crosstab-reports_141